Architecture

The app creates a note for the user with random rho and r, computes stub = H(opk, rho, r), and encrypts (rho, r, 0) to the user's viewing key. The share amount is not known yet. It asks PrivateRouter.quote(true, ethIn) for the expected output and subtracts 1% slippage.

The user's wallet calls PrivateRouter.buy{value: ethIn}(stub, minTokensOut, ciphertext).

The router buys NOIR: on the curve with curve.buy(ethIn, minTokensOut, router) before graduation, or with an exact-input swap on the Pons v4 pool after. Pons charges the same fees on both venues and pays them out in ETH.

The router checks tokensOut >= minTokensOut, approves the vault and calls vault.shield(stub, tokensOut, ciphertext). The vault pulls the NOIR, mints shares, computes cm = H(1, stub, shares), inserts it into the tree and emits Shielded and NoteAdded. The router then calls vault.poke().

The router returns any unspent ETH (a buy that fills the curve is refunded in part). The user's app later finds the note by decrypting the ciphertext, and reads its shares from the Shielded event of the same transaction.

The app scans the tree and picks up to two unspent notes from the same tree (one proof has one root).

It reads the recipient's keysOf(recipient), creates a note for them with fresh rho and r, and a change note for the sender. Each output is encrypted to its owner's viewing key.

It builds ExtData with caller = the vault, gasFee = the network fee in shares, and data = abi.encode(callGasLimit, address(0), 0). The only exit is the gas fee: exitShares = gasFee.

The app estimates gas through a bundler with a placeholder proof, then the wallet signs EIP-712 Spend(bytes32 transaction) once, and the app proves once, in the browser.

The UserOperation (sender = the vault, signature = abi.encode(Transaction, proof)) goes to any bundler. The EntryPoint calls validateUserOp, which checks the fee, verifies the proof, marks the nullifiers spent, inserts both output commitments and moves the fee to the gas reserve.

execute4337(nf0) finds no pending sale and returns. On-chain, the transaction shows two nullifiers, two new commitments and a fee. It does not show sender, recipient or amount.

As in a send, but data = abi.encode(callGasLimit, ethRecipient, minEthOut), where minEthOut is the router's quote less 1%. exitShares = sale shares + fee shares, and recipient is zero.

In validation the vault applies the whole private transition and puts the sale amount in escrow, pendingSales[nf0], instead of paying anyone.

In execution, execute4337(nf0) approves PrivateRouter for the amount and calls onPrivateExit. The router pulls the NOIR, sells it on the live venue and sends the ETH to ethRecipient.

If the sale fails (for example the price moved below minEthOut), the vault transfers the NOIR to ethRecipient instead. If execution ran out of gas, anyone can call claimSale(nf0) to do the same.

Every trade of NOIR, on the curve or on the pool, pays the Pons fees in ETH. The creator share accrues to the harvester.

Anyone calls FeeHarvester.harvest(). It sweeps the fees Pons holds for NOIR, claims the harvester's ETH from the Pons fee escrow and tips the caller 0.5%.

It tops up the vault's EntryPoint deposit to targetDeposit, then buys NOIR with the rest of the ETH and calls vault.donate. The vault's backing B grows, its shares S do not, so every note is worth more NOIR.