SDK Guide

Get started with @zerc20/client-sdk to send private zERC20 transfers from your TypeScript application.

Prerequisites

Requirement	Details
Node.js	>= 18
EVM Wallet	Any wallet that can sign messages (e.g., MetaMask, Rabby)
Supported Chain	Ethereum, Arbitrum, Base, BNB Chain, Polygon, Kaia, and their configured testnets

Installation

npm install @zerc20/client-sdk

Initialize the SDK

Call createSdk() to obtain a Zerc20Sdk instance. All options are optional and fall back to sensible defaults.

import { createSdk } from "@zerc20/client-sdk";

const sdk = createSdk();

Zerc20SdkOptions accepts the following optional fields:

Field	Type	Description
wasm	WasmRuntime	Custom WASM runtime (auto-detected if omitted)
teleportProofs	TeleportProofClient	Custom teleport proof client or proof client options
decider	HttpDeciderClient	Decider prover endpoint
stealth	StealthClientFactory	Custom stealth client factory

The returned Zerc20Sdk exposes the same fields for direct access:

interface Zerc20Sdk {
  wasm: WasmRuntime;
  teleportProofs: TeleportProofClient;
  decider?: HttpDeciderClient;
  stealth: StealthClientFactory;
}

Connect to ICP

Create a StealthCanisterClient to interact with the ICP storage and key-manager canisters:

import { HttpAgent } from "@dfinity/agent";

const agent = await HttpAgent.create({ host: "https://icp-api.io" });

const stealthClient = sdk.createStealthClient({
  agent,
  storageCanisterId: "your-storage-canister-id",
  keyManagerCanisterId: "your-key-manager-canister-id",
});

The agent, storageCanisterId, and keyManagerCanisterId fields are required. If any are missing (and no factory defaults have been set), createStealthClient() will throw an error.

sdk.createStealthClient(config?: Partial<StealthClientConfig>): StealthCanisterClient

EVM Providers

The SDK uses library-agnostic provider interfaces instead of depending directly on viem. This means you can use viem, ethers.js, or any other EVM library:

Interface	Purpose	viem Equivalent
EvmReadProvider	Contract reads, balance queries, fee estimation	PublicClient
EvmWriteProvider	Signing and submitting transactions	WalletClient

viem's PublicClient and WalletClient satisfy these interfaces structurally -- no adapter is needed. For other libraries, provide a thin adapter that implements the required methods.

import type { EvmReadProvider, EvmWriteProvider } from "@zerc20/client-sdk";
import { createPublicClient, createWalletClient, custom, http } from "viem";
import { arbitrum } from "viem/chains";

// These work as EvmReadProvider / EvmWriteProvider directly
const readProvider = createPublicClient({ chain: arbitrum, transport: http() });
const writeProvider = createWalletClient({ chain: arbitrum, transport: custom(window.ethereum!) });

Load Tokens

The SDK provides several ways to load token configuration:

Option A: From compressed data with TokensCacheManager

TokensCacheManager.load(compressed) accepts a Base64-encoded gzip string containing token configuration JSON. This is the format used by the production frontend.

import { TokensCacheManager, findTokenByChain } from "@zerc20/client-sdk";

// `compressed` is a Base64-encoded gzip string of your tokens.json
const cache = new TokensCacheManager();
const { hub, tokens } = await cache.load(compressedTokensString, {
  cacheKey: "zusdc-main",
});

Option B: From raw JSON with normalizeTokens

If you have a tokens.json file (e.g., from your own deployment), use normalizeTokens():

import { normalizeTokens, findTokenByChain } from "@zerc20/client-sdk";

const tokensFile = await import("./tokens.json");
const { hub, tokens } = normalizeTokens(tokensFile);
// hub?: HubEntry           -- Hub contract metadata, undefined for local-only tokens
// tokens: TokenEntry[]     -- per-chain token entries

Local-only tokens, such as zJPYC, intentionally omit hub. Their private receive flow uses local Verifier roots instead of the cross-chain Hub aggregation root.

Option C: With RPC URL overrides

Use normalizeTokensWithOverrides() to replace default RPC URLs at runtime:

import { normalizeTokensWithOverrides, findTokenByChain } from "@zerc20/client-sdk";

const tokensFile = await import("./tokens.json");
const { hub, tokens } = normalizeTokensWithOverrides(tokensFile, {
  tokens: {
    "Arbitrum One": ["https://my-rpc.example.com/arb"],
    "Ethereum": ["https://my-rpc.example.com/eth"],
    "Kairos": ["https://public-en-kairos.node.kaia.io"],
  },
  hub: ["https://my-rpc.example.com/base"],
});

Finding tokens

// Pick the token entry for Arbitrum (chain ID 42161)
const entry = findTokenByChain(tokens, 42161n);
// entry.tokenAddress, entry.liquidityManagerAddress, etc.

See Token Registry for the full token API.

Type signatures

function normalizeTokens(file: TokensFile): NormalizedTokens;
function normalizeTokensWithOverrides(file: TokensFile, overrides?: RpcOverrides): NormalizedTokens;

interface NormalizedTokens {
  hub?: HubEntry;
  tokens: TokenEntry[];
  raw: TokensFile;
}

function findTokenByChain(
  tokens: readonly TokenEntry[],
  chainId: bigint,
): TokenEntry;

First Private Send

Below is a compact end-to-end example. Each helper is covered in detail on the Private Send page.

import {
  createSdk,
  normalizeTokens,
  findTokenByChain,
  deriveSeed,
  preparePrivateSend,
  submitPrivateSendAnnouncement,
  submitPrivateSendTransfer,
} from "@zerc20/client-sdk";
import { createPublicClient, createWalletClient, custom, http } from "viem";
import { arbitrum } from "viem/chains";
import { HttpAgent } from "@dfinity/agent";

// 1. Initialize
const sdk = createSdk();
const agent = await HttpAgent.create({ host: "https://icp-api.io" });
const client = sdk.createStealthClient({
  agent,
  storageCanisterId: "your-storage-canister-id",
  keyManagerCanisterId: "your-key-manager-canister-id",
});
const tokensFile = await import("./tokens.json");
const { tokens } = normalizeTokens(tokensFile);
const entry = findTokenByChain(tokens, 42161n);   // Arbitrum

// 2. Create providers
const readProvider = createPublicClient({ chain: arbitrum, transport: http(entry.rpcUrls[0]) });
const writeProvider = createWalletClient({ chain: arbitrum, transport: custom(window.ethereum!) });

// 3. Derive seed from the wallet signature (canonicalized + hashed to 32 bytes)
const seedHex = await deriveSeed((message) =>
  writeProvider.signMessage({ message }),
);

// 4. Prepare the private send
const preparation = await preparePrivateSend({
  client,
  recipientAddress: "0xRecipient...",
  recipientChainId: 42161n,
  seedHex,
});

// 5. Transfer zERC20 to the burn address
const { transactionHash } = await submitPrivateSendTransfer({
  writeProvider,
  readProvider,
  tokenAddress: entry.tokenAddress,
  burnAddress: preparation.burnAddress,
  amount: 100_000_000n,  // 100 zUSDC (6 decimals)
});

// 6. Submit the encrypted announcement
const result = await submitPrivateSendAnnouncement({
  client,
  preparation,
});
console.log("Announcement submitted:", result);

Next Steps

• Private Send -- detailed walkthrough of each step
• Receiving -- scanning and claiming incoming transfers
• API Reference -- relay-node helpers for gasless redeem and native-gas swaps
• Token Registry -- loading and querying token configuration
• Integration Guide -- on-chain oracle and self-hosted indexer
• Contract Addresses -- deployed addresses per chain