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.

​
Canonical transaction path

The active runtime path is UTXO transactions through:
  • transact for deposit/withdraw/transfer
  • swapWithChange / swapUtxo for swap flows
  • SDK-managed submit and status lifecycle
Note-model and UTXO-model methods are both part of v1, with UTXO-first integrations recommended for most apps.

​
Commitments and Merkle tree

Each deposit/output creates a Poseidon commitment and appends it to the on-chain Merkle tree.
  • Height: 32
  • Root history: 100 recent roots
Proof generation needs:
  • Leaf index
  • Path elements/indices
  • A root still present in root history

​
Nullifiers

Spending creates a nullifier. The program rejects a reused nullifier. This is the core double-spend guard for both note and UTXO flows.

​
Stale-root retries

If your proof root is no longer in history, transactions can fail with RootNotFound (0x1001). The SDK includes retry paths that:
  • fetch fresh Merkle data
  • regenerate proof
  • resubmit

​
Fee model: gross, fee, net

Shared constants:
  • Fixed fee: 5_000_000 lamports
  • Variable fee: amount * 3 / 1000
  • Minimum deposit: 10_000_000 lamports
For SOL withdrawals/swaps:
  • gross = absolute public withdrawal amount
  • fee = fixed + variable
  • net = gross - fee

​
Proof data shapes

  • UTXO transact and swap requests use 264-byte public inputs: root + publicAmount + extDataHash + mint + nullifiers + commitments + chainNoteHash.
  • Proof bytes are always 256 bytes (Groth16).

​
Viewing key registration

  • SDK flows enforce viewing-key registration by default before protocol transactions.
  • Registration is a signed wallet challenge bound to a 32-byte viewing key (nk).
  • Registration is cached in-process to avoid repeat calls.

​
Chain-native scanner and cache model

  • scanTransactions reads chain transactions directly from RPC.
  • It decrypts compact chain notes with viewing key nk and verifies chainNoteHash integrity.
  • It computes per-tx gross, fee, netAmount, and running balance.
  • Client apps can store encrypted report snapshots locally and expose explicit cache clear + rescan.