Types

Core Types

Point

Elliptic curve point on Grumpkin curve.

interface Point {
  x: bigint;
  y: bigint;
}

ElGamalCiphertext

Encrypted value using exponential ElGamal.

interface ElGamalCiphertext {
  R: Point;  // Randomness component (r·G)
  C: Point;  // Ciphertext component (m·G + r·BPK)
}

Recipient

Flexible recipient format for transfers.

type Recipient = Point | string;  // Point or zk1 address

// Usage:
await wallet.transfer({ to: { x: 123n, y: 456n }, amount: 100n });
await wallet.transfer({ to: 'zk1qyp5xs...', amount: 100n });

Client Configuration

EBClientConfig

interface EBClientConfig {
  /** Chain ID for multi-token mode (8453 = Base mainnet) */
  chainId?: number;
  
  /** Viem chain definition (default: Base mainnet) */
  chain?: Chain;
  
  /** RPC endpoint URL (auto-detected from chain) */
  rpcUrl?: string;
  
  /** Single contract address (legacy single-token mode) */
  contract?: `0x${string}`;
  
  /** Transfer circuit (default: /eb_transfer.json) */
  transferCircuit?: CircuitSource;
  
  /** Unshield circuit (default: /eb_unshield.json) */
  unshieldCircuit?: CircuitSource;
  
  /** Stake circuit (default: /eb_stake.json) */
  stakeCircuit?: CircuitSource;
  
  /** Unstake circuit (default: /eb_unstake.json) */
  unstakeCircuit?: CircuitSource;
  
  /** Enable L3 operations (stake/unstake) */
  enableL3?: boolean;
  
  /** Relayer URL for gasless operations */
  relayerUrl?: string;
  
  /** Initialization progress callback */
  onProgress?: (stage: string, progress?: number) => void;
  
  /** SDK log callback */
  onLog?: (level: 'info' | 'warn' | 'error', category: string, message: string, data?: unknown) => void;
  
  /** Prover threads (default: auto-detect, max 4) */
  threads?: number;
  
  /** Cache version for invalidation */
  cacheVersion?: number;
}

ConnectedWalletConfig

interface ConnectedWalletConfig {
  /** EB spending key (private) */
  spendingKey: bigint | string;
  
  /** Viem account for signing ETH transactions */
  account?: Account;
  
  /** Custom wallet client (for MetaMask, etc) */
  walletClient?: WalletClient;
}

Key Types

EBKeys

Full key set derived from spending key.

interface EBKeys {
  /** Master spending key */
  spendingKey: bigint;
  
  /** Balance Public Key (share to receive) */
  BPK: Point;
  
  /** Viewing key (for read-only access, optional) */
  viewingKey?: bigint;
}

StealthKeys

Derived stealth address keys.

interface StealthKeys {
  /** Derivation index */
  index: number;
  
  /** EVM private key (secp256k1) */
  evmPrivateKey: `0x${string}`;
  
  /** EVM address */
  evmAddress: `0x${string}`;
  
  /** EB spending key (Grumpkin scalar) */
  ebSpendingKey: bigint;
  
  /** EB Balance Public Key */
  ebBpk: Point;
}

Stealth Types

StealthAddress

Stealth address metadata (stored locally).

interface StealthAddress {
  /** Derivation index (0, 1, 2, ...) */
  index: number;
  
  /** Optional user-provided label */
  label?: string;
  
  /** EVM address for receiving */
  evmAddress: `0x${string}`;
  
  /** EB Balance Public Key */
  bpk: Point;
  
  /** Compressed BPK hash (storage key) */
  bpkHash: `0x${string}`;
  
  /** Whether to auto-stake incoming funds */
  autoStake: boolean;
  
  /** Registration status on-chain */
  registered: boolean;
  
  /** Timestamp of creation */
  createdAt: number;
  
  /** Transaction hash of registration */
  registrationTxHash?: `0x${string}`;
}

StealthBalance

Stealth address with balance info.

interface StealthBalance {
  index: number;
  label?: string;
  evmAddress: `0x${string}`;
  balance: bigint;
  autoStake: boolean;
}

CreateStealthOptions

Options for creating stealth addresses.

interface CreateStealthOptions {
  /** Optional label for the address */
  label?: string;
  
  /** Enable auto-stake to L3 (default: false) */
  autoStake?: boolean;
}

L3 Types

Stake

L3 stake commitment (stored locally).

interface Stake {
  /** Unique identifier */
  id: string;
  
  /** Contract address (for multi-currency filtering) */
  contractAddress: `0x${string}`;
  
  /** Staked amount */
  amount: bigint;
  
  /** Secret blinding factor */
  blinding: bigint;
  
  /** Position in Merkle tree */
  leafIndex: number;
  
  /** Merkle path for proof generation */
  path: StakePath;
  
  /** Stake root at time of creation */
  stakeRoot: bigint;
  
  /** Creation timestamp */
  createdAt: Date;
  
  /** Current status */
  status: 'active' | 'spent' | 'burned';
  
  /** Transaction hash */
  stakeTxHash?: `0x${string}`;
}

StakePath

Merkle tree path for stake proofs.

interface StakePath {
  siblings: bigint[];  // Tree siblings
  index: number;       // Leaf position
}

StakeOptions

Options for stake operation.

interface StakeOptions {
  /** Progress callback */
  onProgress?: (stage: string, progress: number) => void;
  
  /** Use relayer for gasless operation */
  useRelayer?: boolean;
}

UnstakeOptions

Options for unstake operation.

interface UnstakeOptions {
  /** Progress callback */
  onProgress?: (stage: string, progress: number) => void;
  
  /** Use relayer for gasless operation */
  useRelayer?: boolean;
}

StakeFilter

Filter for querying stakes.

interface StakeFilter {
  /** Filter by status */
  status?: 'active' | 'spent' | 'burned';
  
  /** Filter by contract (for multi-currency) */
  contractAddress?: `0x${string}`;
}

History Types

HistoryItem

Transaction history item with decrypted amounts.

interface HistoryItem {
  /** Transaction type */
  type: 'shield' | 'unshield' | 'transfer_in' | 'transfer_out' | 'swap_in' | 'swap_out' | 'stake' | 'unstake';
  
  /** Transaction hash */
  txHash: `0x${string}`;
  
  /** Block number */
  blockNumber: bigint;
  
  /** Timestamp (if available) */
  timestamp?: number;
  
  /** Amount (decrypted locally for private transfers) */
  amount?: bigint;
  
  /** Counterparty: zk1 address for transfers, EVM address for unshield */
  counterparty?: string;
  
  /** Token contract address */
  contract: `0x${string}`;
  
  /** Currency code (e.g., 'USD', 'EUR', 'PLN') */
  currency: string;
  
  /** Leaf index (for stake events) */
  leafIndex?: number;
}

Type meanings:

Type	Direction	Description
`shield`	in	Public → Encrypted
`unshield`	out	Encrypted → Public
`transfer_in`	in	Received private transfer
`transfer_out`	out	Sent private transfer
`swap_in`	in	Received via atomic swap
`swap_out`	out	Sent via atomic swap
`stake`	out	L2 → L3 stake
`unstake`	in	L3 → L2 unstake

HistoryOptions

Options for history queries.

interface HistoryOptions {
  /** Start block for event query (default: chain-specific deployment block) */
  fromBlock?: bigint;
  
  /** Maximum number of items to return (default: 50) */
  limit?: number;
  
  /** Force refresh, bypass cache (default: false) */
  refresh?: boolean;
}

Swap Types

SwapOffer

Swap offer from the registry.

interface SwapOffer {
  /** Unique offer ID */
  offerId: bigint;
  
  /** Maker's EVM address */
  maker: `0x${string}`;
  
  /** Maker's Balance Public Key */
  makerBPK: Point;
  
  /** Token maker is selling */
  tokenGive: `0x${string}`;
  
  /** Token maker is buying */
  tokenReceive: `0x${string}`;
  
  /** Exchange rate: tokenGive per tokenReceive (1e6 scale) */
  rate: bigint;
  
  /** Whether offer is active */
  active: boolean;
  
  /** Number of successful swaps */
  successfulSwaps: bigint;
}

CreateOfferParams

Parameters for creating a swap offer.

interface CreateOfferParams {
  /** Token maker is selling */
  tokenGive: `0x${string}`;
  
  /** Token maker is buying */
  tokenReceive: `0x${string}`;
  
  /** Exchange rate: tokenGive per tokenReceive (1e6 scale) */
  rate: bigint;
  
  /** Maker's Balance Public Key */
  makerBPK: Point;
}

AtomicSwapParams

Parameters for executing an atomic swap.

interface AtomicSwapParams {
  /** Offer ID */
  offerId: bigint;
  
  /** Amount taker gives (in tokenReceive) */
  takerGives: bigint;
  
  /** Amount taker receives (in tokenGive) */
  takerReceives: bigint;
  
  /** Taker's ZK proof */
  takerProof: `0x${string}`;
  
  /** Taker's public inputs */
  takerInputs: `0x${string}`[];
  
  /** Maker's ZK proof */
  makerProof: `0x${string}`;
  
  /** Maker's public inputs */
  makerInputs: `0x${string}`[];
}

SwapClientConfig

Configuration for SwapClient.

interface SwapClientConfig {
  /** Viem public client for reading */
  publicClient: PublicClient;
  
  /** Viem wallet client for writing (optional) */
  walletClient?: WalletClient;
  
  /** SwapRegistry contract address */
  swapRegistry: `0x${string}`;
  
  /** Prover for generating swap proofs (optional) */
  prover?: EBProver;
}

Proof Types

CircuitSource

Circuit can be JSON object or URL to fetch.

type CircuitSource = CompiledCircuit | string;

CompiledCircuit

Noir compiled circuit artifact.

interface CompiledCircuit {
  abi: any;
  bytecode: string;
}

ProofResult

Generated ZK proof.

interface ProofResult {
  /** Raw proof bytes */
  proof: Uint8Array;
  
  /** Proof bytes as hex string */
  proofHex: `0x${string}`;
  
  /** Public inputs */
  publicInputs: bigint[];
}

Relayer Types

RelayerConfig

Configuration for relayer client.

interface RelayerConfig {
  /** Base URL of relayer service */
  baseUrl: string;
}

Address Encoding

ParsedAddress

Parsed zk1 address.

interface ParsedAddress {
  /** Address type (1 = BPK) */
  version: number;
  
  /** The BPK encoded in the address */
  bpk: Point;
  
  /** Original address string */
  original: string;
}

Currency Tokens

Contract Addresses (Base Mainnet)

const CURRENCY_TOKENS = {
  8453: {
    rpcUrl: 'https://mainnet.base.org',
    tokens: {
      ebUSD: '0x9f6d30758b85bd2f4b6107550756162e04ce1650',
      ebEUR: '0x06f9706c8defcebd9cafe7c49444fc768e89d7a7',
      ebPLN: '0xbdcdbe9a1ee3ce45b6eea8ec4d7cb07cd8444720',
    },
    swapRegistry: '0x667d6c4d1e69399a8b881b474100dccf73ce42a0',
  },
};

Core Types​

Point​

ElGamalCiphertext​

Recipient​

Client Configuration​

EBClientConfig​

ConnectedWalletConfig​

Key Types​

EBKeys​

StealthKeys​

Stealth Types​

StealthAddress​

StealthBalance​

CreateStealthOptions​

L3 Types​

Stake​

StakePath​

StakeOptions​

UnstakeOptions​

StakeFilter​

History Types​

HistoryItem​

HistoryOptions​

Swap Types​

SwapOffer​

CreateOfferParams​

AtomicSwapParams​

SwapClientConfig​

Proof Types​

CircuitSource​

CompiledCircuit​

ProofResult​

Relayer Types​

RelayerConfig​

Address Encoding​

ParsedAddress​

Currency Tokens​

Contract Addresses (Base Mainnet)​