zerotracedocs

Architecture

The contracts and off-chain parts of ZeroTrace, who runs each one, and how a purchase, a private send and a private sale move through them.

ZERO is an ordinary ERC-20 launched on the Pons V2 launchpad. ZeroTrace is the private side around it: a vault that holds ZERO behind encrypted notes, a router that trades on ZERO's market and shields or sells in the same transaction, and a fee harvester that receives the Pons creator fees, pays half to the team and turns the other half into gas and holder yield. The vault is also its own ERC-4337 account. Everything else can be run by anyone (bundlers, the indexer, the app).

Components

ComponentOn-chain / off-chainWho runs itWhat it can do
ZERO (0x316fa3AB9A8FD8d7567a823DedecF28d9FEE2894)On-chain, Pons contractNobody (no owner)A Pons PonsV2LauncherToken: OpenZeppelin ERC20 + ERC20Burnable, 1,000,000,000 supply minted to its bonding curve, no transfer restrictions
Pons bonding curve (0xE276F7E250bC2cD45f1e344d9adc9c9687c2c897)On-chain, Pons contractPonsSells and buys ZERO for ETH until graduation, and holds the fees it charges until they are swept
Pons factory, meme hook, fee escrowOn-chain, Pons contractsPonsGraduate ZERO into its Uniswap v4 pool, charge the fees on that pool, and pay the creator share into the escrow
PrivateVault (0xEE92d20c1b0AAA686DDc8809A1B6A67aB092eb33)On-chain, ERC-1967 proxy (UUPS) over its implementation (0xBc08FAd89f924e1A852D271061977d0fCE40A559)Three roles, held by the deployer at launch: an upgrader replaces the implementation; a guardian pauses spends, entries and exits handed to a target, and sets the operation cost within a fixed range; an admin grants and revokes the rolesHolds the ZERO backing all notes, the key registry, the note tree and nullifier set, the vault totals B and S, the price average and the network fee. Verifies every spend. Acts as the ERC-4337 account for private transactions
PrivateRouter (0x0c242A7E0717D09A5517AD1de282CCb66533365d)On-chain, immutableNobodybuy: trades ETH for ZERO and shields it into a note in one transaction. sell: spends notes and sells them for ETH. Settles ERC-4337 sales as their exit target. quote: prices a trade. Holds no funds between transactions
FeeHarvesterV3 (0xe2f2341AE7C0f8f520216001bc8B9087465Cf856)On-chain, no upgrade pathAnyone may call harvest; an owner may change the team's recipient and hand the fee recipient role onThe vault's harvester. As ZERO's Pons creator fee recipient, it claims the ETH fees and splits them in half: one half to the team's recipient, the other keeps the vault's EntryPoint deposit funded and buys ZERO donated to the vault
Verifier (HonkVerifier, 0x8F27B4B83bd86F11A07E3FFe0369Cb4B08a60735)On-chain, immutableNobodyChecks UltraHonk proofs of the transact circuit. Generated by Barretenberg; calls two linked libraries, RelationsLib and ZKTranscriptLib
Poseidon2 hasher (0xb63c2AA1370B32CcfABaf5d24F854D817b405833)On-chain, immutableNobodyPoseidon2 over BN254 in Yul, kept outside the vault for contract size. FallbackHasher (Stylus first, Yul as backup) exists as an option; deployments use the Yul hasher
EntryPoint v0.8On-chain, canonicalNobody (ERC-4337 standard contract)Calls the vault's validateUserOp and execute4337, pays bundlers from the vault's deposit
BundlerOff-chainAnyone (Pimlico's public endpoint, Alchemy, self-hosted Alto or Rundler)Submits UserOperations. Cannot change the recipient, the fee or the sale terms, which the proof binds
Indexer (optional)Off-chainAnyoneServes the vault's events by block range, the same to everyone. Sees only public and encrypted data. Wallets check its data against an on-chain root and fall back to the chain
App and proverOff-chain, on the user's deviceThe userDerives keys, scans and decrypts notes, builds and proves transactions in the browser, asks the wallet to sign each spend

PrivateRouter and the harvester share one trading library, PonsSwapper. It trades on the bonding curve before graduation and on the Pons Uniswap v4 pool after, and performs a pending graduation step itself before trading. See The market.

The addresses for each network are in Deployments; the contract interfaces are in Contracts.

The upgradeable vault and its roles

The vault is the one upgradeable contract: an OpenZeppelin UUPSUpgradeable implementation behind an ERC1967Proxy. Its state lives in the proxy and is written once by initialize; the implementation's own initializers are disabled. The router, the harvester, the verifier and the hasher have no proxy and no upgrade path, and the router has no owner. Every address the vault works with is a constructor argument of its implementation:

ValueWhere
ZERO, Pons factory, curve, PoolManager, graduated pool IDPrivateVault implementation immutables
Verifier, hasher, EntryPointPrivateVault implementation immutables
EIP-712 name (zerotrace) and version (1)PrivateVault implementation constructor; the domain's verifyingContract is the proxy
Operation cost opCostWei (0.0002 ETH at deployment)PrivateVault storage, written by initialize and set by the guardian between the constants MIN_OP_COST_WEI (0.00005 ETH) and MAX_OP_COST_WEI (0.001 ETH)
RolesPrivateVault storage, granted by initialize
Pool key of the graduated poolPrivateRouter and the harvester, read from the Pons factory at construction
VaultPrivateRouter and harvester immutable: the proxy's address
Target deposit, fee escrow, EntryPointHarvester immutables
TEAM_SHARE_BPS (5000), MAX_IMPACT_BPS (50), MAX_PREMIUM_BPS (1500), CALLER_TIP_BPS (50), GAS_OVERHEAD (25,000)Harvester constants

A new verifier, or any other new address, comes with a new implementation. An upgrade keeps everything in the proxy's storage (notes, the tree, totals, nullifiers, registered keys, roles) and the EntryPoint deposit, and the EIP-712 domain still names the proxy, so signatures stay valid. See Upgrades and the pause.

The vault does not know the router or the harvester: the router is named per sale, as the exit target in the proof, and the harvester only calls the vault's permissionless poke, absorb and donate.

These roles exist, all held by the deployer (0x1B0210b9695BbEB8bD70964A46bf512021127A73) at launch:

RoleCan
Vault UPGRADER_ROLEReplace the vault's implementation (upgradeToAndCall), with no timelock
Vault GUARDIAN_ROLEStop and resume every spend of a note (pause, unpause); pause and resume new entries (setEntriesPaused: shield, and so private buys); pause and resume exits handed to a target (setTargetExitsPaused: ERC-4337 sales through the router, any other target); set the operation cost between 0.00005 and 0.001 ETH (setOpCost)
Vault DEFAULT_ADMIN_ROLEGrant and revoke every vault role (grantRole, revokeRole)
Harvester ownerChange the team's recipient (setTeamRecipient), hand ZERO's creator fee recipient role to a successor at once (handOver), hand ownership on (transferOwnership)

The guardian cannot spend, transfer or exit anything, or move or reveal a note. The harvester owner cannot touch the vault, notes or the EntryPoint deposit, or spend the holders' half. The upgrader's role reaches every rule of the vault, since it replaces the code that runs against the vault's storage. A vault role can be given up with renounceRole; the harvester's ownership with transferOwnership(address(0)). Nobody can withdraw the EntryPoint deposit or stake through the vault's current code, or take the vault's ZERO except by spending notes with valid proofs. See The vault and the trust model.

What Pons controls

ZERO, its curve, its graduated pool and its fees are Pons contracts. The ZeroTrace contracts cannot change them, and they cannot touch the vault. The Pons owner can redirect ZERO's creator fee recipient away from the harvester with setCreatorFeeRecipient: the change waits a 3-day timelock (CREATOR_FEE_RECIPIENT_TIMELOCK), is visible in pendingCreatorFeeRecipient(zero) during that time, and must then be executed within a further 3 days. That would stop the holder yield described in The vault. It would not touch any note, the vault's ZERO or the ability to shield, send, unshield and sell. Apart from Pons, only the harvester itself can hand the role on, through its owner's handOver.

Flow 1: buy through the app

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 ZERO: 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 ZERO, 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.

A purchase anywhere else (a DEX, an aggregator, the Pons site) delivers public ZERO. The holder turns it into a note with one shield call: see Public ZERO and shielding.

Flow 2: private send

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), address(0), ""): no exit target. The only exit is the network 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 gas cost cap and the network fee, verifies the proof, marks the nullifiers spent, inserts both output commitments and burns the fee's shares, leaving its ZERO to every note. The EntryPoint deposit pays the bundler.

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

Flow 3: private sale through ERC-4337

As in a send, but data = abi.encode(callGasLimit, router, ethRecipient, abi.encode(minEthOut)): the router is the exit target, and minEthOut is its quote less 1%. exitShares = sale shares + fee shares, and ext.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 exactly the amount and calls onPrivateExit(amount, ethRecipient, abi.encode(minEthOut)). The router pulls the ZERO, sells it on the live venue and sends the ETH to ethRecipient. The amount stays in pendingSaleTotal until the router has returned.

If the sale fails (for example the price moved below minEthOut), the vault transfers the ZERO to ethRecipient instead. If execution ran out of gas, anyone can call claimSale(nf0) to do the same. While the guardian has paused exits to a target, validation refuses the operation (TargetExitsArePaused); a sale validated before the pause is paid to ethRecipient as ZERO. While the vault is paused, validation reverts (EnforcedPause) for every spend.

The address that receives the ETH is public; which notes paid for it is not. Details in Gas and ERC-4337.

Flow 4: the harvest

Every trade of ZERO, on the curve or on the pool, pays the Pons 1% fee in ETH. Pons keeps 0.3% of the trade; the creator share, 0.7%, accrues to the harvester.

Anyone calls harvest(). It sweeps the fees Pons holds for ZERO, claims the harvester's ETH from the Pons fee escrow and sets half of it aside for the team.

With the holders' half, it tops up the vault's EntryPoint deposit to targetDeposit, then makes at most one small buy of ZERO in the block and calls vault.donate. The vault's backing B grows, its shares S do not, so every note is worth more ZERO. What the buy limits leave unspent waits for the next block.

It refunds the caller's gas, only if the call put ETH to work, and pays the team its half.

The steps and their limits are in The vault.

Paths that need no bundler

A private transaction can also be submitted directly with PrivateVault.transact(t, proof) (with ext.caller zero or the caller's address), and a sale with PrivateRouter.sell(t, proof). The address paying gas is then visible. Neither is an exit to a target, so the guardian's pause of target exits does not reach them; the general pause does. If the router cannot trade, notes can exit to any address as public ZERO and be sold elsewhere. See the threat model.

On this page