How Sesame works

Two lanes#

The public lane holds the DLMM and DAMM pools, perpetuals, capped-call options, the bonding-curve launchpad and analytics. Everything in it is visible: who traded, what, how much, at what price and when. Price discovery needs that. LPs judge their risk from depth and flow, and traders can check the price they got.

The shielded lane is a vault. You deposit one of a few fixed amounts and get a note: a secret only you hold. Later you withdraw with that note, to any address. The vault's job is to make it hard to tell which deposit paid for which withdrawal.

The lanes meet only at deposit and withdrawal. Shielded funds can't trade in the pools directly: a trade made from inside the vault would show its size and timing to everyone, which undoes the point of the vault. Shielded swaps are on the roadmap, not in the app.

Every action lands in one activity feed, tagged with its lane: public, shielded or system.

Demo mode#

Sesame runs on a demo ledger: one SQLite database on the server, with CHAIN_MODE=off. No contracts are deployed and no real funds move. Your browser gets a demo account behind an httpOnly cookie, opened on your first action with 10,000 USDC, 1 ETH and 25,000 SEED; the faucet tops up the same amounts, once every 10 minutes. Connecting a wallet (Robinhood Chain testnet, chain id 46630) stores your address as a label only, and demo mode never asks you to sign anything. Block numbers come from a 250 ms clock that started on 1 January 2026 (UTC), and transaction hashes are keccak256 hashes of ledger records, not on-chain transactions. Reference prices are real, from Yahoo Finance and DefiLlama. The full split is under simulated and real.

The shielded vault goes further: its zero-knowledge proofs are real Groth16 proofs, even on the demo ledger, and its contracts are ready for Robinhood Chain testnet. See the shielded lane.

DLMM pools#

A DLMM pool splits prices into bins. Bin i trades at exactly one price, set by the pool's bin step. Inside a bin a swap has no price impact; a larger swap empties the bin and moves on to the next one, and that is what moves the price.

price(bin i) = (1 + binStep / 10,000) ^ i      quote per base

Bins below the active bin hold only the quote token, bins above it hold only the base token, and the active bin holds both. A buy takes base from the active bin upwards; a sell takes quote from it downwards.

To add liquidity you pick a range, as bin offsets from the active bin, of up to 69 bins per position, and a shape:

• Spot puts the same amount in every bin.
• Curve puts most of it near the active bin and thins out towards the edges.
• Bid-ask puts more towards the edges and less near the active bin.

Quote goes into bins at or below the active bin, base into bins at or above it. A range entirely above the active bin takes only base; a range entirely below takes only quote.

The fee is taken from the swap input and credited to the bins the swap passed through, in proportion to what each bin filled. 80% goes to the LPs in those bins and 20% is protocol revenue. A position earns only while the active bin is inside its range; the app marks each position in range or out of range. You can claim fees at any time. Removing a position closes all of it and pays out its tokens plus any unclaimed fees.

DAMM pools#

A DAMM pool is a full-range constant-product pool. The product of the two reserves stays the same through a swap (before fees), and the price is the quote reserve divided by the base reserve. Liquidity is always in range, so a position never stops earning, but it is spread thinly over every possible price.

x · y = k                         x = base reserve, y = quote reserve
price      = y / x
buy:  out  = x · in′ / (y + in′)    in′ = input after the fee
sell: out  = y · in′ / (x + in′)

The fee is dynamic. It starts at the pool's base fee and rises with the price move since the last trade that is at least an hour old: for every 1% the price has moved, the fee rises by 0.2 percentage points, up to +0.70%. Calm markets pay the base fee; fast markets pay LPs more for the risk they carry.

fee = baseFee + min(70 bps, ⌊0.2 × |ln(P_now / P_1h)| × 10,000⌋ bps)

To add liquidity you enter the quote amount and the app matches the base amount at the pool's current ratio. Your share of the pool is your share of the reserves and of the fees. As with DLMM, 80% of fees go to LPs and 20% to the protocol.

Swaps and slippage#

A swap goes through one pool. Buy means quote in, base out; sell means base in, quote out. There is no routing across several pools yet.

While you type, the swap form asks the server for a quote: the same swap run with dryRun, which changes nothing and returns the output, the fee, the average price, the price before and after, and the price impact. Price impact is the gap between your average price and the price before the swap.

Slippage is what changes between that quote and the fill, because other trades, the keeper or simulated flow can land in between. The form shows Minimum received: the quoted output reduced by your slippage limit. It is sent with the swap as minOut. The server runs the swap again at submit time and, if the output would be below minOut, rejects it with a “price moved” error and changes nothing.

Each swap runs in one database transaction, so it fills completely or not at all. A DLMM swap that runs out of liquidity in range is rejected, and the error says how much the pool can fill. A DAMM swap is rejected if it would empty a reserve.

Pool registry and simulated flow#

The ledger starts with 13 pools, created on first run at that day's reference prices and funded with protocol-owned liquidity. DLMM seed positions span 69 bins around the starting price in the curve shape.

Pool ids look like addresses but are not contracts: each is the last 20 bytes of the keccak256 hash of the pool's name, for example sesame.pool.ETH.USDC.DLMM. Graduated launches add more DAMM pools to this registry.

So that charts have a past, seeding writes 7 days of simulated history: three trades per hourly reference candle (open, then high or low, then close). SEED has no outside price, so its history is a seeded random walk that ends at 0.042 USDC.

After that, a keeper runs whenever pools are read, at most once every 20 seconds per pool. If a pool is more than 0.15% away from its reference price, the keeper trades it back, as an arbitrageur would. A DLMM pool can only follow as far as its bins hold liquidity. If a pool has had no trade for 150 seconds, there is a 60% chance of a random trade worth between $60 and $1,860. Pools without an outside price (SEED/USDC and graduated launch pools) only get the random trades; SEED/ETH follows SEED/USDC.

Fees and the assistance fund#

Protocol revenue comes from four places, each recorded in the asset it was paid in:

• Pool swaps: 20% of the swap fee, in the input token.
• Perps: 6 bps of notional on open and again on close, in USDC.
• Options: 1% of the premium, in USDC.
• Launchpad curves: 1% of every curve trade, in USDC.

The assistance fund turns that revenue into SEED buybacks when someone presses the button on Analytics (POST /api/analytics). It values the pending revenue in USDC at current prices, then splits it:

• 99% buys SEED in the SEED/USDC pool. The SEED bought is burned: it is credited to no account, so it leaves circulation.
• 1% goes to the treasury account, in USDC.

The buyback is an ordinary swap. It pays the pool fee and moves the SEED price like any trade, and its own protocol fee becomes new pending revenue. If pending revenue is worth less than 1 USDC, nothing happens.

Bonding curves#

Every launch has 1,000,000,000 tokens. 800,000,000 are sold on the curve and 200,000,000 are held back for the pool. The curve is constant-product with virtual reserves: it starts with T₀ = 1,073,000,000 virtual tokens and Q₀ virtual USDC, and the price is Q ÷ T. Q₀ is set so that selling exactly the 800,000,000 curve tokens raises exactly the template's threshold.

T · Q = k = T₀ · Q₀
price  = Q / T                                  USDC per token
Q₀     = threshold × (T₀ − 800,000,000) / 800,000,000

Prices in USDC per token. The pool opens at the threshold divided by the reserved tokens.

Every buy and sell pays a 1% fee on the USDC side, which goes to protocol revenue. A buy that would pass the threshold is cut to exactly what the curve still needs, and the rest isn't charged. Sells put tokens back into the curve, up to the number sold so far. Quotes and the slippage limit (minOut) work as they do for swaps.

To create a launch you pick a template, a name (2 to 32 characters), a ticker (2 to 8 letters, not already in use), and optionally a description and a first buy. Each demo account can create up to 10 launches. The list starts with five demo launches whose trades are simulated and labelled as such.

Graduation and LP allocation#

When the USDC raised reaches the threshold, the curve closes and the launch shows graduation pending. Anyone can then migrate it. Migration creates a TICKER/USDC DAMM pool from the raised USDC and the 200,000,000 reserved tokens, in the 1% fee tier; the dynamic fee applies on top, as in every DAMM pool. From then on the token trades in that pool under Pools.

The LP shares minted at migration go into an escrow position and are split three ways:

Because 80% of the starting liquidity can't be withdrawn by anyone, neither the creator nor the protocol can empty the new pool.

Notes and commitments#

When you deposit, your browser makes a note: a random secret and a random nonce, 31 bytes each from crypto.getRandomValues, so both fit in the proof's field. From them it computes a commitment with the Poseidon hash over the BN254 field:

context    = keccak256(abi.encode(chainId, vault)) mod p
commitment = Poseidon(context, asset, amount, secret, nonce)
  asset    = token address as a field element
  amount   = fixed amount in 6-decimal units

The context binds a note to one chain and one vault, so a proof made for one vault fails in any other. The note is saved before the deposit is sent, in a journal kept in your browser and encrypted with your passphrase (AES-GCM, with the key derived by PBKDF2-SHA-256 over 250,000 iterations). You can export the encrypted journal as a backup file and import it in another browser.

Only the commitment, the asset and the amount leave your browser. The vault appends the commitment as the next leaf of a Poseidon Merkle tree. Every insert makes a new root, and the vault accepts the last 64 of them.

Hash

Poseidon over the BN254 scalar field, the same in the circuit, the browser, the server and the contract

Tree depth

20 levels, room for 1,048,576 notes

Node hash

Poseidon(left, right)

Empty leaf

keccak256("sesame.vault.zero") mod p

Root history

Last 64 roots

Demo vault address

0x8fcc02aec01725f6ab3784fadd4b4da9ed459396, derived from keccak256("sesame.vault.v1"); it feeds the context but is not a contract

Deposits come in fixed amounts so that they look alike:

• Demo ledger, USDC: 100, 1,000, 10,000
• Demo ledger, ETH: 0.1, 1
• On-chain, sUSDC: 100, 1,000, 10,000

Your anonymity set is every deposit of the same asset and amount. The deposit form shows how many unspent notes are in the set you picked. A small set hides little.

Withdrawing#

A withdrawal proves the statement in zk/withdraw.circom: “I know a secret and nonce whose commitment is a leaf of the tree under this root, and whose nullifier hash is this one.” The nullifier hash is published when the note is spent. A second withdrawal of the same note gives the same hash and is rejected.

nullifierHash = Poseidon(1, secret, nonce)
public  = [root, nullifierHash, recipient, amount, asset, context]
private = secret, nonce, 20 sibling hashes, 20 left/right bits

The circuit has 11,841 constraints. The recipient is bound to the proof (the circuit squares it), so a proof made for one address fails for any other and whoever submits it can't redirect the funds. The context input ties the proof to one chain and one vault.

Your browser builds the proof with snarkjs. The first time you withdraw it downloads the circuit (/zk/withdraw.wasm, 2.9 MB) and the proving key (/zk/withdraw.zkey, 5.3 MB). Proving takes about a second on a laptop, and the panel shows how long it took.

Errors you may see when withdrawing (contract error names in brackets):

• Root no longer in the root history (UnknownRoot): more than 64 deposits landed since you read the tree. Build the proof again.
• Nullifier is spent (NullifierSpent): this note was already withdrawn.
• Proof does not verify (InvalidProof): the proof doesn't match the root, nullifier, recipient, asset or amount, for example because the recipient changed after proving.
• On chain only: NotADenomination, ZeroRecipient, and at deposit NotInField, CommitmentExists or TreeFull.

What stays public#

The vault hides one link: which deposit paid for which withdrawal. Everything else about a deposit or a withdrawal is as public as a pool trade. This table covers both modes and says where they differ.

Asset and amount

Public pools: Public. Every swap, LP position, perp, option and curve trade records the asset, size and price.

Shielded vault: Public at deposit and at withdrawal, but always one of the fixed amounts (demo ledger: USDC 100, 1,000, 10,000; ETH 0.1, 1; on-chain: sUSDC 100, 1,000, 10,000).

Depositor address

Public pools: Public. Each trade is tied to the trader: an address on chain, a demo account in the ledger.

Shielded vault: Public. A deposit is an ordinary transfer into the vault, from your wallet on chain or from your demo account on the ledger.

Withdrawal recipient

Public pools: Not applicable: proceeds go back to the trader.

Shielded vault: Public. In the Withdrawal event on chain; stored with the nullifier on the demo ledger.

Who paid the gas

Public pools: Public: the trader's wallet.

Shielded vault: On chain, public: whoever sends the withdraw transaction. The app sends it from your connected wallet, which is also the recipient, and there is no relayer yet. Withdrawing with the wallet you deposited from links the two.

Timing

Public pools: Public: block and time of every action.

Shielded vault: Public: block and time of each deposit and each withdrawal. A withdrawal soon after a lone deposit is easy to link.

Which deposit funded a withdrawal

Public pools: Not applicable: the same account trades and receives.

Shielded vault: Hidden among the notes of the same asset and amount, in both modes: the proof doesn't say which leaf, and nobody is told which path you built. Caveats: on a fresh vault the set is small; timing, amount and who paid the gas can still link you; and on the demo ledger the server sees your session cookie, because it credits your demo account, so demo-mode privacy is limited to the proof itself.

Note secret, nonce and leaf

Public pools: Not applicable.

Shielded vault: Never leave your browser. The path is rebuilt from the public leaf list (demo ledger) or from Deposit events (on chain).

Commitment and nullifier

Public pools: Not applicable.

Shielded vault: Public. Commitments are tree leaves; a nullifier hash is published when its note is spent. Without the secret, one can't be matched to the other.

Swap size and route

Public pools: Public: pool, side, size, price and fee.

Shielded vault: Shielded swaps are not offered yet. To trade, you withdraw first, and that trade is fully public.

Threat model#

• Stolen or lost notes

  A note is a bearer secret. Anyone who has the secret and nonce can withdraw it, and a lost note can't be recovered.

  Defence. Notes are made and kept in your browser, encrypted with your passphrase, and the backup file is the same encrypted journal. The secret never leaves the browser, not even when you withdraw. Treat the backup and passphrase like cash.

  Today. Same in both modes.

• Malicious frontend

  The page you load makes your secret and serves the prover. A modified page could use weak randomness, copy notes out, ship a different prover, or deposit a commitment that isn't yours.

  Defence. Secrets come from crypto.getRandomValues, and the commitment formula is published, so a deposit can be recomputed independently. A deployment also needs a way to check the page and the prover files themselves, for example published source with reproducible builds. That doesn't exist yet.

  Today. The page comes from the same server that runs the ledger, so you are trusting both.

• Malicious relayer

  A relayer submits your withdrawal so the recipient doesn't need gas from a linked address. A dishonest one could try to change the recipient or sit on the transaction.

  Defence. The recipient is bound to the proof, so a proof made for one address fails for any other; a Foundry test checks exactly that. A relayer could still delay or refuse.

  Today. There are no relayers yet. On chain your own wallet sends the withdrawal, and the gas payer is public.

• Replay across chains or vaults

  A note or proof made for one vault could be replayed against another vault, or against the same vault on another chain.

  Defence. Every commitment hashes in a context, keccak256(abi.encode(chainId, vault)) mod p, and every proof takes it as a public input. The contract computes its own context from the chain it runs on and its own address, so a proof for any other chain or vault fails. Nullifiers are tracked per vault.

  Today. Implemented: the demo ledger uses chain id 46630 and its placeholder vault address in the context.

• Stale or forged roots

  Every proof refers to a root. If the vault accepted any root, a made-up tree could prove a note that was never deposited. If it accepted only the newest, every deposit would break the proofs in flight.

  Defence. The vault accepts only roots it produced itself, and only the last 64. Older or unknown roots are rejected (UnknownRoot on chain) and the proof has to be built again.

  Today. Implemented the same way on the demo ledger and in the contract.

• Double spend

  Withdrawing the same note twice.

  Defence. Spending a note publishes its nullifier hash, which is fixed by the note's secret and nonce. The vault rejects any nullifier hash it has already seen (NullifierSpent on chain).

  Today. On the demo ledger the nullifier is checked again inside one database transaction after the proof is verified, so two requests at once can't both pass.

• Forged proofs from the setup

  Groth16 needs a one-time trusted setup. Whoever keeps that setup's secret randomness can make valid-looking proofs for notes that were never deposited, and empty the vault.

  Defence. Sesame's setup is a single-contributor ceremony run locally (zk/setup.sh), marked testnet-only in the script and in the generated verifier. Mainnet needs a multi-party ceremony first.

  Today. Acceptable for test tokens with no value. Not acceptable for real funds.

• Linking by metadata

  The proof hides which leaf you spend, but timing, amounts and who paid the gas can still tie a withdrawal to a deposit.

  Defence. Fixed amounts make deposits look alike. Waiting helps, and so does withdrawing with a wallet that has no link to the one you deposited from, though that wallet still needs gas from somewhere. A relayer would hide the gas payer; none exists yet.

  Today. The demo ledger also sees your session cookie on both deposit and withdrawal, so it can link them by account.

• Oracle manipulation

  Perps and options pay out on a price. Whoever can move that price can force liquidations or inflate a settlement.

  Defence. Perps and options read the reference feed, not the pools, so pushing a thin demo pool moves neither. The weak point is the feed itself: one unofficial source, delayed for stocks, which falls back to the last good value or a snapshot (marked not live) when it fails. Options wait up to 6 hours for a live price before settling on a snapshot. A deployment needs several independent sources and limits on how stale a price may be.

  Today. As described. Perps still open and close on a snapshot price when the feed is down.

• Admin keys

  Whoever holds admin or upgrade keys can change the rules, pause withdrawals or move funds.

  Defence. SesameVault, Groth16Verifier and DemoUSD have no owner, no admin functions and no upgrade path: the vault's verifier, token and context are fixed when it is deployed. A new circuit means a new vault. Contracts for the rest of the app don't exist yet; when they do, this section needs to list every admin power they carry.

  Today. The server operator controls the ledger completely and can change any balance, pool or record.

• Demo account theft

  Your demo account is a random 128-bit id in a cookie. Anyone who learns it controls the account.

  Defence. The cookie is httpOnly and SameSite=Lax (and Secure in production), so page scripts can't read it. The activity feed never shows account ids.

  Today. This is a demo-ledger concern: the on-chain vault uses your wallet, not a cookie.

Simulated and real#

Demo mode is real about prices, math and proofs, and simulated about money and the chain.

Data sources and licences#