zerotracedocs

The vault and the holder yield

How notes hold shares of the vault's ZERO, the exact conversion formulas and rounding, how the network fee and the fee harvester's buys become donations, how the harvester splits the Pons creator fees, the vault's roles, upgrades and pause, and the locked seed against the first-depositor attack.

Notes do not hold tokens. They hold shares of one vault, PrivateVault (0xEE92d20c1b0AAA686DDc8809A1B6A67aB092eb33), which holds the ZERO behind all notes. The vault's ZERO grows with every donation while the number of shares stays the same, so each share is worth more ZERO over time, without any note being touched. The donations come from two sources: the holders' half of the Pons creator fees on every ZERO trade, spent on ZERO by the fee harvester, and the network fee every private operation pays.

The vault runs behind an ERC-1967 proxy: 0xEE92d20c1b0AAA686DDc8809A1B6A67aB092eb33 is the proxy, the address users, integrators and the app use, and the code runs from its implementation (0xBc08FAd89f924e1A852D271061977d0fCE40A559). See Upgrades and the pause.

State

SymbolStorageMeaning
BtotalBackingZERO backing all notes
StotalSharesShares held by all unspent notes
VVIRTUAL_SHARES = 1e6Virtual shares, as in OpenZeppelin's ERC-4626

B and S are public. VaultUpdated(totalBacking, totalShares) is emitted after every change, so the share value over time can be rebuilt from events alone.

Conversions

function convertToShares(uint256 assets) public view returns (uint256) {
    return assets * (totalShares + VIRTUAL_SHARES) / (totalBacking + 1);
}

function convertToAssets(uint256 shares) public view returns (uint256) {
    return shares * (totalBacking + 1) / (totalShares + VIRTUAL_SHARES);
}
share value = (B + 1) / (S + 1e6)     ZERO (wei) per share

Both divisions round down, which is always in favour of the vault: shielding a ZERO mints at most a * (S + V) / (B + 1) shares, and exiting s shares pays at most s * (B + 1) / (S + V) ZERO. As a consequence, the share value never decreases. A shield that would mint zero shares reverts (ZeroShares).

Share amounts are limited to 120 bits by the circuit. At the initial rate of 1e6 shares per ZERO wei, the whole 1e9 ZERO supply is 1e33 shares, below 2^120 (about 1.3e36), and the rate only falls as the share value rises.

Entering the vault

PathWhat happens
shield(stub, amount, ciphertext)The vault pulls amount ZERO from the caller with transferFrom (the caller approves the vault first) and mints convertToShares(amount) shares into a note
PrivateRouter.buyThe router buys ZERO with ETH and shields it for the buyer in the same transaction

Minting adds amount to B and the shares to S. While the guardian has paused entries, both revert (EntriesArePaused); see Roles. See Public ZERO and shielding.

Exits

A transact with exitShares > 0 removes shares from the private side:

total   = convertToAssets(exitShares)
fee     = convertToAssets(ext.gasFee)          0 if gasFee is 0
amount  = total - fee                          ZERO transferred to ext.recipient, or held in escrow for an exit target
S      -= exitShares
B      -= amount

The fee's shares are burned with the rest, but its ZERO stays in B: it is a donation from the vault itself to every remaining note (event Donation(vault, fee)). The amount leaves the vault as an ERC-20 transfer of ZERO to ext.recipient (event Exited), or, for an ERC-4337 exit to a target such as the router, is held in pendingSales until execution. It is counted in pendingSaleTotal from validation until its target has returned. See Gas and ERC-4337.

The network fee

Every private operation through the vault's ERC-4337 account pays a flat network fee, in shares (ext.gasFee), worth the operation cost opCostWei of ZERO at the vault's price average:

networkFee = opCostWei * tokensPerEthEma / 1e18             ZERO; opCostWei = 0.0002 ETH at deployment
accepted   = convertToAssets(ext.gasFee) >= min(networkFee, previousNetworkFee)

poke() resets the fee from the average at most once per NETWORK_FEE_INTERVAL (1 hour), and the fee it replaces stays accepted until the next reset, so an operation signed just before a reset still goes through (NetworkFeeUpdated). The fee goes to holders, as above.

opCostWei is storage, read through maxOpCostWei(). The guardian sets it with setOpCost(newOpCostWei), within the constants MIN_OP_COST_WEI (0.00005 ETH) and MAX_OP_COST_WEI (0.001 ETH); a value outside them reverts (OpCostOutOfRange), in initialize too. Setting it resets the network fee at once and emits OpCostSet. The same number is also the most an operation may cost the gas deposit, and each fee goes with its own cost: until the next fee reset, an operation may still pay the fee that was replaced, and is then held to the cost that was replaced (previousOpCostWei). The gas itself is paid by the vault's EntryPoint deposit, which the harvester refills; see Gas and ERC-4337.

Donations

donate(amount) pulls amount ZERO from the caller with transferFrom, adds it to B, leaves S unchanged, and emits Donation(from, amount). Anyone may call it. Sources in the protocol:

SourceEventAmount
The harvester's buysDonation(harvester, amount)The ZERO bought with the holders' half of the creator fees, after the gas deposit and the caller's refund
Network feesDonation(vault, fee)The fee of every operation that pays one
Plain transfers, by absorb()Donation(address(0), amount)ZERO sent to the vault's address with a plain transfer
AnyoneDonation(from, amount)Any donate(amount) after approving the vault

A donation raises the value of every share, including the locked seed's, in proportion to shares held. Public ZERO held outside the vault receives nothing. Half of the Pons creator fees goes to the team (see the fee harvester); nothing from private operations does: every network fee goes to holders.

A plain ERC-20 transfer of ZERO to the vault's address becomes a donation once anyone calls absorb(): it adds the vault's balance above totalBacking + pendingSaleTotal to B. Every harvest calls it. To get ZERO back into a note, use shield, never a transfer.

The fee harvester

The vault's harvester is a FeeHarvesterV3 (0xe2f2341AE7C0f8f520216001bc8B9087465Cf856). It serves one vault, an immutable set in its constructor: it tops up that vault's EntryPoint deposit and donates to that vault. It receives the fees as ZERO's creator fee recipient on Pons (see ZERO on Pons and Owner and successor). Every trade of ZERO, on the curve or on the graduated pool, pays the Pons fees in ETH:

FeeRateWhere it goes
Standard feecurve.feeBps(): 1%Pons keeps protocolFeeShareBps = 30% of it, 0.3% of the trade; the other 0.7% goes to the creator fee recipient, the harvester (buybacks are off)
Creator taxcurve.creatorTaxBps(): 0 for ZEROAll of it to the creator fee recipient; ZERO has none

Pons credits the creator share to its fee escrow, where the harvester claims it. The harvester splits every ETH it collects in half (TEAM_SHARE_BPS = 5000):

HalfShare of each tradeUse
The team's0.35%Paid to teamRecipient. Never spent on gas or ZERO
The holders'0.35%Tops up the vault's EntryPoint deposit, then buys ZERO donated to the vault

harvest()

harvest() has no access control and runs in this order:

collect:  if ZERO trades on its pool (after performing a pending graduation step):
              try memeHook.sweepPoolFees(poolId, 0, 0)
          else:
              try curve.sweepFees(0)
          if feeEscrow.balanceOf(harvester) != 0: feeEscrow.claim()
teamOwed  += collected * 5_000 / 10_000             the team's half of what this call collected
available  = harvester's ETH balance - teamOwed      the holders' ETH, including what earlier harvests left
vault.poke(); vault.absorb()
eth        = available * (10_000 - 50) / 10_000      the rest is kept for the caller's refund

1. deposit = EntryPoint.balanceOf(vault)
   if deposit < targetDeposit:  depositTo(vault, min(targetDeposit - deposit, eth)); eth -= that

2. if eth != 0 and ema != 0 and block.number != lastBuyBlock:
       fit a buy (below); if one fits: lastBuyBlock = block.number, buy, vault.donate(tokens), vault.poke()

3. refund the caller (below)
4. pay the team what it is owed

Each sweep is wrapped in try: it may have nothing to do, and converting fees that sit in ZERO on the pool can require the Pons fee sweep operator. A failed sweep never blocks the claim or the rest of the harvest.

The buys

The holders' ETH buys ZERO in small steps:

  • One buy per L1 block (lastBuyBlock; on Robinhood Chain block.number follows the L1 block). A second harvest in the same block deposits if it can, and buys nothing.
  • At most 0.5% of price impact (MAX_IMPACT_BPS = 50). The first size is capped from the market's depth: on the pool from its active liquidity, on the curve from its ETH reserve. A buy that adds a share x of the ETH side moves the price by about 2x, so the cap is 0.25% of the ETH side. On average such a buy fills about 0.25% from the spot price.
  • At least 85% of the ZERO the vault's price average gives, after fees (MAX_PREMIUM_BPS = 1500): never much dearer than the average.
feeBps   = curve.feeBps() + curve.creatorTaxBps()
expected(spend, price) = spend * price * (10_000 - feeBps) / (1e18 * 10_000)          ZERO

ethSide  = liquidity * 2^96 / sqrtPriceX96 (pool)  |  quoteReserve (curve)
spend    = min(eth, ethSide * 50 / 20_000)
repeat up to 8 times:
    minOut = max(expected(spend, spot) * (10_000 - 25) / 10_000,
                 expected(spend, ema)  * (10_000 - 1_500) / 10_000)
    if quote(spend) >= minOut:  buy spend with minOut; stop
    spend /= 2

The harvester quotes each size first, on the curve from its reserves or on the pool with a swap that is run and undone. If the market does not take a size within both limits, it halves it, up to 8 sizes in all. ETH that is not spent waits in the harvester for the next block's harvest.

A buy that small is not worth sandwiching: pushing the price up before it and selling after costs the Pons fees on both legs, about 2% of the round trip, for at most the 0.5% the buy moves the price. Someone who buys ahead of a run of buys and holds through several blocks of them can sell higher afterwards, as ahead of any buyback.

The caller's refund

The caller is refunded only the gas of a call that put ETH to work, by depositing or by buying:

worked = deposited + spent                  no refund if 0
price  = min(tx.gasprice, 2 * block.basefee)
refund = min((gas the call measured + GAS_OVERHEAD) * price, worked * 50 / 9_950)       GAS_OVERHEAD = 25_000

The cap is about 0.5% of the ETH put to work (CALLER_TIP_BPS = 50). A call that does nothing earns nothing: a call that neither tops up the deposit nor buys, such as a second call in the same block with the deposit full, gets no refund. Anyone, for example a bot, can keep the loop running without an operator, but calling it in a loop pays nobody.

The team's half

The team's half accrues in teamOwed and is paid to teamRecipient at the end of every harvest, or by payTeam(), which anyone may call. If the recipient is zero or refuses the ETH, the amount stays owed and is paid later; it is never counted in available, so it is never spent on gas or ZERO. The owner can change the recipient with setTeamRecipient, which pays what is owed to the new one (TeamRecipientChanged).

Parameters and events

ParameterValue
TEAM_SHARE_BPS5000 (50%) of each ETH collected, to the team
targetDepositImmutable; 0.1 ETH
MAX_IMPACT_BPS50 (0.5%) most a buy may move the price
MAX_PREMIUM_BPS1500 (15%): a buy must get at least 85% of the ZERO the price average gives, after fees
CALLER_TIP_BPS50 (0.5%) cap on the caller's refund, of the ETH put to work
GAS_OVERHEAD25,000 gas added to the measured gas
claimable()The holders' ETH the next harvest would have right away, not counting fees Pons has yet to sweep

Events: Harvested(ethAvailable, ethToDeposit, ethSpent, tokensDonated), TeamShareAccrued, TeamPaid, TeamRecipientChanged, CallerTipped, OwnershipTransferred and FeeRecipientHandedOver.

Owner and successor

The harvester's owner can change the team's recipient, hand the fee recipient role on, and hand ownership on, and nothing else:

FunctionEffect
setTeamRecipient(newRecipient)Sets who receives the team's half from now on and pays it what is owed (TeamRecipientChanged)
handOver(successor)Calls Pons' transferCreatorFeeRecipient(zero, successor) at once: one step, with no acceptance needed from the successor (FeeRecipientHandedOver). A zero successor reverts (NoSuccessor)
transferOwnership(newOwner)Hands ownership on; address(0) renounces it (OwnershipTransferred)

Fees already credited to the harvester before a hand-over stay claimable by its harvest. Once ownership is renounced, the team's recipient and the fee recipient can never change again through the harvester. The owner at launch is the deployer.

The holder yield depends on the harvester staying ZERO's creator fee recipient. Besides the harvester's own handOver, the Pons owner can redirect it with setCreatorFeeRecipient(zero, newRecipient) after a 3-day timelock, visible in pendingCreatorFeeRecipient(zero) before it can be executed. The yield would then stop. Notes, the vault's ZERO, shielding, private sends, unshields and sales would not change.

Roles

The vault has three OpenZeppelin AccessControl roles, granted by initialize(maxOpCostWei, admin, upgrader, guardian), which reverts on a zero address (ZeroAddress):

RoleFunctionsEffect
UPGRADER_ROLEupgradeToAndCall(newImplementation, data)Replaces the implementation behind the proxy, with no timelock. See Upgrades
GUARDIAN_ROLEpause(), unpause()Stops and resumes every spend of a note. See The pause
setEntriesPaused(bool)While true, shield reverts (EntriesArePaused), and so do private buys through the router. Emits EntriesPaused
setTargetExitsPaused(bool)While true, an ERC-4337 operation that names an exit target is refused in validation (TargetExitsArePaused): a private sale through the router, or any other target. An exit already validated when it came is paid to its recipient as ZERO, and its target is not called. Emits TargetExitsPaused
setOpCost(newOpCostWei)Sets what the network fee is worth in ETH and the most an operation may cost the deposit, within MIN_OP_COST_WEI (0.00005 ETH) and MAX_OP_COST_WEI (0.001 ETH). Emits OpCostSet
DEFAULT_ADMIN_ROLEgrantRole(role, account), revokeRole(role, account)Grants and revokes every role, its own included

Any holder can give up a role with renounceRole(role, ownAddress); hasRole(role, account) reads who holds one. At launch all three roles are held by the deployer, 0x1B0210b9695BbEB8bD70964A46bf512021127A73.

No role can read a note: notes are encrypted to their owners' viewing keys, and spending one needs its owner's keys and a fresh wallet signature. The guardian can stop spends, entries and exits to a target, and move the operation cost within its range; it cannot move or create shares. The upgrader replaces the code that runs against the vault's storage, so it decides every rule of the vault, the verifier among them.

Upgrades and the pause

Upgrades

PrivateVault is an OpenZeppelin UUPSUpgradeable implementation behind an ERC1967Proxy. The proxy holds the state and the ZERO; the implementation holds the code.

  • State. The proxy's storage is written once by initialize: the empty note tree, the operation cost and the roles. The implementation's own initializers are disabled in its constructor, so nobody can initialize it.
  • Immutables. Every address the vault works with is an immutable of the implementation, set in its constructor: ZERO, the Pons factory, the curve, the PoolManager, the graduated pool ID, the verifier, the hasher and the EntryPoint. A new verifier, or any other new address, comes with a new implementation.
  • Upgrade. A holder of UPGRADER_ROLE calls upgradeToAndCall(newImplementation, data) (_authorizeUpgrade checks the role). It takes effect in that transaction.
  • What an upgrade keeps. Everything in the proxy's storage: every note, the note tree and its root history, the totals B and S, the spent nullifiers, the registered keys, the pending exits, the price average and the network fee, the roles and the pause flags. The EntryPoint deposit and stake belong to the proxy's address, and so does the EIP-712 domain (verifyingContract is the proxy), so Spend and Register signatures stay valid.
  • Storage layout. An upgrade may only append storage variables after the existing ones.

The pause

pause() (OpenZeppelin PausableUpgradeable) stops every spend of a note until the guardian calls unpause(). It has no time limit. paused() reads it, and OpenZeppelin's Paused(account) and Unpaused(account) are emitted.

While pausedFunctions
Revert (EnforcedPause)transact, validateUserOp, execute4337, claimSale
Keep workingshield, donate, absorb, register, registerFor, poke, addStake, and every view

So private transfers, unshields, sales and payment-link claims all stop: a spend is refused as a whole, not only its exit, whether it goes through the ERC-4337 account, transact or PrivateRouter.sell. An exit already validated whose execution did not settle it stays held in pendingSales until the pause ends; anyone can then release it to its recipient with claimSale. Shielding, private buys (unless entries are paused too), donations, harvests and key registration go on.

setEntriesPaused and setTargetExitsPaused are narrower and independent of the general pause: the first stops only shield, the second only exits handed to a target. With exits to a target paused but no general pause, a holder can still unshield to an address and sell the public ZERO on any venue.

The locked seed and the first-depositor attack

In an empty ERC-4626-style vault, an attacker can deposit a tiny amount, then donate a large amount to inflate the share value so that the next depositor's shares round down to little or nothing. ZeroTrace has two defences:

  1. Virtual shares. V = 1e6 and the + 1 on B act as a permanent virtual deposit. Most of an inflating donation accrues to the virtual shares, so the attack costs the attacker more than it can take from a victim.
  2. The locked seed. Right after deploying the vault and its router, DeployV3.s.sol buys ZERO through the router with SEED_ETH (default 0.001 ETH) and shields it into a note whose stub is keccak256("zerotrace/locked-seed") mod p. Nobody knows a preimage, so the note is unspendable.

The seed also keeps early donations from being split with the virtual shares: with S = 0, a donation made before the first holder shields would accrue mostly to V and dilute the first holder. With the seed, early donations accrue to the seed note instead.

The seed's shares, and every donation that accrues to them, are locked forever. Its fraction of every donation is seed shares / S, which shrinks as more is shielded.

Invariants

These follow from the code paths above:

zero.balanceOf(vault) >= totalBacking + pendingSaleTotal
S                     = sum of shares in unspent notes                 (given a sound circuit)
(B + 1) / (S + V) never decreases

The first holds with equality unless someone sent ZERO to the vault with a plain transfer, and the next absorb restores it. Every path that moves ZERO into or out of the vault changes B or the exit escrow by the same amount: shield and donate pull exactly amount, an exit transfers exactly total - fee (or moves it to the escrow) and leaves fee in B, and an escrowed exit leaves either through the target's pull and a transfer of the rest to its recipient, or by a transfer of all of it to the recipient.

While an exit target runs, the exit's ZERO is partly or wholly still in the vault. execute4337 keeps the exit in pendingSaleTotal until the target has returned, so that ZERO never reads as ZERO that backs no note. shield, donate, absorb, transact, execute4337 and claimSale are nonReentrant (OpenZeppelin ReentrancyGuardTransient), so a target cannot call back into a function that moves the totals while it runs. poke stays open: the router calls it during a sale, and it only moves the price.

B is the total a holder can ever exit, at most. If the circuit or the contracts had a bug that let shares be created from nothing, every holder's share value would fall.

On this page