Skip to main content

​
API Reference

Complete API reference for the Privacy Boost iOS SDK.

​
Generated Documentation

Full API documentation can be generated using cargo doc: 
# From rust-sdk directory
make docs-rust

# iOS-specific docs
cargo doc --no-deps -p privacy-boost-ios

​
PrivacyBoost

Main SDK class for iOS.

​
Constructor

init(config: PrivacyBoostConfig) throws
Creates a new SDK instance. Parameters:
  • config - SDK configuration
Throws: SDKError.internalError if initialization fails

​
Properties

var isConnected: Bool { get }
var isAuthenticated: Bool { get }

​
Connection & Authentication Methods

​
authenticate

func authenticate(wallet: WalletDelegate, keySource: KeySource? = nil, tokenProvider: TokenProvider? = nil) async throws -> AuthResult
Connect a wallet, derive privacy keys, and authenticate with the Privacy Boost backend in a single call. Parameters:
  • wallet - Implementation of WalletDelegate protocol
  • keySource - Optional key derivation source. If nil and no persistence is configured, defaults to .walletDerived. If nil with persistence configured and no existing vault, an error is thrown.
  • tokenProvider - Optional custom token provider. If nil, the SDK sends the login payload directly to the Privacy Boost backend. Supply a TokenProvider to route authentication through your own server.
Returns: AuthResult - either .authenticated(LoginResult) or .credentialRequired(CredentialChallenge) Throws:
  • SDKError.walletError if signing fails
  • SDKError.invalidConfig if configuration is invalid or keySource is required but missing
  • SDKError.networkError if backend unreachable

​
submitCredential

func submitCredential(_ credential: String, tokenProvider: TokenProvider? = nil) async throws -> LoginResult
Submit a credential when authenticate() returns .credentialRequired. Parameters:
  • credential - The credential string
  • tokenProvider - Optional custom token provider for routing authentication through your own server
Returns: LoginResult with privacy address and MPK

​
logout

func logout()
End session completely, clear all state.

​
clearSession

func clearSession()
Clear JWT only, keep keys for quick re-auth.

​
State Accessors

func getPrivacyAddress() -> String?
func getMpk() -> String?
func getWalletAddress() -> String?

​
Balance Methods

​
getBalance

func getBalance(tokenAddress: String) async throws -> TokenBalance
Get balance for a specific token. Parameters:
  • tokenAddress - ERC-20 token contract address
Returns: TokenBalance with shielded and wallet amounts

​
getAllBalances

func getAllBalances() async throws -> [TokenBalance]
Get all token balances.

​
Vault Operations

​
deposit

func deposit(tokenAddress: String, amount: String) async throws -> DepositResult
Deposit tokens into the shielded pool. Parameters:
  • tokenAddress - Token contract address
  • amount - Amount in wei (as string)
Returns: DepositResult with transaction hash

​
withdraw

func withdraw(tokenAddress: String, amount: String, recipient: String) async throws -> UnshieldResult
Withdraw tokens from the shielded pool. Parameters:
  • tokenAddress - Token contract address
  • amount - Amount in wei (as string)
  • recipient - Recipient Ethereum address
Returns: UnshieldResult with transaction hash

​
send

func send(tokenAddress: String, amount: String, recipientPrivacyAddress: String) async throws -> TransferResult
Send a private transfer. Parameters:
  • tokenAddress - Token contract address
  • amount - Amount in wei (as string)
  • recipientPrivacyAddress - Recipient’s 194-char privacy address
Returns: TransferResult with transaction hash

​
Transaction History

func getTransactionHistory(
    txType: String?,
    tokenAddress: String?,
    limit: UInt32?
) async throws -> [Transaction]
Get transaction history. Parameters:
  • txType - Filter by type: “deposit”, “withdraw”, “transfer”
  • tokenAddress - Filter by token
  • limit - Maximum results

​
Session Persistence

​
exportSession

func exportSession() -> ExportedSession?
Export session data for persistence. Returns: ExportedSession or nil if not authenticated

​
importSession

func importSession(_ session: ExportedSession) throws -> Bool
Import a previously exported session. Returns: true if session is valid and imported

​
Address Lookup

​
resolveIdentity

func resolveIdentity(identifier: String) async throws -> IdentityResult
Look up a user’s privacy address by MPK or Ethereum address. Parameters:
  • identifier - MPK or Ethereum address
Returns: IdentityResult with privacy address and public keys

​
Utilities

func isValidPrivacyAddress(_ address: String) -> Bool
func isValidAddress(_ address: String) -> Bool
func parseAmount(_ amount: String, decimals: UInt8) throws -> String
func formatAmount(_ wei: String, decimals: UInt8) throws -> String

​
Module Functions

func sdkVersion() -> String
func generateMnemonic() throws -> String
  • sdkVersion() — Returns the SDK version string
  • generateMnemonic() — Generates a random 12-word BIP-39 mnemonic

​
Types

​
PrivacyBoostConfig

struct PrivacyBoostConfig {
    let serverUrl: String
    let wethContractAddress: String
    let appId: String
    let chainId: UInt64?
    let shieldContractAddress: String?
    let teePublicKey: String?
}
FieldTypeDescription
serverUrlStringPrivacy Boost server URL
wethContractAddressStringWETH contract address
appIdStringApplication ID (required)
chainIdUInt64?EIP-155 chain ID (optional, auto-discovered from server)
shieldContractAddressString?Shield contract address (optional, auto-discovered from server)
teePublicKeyString?TEE public key for encryption (optional)

​
KeySource

enum KeySource {
    case walletDerived
    case mnemonic(phrase: String)
    case rawSeed(hexSeed: String)
}
Specifies how privacy keys are derived. Passed as an optional parameter to authenticate().
  • walletDerived - Derive keys from a deterministic wallet signature (default when no persistence configured)
  • mnemonic - Derive keys from a BIP-39 mnemonic phrase
  • rawSeed - Derive keys from raw hex entropy (for testing)

​
AuthResult

enum AuthResult {
    case authenticated(LoginResult)
    case credentialRequired(CredentialChallenge)
}

​
LoginResult

struct LoginResult {
    let privacyAddress: String
    let mpk: String
}

​
TokenBalance

struct TokenBalance {
    let tokenAddress: String
    let shieldedBalance: String
    let walletBalance: String
    let symbol: String?
    let decimals: UInt8
}

​
DepositResult

struct DepositResult {
    let txHash: String
    let commitment: String
    let fee: String
}

​
UnshieldResult

struct UnshieldResult {
    let txHash: String
    let fee: String
}

​
TransferResult

struct TransferResult {
    let txHash: String
    let fee: String
}

​
Transaction

struct Transaction {
    let txHash: String
    let txType: String
    let tokenAddress: String
    let amount: String
    let direction: String
    let senderPubKey: String
    let receiverPubKeys: [String]
    let createdAt: UInt64
}

​
IdentityResult

struct IdentityResult {
    let mpk: String
    let ethereumAddress: String
    let viewingPublicKeyX: String
    let viewingPublicKeyY: String
    let privacyAddress: String
}

​
ExportedSession

struct ExportedSession {
    let walletPublicKeyX: String
    let walletPublicKeyY: String
    let viewingKey: String
    let viewingPublicKeyX: String
    let viewingPublicKeyY: String
    let nullifyingKey: String
    let nullifyingPublicKeyX: String
    let nullifyingPublicKeyY: String
    let mpk: String
    let accountId: String
    let jwt: String
    let jwtExpiry: UInt64
    let walletAddress: String
}

​
WalletDelegate Protocol

protocol WalletDelegate: AnyObject {
    func getAddress() async throws -> String
    func getChainId() async throws -> UInt64
    func signMessage(message: String) async throws -> String
    func signTypedData(typedDataJson: String) async throws -> String
    func sendTransaction(toAddress: String, value: String, data: String) async throws -> String
}

​
TokenProvider Protocol

protocol TokenProvider: AnyObject {
    func getToken(loginPayloadJson: String) async throws -> TokenResponse
}
Implement this protocol to route authentication through your own server. The SDK serializes the login payload as a JSON string and passes it to getToken(). Your implementation should forward this payload to your backend, which adds its own credentials and calls the Privacy Boost API.

​
TokenResponse

struct TokenResponse {
    let token: String      // JWT access token
    let expiresIn: UInt64  // Token lifetime in seconds
}

​
Example

class MyTokenProvider: TokenProvider {
    func getToken(loginPayloadJson: String) async throws -> TokenResponse {
        var request = URLRequest(url: URL(string: "https://your-server.com/api/privacy-auth")!)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = loginPayloadJson.data(using: .utf8)

        let (data, _) = try await URLSession.shared.data(for: request)
        let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
        return TokenResponse(
            token: json["token"] as! String,
            expiresIn: json["expiresIn"] as! UInt64
        )
    }
}

let result = try await sdk.authenticate(
    wallet: walletDelegate,
    tokenProvider: MyTokenProvider()
)

​
SDKError

enum SDKError: Error {
    case notConnected
    case notAuthenticated
    case invalidConfig
    case networkError(String)
    case walletError(String)
    case signatureRejected
    case insufficientBalance
    case invalidAddress
    case invalidAmount
    case serializationError(String)
    case authServerError(code: String, message: String)
    case shieldError(code: String, message: String)
    case transferError(code: String, message: String)
    case noteError(code: String, message: String)
    case merkleError(code: String, message: String)
    case apiError(code: String, message: String, retryable: Bool)
    case rateLimited(retryAfterMs: UInt64)
    case forbidden(String)
    case resourceNotFound(String)
    case internalError(String)
}

​
See Also