Skip to main content

Getting Started

This guide walks through integrating the Privacy Boost TypeScript SDK into your application.

Prerequisites

  • Node.js 18+ or modern browser
  • A wallet (MetaMask, WalletConnect, etc.)
  • Access to Privacy Boost services (indexer, prover)

Step 1: Initialize the SDK

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

const sdk = await PrivacyBoost.create({
  indexerUrl: 'https://test-api.privacy-boost.sunnyside.io/indexer',
  proverUrl: 'https://test-api.privacy-boost.sunnyside.io/prover',
  chainId: 11155420, 
  shieldContract: '0xB22fD661b322F10d4B7cd0cFcb9578C485423119',
  wethContract: '0x4200000000000000000000000000000000000006',
});

Configuration Options

OptionTypeRequiredDescription
indexerUrlstringYesIndexer service endpoint
proverUrlstringYesProver service endpoint
chainIdnumberYesEVM chain ID
shieldContractstringYesShield contract address
wethContractstringNoWETH contract for ETH handling

Step 2: Connect a Wallet

Using Browser Wallet (MetaMask, etc.)

import { Eip1193WalletAdapter } from '@testinprod-io/privacy-boost';

// Create adapter from window.ethereum
const adapter = new Eip1193WalletAdapter(window.ethereum);

// Connect
const { address, chainId } = await sdk.auth.connect(adapter);
console.log(`Connected: ${address} on chain ${chainId}`);

Using WalletConnect

import { createWalletRegistry } from '@testinprod-io/privacy-boost';

const registry = createWalletRegistry({
  chains: [1],
  walletConnect: { projectId: 'your-walletconnect-project-id' },
});

const adapter = registry.getAdapter('walletconnect');
await sdk.auth.connect(adapter);

Connection State

// Check connection status
console.log('Connected:', sdk.auth.isConnected());
console.log('Address:', sdk.auth.getAddress());

Step 3: Authenticate (Login)

After connecting, login to derive privacy keys:
const { privacyAddress, mpk } = await sdk.auth.login();
console.log('Privacy Address:', privacyAddress);
The login process:
  1. Requests a challenge from the indexer
  2. Signs the challenge with EIP-712
  3. Derives privacy keys from the signature
  4. Registers with the indexer
// Check authentication status
console.log('Authenticated:', sdk.auth.isAuthenticated());
console.log('Privacy Address:', sdk.auth.getPrivacyAddress());

Step 4: Check Balance

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

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

Step 5: Deposit Tokens

Move tokens from your wallet to private balance:
const result = await sdk.vault.deposit({
  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:
  1. wrapping - If depositing ETH, wrap to WETH
  2. approving - Approve token spending
  3. shielding - Execute the deposit transaction
  4. compliance - Wait for compliance check

Step 6: Send Private Transfer

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

console.log('Transfer tx:', result.txHash);
The recipient will see the tokens in their shielded balance after the transaction confirms.

Step 7: Withdraw Tokens

Move tokens from private balance to any public address:
const result = await sdk.vault.withdraw({
  tokenAddress: '0x...',
  amount: 250000000000000000n,
  recipientAddress: '0x...any-public-address',
  unwrapWeth: true, // Unwrap WETH to ETH if applicable
  onProgress: ({ step, message }) => {
    console.log(`${step}: ${message}`);
  },
});

console.log('Withdraw tx:', result.txHash);

Step 8: Manage Contacts

Save frequently used privacy addresses:
// Add a contact
await sdk.contacts.addContact({
  name: 'Alice',
  privacyAddress: '0x04...alice-privacy-address',
  note: 'Friend from work',
});

// List contacts
const contacts = sdk.contacts.getContacts();
for (const contact of contacts) {
  console.log(`${contact.name}: ${contact.privacyAddress}`);
}

// Search contacts
const found = sdk.contacts.search('alice');

Step 9: View Transaction History

const history = await sdk.transactions.fetchHistory({
  type: 'transfer', // 'deposit', 'withdraw', or 'transfer'
  limit: 10,
});

for (const tx of history) {
  console.log(`${tx.type}: ${tx.amount} (${tx.status})`);
}

Step 10: Session Management

Export Session

Save the session for later restoration:
const session = sdk.auth.exportSession();
localStorage.setItem('privacy_session', JSON.stringify(session));

Import Session

Restore a saved session:
const savedSession = JSON.parse(localStorage.getItem('privacy_session'));
if (savedSession) {
  await sdk.auth.importSession(savedSession);
  console.log('Session restored');
}

Session Info

Check session validity:
const info = await sdk.auth.getSessionInfo();
if (info) {
  console.log('Session valid until:', new Date(info.expiresAt * 1000));
  console.log('Is auditor:', info.isAuditor);
}

Step 11: Logout

// Disconnect wallet
await sdk.auth.disconnect();

// Or fully logout (clears all state)
await sdk.auth.logout();

Complete Example

import { PrivacyBoost, Eip1193WalletAdapter } from '@testinprod-io/privacy-boost';

async function main() {
  // Initialize
  const sdk = await PrivacyBoost.create({
    indexerUrl: 'https://test-api.privacy-boost.sunnyside.io/indexer',
    proverUrl: 'https://test-api.privacy-boost.sunnyside.io/prover',
    chainId: 11155420,
    shieldContract: "0xB22fD661b322F10d4B7cd0cFcb9578C485423119",
    wethContract: "0x4200000000000000000000000000000000000006"
  });

  // Connect wallet
  const adapter = new Eip1193WalletAdapter(window.ethereum);
  await sdk.auth.connect(adapter);

  // Login
  const { privacyAddress } = await sdk.auth.login();
  console.log('Your privacy address:', privacyAddress);

  // Check balance
  const balance = await sdk.vault.getBalance('0x...token');
  console.log('Current balance:', balance);

  // Deposit
  await sdk.vault.deposit({
    tokenAddress: '0x...token',
    amount: 1000000000000000000n,
    onProgress: console.log,
  });

  // Send to friend
  await sdk.vault.send({
    to: '0x04...friend-address',
    tokenAddress: '0x...token',
    amount: 100000000000000000n,
  });

  // Save session
  const session = sdk.auth.exportSession();
  localStorage.setItem('session', JSON.stringify(session));
}

main().catch(console.error);

Next Steps