Shield & Send

Deposit tokens into the privacy pool and send them privately using zero-knowledge proofs.

How Shielding Works

Shielding deposits tokens into a token pool. You receive a shielded note (a UTXO) - a cryptographic commitment that proves ownership without revealing the amount or your identity. Each token has its own pool; there is no shared vault.

1. Your account keys are derived deterministically from a one-time wallet signature, in the browser. Nothing is stored on a server.
2. A note commitment is computed as Poseidon(amount, pubkey, blinding, mintAddress).
3. The deposit merges any existing note with the new amount, producing your updated private balance (a transaction has up to 2 inputs and 2 outputs).
4. The token pool pulls the tokens and inserts the new commitment into its Merkle tree.
5. The note's encrypted output is written on-chain, so you can always recover your balance from just your signature - no external backup needed.

Shielding Example

// Alice shields 100 USDC into the USDC pool.
// The app derives her keys from a wallet signature, builds the note,
// and prepares the deposit transaction via the API.
const amount = parseUnits("100", 6); // USDC has 6 decimals

const prep = await fetch("https://api.rail20.org/api/deposit/prepare", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ signature, address, amount: "100", pool: "usdc" }),
}).then(r => r.json());

// prep.approveTx (ERC-20 approve) then prep (the deposit tx) are signed
// and broadcast by the user's wallet. The output note is encrypted on-chain.
await wallet.sendTransaction(prep.approveTx);
await wallet.sendTransaction({ to: prep.to, data: prep.data, value: prep.value });

How Private Sending Works

A zero-knowledge proof proves:

• You own a valid note (Merkle inclusion proof)
• Its nullifier hasn't been spent (no double-spend)
• Inputs equal outputs plus fee (conservation)
• New commitments are correctly formed (up to 2 outputs)

Transfer Flow

1. Input note - Alice's existing note (e.g., 100 USDC)
2. Output notes - Bob (60 USDC) + Alice change (40 USDC); at most 2 outputs per tx
3. ZK proof - valid without revealing amounts or addresses
4. Relayer - submits the proof, pays gas, collects a flat + 0.35% fee
5. Pool - verifies, marks the nullifier spent, inserts the new commitments

// Alice sends 60 USDC to Bob (recipient + change = 2 outputs).
// The relayer derives keys from the signature, builds the proof, and broadcasts.
const withdraw = await fetch("https://api.rail20.org/api/withdraw", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    signature,          // derives Alice's account keys
    pool: "usdc",
    amount: "60",
    recipient: bobShieldedAddress,
  }),
}).then(r => r.json());
// The relayer broadcasts and pays gas; Alice's wallet is never the sender.

Privacy Model

Privacy strength = anonymity set size. Every shielded note is a commitment hash - indistinguishable on-chain.

What's visible on-chain

Best practices

• Don't deposit and immediately transfer - wait for others to shield.
• Avoid round amounts - they can link a deposit to a transfer.
• Use the relayer - direct calls reveal your IP and public wallet.
• Vary timing - spacing out spends widens your anonymity set.