Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cloak.ag/llms.txt

Use this file to discover all available pages before exploring further.

​
Program identifier

  • zh1eLd6rSphLejbFfJEneUwzHRfMKxgzrgkfwA6qRkW

​
Instruction surface

  • 0: Transact (deposit, withdraw, shielded transfer)
  • 1: TransactSwap (swap flow entrypoint)
  • 2: Initialize (mint-scoped pool bootstrap)
  • 3: PrepareSwapSol
  • 4: ExecuteSwap
  • 5: CloseSwapState
  • 6: CollectTreasury
SDK consumers typically interact through Transact and TransactSwap.

​
Public input layout

Transact and TransactSwap both use a 264-byte public input blob:
  • root[32]
  • publicAmount[8] (i64, LE)
  • extDataHash[32]
  • mintAddress[32]
  • inputNullifiers[64] (2 x 32)
  • outputCommitments[64] (2 x 32)
  • chainNoteHash[32]
This matches the transaction circuit constraints.

​
Fees and amount semantics

  • FIXED_FEE_LAMPORTS = 5_000_000 (0.005 SOL floor)
  • Variable fee: amount * 3 / 1000 (0.3%)
  • MIN_DEPOSIT_LAMPORTS = 10_000_000 (0.01 SOL)
SOL withdrawal and swap math:
  • gross = abs(publicAmount)
  • fee = 5_000_000 + gross * 3 / 1000
  • net = gross - fee
The program enforces sufficient withdrawal amount so net > 0.

​
Merkle tree and nullifiers

  • Tree height: 32
  • Root history size: 100
  • Nullifier PDA seed model: ["nullifier", pool_pubkey, nullifier_hash]
Mint-scoped PDAs:
  • Pool: ["pool", mint]
  • Treasury: ["treasury", mint]
  • Merkle tree: ["merkle_tree", mint]

​
Execution model

​
Transact

  • Verifies 256-byte Groth16 proof against transaction verifier key.
  • Validates root exists in root history ring.
  • Creates nullifier PDAs for non-zero input nullifiers (double-spend protection).
  • Appends non-zero output commitments to Merkle tree.
  • Applies external transfer based on publicAmount:
    • positive: deposit from payer to pool
    • negative: withdrawal from pool to recipient + fee to treasury
    • zero: pure shield transfer (no external SOL movement)
  • Deposit path can require risk-oracle quote accounts when configured.

​
TransactSwap

  • Runs the same proof/nullifier/commitment checks as Transact.
  • Requires negative publicAmount (swap is a withdrawal path).
  • Creates SwapState for the follow-up settlement path.

​
Circuit assumptions the program relies on

  • Transaction circuit is fixed to 2 inputs / 2 outputs.
  • Tree depth is fixed to 32 levels.
  • Circuit enforces value conservation: sum(inputs) + publicAmount = sum(outputs).
  • Circuit includes chainNoteHash binding constraints for chain-note integrity.

​
Error mapping

For SDK-side mapping utilities, see ShieldPoolErrors in Error Handling.

​
Common failure modes

  • 0x1001 RootNotFound: proof used an old root no longer in ring history.
  • 0x1020/nullifier-already-used: input already spent (or reused test nullifier).
  • Invalid instruction data: wrong public input length (must be 264 bytes).