Skip to main content

Quick Start

Get started with encrypted balances in 5 minutes.

Installation​

First, configure npm for GitHub Packages, then:

npm install @zk-privacy/eb-sdk @zk-privacy/eb-contracts viem

Setup Client​

import { createClient, keysFromMnemonic, generateMnemonic } from '@zk-privacy/eb-sdk';
import { privateKeyToAccount } from 'viem/accounts';

const client = await createClient({
  chainId: 8453,
  enableL3: true,
  relayerUrl: 'https://eb-relayer.zkprivacy.dev',
});

Heavy assets (solver, prover) load lazily on first use — createClient returns in milliseconds.

Single-Token Mode (Legacy)​

const client = await createClient({
  rpcUrl: 'https://mainnet.base.org',
  contract: '0x...',
});

Create Wallet​

From Mnemonic (Standalone Mode)​

const mnemonic = generateMnemonic();
const keys = keysFromMnemonic(mnemonic);

const wallet = client.wallet({
  spendingKey: keys.spendingKey,
  account: privateKeyToAccount('0x...'),
});

console.log('Your BPK:', wallet.BPK);
console.log('EB Address:', bpkToAddress(wallet.BPK));

From MetaMask Signature (Linked Mode)​

import { keysFromSignature } from '@zk-privacy/eb-sdk';

const signature = await walletClient.signMessage({
  message: `zkPrivacy spending key for ${address}`,
});

const keys = keysFromSignature(signature);

Basic Operations​

Shield (Public → Encrypted)​

await wallet.USD.shield({ amount: 1000_000000n });

console.log('Encrypted balance:', await wallet.USD.getBalance());

Private Transfer​

const recipientBPK = addressToBpk('zk1qyp5...');

await wallet.USD.transfer({
  to: 'zk1qyp5...',
  amount: 500_000000n,
});

console.log('My balance:', await wallet.USD.getBalance());

Unshield (Encrypted → Public)​

await wallet.USD.unshield(200_000000n);

console.log('Public balance:', await wallet.USD.getPublicBalance());
console.log('Encrypted balance:', await wallet.USD.getBalance());

Multi-Currency Support​

await wallet.USD.shield({ amount: 1000n });
await wallet.EUR.shield({ amount: 500n });
await wallet.PLN.shield({ amount: 2000n });

const balances = await wallet.getAllBalances();
// { USD: 1000n, EUR: 500n, PLN: 2000n }

const eurBalance = await wallet.token('EUR').getBalance();

Complete Example​

import { 
  createClient,
  keysFromMnemonic, 
  bpkToAddress,
  generateMnemonic,
} from '@zk-privacy/eb-sdk';
import { privateKeyToAccount } from 'viem/accounts';

async function main() {
  const client = await createClient({
    chainId: 8453,
    enableL3: true,
    relayerUrl: 'https://eb-relayer.zkprivacy.dev',
  });

  const aliceKeys = keysFromMnemonic(generateMnemonic());
  const bobKeys = keysFromMnemonic(generateMnemonic());

  const alice = client.wallet({
    spendingKey: aliceKeys.spendingKey,
    account: privateKeyToAccount('0xalice...'),
  });

  const bob = client.wallet({
    spendingKey: bobKeys.spendingKey,
    account: privateKeyToAccount('0xbob...'),
  });

  console.log('Alice EB address:', bpkToAddress(alice.BPK));
  console.log('Bob EB address:', bpkToAddress(bob.BPK));

  await alice.USD.shield({ amount: 1000_000000n });
  console.log('Alice shielded 1000 USD');

  await alice.USD.transfer({ to: bob.BPK, amount: 300_000000n });
  console.log('Alice sent 300 USD to Bob');

  console.log('Alice USD:', await alice.USD.getBalance());
  console.log('Bob USD:', await bob.USD.getBalance());

  await bob.USD.unshield(100_000000n);
  console.log('Bob unshielded 100 USD');

  console.log('Bob encrypted:', await bob.USD.getBalance());
  console.log('Bob public:', await bob.USD.getPublicBalance());

  const stake = await alice.USD.stake(500_000000n);
  console.log('Alice staked 500 USD, stake ID:', stake.id);

  const freshKeys = keysFromMnemonic(aliceKeys.mnemonic, 1);
  await alice.USD.unstake([stake.id], freshKeys.BPK);
  console.log('Unstaked to fresh BPK');

  await client.destroy();
}

main().catch(console.error);

Registration (Optional)​

Register your BPK to enable:

  • Others to look up your BPK from your EVM address
  • Autoshield (auto-convert incoming ERC-20 to encrypted)
await wallet.USD.registerBPK();
await wallet.USD.setAutoshield(true);

Stealth Addresses​

Create privacy-preserving receive addresses:

const stealth = await wallet.USD.stealth.create({
  label: 'Invoice #123',
  autoStake: true,
});

console.log('Send USD to:', stealth.evmAddress);

const balances = await wallet.USD.stealth.getBalances();
for (const b of balances) {
  console.log(`${b.label}: ${b.balance}`);
}

Next Steps​