Multi-Chain

Privacy Boost supports operating across multiple EVM-compatible blockchains from a single SDK instance. Your cryptographic identity (keys) is shared across all chains, while each chain maintains its own authentication state, balances, and transaction history.

How It Works

The multi-chain architecture has two layers:

Parent SDK (PrivacyBoost): initialized once with your primary chain. Holds your identity keys.
Chain clients: created per chain from the parent. Each has its own server connection, JWT, and chain state, but shares the parent’s identity. On TypeScript and React this is a ChainClient from sdk.forChain(); on React Native, iOS, and Android it is a ChainContextHandle from sdk.createChainContext().

PrivacyBoost (identity keys, primary chain)
├── chain client (Optimism): own auth, balances, transactions
├── chain client (Ethereum): own auth, balances, transactions
└── chain client (Base):     own auth, balances, transactions

This means you authenticate once per chain, but your privacy address is consistent across all of them, on every platform.

Quick Example

import { PrivacyBoost } from '@sunnyside-io/privacy-boost';

// Initialize SDK with your primary chain
const sdk = await PrivacyBoost.create({
  serverUrl: 'https://op.example.com',
  appId: 'my-app',
});

// Create chain clients for other chains
const ethereum = sdk.forChain({ serverUrl: 'https://eth.example.com' });
const base = sdk.forChain({ serverUrl: 'https://base.example.com' });

// Authenticate on each chain (uses shared identity keys)
await ethereum.authenticate(walletAdapter);
await base.authenticate(walletAdapter);

// Operate independently per chain
await ethereum.vault.shield({ tokenAddress: '0x...', amount: 1000n });
await base.vault.send({ to: '0x04...', tokenAddress: '0x...', amount: 500n });

import { useChain } from '@sunnyside-io/privacy-boost-react';

function MultiChainApp() {
  const ethereum = useChain({ serverUrl: 'https://eth.example.com' });
  const base = useChain({ serverUrl: 'https://base.example.com' });

  // Each chain client is independent
  const depositOnEthereum = async () => {
    await ethereum?.vault.shield({ tokenAddress: '0x...', amount: 1000n });
  };

  const sendOnBase = async () => {
    await base?.vault.send({ to: '0x04...', tokenAddress: '0x...', amount: 500n });
  };

  return (
    <div>
      <button onClick={depositOnEthereum}>Deposit on Ethereum</button>
      <button onClick={sendOnBase}>Send on Base</button>
    </div>
  );
}

import { PrivacyBoost, PrivacyBoostConfig } from '@sunnyside-io/privacy-boost-react-native';

const sdk = new PrivacyBoost(PrivacyBoostConfig.create({
  serverUrl: 'https://op.example.com',
  chainId: undefined,
  shieldContractAddress: undefined,
  wethContractAddress: undefined,
  teePublicKey: undefined,
  appId: 'my-app',
  persistenceStorage: undefined,
  persistenceUnlock: undefined,
}));

// Authenticate the parent once (establishes identity keys), then open
// a handle per additional chain.
await sdk.authenticate(walletDelegate, undefined, undefined);

const ethereum = sdk.createChainContext({
  serverUrl: 'https://eth.example.com',
  chainId: 1n,
  shieldContractAddress: undefined,
  wethContractAddress: undefined,
  rpcUrl: undefined,
  teePublicKey: undefined,
  timeoutMs: 30_000n,
});

// Each handle obtains its own JWT with the shared identity keys
await ethereum.authenticate(walletDelegate);

// Operate independently per chain
await ethereum.shield('0x...', '1000');

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

// Authenticate the parent once (establishes identity keys), then open
// a handle per additional chain.
_ = try await sdk.authenticate(wallet: walletDelegate, keySource: .walletDerived, tokenProvider: nil)

let ethereum = try sdk.createChainContext(config: ChainContextConfig(
    serverUrl: "https://eth.example.com",
    chainId: 1
))

// Each handle obtains its own JWT with the shared identity keys
_ = try await ethereum.authenticate(wallet: walletDelegate)

// Operate independently per chain
_ = try await ethereum.shield(tokenAddress: "0x...", amount: "1000")

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

// Authenticate the parent once (establishes identity keys), then open
// a handle per additional chain.
sdk.authenticate(wallet = walletDelegate, keySource = KeySource.WalletDerived, tokenProvider = null)

val ethereum = sdk.createChainContext(ChainContextConfig(
    serverUrl = "https://eth.example.com",
    chainId = 1u
))

// Each handle obtains its own JWT with the shared identity keys
ethereum.authenticate(wallet = walletDelegate)

// Operate independently per chain
ethereum.shield(tokenAddress = "0x...", amount = "1000")

ChainClient Configuration

Only serverUrl is required. All other fields are auto-discovered from the chain’s server /api/v1/info endpoint.

Parameter	Type	Required	Description
`serverUrl`	`string`	Yes	URL of this chain’s server
`chainId`	`number`	No	EVM chain ID (auto-discovered)
`shieldContractAddress`	`string`	No	Shield contract address (auto-discovered)
`wethContractAddress`	`string`	No	WETH contract address (for ETH wrapping)
`rpcUrl`	`string`	No	RPC URL for on-chain reads
`tokenRegistryAddress`	`string`	No	Token registry contract (auto-discovered)
`teePublicKey`	`string`	No	TEE public key (auto-discovered)

On React Native, iOS, and Android the equivalent record is ChainContextConfig. It takes the same serverUrl, shieldContractAddress, wethContractAddress, rpcUrl, and teePublicKey, but chainId and timeoutMs (request timeout in milliseconds) are required, and there is no tokenRegistryAddress field.

Caching

Chain clients are cached by serverUrl. Calling sdk.forChain() with the same URL returns the same instance:

const a = sdk.forChain({ serverUrl: 'https://eth.example.com' });
const b = sdk.forChain({ serverUrl: 'https://eth.example.com' });
// a === b (same instance)

This means you can call sdk.forChain() freely in components or functions without worrying about creating duplicate clients. createChainContext() on React Native, iOS, and Android does not cache: every call returns a new handle with its own session, so create each handle once and hold on to it.

Per-Chain Authentication

Each chain client must be authenticated independently. The authentication uses shared identity keys from the parent SDK, but obtains a separate JWT for each chain’s server.

const eth = sdk.forChain({ serverUrl: 'https://eth.example.com' });

// Must authenticate before using vault/transactions
await eth.authenticate(walletAdapter);

// Now you can use chain-scoped operations
console.log('Chain ID:', eth.chainId);
console.log('Authenticated:', eth.isAuthenticated);
const balance = await eth.vault.getBalance('0x...');

On React Native, iOS, and Android, ChainContextHandle.authenticate(wallet) takes only the wallet delegate; the key source and token provider come from the parent, and the handle exposes chainId(), isAuthenticated(), and isRegistered() as methods.

Available Operations

A ChainClient provides the same core operations as the parent SDK:

Resource	Operations
`vault`	`shield()`, `unshield()`, `send()`, `getBalance()`, `getAllBalances()`
`transactions`	Transaction history and status polling
`audit`	Auditor-specific operations
`campaigns`	Mission progress on this chain’s deployment

A native ChainContextHandle carries the operations whose state is per chain: shield, unshield, send and batch send, WETH unwrapping, note consolidation, balances and the token catalog, fees, status polling, history (including queryTransactionHistory), unspent notes, pending-transaction tracking, and claimable transfers. Portal deposits, earn and swap, and the private treasury (contacts and labels) stay on the root PrivacyBoost instance, as do identity lookup and the amount utilities. The two do not scope an identical set, and the difference is worth knowing before you write code against both:

Surface	TypeScript `ChainClient`	Native `ChainContextHandle`
Transfers, balances, history, notes	per chain	per chain
Claimable transfers (gifts)	root only	per chain
Audit	per chain	root only
Campaign progress	per chain	root only
Portal, earn, swap, contacts, labels	root only	root only

Gifts are root-bound on TypeScript because the browser key vault they run in is fixed to the root SDK’s chain; audit and campaigns are root-only on the native bindings because the core chain context does not carry them yet. Anything marked root only rejects on a chain-scoped client rather than silently reading the wrong chain.

// Deposit on a specific chain
await eth.vault.shield({ tokenAddress: '0x...', amount: 1000n });

// Check balance on that chain
const balance = await eth.vault.getBalance('0x...');

// Send privately on that chain
await eth.vault.send({ to: '0x04...', tokenAddress: '0x...', amount: 500n });

// Withdraw from that chain
await eth.vault.unshield({
  tokenAddress: '0x...',
  amount: 250n,
  recipientAddress: '0x...',
});

Identity Lookup

Look up a user’s privacy address on a specific chain:

const identity = await eth.resolveIdentity('0x1234...abcd');
console.log('Privacy address:', identity.privacyAddress);

On React Native, iOS, and Android, resolveIdentity lives on the parent PrivacyBoost. A privacy address is chain-independent, so the result is valid on every handle.

Cleanup

Chain clients are disposed automatically when the parent SDK is disposed. You can also dispose individual clients:

// Dispose a single chain client
eth.clearSession(); // Clear JWT and pending transactions
eth.dispose();      // Release all resources

// Or dispose everything at once
sdk.dispose(); // Disposes parent + all chain clients

On React Native, iOS, and Android each handle has clearSession(), which drops that chain’s JWT while the parent’s identity stays intact. The parent’s clearSession() and lock() do not reach handles (lock() wipes the keys they share but leaves each handle’s JWT in place), so clear each one you created; logout() on the parent clears the identity every handle shares.

Next Steps

TypeScript Multi-Chain Guide

Detailed TypeScript examples and patterns

React Multi-Chain Guide

React hooks and component patterns for multi-chain

React Native Multi-Chain Guide

ChainContextHandle patterns for React Native

iOS Multi-Chain Guide

ChainContextHandle patterns in Swift

Android Multi-Chain Guide

ChainContextHandle patterns in Kotlin

Configuration

SDK configuration and auto-discovery

Authentication

Authentication methods and wallet integration

Quickstart

Setup

SDKs

Multi-Chain

Multi-Chain

How It Works

Quick Example

ChainClient Configuration

Caching

Per-Chain Authentication

Available Operations

Identity Lookup

Cleanup

Next Steps

TypeScript Multi-Chain Guide

React Multi-Chain Guide

React Native Multi-Chain Guide

iOS Multi-Chain Guide

Android Multi-Chain Guide

Configuration

Authentication

​Multi-Chain

​How It Works

​Quick Example

​ChainClient Configuration

​Caching

​Per-Chain Authentication

​Available Operations

​Identity Lookup

​Cleanup

​Next Steps

TypeScript Multi-Chain Guide

React Multi-Chain Guide

React Native Multi-Chain Guide

iOS Multi-Chain Guide

Android Multi-Chain Guide

Configuration

Authentication

Multi-Chain

How It Works

Quick Example

ChainClient Configuration

Caching

Per-Chain Authentication

Available Operations

Identity Lookup

Cleanup

Next Steps