# 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](api-surface-tables), generated at the pinned monorepo commit.

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](api-surface-tables), generated at the pinned monorepo commit.

## Builder + session

-   [`PoolSessionBuilder`](/sdk/pool-session-builder): class. Methods: `fromConfig(config)` (static), `create(config)` (static one-call), `.withCircuitArtifacts(impl)`, `.withRelayerInteractor(impl)`, `.withKeystoreManager(impl)`, `.withStorageService(impl)`, `.create()`.
-   [`PoolSession`](/sdk/pool-session): 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](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](../concepts/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`](/sdk/pool-session) 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](/sdk/stealth); 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](/for-agents/api-surface-tables): `PPRouter`, `PPRouterFactory`, `PPYieldToken`, `PPYieldTokenFactory`, `PPYieldTokenZap`, `PPYieldTokenZapFactory`, `ERC5564Announcer`, `RelaySwaps`.