This page tracks the current public exports of @cloak.dev/sdk.
UTXO API
The UTXO free functions are the primary entrypoint. There is no client class to construct.
transact is the single engine entrypoint and the sign of externalAmount classifies the
flow: positive shields (deposit), negative withdraws, zero is a shielded transfer.
transfer, partialWithdraw and fullWithdraw are shaped wrappers over it.
Every one of these takes a TransactOptions object. connection, programId and relayUrl
are required on all flows; supply either depositorKeypair (programmatic) or the wallet
callbacks signTransaction / signMessage plus walletPublicKey (browser). relayUrl has
no default and is not read from the environment, so pass it explicitly on every call. Every flow
except a deposit needs an authenticated sender and throws before proof generation without one:
see Request authentication.
UTXO primitives:
selectUtxos needs two checks at every call site, not one. It returns null instead of throwing
when the available notes do not cover the target, so a truthy check is the whole insufficient-balance
path. And it knows nothing about the circuit’s two-input cap: it will happily return three notes for
a large target, and transact then throws Maximum 2 input UTXOs allowed before proving. Check the
length as well as the null. partialWithdraw and fullWithdraw consolidate down to two inputs for
you; transfer does not, so cap the selection yourself.
That consolidation is not free, and it is worth budgeting for. partialWithdraw merges the two
smallest notes at a time, so n inputs cost n - 2 shielded transactions before the withdrawal
itself, each one separately proved, signed and submitted. fullWithdraw delegates to it and behaves
the same. In a browser that is n - 2 extra wallet approvals, and options.onProgress is the only
thing that reports them: it fires Consolidating notes (n remaining)... on each round. Each merge
also creates a fresh intermediate note that the SDK never hands back, and its blinding is fresh
randomness held only in that process, so a run that dies between a merge and the final withdrawal
strands that note on-chain permanently, exactly as the change-note warning below describes. Prefer
two inputs where you can, and treat a many-input withdrawal as a long resumable operation rather
than a single call.
serializeUtxo / deserializeUtxo are a fixed 128-byte encoding of one note: amount, private key,
blinding, mint and leaf index. That is the full spending secret in a byte array, so treat the output
as key material and encrypt it at rest. deserializeUtxo is async because it re-derives the public
key and recomputes commitment. One edge to know: a note at leaf index 0 comes back with index
undefined, because the encoding cannot tell index 0 from unset.
Note storage and key material. The SDK persists nothing on its own; these are the pieces you build a
store out of, and the full pattern is
Where your notes live between sessions.
UtxoWallet is the live note set:
Utxo objects per mint, spent flags, balance, stats and input selection. It does not persist
itself. serialize() and the static UtxoWallet.deserialize(json) give you a JSON string that
handles the bigint fields; where that string goes is your choice. It drops commitment, so
recompute with computeUtxoCommitment after restoring, or verifyUtxos reports every restored
note as skipped rather than spent or unspent.LocalStorageAdapter implements
StorageAdapter over browser localStorage, holding CloakNote records and wallet keys under the
keys cloak_notes and cloak_wallet_keys by default.MemoryStorageAdapter is the same
interface held in process. It persists nothing and loses everything on reload: use it for tests, or
when storage lives entirely on your side.importWalletKeys / exportWalletKeys move a CloakKeyPair in and out of a JSON string.expandSpendKey derives (ask, nsk, ovk) from a spend key; getNkFromUtxoPrivateKey returns the
32-byte nk for a note’s private key. nk is the incoming viewing base: it is what decrypts chain
notes and what the recovery helpers below scan with.
The two halves do not connect. UtxoWallet does not take a StorageAdapter, and a StorageAdapter
does not store Utxo objects. The note set is the half that decides solvency.
Do not build sends with UtxoWallet.prepareSend or with SimpleWallet, even though both are
exported. prepareSend derives the recipient output from a freshly generated random keypair rather
than from the recipient’s key, so the note it produces is unspendable by the recipient and by you.
SimpleWallet.sync() throws Sync not yet implemented. Use transfer, which builds the recipient
output from the Cloak pubkey you pass it. The rest of UtxoWallet is sound: addUtxo, markSpent,
getBalance, getUnspentUtxos, getStats, selectInputs, serialize and deserialize.
Result types
Every UTXO flow resolves to a TransactResult:
swapUtxo and swapWithChange both resolve to a UtxoSwapResult, which extends it:
Persist refund. It is the recovery secret for reclaiming the input if the swap times out
before its second transaction lands.
Recovery helpers
Two exports let a wallet rebuild notes from key material alone, with no local note store.
createRecoverableDepositUtxo builds a deposit output whose keypair and blinding are derived from
(nk, noteSalt) instead of raw randomness, which is what makes a later cold scan able to rebuild it.
It resolves to { utxo, noteSalt }, and the same salt must reach transact as
options.chainNoteSalt alongside options.chainNoteViewingKeyNk. A salt that never reaches the
chain note leaves the deposit exactly as undiscoverable as before.
discoverSwapRefunds walks program history for swap timeout-refund leaves that belong to the holder
of viewingKeyNk and returns each in spendable form. It is forward-looking only: it finds refunds
whose keys were derived from nk, so a swap built without an nk has no derivation to replay and no
key-only scan can recover it. An empty result is not proof that a wallet has no stranded refund.
Change notes are outside both helpers. createUtxo draws each change note’s blinding from fresh
randomness and publishes it nowhere, so a change note whose secrets you lost is unspendable by
anyone, permanently. Persist result.outputUtxos before you report success:
where your notes live between sessions. Proof and Merkle utilities
Notes:
- UTXO transact/swap flows submit 256-byte proofs and 264-byte public inputs.
Fee constants
Fees are enforced on-chain from each pool’s PoolConfig; transact reads the live config before
building a fee-bearing proof. These constants mirror the deployed SOL-pool defaults for display
math. SPL pools (USDC/USDT) charge 450_000 base units fixed (0.45) + 0.3%; see
Fee Model.
These values cover the native SOL pool. SPL pools (USDC and USDT) charge a fixed 0.45 token,
450,000 raw units at 6 decimals, plus the same 0.3 percent variable fee. The program reads the
effective values from the pool_config PDA; the SDK does not compute SPL fees.
Advanced TransactOptions
Five options a standard integration never sets, listed because nothing else documents them.
expectedMint — every flow takes the pool from the notes it is handed, so the SDK cannot
otherwise tell a deliberate USDC withdrawal from a SOL withdrawal that was handed a USDC note by
mistake. Both are well-formed and both settle. Set expectedMint and the SDK refuses the
transaction when the input notes disagree. Optional for backward compatibility — pass it on every
flow you can.
relaySupplementalAlt — when true and relayUrl is set, an SPL deposit that needs a
supplemental address lookup table asks for a shared table to be extended instead of creating a
depositor-signed throwaway one, so the user signs exactly once instead of twice. Any failure
falls back to the depositor-signed ephemeral-ALT path automatically. Off by default, which preserves
the old behaviour exactly.
transactionVersion — 0 (default) builds a v0 message with ComputeBudget instructions. 1
builds a Transaction V1 message (SIMD-0385): 4,096-byte packet, every account static with no lookup
tables, compute budget in the message header. It needs the cluster’s v1 gate active and a signer
that signs v1 messages — a local key pair does; a browser wallet may not yet.
externalFeePayer — lets a deposit come from a wallet holding no SOL: the adapter’s payer covers
the network fee and on-chain rent and is reimbursed in an SPL token inside the same transaction.
relayAuthBatch — the handle transactBatch passes to each item so the row is authenticated by
the batch’s single signature. It takes precedence over depositorKeypair and relayAuthSigner.
Set it yourself only if you drive the coordinator directly.
Request authentication and endpoint pinning
Private sends, withdrawals and swaps carry a signed sender. Standard integrations only pass
signMessage + walletPublicKey (browser) or depositorKeypair (server) in TransactOptions and
never touch these; they exist for callers driving submission themselves.
maxWalletApprovals on TransactOptions caps wallet dialogs for one swap (default 5). Sends and
withdrawals sign exactly once. Full contract: Request authentication.
Error utilities
Detailed usage: Error Handling
Versioned exports
VERSION tracked the package version incorrectly before 0.2.5 and is now in step with it. It is
still informational — to confirm which version you are on, check the published package with
npm view @cloak.dev/sdk version or npm ls @cloak.dev/sdk.
Batch signing
transactBatch runs N private spends behind one wallet approval. Each item is proved
concurrently so every proof exists before the wallet is asked, then all items are submitted under a
single batch signature.
results has one entry per item in input order, and a rejected item leaves the others unaffected.
approvals counts the wallet dialogs actually raised: 1 for the batch, plus 1 per wave of
stale-root re-proves.
The call requires relayUrl and an authenticated sender — depositorKeypair, or walletPublicKey
with signMessage, or signer. Both are checked before any proof is computed, so a batch that
cannot be authenticated fails without doing work.
transactBatch does not plan the rows. Two items that spend the same note collide on their
nullifier, and an item that spends another item’s change cannot be proved until that change has
landed. Give each item its own already-landed input notes; selecting them is the caller’s job.
Above RELAY_BATCH_AUTH_MAX_ITEMS the call throws — chunk the payout. The practical bound is
lower than 64, because the chain keeps a ring of 100 recent roots and each item consumes room in
it.
Solana Kit runtime
Since 0.2.5 the SDK is built on @solana/kit. These are the helpers a normal integration touches.
connection takes a CloakRpc, programId and other addresses take Kit Address strings, and
depositorKeypair takes a KeyPairSigner. Wiring a browser wallet is covered in Solana Kit
integration.
Protocol and service docs
