Skip to main content

​
Design Philosophy

The Umbra SDK is written in the same functional, dependency-injected style as Anza’s @solana/kit. Every capability is either a pure function or a factory that returns one. There are no classes with internal state, no singletons, and no implicit globals. Dependencies are explicit, injectable, and testable. This mirrors the architecture of @solana/kit itself — functions like getTransferSolInstruction and createSolanaRpc follow the same closure-based factory pattern you will find throughout the Umbra SDK.

​
The Factory Pattern

Every SDK operation follows the same two-step pattern: 
import { getATAIntoETADirectDepositorFunction } from "@umbra-privacy/sdk/deposit";

// 1. Build the function once, at setup time.
const deposit = getATAIntoETADirectDepositorFunction({ client });

// 2. Call it at runtime.
const result = await deposit(destinationAddress, mint, amount);
The factory call (get*Function) is cheap — it binds configuration and resolves defaults. The returned function is what does the actual async work: sending transactions, generating proofs, querying the indexer, polling the relayer. This is the same pattern @solana/kit uses for its instruction builders: 
// @solana/kit instruction builder
const ix = getTransferSolInstruction({ source, destination, amount });

// Umbra SDK factory function — same pattern, describing the data flow end-to-end.
const withdraw = getETAIntoATAWithdrawerFunction({ client });

​
Naming Conventions (V18)

Names are long, but they spell out the exact data flow.
  • Deposit family (@umbra-privacy/sdk/deposit)
    • getATAIntoETADirectDepositorFunction — ATA → ETA.
    • getATAIntoSelfBurnableStealthPoolNoteCreatorFunction — ATA → self-burnable Stealth Pool Note.
    • getATAIntoReceiverBurnableStealthPoolNoteCreatorFunction — ATA → receiver-burnable Stealth Pool Note.
    • getETAIntoSelfBurnableStealthPoolNoteCreatorFunction — ETA → self-burnable Stealth Pool Note (MPC).
    • getETAIntoReceiverBurnableStealthPoolNoteCreatorFunction — ETA → receiver-burnable Stealth Pool Note (MPC).
  • Withdrawal family (@umbra-privacy/sdk/withdrawal)
    • getETAIntoATAWithdrawerFunction — ETA → ATA.
  • Burn family (@umbra-privacy/sdk/burn)
    • getBurnableStealthPoolNoteScannerFunction — zero-arg scanner, cursor in client.utxoDataStore.
    • getReceiverBurnableStealthPoolNoteIntoETABurnerFunction — receiver-burnable → ETA.
    • getSelfBurnableStealthPoolNoteIntoETABurnerFunction — self-burnable → ETA.
    • getSelfBurnableStealthPoolNoteIntoATABurnerFunction — self-burnable → ATA.
    • (Receiver-burnable → ATA exists on-chain but is not yet shipped in the SDK.)
  • Registration (@umbra-privacy/sdk/registration) — getUserRegistrationFunction.
  • Query (@umbra-privacy/sdk/query) — getUserAccountQuerierFunction, getEncryptedBalanceQuerierFunction.
  • Conversion (@umbra-privacy/sdk/conversion) — getNetworkEncryptionToSharedEncryptionConverterFunction.
  • Compliance (@umbra-privacy/sdk/compliance) — grant issuer / revoker / re-encryptors / queriers.
  • Account (@umbra-privacy/sdk/account) — staged-token recoverers (getStagedSplRecovererFunction, getStagedSolRecovererFunction), key rotators, maintenance helpers.
You read each name as [verb] from [source] (into|to) [destination] or [verb] [object]. Factory names use the abbreviations ATA (AssociatedTokenAccount) and ETA (EncryptedTokenAccount) — e.g. getATAIntoETADirectDepositorFunction — so they stay short while remaining searchable and self-describing in code.

​
V18 vocabulary

  • Stealth Pool Note replaces V13’s “UTXO” in factory names and types. The wire protocol and on-chain instructions retain claim_* / utxo_* spellings for compatibility.
  • Burn replaces V13’s “claim” in factory names. The relayer endpoint is still /v1/claims, and the burner factory’s relayer dep takes { submitBurn, pollBurnStatus, getRelayerAddress } — submitBurn and pollBurnStatus are TypeScript aliases of submitClaim and pollClaimStatus, so the relayer client’s existing methods plug in unchanged under the renamed property names.

​
args and deps

Every factory accepts two arguments: 
const fn = getOperationFunction(args, deps?);
  • args — required. Always contains client: IUmbraClient and any fixed configuration for this operation (e.g. a specific mint).
  • deps — optional. Contains every infrastructure provider, key generator, ZK prover, and relayer adapter used internally. All deps fields have sensible defaults derived from the client. The only exceptions are ZK provers and the burner factory relayer adapter, which have no built-in defaults and must always be supplied explicitly.
// Using all defaults.
const deposit = getATAIntoETADirectDepositorFunction({ client });

// Overriding the transaction forwarder (e.g. Jito bundles).
const deposit = getATAIntoETADirectDepositorFunction(
  { client },
  { transactionForwarder: jitoForwarder },
);
Function-level deps override client-level deps. Client-level deps override built-in defaults.
The Advanced section covers dependency injection internals, key generators, ZK provers, transaction callbacks, and key rotation in depth. Most applications do not need those details to get started.