Multi-Chain

This guide covers using ChainContextHandle to operate on multiple blockchains from a single iOS SDK instance.

For an overview of multi-chain concepts, see Multi-Chain Concepts. The same identity keys and privacy address apply on every chain.

Setup

Initialize the parent SDK against your primary chain, then open a chain context for each additional chain:

import PrivacyBoost

let sdk = try PrivacyBoost(config: PrivacyBoostConfig(
    serverUrl: "https://op.example.com",
    chainId: nil,                      // discovered from server
    shieldContractAddress: nil,
    wethContractAddress: nil,
    teePublicKey: nil,
    appId: "my-app",
    persistenceStorage: nil,
    persistenceUnlock: nil
))

// After authenticating the parent SDK once, open per-chain contexts.
let ethereum = try sdk.createChainContext(config: ChainContextConfig(
    serverUrl: "https://eth.example.com",
    chainId: 1
))

let base = try sdk.createChainContext(config: ChainContextConfig(
    serverUrl: "https://base.example.com",
    chainId: 8453
))

serverUrl and chainId are the only fields you have to give: an omitted contract address is discovered from that chain’s server, and timeoutMs defaults to the SDK-wide 30s. A contract address you do pass has to parse, so a typo fails rather than falling back to the server-advertised pool. createChainContext is synchronous and throws if serverUrl is empty or not an HTTPS URL. Every call returns a new handle with its own session, so create each one once and keep it, for example on the actor or object that owns sdk.

Authentication

Each chain context authenticates before it can operate. Authentication reuses the parent SDK’s privacy keys but obtains a chain-specific JWT and registration, so the user signs once per chain:

// Authenticate the parent SDK once; this establishes the identity keys.
_ = try await sdk.authenticate(
    wallet: walletDelegate,
    keySource: .walletDerived,
    tokenProvider: nil
)

// Authenticate each chain context with the same wallet.
let ethLogin = try await ethereum.authenticate(wallet: walletDelegate)
let baseLogin = try await base.authenticate(wallet: walletDelegate)

print("Ethereum chain id:", ethereum.chainId())
print("Ethereum authenticated:", ethereum.isAuthenticated())
print("Ethereum registered:", ethereum.isRegistered())

ChainContextHandle.authenticate(wallet:) takes only a WalletDelegate; the key source and token provider come from the parent SDK. Apps that authenticate through an external identity provider pass that provider’s token as externalToken:.

Operations

Once authenticated, a ChainContextHandle exposes the same per-chain operations as the parent SDK.

Deposits

let amount = try sdk.parseAmount("1.0", decimals: 18)
let result = try await ethereum.shield(
    tokenAddress: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH on Ethereum
    amount: amount
)
print("Ethereum shield tx:", result.txHash)

Private Transfers

// resolveIdentity lives on the parent SDK; the handle shares its identity.
let recipient = try await sdk.resolveIdentity(identifier: "0x1234...abcd")

let transfer = try await base.send(
    tokenAddress: "0x...token-on-base",
    amount: try sdk.parseAmount("0.5", decimals: 18),
    recipientPrivacyAddress: recipient.privacyAddress
)
print("Base transfer tx:", transfer.txHash)

Withdrawals

_ = try await ethereum.unshield(
    tokenAddress: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    amount: try sdk.parseAmount("0.25", decimals: 18),
    recipient: "0x...destination"
)

Balances

let ethBalance = try await ethereum.getBalance(
    tokenAddress: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
)
let baseBalance = try await base.getBalance(tokenAddress: "0x...token-on-base")

print("Ethereum shielded:", ethBalance.shieldedBalance)
print("Base shielded:", baseBalance.shieldedBalance)

Status Polling and History

let status = try await ethereum.getShieldStatus(requestId: result.requestId)
let history = try await base.getTransactionHistory(txType: nil, limit: 20, cursor: nil)
let notes = try await ethereum.getUnspentNotes(tokenAddress: nil)

// Token and direction filters, and collapsed gateway rows, go through the full query.
let incoming = try await base.queryTransactionHistory(query: TransactionHistoryQuery(
    direction: .incoming,
    limit: 20,
    collapseGateway: true
))

What the Handle Carries

A handle covers the operations whose state is per chain: shield, prepareShield, unshield, send and sendBatch, unwrapWeth, consolidateNotes, balances and the token catalog, fees, status polling, history and unspent notes, pending-transaction tracking (including waitForPreconfirmation and waitForFinality), and the claimable-transfer (gift) methods. It does not carry portal deposits, earn and swap, audit, or the private treasury (contacts and labels). Those stay on the parent PrivacyBoost, as do resolveIdentity, parseAmount, formatAmount, address validation, setChainReader, and session export. The parent’s pending transactions and token registry reflect its own chain only, so read each chain’s pending transactions and balances through that chain’s handle rather than the parent. The handle has no vault of its own: it shares the parent’s resident keys, so lock() and the auto-lock timers on the parent apply to it as well. Its JWT is separate, which is why clearSession() on the parent does not reach it.

Cross-Chain Patterns

Parallel Operations

Chain contexts are independent, so fan out with async let:

async let ethTask  = ethereum.shield(tokenAddress: "0x...", amount: ethAmount)
async let baseTask = base.shield(tokenAddress: "0x...", amount: baseAmount)

let (ethResult, baseResult) = try await (ethTask, baseTask)

Aggregating Balances

struct ChainEntry {
    let ctx: ChainContextHandle
    let token: String
}

func totalShielded(across chains: [ChainEntry]) async throws -> String {
    try await withThrowingTaskGroup(of: String.self) { group in
        for chain in chains {
            group.addTask {
                let bal = try await chain.ctx.getBalance(tokenAddress: chain.token)
                return bal.shieldedBalance
            }
        }
        var sum: UInt64 = 0
        for try await wei in group {
            sum &+= UInt64(wei) ?? 0
        }
        return String(sum)
    }
}

let total = try await totalShielded(across: [
    ChainEntry(ctx: ethereum, token: "0x..."),
    ChainEntry(ctx: base, token: "0x..."),
])

For amounts that exceed UInt64, use BigInt from a library such as BigInt.

Chain Selection

let chains: [String: ChainContextHandle] = [
    "ethereum": ethereum,
    "base": base,
]

func chain(_ name: String) throws -> ChainContextHandle {
    guard let ctx = chains[name] else {
        throw SDKError.invalidInput(message: "Unknown chain: \(name)")
    }
    return ctx
}

_ = try await chain("ethereum").shield(
    tokenAddress: "0x...",
    amount: try sdk.parseAmount("1.0", decimals: 18)
)

Cleanup

Each chain context can drop its JWT independently while the parent SDK identity stays intact:

ethereum.clearSession()   // drop just Ethereum's JWT
sdk.clearSession()        // drop the parent JWT (does not clear contexts)
sdk.lock()                // wipe the shared keys; contexts keep their JWT until cleared
sdk.logout()              // end the whole session and clear the shared identity

Quickstart

Setup

SDKs

Multi-Chain

Multi-Chain

Setup

Authentication

Operations

Deposits

Private Transfers

Withdrawals

Balances

Status Polling and History

What the Handle Carries

Cross-Chain Patterns

Parallel Operations

Aggregating Balances

Chain Selection

Cleanup

Next Steps

​Multi-Chain

​Setup

​Authentication

​Operations

​Deposits

​Private Transfers

​Withdrawals

​Balances

​Status Polling and History

​What the Handle Carries

​Cross-Chain Patterns

​Parallel Operations

​Aggregating Balances

​Chain Selection

​Cleanup

​Next Steps

Multi-Chain

Setup

Authentication

Operations

Deposits

Private Transfers

Withdrawals

Balances

Status Polling and History

What the Handle Carries

Cross-Chain Patterns

Parallel Operations

Aggregating Balances

Chain Selection

Cleanup

Next Steps