Multi-Chain

This guide covers using ChainContextHandle to operate on multiple blockchains from a single Android 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:

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

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

val base = sdk.createChainContext(ChainContextConfig(
    serverUrl = "https://base.example.com",
    chainId = 8453u
))

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 SDKError 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 in the repository or ViewModel 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. The calls below are suspend functions; run them inside a coroutine:

// Authenticate the parent SDK once; this establishes the identity keys.
sdk.authenticate(
    wallet = walletDelegate,
    keySource = KeySource.WalletDerived,
    tokenProvider = null
)

// Authenticate each chain context with the same wallet.
val ethLogin = ethereum.authenticate(wallet = walletDelegate)
val baseLogin = base.authenticate(wallet = walletDelegate)

println("Ethereum chain id: ${ethereum.chainId()}")
println("Ethereum authenticated: ${ethereum.isAuthenticated()}")
println("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

val amount = sdk.parseAmount("1.0", decimals = 18u)
val result = ethereum.shield(
    tokenAddress = "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH on Ethereum
    amount = amount
)
println("Ethereum shield tx: ${result.txHash}")

Private Transfers

// resolveIdentity lives on the parent SDK; the handle shares its identity.
val recipient = sdk.resolveIdentity("0x1234...abcd")

val transfer = base.send(
    tokenAddress = "0x...token-on-base",
    amount = sdk.parseAmount("0.5", decimals = 18u),
    recipientPrivacyAddress = recipient.privacyAddress
)
println("Base transfer tx: ${transfer.txHash}")

Withdrawals

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

Balances

val ethBalance = ethereum.getBalance("0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2")
val baseBalance = base.getBalance("0x...token-on-base")

println("Ethereum shielded: ${ethBalance.shieldedBalance}")
println("Base shielded: ${baseBalance.shieldedBalance}")

Status Polling and History

val status = ethereum.getShieldStatus(result.requestId)
val history = base.getTransactionHistory(txType = null, limit = 20u, cursor = null)
val notes = ethereum.getUnspentNotes(tokenAddress = null)

// Token and direction filters, and collapsed gateway rows, go through the full query.
val incoming = base.queryTransactionHistory(TransactionHistoryQuery(
    direction = TransactionDirection.INCOMING,
    limit = 20u,
    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 coroutines:

import kotlinx.coroutines.async
import kotlinx.coroutines.coroutineScope

suspend fun shieldBoth(): Pair<ShieldResult, ShieldResult> = coroutineScope {
    val ethTask  = async { ethereum.shield(ethToken, ethAmount) }
    val baseTask = async { base.shield(baseToken, baseAmount) }
    Pair(ethTask.await(), baseTask.await())
}

Aggregating Balances

import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.coroutineScope
import java.math.BigInteger

data class ChainEntry(val ctx: ChainContextHandle, val token: String)

suspend fun totalShielded(chains: List<ChainEntry>): BigInteger = coroutineScope {
    chains
        .map { entry -> async { entry.ctx.getBalance(entry.token).shieldedBalance } }
        .awaitAll()
        .map { BigInteger(it) }
        .fold(BigInteger.ZERO, BigInteger::add)
}

val total = totalShielded(listOf(
    ChainEntry(ethereum, "0x..."),
    ChainEntry(base, "0x...")
))

Chain Selection

val chains = mapOf(
    "ethereum" to ethereum,
    "base" to base
)

fun chain(name: String): ChainContextHandle =
    chains[name] ?: throw IllegalArgumentException("Unknown chain: $name")

chain("ethereum").shield(
    tokenAddress = "0x...",
    amount = sdk.parseAmount("1.0", decimals = 18u)
)

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