Skip to main content

​
Canonical transaction path

The active runtime path is UTXO transactions through:
  • transact for deposit/withdraw/transfer
  • swapWithChange / swapUtxo for swap flows
  • Relay endpoints /transact and /transact_swap
Legacy note-model methods still exist, but protocol docs and web flows are UTXO-first.

​
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 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/web enforce viewing-key registration by default before protocol transactions.
  • Registration uses POST /viewing-key/register with:
    • wallet pubkey
    • 32-byte viewing key (nk)
    • signature over fixed sign-in message
  • Registration is cached in-process to avoid repeat calls.

​
Chain-native scanner and cache model

  • scanTransactions reads chain transactions directly from RPC (no relay dependency).
  • It decrypts compact chain notes with viewing key nk and verifies chainNoteHash integrity.
  • It computes per-tx gross, fee, netAmount, and running balance.
  • Web stores report snapshots in encrypted local storage and exposes explicit cache clear + rescan.