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
| Symbol | Storage | Meaning |
|---|---|---|
| B | totalBacking | ZERO backing all notes |
| S | totalShares | Shares held by all unspent notes |
| V | VIRTUAL_SHARES = 1e6 | Virtual 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 shareBoth 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
| Path | What 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.buy | The 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 -= amountThe 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:
| Source | Event | Amount |
|---|---|---|
| The harvester's buys | Donation(harvester, amount) | The ZERO bought with the holders' half of the creator fees, after the gas deposit and the caller's refund |
| Network fees | Donation(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 |
| Anyone | Donation(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:
| Fee | Rate | Where it goes |
|---|---|---|
| Standard fee | curve.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 tax | curve.creatorTaxBps(): 0 for ZERO | All 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):
| Half | Share of each trade | Use |
|---|---|---|
| The team's | 0.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 owedEach 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 Chainblock.numberfollows 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 /= 2The 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_000The 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
| Parameter | Value |
|---|---|
TEAM_SHARE_BPS | 5000 (50%) of each ETH collected, to the team |
targetDeposit | Immutable; 0.1 ETH |
MAX_IMPACT_BPS | 50 (0.5%) most a buy may move the price |
MAX_PREMIUM_BPS | 1500 (15%): a buy must get at least 85% of the ZERO the price average gives, after fees |
CALLER_TIP_BPS | 50 (0.5%) cap on the caller's refund, of the ETH put to work |
GAS_OVERHEAD | 25,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:
| Function | Effect |
|---|---|
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):
| Role | Functions | Effect |
|---|---|---|
UPGRADER_ROLE | upgradeToAndCall(newImplementation, data) | Replaces the implementation behind the proxy, with no timelock. See Upgrades |
GUARDIAN_ROLE | pause(), 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_ROLE | grantRole(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_ROLEcallsupgradeToAndCall(newImplementation, data)(_authorizeUpgradechecks 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 (
verifyingContractis the proxy), soSpendandRegistersignatures 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 paused | Functions |
|---|---|
Revert (EnforcedPause) | transact, validateUserOp, execute4337, claimSale |
| Keep working | shield, 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:
- Virtual shares. V = 1e6 and the
+ 1on 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. - The locked seed. Right after deploying the vault and its router,
DeployV3.s.solbuys ZERO through the router withSEED_ETH(default 0.001 ETH) and shields it into a note whose stub iskeccak256("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 decreasesThe 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.
The transact circuit
The one zero-knowledge circuit behind every private spend - its inputs, constraints, public inputs, ExtData binding, sizes and toolchain.
The market and the router
Where ZERO trades - its Pons bonding curve, then the Pons Uniswap v4 pool after graduation - how ZeroTrace identifies that pool, the price average the vault keeps, and PrivateRouter's buy, sell and quote.