Getting Started

This guide walks through the core integration flow: initialize the SDK, authenticate a wallet, and perform your first private transactions.

For a minimal copy-paste example, see the TypeScript 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 (MetaMask, WalletConnect, etc.)
Familiarity with authentication options (optional for development, required for production)

Step 1: Initialize the SDK

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

const sdk = await PrivacyBoost.create({
  appId: 'your-app-id',
  serverUrl: 'https://optimism.sepolia.privacyboost.io',
  wethContractAddress: '0x4200000000000000000000000000000000000006',
});

Configuration Options

Option	Type	Required	Description
`appId`	`string`	Yes	Application identifier
`serverUrl`	`string`	Yes	Privacy Boost server endpoint
`chainId`	`number`	No	EVM chain ID (auto-discovered from server)
`shieldContractAddress`	`string`	No	Shield contract address (auto-discovered from server)
`wethContractAddress`	`string`	No	WETH contract for ETH handling

Step 2: Authenticate

Connect a wallet and authenticate in a single call:

Using Browser Wallet (MetaMask, etc.)

// Create a wallet adapter that wraps window.ethereum
const adapter = {
  async connect() {
    const accounts = await window.ethereum.request({ method: 'eth_requestAccounts' });
    const chainId = await window.ethereum.request({ method: 'eth_chainId' });
    return { address: accounts[0], chainId: parseInt(chainId, 16) };
  },
  async disconnect() {},
  async signMessage(message: string) {
    const accounts = await window.ethereum.request({ method: 'eth_accounts' });
    return window.ethereum.request({ method: 'personal_sign', params: [message, accounts[0]] });
  },
  async signTypedData(typedDataJson: string) {
    const accounts = await window.ethereum.request({ method: 'eth_accounts' });
    return window.ethereum.request({ method: 'eth_signTypedData_v4', params: [accounts[0], typedDataJson] });
  },
  async sendTransaction(tx: unknown) {
    return window.ethereum.request({ method: 'eth_sendTransaction', params: [tx] });
  },
  async getAddress() {
    const accounts = await window.ethereum.request({ method: 'eth_accounts' });
    return accounts[0];
  },
  async getChainId() {
    const chainId = await window.ethereum.request({ method: 'eth_chainId' });
    return parseInt(chainId, 16);
  },
};

// Authenticate — connects wallet, derives keys, and authenticates with server
const result = await sdk.auth.authenticate(adapter);

if (result.status === 'authenticated') {
  console.log('Privacy Address:', result.privacyAddress);
  console.log('MPK:', result.mpk);
} else if (result.status === 'credentialRequired') {
  // Prompt user for credential, then submit
  const loginResult = await result.submit(credential);
}

When does credentialRequired fire? credentialRequired only fires when persistence with pin or password unlock is configured. For the simple case (no persistence), authenticate() always returns authenticated directly.

Using React? The React SDK provides createWalletAdapter() and authenticateWithWalletAdapter() which handle this for you. See the React Getting Started guide.

Authentication State

// Check authentication status
console.log('Authenticated:', sdk.auth.isAuthenticated());
console.log('Privacy Address:', sdk.auth.getPrivacyAddress());

Step 3: Check Balance

Each token has two balances: a shielded balance (tokens inside the private pool, only visible to you) and a wallet balance (your public on-chain balance). Both are returned together in a TokenBalance object.

// Get balance for a specific token
const tokenAddress = '0x...';
const balance = await sdk.vault.getBalance(tokenAddress);
console.log('Shielded:', balance.shieldedBalance);
console.log('Wallet:', balance.walletBalance);

// Get all balances
const allBalances = await sdk.vault.getAllBalances();
for (const b of allBalances) {
  console.log(`${b.symbol}: ${b.shieldedBalance} (shielded), ${b.walletBalance} (wallet)`);
}

Step 4: Deposit Tokens

Move tokens from your public wallet into the shielded pool. Once deposited, your balance is private — only you can see it.

const result = await sdk.vault.shield({
  tokenAddress: '0x...',
  amount: 1000000000000000000n, // 1 token (18 decimals)
  onProgress: ({ step, message }) => {
    console.log(`${step}: ${message}`);
  },
});

console.log('Deposit tx:', result.txHash);
console.log('Commitment:', result.commitment);

Deposit Steps

The deposit operation goes through several steps:

wrapping - If depositing ETH, wrap to WETH
approving - Approve token spending
shielding - Execute the deposit transaction
compliance - Wait for compliance check

Step 5: Send Private Transfer

Send tokens privately to another user’s privacy address. The recipient shares their privacy address with you (similar to sharing a bank account number). No on-chain observer can see the sender, recipient, or amount.

const result = await sdk.vault.send({
  to: '0x04...recipient-privacy-address',
  tokenAddress: '0x...',
  amount: 500000000000000000n, // 0.5 tokens
});

console.log('Transfer requestId:', result.requestId);

The recipient will see the tokens in their shielded balance after the transaction confirms.

For send() and unshield(), the returned txHash is a local placeholder until the canonical on-chain hash is available. Track status by requestId (e.g. sdk.transactions.getTransferStatus(requestId) / sdk.transactions.getUnshieldStatus(requestId)). For shield(), txHash is the real on-chain hash because the wallet signs and submits it directly.

Step 6: Withdraw Tokens

Move tokens out of the shielded pool to any public Ethereum address. This is how you “cash out” back to a regular wallet.

const result = await sdk.vault.unshield({
  tokenAddress: '0x...',
  amount: 250000000000000000n, // 0.25 tokens
  recipientAddress: '0x...any-public-address',
  // Optional: when the token is WETH, automatically unwrap to native ETH
  // after the unshield lands. Requires `wethContractAddress` to be set.
  unwrapWeth: false,
  onProgress: ({ step, message }) => {
    console.log(`${step}: ${message}`);
  },
});

console.log('Withdraw requestId:', result.requestId);

Step 7: Multi-Chain (Optional)

To operate on additional blockchains, create chain clients from the same SDK instance. Each chain client shares your identity but has independent auth, balances, and transactions:

// Create a chain client (only serverUrl is required; rest is auto-discovered)
const ethereum = sdk.forChain({ serverUrl: 'https://eth.example.com' });

// Authenticate on the new chain
await ethereum.authenticate(adapter);

// Use it just like the primary SDK
await ethereum.vault.shield({
  tokenAddress: '0x...token-on-ethereum',
  amount: 1000000000000000000n,
});

const ethBalance = await ethereum.vault.getBalance('0x...');

See the Multi-Chain guide for patterns like parallel operations and cross-chain balance aggregation.

What’s Next

You’ve completed the core flow: init → auth → balance → deposit → send → withdraw. Here’s where to go from here:

Deposits

Deposit tokens into the shielded pool

Withdrawals

Withdraw tokens from the shielded pool

Private Transfers

Send tokens privately between users

Error Handling

Error codes and retry patterns

Multi-Chain

Operate across multiple blockchains

API Reference

Complete method signatures and type definitions

For cross-platform concepts (key management, auth methods, error codes), see the Setup section.

​Getting Started

​Prerequisites

​Step 1: Initialize the SDK

​Configuration Options

​Step 2: Authenticate

​Using Browser Wallet (MetaMask, etc.)

​Authentication State

​Step 3: Check Balance

​Step 4: Deposit Tokens

​Deposit Steps

​Step 5: Send Private Transfer

​Step 6: Withdraw Tokens

​Step 7: Multi-Chain (Optional)

​What’s Next

Deposits

Withdrawals

Private Transfers

Error Handling

Multi-Chain

API Reference

Getting Started

Prerequisites

Step 1: Initialize the SDK

Configuration Options

Step 2: Authenticate

Using Browser Wallet (MetaMask, etc.)

Authentication State

Step 3: Check Balance

Step 4: Deposit Tokens

Deposit Steps

Step 5: Send Private Transfer

Step 6: Withdraw Tokens

Step 7: Multi-Chain (Optional)

What’s Next