Skip to main content

API surface index

A partial overview of the SDK's public API, handy for orientation but not a complete or authoritative listing. For the complete compiler-derived surface (all 600 SDK exports, full contract ABI tables with selectors, including inherited members), see API Surface Tables, generated at the pinned monorepo commit.

Builder + session​

  • PoolSessionBuilder: class. Methods: fromConfig(config) (static), create(config) (static one-call), .withCircuitArtifacts(impl), .withRelayerInteractor(impl), .withKeystoreManager(impl), .withStorageService(impl), .create().
  • PoolSession: class. Methods: deposit, discoverNotes, exportAccount, prepareTransfer, relayTransfer, executeTransfer, prepareWithdraw, relayWithdraw, rageQuit, registerKeystore, rotateRevocableKey, isKeystoreRegistered, importReceivedNote, generatePaymentRequest, prepareFulfillPaymentRequest.

The session facade delegates to per-domain sub-session classes. Of these, only PoolSessionDeposit, PoolSessionTransfer, PoolSessionWithdraw, PoolSessionNoteManager, and PoolSessionFactory are runtime exports; the others below are reachable as types only:

  • PoolSessionRagequit: forced exit. Methods: prepareRageQuit(params), executeRageQuit(result), rageQuit(params) (one-call). Requires the note's noteSecret, so ragequit cannot recover a note whose secret is lost.
  • PoolSessionExport: account portability. Methods: exportAccount() (full NoteManager state plus owner/chainId/paymentRequests, keys excluded), importAccount(data), importReceivedNote(note) (recomputes the commitment from imported fields and throws InvalidNoteError on mismatch before storing).
  • PoolSessionKeystore: registration and key rotation. Methods: isKeystoreRegistered(), prepareRegisterKeystore(options?), executeRegisterKeystore(result), registerKeystore(options?), getRevocableKeyIndex(), discoverRevocableKeyIndex(config, gapLimit?), prepareRotateRevocableKey(config), executeRotateRevocableKey(result), rotateRevocableKey(config).
  • PoolSessionNoteDiscovery: read side. Methods: discoverNotes(params?), purgePhantomNotes(params?).
  • Also exported: PoolSessionDeposit, PoolSessionTransfer, PoolSessionWithdraw, PoolSessionNoteManager, PoolSessionFactory (full member tables in API Surface Tables).

Services (constructable)​

  • PoseidonHashService: PoseidonHashService.create() returns an instance with hash(inputs).
  • CryptoService: new CryptoService().
  • NoteComputationService: wraps Poseidon and Crypto for note math.
  • WitnessPreparationService: internal but exported.
  • ProofService: Groth16 prover wrapper. Takes a Groth16Prover and circuit artifacts.
  • Groth16Prover: snarkjs adapter.

Interactors (typically built by the builder)​

  • ViemRPCInteractor: JSON-RPC.
  • PoolVaultInteractor: typed wrapper over PoolVault.
  • EntrypointInteractor: typed wrapper over Entrypoint.
  • KeystoreInteractor: typed wrapper over Keystore.
  • ASPRegistryInteractor: typed wrapper over ASPRegistry.
  • RelayerInteractor: HTTP relayer client. Methods: getRelayers, getTransferQuote, getWithdrawalQuote, relayTransfer, relayWithdrawal.
  • HTTPClient: internal but exported.

Data providers​

  • HttpASPDataProvider: fetches ASP data over HTTP. Used by default when aspUrl is set.
  • IpfsASPDataProvider: fetches ASP data from IPFS.

Circuit artifact loaders​

  • LocalCircuitArtifacts: Node, filesystem-backed.
  • FetchCircuitArtifacts: browser, HTTP-backed (the sample-app variant at apps/sample-web/src/FetchCircuitArtifacts.ts, not exported by the SDK).
  • IpfsCircuitArtifacts: IPFS-CID-backed.

Utilities​

  • cryptoService.deriveKeysFromSignature({ signature, signerAddress, addressHash, revocableKeyIndex }): canonical HKDF derivation. Returns the four-key bundle.
  • buildSecretDerivationPayload(signerAddress): EIP-712 payload helper. Not exported by @privacy-pools-v2/sdk (by design: the SDK ships no app-specific EIP-712 payload builder, though CryptoService does expose key derivation helpers such as deriveKeysFromSignature and derivePaymentRequestKeyPair). Reference implementation lives at v2-monorepo/apps/sample/src/keystore/secretDerivationPayload.ts. Integrators copy it or roll their own payload. See Keys.
  • utils.encodeASPCipherText / utils.decodeASPCipherText: the only members of the utils export (see packages/sdk/src/external.ts).
  • resolveCommitmentTimestamp(interactor, commitment, opts): bounded-retry timestamp lookup. Internal-only; not exported from the package entrypoint.
  • NotePayload codec (encode/decode functions for the on-chain encrypted blob).

Types & enums​

Full list at packages/sdk/src/types/. Most-used:

  • Note, PendingNote, NoteStatus enum.
  • TransferParams, PrepareTransferResult, ExecuteTransferParams, RelayTransferParams, TransferResult.
  • RecipientDiscoveryData (discriminated union).
  • ProtocolKeys, DeploymentAddresses, RelayerInfo.
  • Hex, Address, Secret, PublicKey (type aliases).

Errors​

Per-service hierarchy. The source-level base classes (branch on error.name in published-package code, since most aren't exported as runtime values):

  • HTTPClientBaseError: subclasses HTTPRequestFailed, HTTPResponseError.
  • RelayerInteractorBaseError: subclasses InvalidRelayerConfig, RelayerRequestFailed, RelayerRejected, FeeCommitmentExpired.
  • NoteManagerBaseError: subclasses NoteNotFoundError, InvalidStatusTransitionError, NoteConflictError.
  • PoolSessionBuilderBaseError: subclasses InvalidBuilderConfig, UnsupportedChainId.
  • ProofServiceBaseError: subclasses ProofGenerationFailed, CircuitArtifactLoadFailed.
  • ContractInteractorBaseError: subclasses ContractCallError, InvalidInteractorAddress, InvalidAddressArgument, InvalidHashArgument, InvalidContractResult.
  • RecipientViewingKeyUnregistered: at the transfer level.

Yield, batch, swaps, stealth (added at pin d3bdb174)​

  • PoolSession gained yield / yields / yieldFor(token), the batch trio (prepareBatchWithdraw, relayBatchWithdraw, selfSubmitBatchWithdraw + prepare/execute halves), swap (prepareSwapQuote, relayWithdrawAndSwap), reshield (estimateReshieldAmount, prepareReshieldQuote, relayReshield, and the ...Crosschain trio), and swap-deposit (prepareSwapAndDeposit, executeSwapAndDeposit, swapAndDeposit).
  • PoolSessionBuilder gained withYieldDeployment(s), withDestinationYieldDepositTargets, withSwapQuoteProvider, withSwapAndDepositQuoteProvider.
  • RelayerInteractor gained relayWithAnnounce(relayer, params).
  • LiFiSwapQuoteProvider: runtime class implementing ISwapQuoteProvider and ISwapAndDepositQuoteProvider.
  • Yield sessions (type-only, reached via yieldFor): IPoolSessionYieldDeposit (sharesForUnderlying, sizeSharesForBudget, prepareYieldDeposit), IPoolSessionYieldWithdraw (prepareYieldWithdraw, prepareYieldWithdrawRelay); interactors PPYieldTokenInteractor, PPYieldTokenZapInteractor.
  • Runtime constants: MAX_BATCH, DEPOSIT_RATE_HEADROOM_PPM, CROSS_CHAIN_DEPOSIT_RATE_HEADROOM_PPM, WITHDRAW_SLIPPAGE_BPS, ZAP_SUPPLY_BUFFER_UNITS, YIELD_DEPLOYMENTS (empty), LOCAL_FORK_YIELD_DEPLOYMENT, PP_RELAY_BATCH_ABI; helpers getYieldDeployment, isYieldToken, computeBatchFees, computeBatchItemFee.
  • Subpaths: @privacy-pools-v2/sdk/batch-fee (computeBatchFees, computeBatchItemFee, MAX_BATCH) and @privacy-pools-v2/sdk/stealth (the whole stealth module; none of it is on the main barrel).
  • Errors: YieldSessionBaseError (InvalidYieldAmount, UnexpectedDepositCalldata, UnexpectedWithdrawCalldata, InvalidYieldAddress, DuplicateYieldDeployment); BatchWithdrawBaseError (EmptyBatchSelection, BatchTooLarge, AssetNotRelayable, InfeasibleBatchFee, BatchRoutingMismatch, BatchRoutingInvalid); SwapQuoteProviderBaseError (SwapQuoteFailed, SwapStatusFailed, UnallowedLiFiAddress, RelaySwapsLayoutMismatch, LiFiDepositCalldataNotFound, LiFiDepositTargetNotFound, LiFiRecipientNotFound); PoolSessionSwapDepositBaseError (InvalidSwapAndDepositParams, SwapAndDepositQuoteFailed); on the stealth subpath, StealthAddressError and five subclasses (runtime values there).
  • Contracts added to the generated ABI tables: PPRouter, PPRouterFactory, PPYieldToken, PPYieldTokenFactory, PPYieldTokenZap, PPYieldTokenZapFactory, ERC5564Announcer, RelaySwaps.