Privacy / Shielded Vaults

Zero-knowledge shielded deposits that break the on-chain link between depositor and withdrawer using Groth16 BN254 proofs verified on StarkNet via Garaga.

Overview

Sable’s privacy layer allows users to deposit into yield vaults without revealing their identity on-chain. Withdrawals can be made to any address with no traceable connection to the original deposit.

Deposit Address A  ──┐
                     ├──► Shielded Pool ──► Withdraw to Address B
Deposit Address C  ──┘        (ZK proof)      (no on-chain link)

Pool Types

Tab	Pool Type	Token	Description
Lending	Sentinel Vault	WBTC	Private deposits into Sable Sentinel (lending yield)
Yield	Delta Neutral Vault	WBTC	Private deposits into Sable Delta Neutral (spread yield)
Stables	Stablecoin Vault	USDC	Private USDC deposits into Vesu RE7 USDC Core
Swap	Swap Pool	WBTC→ETH/USDC/STRK	Private token swaps via pool-to-pool transfers

How Shielded Deposits Work

Deposit Flow

Generate Note Locally

User generates a random note in the browser:

const note = {
  secret:    randomBytes(31),
  nullifier: randomBytes(31),
  commitment: Poseidon(secret, nullifier)
}

The note is saved to browser localStorage. Losing the note = losing your funds permanently.

Submit Deposit

User approves WBTC and submits deposit transaction:

WBTC.approve(pool_address, denomination)
pool.deposit(commitment)

Fixed denominations ensure uniform anonymity sets:

Sentinel: 0.0002, 0.0004, 0.0006, 0.0008 BTC
Delta Neutral: 0.00036, 0.00072, 0.00108, 0.00144 BTC
Stablecoin: 10, 25, 50, 100 USDC

Batch Processing

Relayer batches 3 deposits together:

pool.process_batch([
  commitment_1,
  commitment_2,
  commitment_3
])

All 3 commitments are inserted into the Merkle tree.

Batching improves anonymity — withdrawals cannot be linked to specific deposits within a batch.

Note Saved

Note is saved to browser localStorage with:

Commitment
Nullifier
Secret
Leaf index (after batch confirmation)
Merkle path

Withdrawal Flow

Generate ZK Proof

User generates a Groth16 proof locally in the browser:

const proof = await generateProof({
  // Private inputs (not revealed on-chain)
  secret,
  nullifier,
  pathElements,
  pathIndices,
  
  // Public inputs (verified on-chain)
  root,
  nullifierHash,
  recipient,
  relayer,
  fee,
  batchStart,
  batchSize
})

Proof generation takes ~5-10 seconds in browser.

Submit to Relayer

Proof is submitted to the relayer API:

POST /api/relayer/withdraw
{
  "proof": "0x...",
  "publicInputs": [...],
  "recipient": "0x...",
  "fee": "0.0001"
}

On-Chain Verification

Relayer calls the pool contract:

pool.withdraw(
  proof,
  root,
  nullifierHash,
  recipient,
  relayer,
  fee
)

Garaga verifier contract validates the Groth16 proof on-chain.

Receive Funds

On successful verification:

Nullifier hash is recorded (prevents double-spend)
Funds sent to recipient address
Relayer fee deducted

Recipient has no on-chain link to the original depositor.

Merkle Tree Structure

                     ROOT
                    /    \
                   /      \
               H(0,1)    H(2,3)
               /    \    /    \
             L0    L1  L2    L3     ◄── Leaf = Poseidon(commitment)
             │     │   │     │
           Note0 Note1 Note2 Note3

Tree Parameters

Depth: 20 levels (supports ~1M deposits)
Hash function: Poseidon (StarkNet-native, efficient in-circuit)
Batch size: 3 deposits per batch
Proof size: ~1KB (Groth16 BN254)

Fixed Denomination Pools

Sentinel (Lending)

Pool Key	Denomination	Contract Address
`sentinel_1x`	0.0002 BTC	`0x002bdb9769851d0307e812351cc1eb31b617951fba786cfd5d58baff36589a33`
`sentinel_2x`	0.0004 BTC	`0x02a94630f46bcf7362c12ed5b0163b4dd7644eb923aaada61ffb858d7912e03d`
`sentinel_3x`	0.0006 BTC	`0x038224d3966b850913cfc4dd610032d8082e14c90fce91819a0fb994b1cc63f3`
`sentinel_4x`	0.0008 BTC	`0x06de0d6c46431628f0cd257aa4384125b2380a7c5362aab2b146283181c2dff3`

Delta Neutral (Yield)

Pool Key	Denomination	Contract Address
`dn_1x`	0.00036 BTC	`0x07298d2765e1dc61dae0f5d8c70b86e1857b038ab7a1f7c473111321aaac51aa`
`dn_2x`	0.00072 BTC	`0x059511116f7e1877fc9e3d26a2b9165d02cc367414c009c94b7b76f6d1e4c929`
`dn_3x`	0.00108 BTC	`0x01191727f6135bb878e9771066b0c6bcc18faed9146eb0a04eabb83190b90ce3`
`dn_4x`	0.00144 BTC	`0x040babfa49b967c7873e3b275b7f8d6bea88028854f5b5923c2de5af76d78c56`

Stablecoin (Private USDC)

Pool Key	Denomination	Contract Address
`stable_10`	10 USDC	`0x04f4af2cf01a1cf28f424ce2ce3d7fed7f11792c88e5ce7a3eedd21cea24a5eb`
`stable_25`	25 USDC	`0x05aa66a4541caf4d43a526edd89c0285a671e0be0024ae5f8ca9f6734f4b7c89`
`stable_50`	50 USDC	`0x03226cbb8976f41eddf88c2871cf4d04653a1b6415dee7037a1ceaf641e977a9`
`stable_100`	100 USDC	`0x06348e9e2db703841bed848146ef895c8aed4f3c143e76bd145d9b3c544cea68`

Private Swap Flow

Overview
Supported Swaps
Flow Diagram

Private swaps break the link between input token depositor and output token recipient:

Deposit WBTC into swap input pool (shielded)
Generate withdrawal proof targeting swap pool contract
Swap pool receives WBTC, swaps via AVNU DEX
Output token sent to recipient address
No on-chain link between depositor and recipient

┌──────────┐    ┌───────────────┐    ┌──────────┐
│ Depositor│───►│ Swap Input    │───►│ Swap Pool│
│ (hidden) │    │ Pool (ZK)     │    │ Contract │
└──────────┘    └───────────────┘    └────┬─────┘
                                          │
                                          ▼
                                   ┌──────────────┐
                                   │ AVNU Router  │
                                   │ (DEX swap)   │
                                   └──────┬───────┘
                                          │
                                          ▼
                                   ┌──────────────┐
                                   │  Recipient   │
                                   │  (different  │
                                   │   address)   │
                                   └──────────────┘

ZK Circuit Versions

Version	Proof System	Verifier	Status
V1	UltraHonk (Noir)	`@aztec/bb.js`	Legacy
V2	Groth16 BN254	`snarkjs` + Garaga	Legacy
V3	Groth16 BN254 (6 public inputs)	Garaga `0x0410...`	Legacy
V4	Groth16 BN254 (7 public inputs)	Garaga `0x0332...`	Current

Current Verifier

Contract: 0x03329c4d5c2e37dfd20d46c3c20be9230b2152c71947ead441c342d989d52ffa Public Inputs (7):

Merkle root
Nullifier hash
Recipient address
Relayer address
Fee amount
Batch start index
Batch size

Security Considerations

Critical: Notes are stored in browser localStorage. If you lose your note, you lose your funds permanently. Always export and backup your notes.

Best Practices

Export Notes Immediately: After each deposit, export your notes to a secure location
Multiple Backups: Store encrypted note backups in 2+ locations
Use Different Withdrawal Address: Withdraw to a fresh address for maximum privacy
Wait for Larger Anonymity Set: More deposits in your denomination = stronger privacy
Use Relayer: Let the relayer submit your withdrawal transaction to hide your IP

Privacy Limitations

Anonymity Set Size
Timing Analysis
Amount Correlation

Privacy depends on the number of deposits in your denomination pool:

< 10 deposits: Weak anonymity
10-100 deposits: Moderate anonymity
> 100 deposits: Strong anonymity

Check pool size before depositing.

Relayer Flow

Fee Estimation

GET /api/relayer/fee-estimate?pool=sentinel_1x

Returns estimated relayer fee (typically 0.5-1% of denomination).

Generate Proof

User generates proof locally with relayer address and fee.

Submit to Relayer

POST /api/relayer/withdraw
{
  "proof": "0x...",
  "publicInputs": [...],
  "poolKey": "sentinel_1x"
}

Relayer Execution

Relayer submits transaction on-chain, pays gas, receives fee.

Technical Files

File	Purpose
`src/lib/privacy/note.ts`	Note generation, Poseidon hashing, nullifiers
`src/lib/privacy/prover.ts`	Groth16 proof generation (snarkjs WASM)
`src/lib/privacy/merkle.ts`	Merkle tree management
`src/lib/privacy/calldata.ts`	Proof calldata serialization
`contracts/src/shielded_pool_v4.cairo`	Current shielded pool contract
`contracts/src/shielded_swap_pool.cairo`	Private swap pool contract

Next Steps

Make Your First Shielded Deposit

Step-by-step guide to private deposits

Withdraw Privately

Generate ZK proofs and withdraw to a new address

Export & Backup Notes

Secure your notes to prevent fund loss

Understanding ZK Proofs

Learn how Groth16 proofs work

Get Started

Features

Protocol Integrations

Privacy (Shielded Vaults)

Privacy / Shielded Vaults

Overview

Pool Types

How Shielded Deposits Work

Deposit Flow

Withdrawal Flow

Merkle Tree Structure

Tree Parameters

Fixed Denomination Pools

Sentinel (Lending)

Delta Neutral (Yield)

Stablecoin (Private USDC)

Private Swap Flow

ZK Circuit Versions

Current Verifier

Security Considerations

Best Practices

Privacy Limitations

Relayer Flow

Technical Files

Next Steps

Make Your First Shielded Deposit

Withdraw Privately

Export & Backup Notes

Understanding ZK Proofs

Build docs developers (and LLMs) love

Get Started

Features

Protocol Integrations

​Privacy / Shielded Vaults

​Overview

​Pool Types

​How Shielded Deposits Work

​Deposit Flow

​Withdrawal Flow

​Merkle Tree Structure

​Tree Parameters

​Fixed Denomination Pools

​Sentinel (Lending)

​Delta Neutral (Yield)

​Stablecoin (Private USDC)

​Private Swap Flow

​ZK Circuit Versions

​Current Verifier

​Security Considerations

​Best Practices

​Privacy Limitations

​Relayer Flow

​Technical Files

​Next Steps

Make Your First Shielded Deposit

Withdraw Privately

Export & Backup Notes

Understanding ZK Proofs

Build docs developers (and LLMs) love

Privacy / Shielded Vaults

Overview

Pool Types

How Shielded Deposits Work

Deposit Flow

Withdrawal Flow

Merkle Tree Structure

Tree Parameters

Fixed Denomination Pools

Sentinel (Lending)

Delta Neutral (Yield)

Stablecoin (Private USDC)

Private Swap Flow

ZK Circuit Versions

Current Verifier

Security Considerations

Best Practices

Privacy Limitations

Relayer Flow

Technical Files

Next Steps