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
| Component | On-chain / off-chain | Who runs it | What it can do |
|---|---|---|---|
ZERO (0x316fa3AB9A8FD8d7567a823DedecF28d9FEE2894) | On-chain, Pons contract | Nobody (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 contract | Pons | Sells and buys ZERO for ETH until graduation, and holds the fees it charges until they are swept |
| Pons factory, meme hook, fee escrow | On-chain, Pons contracts | Pons | Graduate 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 roles | Holds 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, immutable | Nobody | buy: 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 path | Anyone may call harvest; an owner may change the team's recipient and hand the fee recipient role on | The 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, immutable | Nobody | Checks UltraHonk proofs of the transact circuit. Generated by Barretenberg; calls two linked libraries, RelationsLib and ZKTranscriptLib |
Poseidon2 hasher (0xb63c2AA1370B32CcfABaf5d24F854D817b405833) | On-chain, immutable | Nobody | Poseidon2 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.8 | On-chain, canonical | Nobody (ERC-4337 standard contract) | Calls the vault's validateUserOp and execute4337, pays bundlers from the vault's deposit |
| Bundler | Off-chain | Anyone (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-chain | Anyone | Serves 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 prover | Off-chain, on the user's device | The user | Derives 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:
| Value | Where |
|---|---|
| ZERO, Pons factory, curve, PoolManager, graduated pool ID | PrivateVault implementation immutables |
| Verifier, hasher, EntryPoint | PrivateVault 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) |
| Roles | PrivateVault storage, granted by initialize |
| Pool key of the graduated pool | PrivateRouter and the harvester, read from the Pons factory at construction |
| Vault | PrivateRouter and harvester immutable: the proxy's address |
| Target deposit, fee escrow, EntryPoint | Harvester 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:
| Role | Can |
|---|---|
Vault UPGRADER_ROLE | Replace the vault's implementation (upgradeToAndCall), with no timelock |
Vault GUARDIAN_ROLE | Stop 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_ROLE | Grant and revoke every vault role (grantRole, revokeRole) |
| Harvester owner | Change 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.