Getting Started

This guide walks you through integrating the Privacy Boost iOS SDK into your app.

For a minimal copy-paste example, see the iOS Quickstart. This guide explains each step in detail.

Prerequisites

The SDK installed in your project
An App ID and server URL (see Configuration)
A wallet integration (WalletConnect, custom, etc.)
Familiarity with authentication options (optional for development, required for production)

Overview

The iOS SDK follows a simple flow:

Initialize - Create SDK instance with configuration
Authenticate - Connect wallet and authenticate via WalletDelegate
Use - Deposit, unshield, transfer tokens

Basic Setup

1. Import the SDK

import PrivacyBoost

2. Configure the SDK

let config = PrivacyBoostConfig(
    serverUrl: "https://optimism.sepolia.privacyboost.io",
    wethContractAddress: "0x4200000000000000000000000000000000000006",
    appId: "app_abc123xyz"
)

3. Initialize

do {
    let sdk = try PrivacyBoost(config: config)
} catch {
    print("Failed to initialize SDK: \(error)")
}

Connecting a Wallet

The SDK uses the WalletDelegate protocol to interact with wallets. You must implement this protocol:

class MyWalletDelegate: WalletDelegate {
    func getAddress() async throws -> String {
        // Return the connected wallet address
        return "0x..."
    }

    func getChainId() async throws -> UInt64 {
        // Return the current chain ID
        return 1
    }

    func signMessage(message: String) async throws -> String {
        // Sign using EIP-191 personal_sign
        // Return signature as hex string with 0x prefix
        return "0x..."
    }

    func signTypedData(typedDataJson: String) async throws -> String {
        // Sign using EIP-712 eth_signTypedData_v4
        return "0x..."
    }

    func sendTransaction(toAddress: String, value: String, data: String) async throws -> String {
        // Submit transaction and return hash
        return "0x..."
    }

    func waitForTransactionReceipt(txHash: String) async throws -> TransactionReceipt {
        // Poll eth_getTransactionReceipt until the transaction is mined
        return TransactionReceipt(txHash: txHash, status: true, logs: [])
    }
}

You can choose any web3 libraries in Swift to integrate with this delegate. Then authenticate:

let wallet = MyWalletDelegate()
do {
    // Default (wallet-derived keys)
    let result = try await sdk.authenticate(wallet: wallet)

    // Or with a specific key source
    // let result = try await sdk.authenticate(
    //     wallet: wallet,
    //     keySource: .mnemonic(phrase: "your twelve word mnemonic ...")
    // )

    switch result {
    case .authenticated(let loginResult):
        print("Privacy Address: \(loginResult.privacyAddress)")
        print("MPK: \(loginResult.mpk)")
    case .credentialRequired(let challenge):
        // Handle credential challenge
        let loginResult = try await sdk.submitCredential(credential)
        print("Privacy Address: \(loginResult.privacyAddress)")
    }
} catch {
    print("Authentication failed: \(error)")
}

Core Operations

Check Balance

do {
    let balance = try await sdk.getBalance(tokenAddress: "0x...")
    print("Shielded: \(balance.shieldedBalance)")
    print("Wallet: \(balance.walletBalance)")
} catch {
    print("Failed to get balance: \(error)")
}

Deposit Tokens

Move tokens from wallet to shielded pool:

do {
    let result = try await sdk.shield(
        tokenAddress: "0x...",
        amount: "1000000000000000000"  // 1 token (18 decimals)
    )
    print("Deposit TX: \(result.txHash)")
} catch {
    print("Deposit failed: \(error)")
}

Withdraw Tokens

Move tokens from shielded pool to wallet:

do {
    let result = try await sdk.unshield(
        tokenAddress: "0x...",
        amount: "500000000000000000",
        recipient: "0x..."  // Recipient address
    )
    print("Withdraw TX: \(result.txHash)")
} catch {
    print("Withdraw failed: \(error)")
}

Private Transfer

Send tokens privately to another user:

do {
    let result = try await sdk.send(
        tokenAddress: "0x...",
        amount: "250000000000000000",
        recipientPrivacyAddress: "0x04..."  // 194-char privacy address
    )
    print("Transfer TX: \(result.txHash)")
} catch {
    print("Transfer failed: \(error)")
}

Error Handling

The SDK throws SDKError for various failure conditions:

do {
    let result = try await sdk.shield(tokenAddress: token, amount: amount)
} catch SDKError.notConnected {
    print("Wallet not connected")
} catch SDKError.notAuthenticated {
    print("Not logged in")
} catch SDKError.insufficientBalance {
    print("Insufficient balance")
} catch SDKError.invalidAmount {
    print("Invalid amount format")
} catch SDKError.walletError(let message) {
    print("Wallet error: \(message)")
} catch SDKError.networkError(let message) {
    print("Network error: \(message)")
} catch {
    print("Unknown error: \(error)")
}

Session Persistence

Save and restore sessions to avoid re-signing:

// Export session
if let session = sdk.exportSession() {
    // Store securely (e.g., Keychain)
    saveToKeychain(session)
}

// Import session
if let session = loadFromKeychain() {
    do {
        let success = try sdk.importSession(session)
        if success {
            print("Session restored")
        }
    } catch {
        print("Session expired or invalid")
    }
}

Next Steps

Wallet Integration

Detailed WalletDelegate implementation

Session Storage

Secure Keychain storage and biometric unlock

API Reference

Complete API documentation

Key Management

Key derivation, persistence options, and recovery

Quickstart

Setup

SDKs

Getting started

Getting Started

Prerequisites

Overview

Basic Setup

1. Import the SDK

2. Configure the SDK

3. Initialize

Connecting a Wallet

Core Operations

Check Balance

Deposit Tokens

Withdraw Tokens

Private Transfer

Error Handling

Session Persistence

Next Steps

Wallet Integration

Session Storage

API Reference

Key Management

​Getting Started

​Prerequisites

​Overview

​Basic Setup

​1. Import the SDK

​2. Configure the SDK

​3. Initialize

​Connecting a Wallet

​Core Operations

​Check Balance

​Deposit Tokens

​Withdraw Tokens

​Private Transfer

​Error Handling

​Session Persistence

​Next Steps

Wallet Integration

Session Storage

API Reference

Key Management

Getting Started

Prerequisites

Overview

Basic Setup

1. Import the SDK

2. Configure the SDK

3. Initialize

Connecting a Wallet

Core Operations

Check Balance

Deposit Tokens

Withdraw Tokens

Private Transfer

Error Handling

Session Persistence

Next Steps