Contracts
Every external function, event, struct and error of PrivateVault, PrivateRouter, FeeHarvesterV3 and the Pons market code they share.
The ZeroTrace contracts are verified on the explorer. The vault, PrivateVault, runs behind an ERC-1967 proxy and
can be upgraded. Every other contract is deployed once, without a proxy, and every address it works with is fixed in
its constructor, except the harvester's team recipient.
The vault has three roles (OpenZeppelin AccessControl). The upgrader replaces the vault's implementation, with
no delay. The guardian pauses every spend of a note, pauses new entries, pauses exits handed to a target
contract, and sets the operation cost within a fixed range. The admin grants and revokes roles. The harvester's
owner changes who receives the team's half of the creator fees and can hand ZERO's creator fee recipient to
another contract at once. At launch the deployer holds all of them. See Trust model.
ZERO itself is not a ZeroTrace contract: it is a plain ERC-20 created by Pons V2 (see ZERO). Addresses are on Deployments; how the pieces fit is in Architecture.
Solidity ^0.8.26, compiled for the Cancun EVM, with OpenZeppelin Contracts and Contracts Upgradeable 5.7.0. The
vault is compiled at 200 optimizer runs to fit the contract size limit; the verifier and every other contract at
10,000. The verifier (HonkVerifier) is generated by Barretenberg 5.2.1 and not covered here beyond its interface.
| Contract | Role |
|---|---|
PrivateVault | Shielded ZERO, notes, keys, vault shares, price average, network fee, ERC-4337 account. Behind an ERC1967Proxy (UUPS) |
PrivateRouter | Private buys and sales in one transaction, quotes; the exit target of ERC-4337 sales |
FeeHarvesterV3 | The vault's harvester: half of the creator fees to the team, the other half into gas and ZERO for the vault |
FeeHarvesterV2, FeeHarvester | Earlier harvesters, with a 24-hour successor procedure instead of an immediate hand-over |
PonsSwapper, PonsMarket | Trading and pricing on the Pons curve or the graduated pool, shared by the router and the harvesters |
PoseidonMerkleTree | The note tree, inherited by the vault |
ZERO
ZERO is a Pons PonsV2LauncherToken: OpenZeppelin ERC20 plus ERC20Burnable, 18 decimals, a fixed supply of
1,000,000,000 minted into its bonding curve at launch, no owner and no transfer restrictions. ZeroTrace adds nothing
to it. Name zerotrace, symbol ZERO.
PrivateVault
The private side of ZERO. Shielding moves ZERO into the vault and creates an encrypted note; unshielding moves it
back out. Inside, notes are spent with a zero-knowledge proof and a signature by the owner's wallet. The vault is
also the ERC-4337 account that carries private transactions. It inherits PoseidonMerkleTree, OpenZeppelin
EIP712, ReentrancyGuardTransient, UUPSUpgradeable, AccessControlUpgradeable and PausableUpgradeable, and
IAccount.
Proxy and initializer
The vault's address, 0xEE92d20c1b0AAA686DDc8809A1B6A67aB092eb33, is an OpenZeppelin ERC1967Proxy. It holds all the state and delegates
every call to the current implementation (0xBc08FAd89f924e1A852D271061977d0fCE40A559 at deployment). Users, integrators and
the app only ever use the proxy's address.
// the implementation
constructor(
string memory name_, // EIP-712 domain name (the deploy passes TOKEN_NAME, "zerotrace")
IERC20 zero_,
IPonsFactory ponsFactory_,
IPonsCurve curve_,
IPoolManager poolManager_,
PoolId poolId_, // the Pons graduated pool
IVerifier verifier_,
IPoseidon2 hasher_,
IEntryPoint entryPoint_
);
// the proxy's state, written once through the proxy's constructor
function initialize(
uint256 maxOpCostWei_, // the operation cost at the start (0.0002 ether), within the range below
address admin, // DEFAULT_ADMIN_ROLE
address upgrader, // UPGRADER_ROLE
address guardian_ // GUARDIAN_ROLE
) external;The constructor reverts ZeroAddress without ZERO or the verifier and disables the implementation's initializers,
so the implementation itself can never be initialized. The addresses it takes are immutables of the implementation,
readable as zero(), ponsFactory(), curve(), poolManager(), poolId(), verifier(), hasher() and
entryPoint(): a new verifier comes with a new implementation.
initialize runs once (InvalidInitialization after that). It reverts ZeroAddress if a role address is zero and
OpCostOutOfRange if maxOpCostWei_ is outside [MIN_OP_COST_WEI, MAX_OP_COST_WEI]. It writes the empty note
tree, sets opCostWei and previousOpCostWei to maxOpCostWei_, and grants the three roles (RoleGranted for
each).
An upgrade keeps everything in the proxy's storage: every note, the note tree, the totals, the nullifiers, the
registered keys, the pending exits and the price average. The EntryPoint deposit and the EIP-712 domain belong to the
proxy's address, so the gas deposit stays and signatures stay valid. A new implementation may only append storage
variables. The EIP-712 version is "1", and eip712Domain() names the proxy as the verifying contract.
Structs
struct Transaction {
uint256 root; // a root of the note tree the proof was made against
uint256[2] nullifiers; // one per input note (dummies included)
uint256[2] commitments; // one per output note (dummies included)
uint256 exitShares; // shares leaving the private side, network fee included
ExtData ext;
}
/// Bound to the proof through extDataHash: nobody can change it after the wallet signs.
struct ExtData {
address recipient; // receives exitShares - gasFee, converted to ZERO
address caller; // if non-zero, only this address may submit (the router; the vault itself for ERC-4337)
uint256 gasFee; // shares, out of exitShares, donated to every note as the network fee
bytes data; // parameters for `caller`: router sale terms, or the ERC-4337 fields
bytes ciphertext0; // encrypted data of output note 0
bytes ciphertext1; // encrypted data of output note 1
}
struct Keys {
uint256 opk; // owner public key, H(nk, wallet key)
bytes32 viewKey; // X25519 public key for note encryption
}
/// An exit applied in validation and settled in execution by the target the proof names.
struct Sale {
uint256 amount; // ZERO in escrow
address target; // the IExitTarget, e.g. the PrivateRouter
address recipient; // gets whatever the target does not take
bytes data; // passed to the target
}What goes in ext.data depends on ext.caller:
ext.caller | ext.data |
|---|---|
address(0) | anything; anyone may submit the transaction to transact |
PrivateRouter | abi.encode(address ethRecipient, uint256 minEthOut) for sell |
| the vault itself | abi.encode(uint256 minCallGasLimit, address exitTarget, address recipient, bytes exitData) for ERC-4337 |
For an ERC-4337 sale, exitTarget is the router, recipient the ETH recipient, exitData is
abi.encode(uint256 minEthOut), and ext.recipient is zero. Without an exit target (exitTarget == address(0)),
the exit goes to ext.recipient at once and recipient and exitData are ignored.
Key registry
function register(uint256 opk, bytes32 viewKey) external;
function registerFor(address owner, uint256 opk, bytes32 viewKey, uint256 deadline, bytes calldata signature) external;
function keysOf(address owner) external view returns (uint256 opk, bytes32 viewKey);
function registerNonces(address owner) external view returns (uint256);| Function | Description |
|---|---|
register | Registers the caller's owner key and viewing key. opk must be non-zero and below the field modulus. Calling it again replaces the keys |
registerFor | Same for owner, with an EIP-712 signature (EOA or ERC-1271) that anyone can submit. Reverts SignatureExpired after deadline, InvalidSignature for a bad signature |
keysOf | The registered keys; opk == 0 means not registered |
registerNonces | Next nonce of owner for registerFor |
The registerFor typed data is
Register(address owner,uint256 opk,bytes32 viewKey,uint256 nonce,uint256 deadline) under the vault's EIP-712
domain. Registering lets others send you private notes; it changes nothing about ZERO held publicly. See
Keys.
Roles, pause and upgrades
function DEFAULT_ADMIN_ROLE() external view returns (bytes32); // 0x00
function UPGRADER_ROLE() external view returns (bytes32); // keccak256("UPGRADER_ROLE")
function GUARDIAN_ROLE() external view returns (bytes32); // keccak256("GUARDIAN_ROLE")
function hasRole(bytes32 role, address account) external view returns (bool);
function getRoleAdmin(bytes32 role) external view returns (bytes32);
function grantRole(bytes32 role, address account) external;
function revokeRole(bytes32 role, address account) external;
function renounceRole(bytes32 role, address callerConfirmation) external;
function supportsInterface(bytes4 interfaceId) external view returns (bool);
function pause() external;
function unpause() external;
function paused() external view returns (bool);
function upgradeToAndCall(address newImplementation, bytes memory data) external payable;
function proxiableUUID() external view returns (bytes32);
function UPGRADE_INTERFACE_VERSION() external view returns (string memory); // "5.0.0"| Function | Description |
|---|---|
hasRole | Whether account holds role |
getRoleAdmin | The role that grants and revokes role: DEFAULT_ADMIN_ROLE for all three, itself included |
grantRole / revokeRole | Admin only (AccessControlUnauthorizedAccount). Gives or takes a role, to or from any address. A role can be held by several addresses. Emit RoleGranted / RoleRevoked |
renounceRole | Any holder gives up its own role; callerConfirmation must be the caller (AccessControlBadConfirmation). Emits RoleRevoked |
pause | Guardian only. Stops every spend of a note until unpause, with no time limit: transact, validateUserOp, execute4337 and claimSale revert EnforcedPause. That stops private transfers, unshields, sales and payment-link claims, and an exit waiting in escrow stays there until the pause ends. A spend is refused as a whole, not only its exit. Emits Paused(account); reverts EnforcedPause if already paused |
unpause | Guardian only. Ends the pause. Emits Unpaused(account); reverts ExpectedPause if not paused |
paused | Whether spends are paused |
upgradeToAndCall | Upgrader only, and only through the proxy (UUPSUnauthorizedCallContext otherwise). Points the proxy at newImplementation, at once, then delegatecalls data on it if data is not empty. The new implementation must answer proxiableUUID with the ERC-1967 implementation slot (UUPSUnsupportedProxiableUUID if it answers otherwise, ERC1967InvalidImplementation if it does not answer). Emits Upgraded(newImplementation) |
proxiableUUID | The ERC-1967 implementation slot. Answers on the implementation only; through the proxy it reverts UUPSUnauthorizedCallContext |
While the vault is paused, shield, donate, absorb, register, registerFor, poke, addStake and every
read keep working, so private buys through the router still create notes. PrivateRouter.sell reverts, since it
spends through transact.
function MIN_OP_COST_WEI() external view returns (uint256); // 0.00005 ether
function MAX_OP_COST_WEI() external view returns (uint256); // 0.001 ether
function entriesPaused() external view returns (bool);
function targetExitsPaused() external view returns (bool);
function opCostWei() external view returns (uint128);
function previousOpCostWei() external view returns (uint128);
function maxOpCostWei() external view returns (uint256);
function setEntriesPaused(bool paused) external;
function setTargetExitsPaused(bool paused) external;
function setOpCost(uint256 newOpCostWei) external;| Function | Description |
|---|---|
entriesPaused | While true, shield reverts EntriesArePaused, and so do private buys through the router |
targetExitsPaused | While true, no exit is handed to a target. validateUserOp reverts TargetExitsArePaused for an operation that names an exit target, and execute4337 pays an exit already validated to its recipient without calling the target |
opCostWei | The operation cost in wei: what the network fee is worth in ETH, and the most an operation paying the current fee may charge the deposit |
previousOpCostWei | The cost that goes with previousNetworkFee. Equal to opCostWei except between a setOpCost and the next fee reset |
maxOpCostWei | Returns opCostWei |
setEntriesPaused | Guardian only (AccessControlUnauthorizedAccount). Pauses or resumes shield. Emits EntriesPaused |
setTargetExitsPaused | Guardian only. Pauses or resumes exits through a target contract: sales through the router, or any other target. Emits TargetExitsPaused |
setOpCost | Guardian only. Sets opCostWei within [MIN_OP_COST_WEI, MAX_OP_COST_WEI] (OpCostOutOfRange otherwise). If a price average exists it resets the network fee at once; the cost it replaced becomes previousOpCostWei. Emits OpCostSet |
The guardian's functions never move a note or ZERO. The upgrader's do not either, but the implementation it installs decides everything the vault does from then on, including what happens to the ZERO it holds.
Private side
function shield(uint256 stub, uint256 amount, bytes calldata ciphertext) external returns (uint32 index);
function donate(uint256 amount) external;
function absorb() external returns (uint256 amount);
function transact(Transaction calldata t, bytes calldata proof) external;
function nullifierSpent(uint256 nullifier) external view returns (bool);
function publicInputs(Transaction calldata t) external view returns (bytes32[] memory);
function extDataHash(ExtData memory ext) external pure returns (uint256);| Function | Description |
|---|---|
shield | Reverts EntriesArePaused while entries are paused. Pulls amount ZERO from the caller with transferFrom (approve the vault first) and creates a note completed with stub = H(opk, rho, r). Returns the leaf index. The router uses it for private buys |
donate | Pulls amount ZERO from the caller and adds it to totalBacking without minting shares, which raises the value of every share. The harvester donates through it |
absorb | Anyone. Adds ZERO that reached the vault by a plain transfer (the balance above totalBacking + pendingSaleTotal) to totalBacking, and emits Donation from the zero address. Returns 0 and changes nothing when there is none. The harvester calls it on every harvest |
transact | Spends up to two notes and creates two, with a proof; optionally exits shares as ZERO to ext.recipient. If ext.caller is set, only that address may call (WrongCaller). Reverts EnforcedPause while the vault is paused |
nullifierSpent | Whether a nullifier has been used |
publicInputs | The 9 public inputs of the proof, in circuit order: root, 2 nullifiers, 2 commitments, exit shares, extDataHash, and the EIP-712 domain separator as two 128-bit halves |
extDataHash | keccak256(abi.encode(ext)) mod FIELD |
shield, donate, absorb and transact are nonReentrant, with execute4337 and claimSale (OpenZeppelin
ReentrancyGuardTransient): none of them can be entered while another is running, so an exit target cannot call
them during its onPrivateExit. They revert ReentrancyGuardReentrantCall in that case.
An exit converts exitShares to ZERO at the share price. The network fee's shares (ext.gasFee) are burned with
the rest, but their ZERO stays in totalBacking: a donation to every remaining note, emitted as
Donation(address(this), fee). The recipient gets convertToAssets(exitShares) - convertToAssets(gasFee).
A note created by shield carries its share amount on-chain only (in Shielded), because the shares are known
only when the transaction runs. See Notes and The circuit.
Vault
function totalBacking() external view returns (uint256); // B: ZERO behind all notes
function totalShares() external view returns (uint256); // S: shares in all notes
function convertToShares(uint256 assets) external view returns (uint256);
function convertToAssets(uint256 shares) external view returns (uint256);convertToShares(a) = a * (S + VIRTUAL_SHARES) / (B + 1) and
convertToAssets(s) = s * (B + 1) / (S + VIRTUAL_SHARES), rounding down. The vault's ZERO balance is
totalBacking plus pendingSaleTotal plus ZERO sent by plain transfer and not yet absorbed. See
The vault.
Note tree
Inherited from PoseidonMerkleTree.
function root() external view returns (uint256);
function isKnownRoot(uint256 root) external view returns (bool);
function nextLeafIndex() external view returns (uint32);
function treeNumber() external view returns (uint32);
function isFinalRoot(uint256 root) external view returns (bool);
function hasher() external view returns (address);| Function | Description |
|---|---|
root | Current root |
isKnownRoot | True for any of the last 64 roots and for the final root of every full tree; false for 0 |
nextLeafIndex | Next free leaf in the current tree. Leaves are always inserted in pairs, so it is even |
treeNumber | Number of full trees before the current one |
isFinalRoot | Whether a root is the final root of a full tree (valid forever) |
hasher | The Poseidon2 contract |
See The Merkle tree.
ERC-4337 account
function validateUserOp(PackedUserOperation calldata op, bytes32 userOpHash, uint256 missingAccountFunds)
external returns (uint256 validationData);
function execute4337(uint256 saleId) external;
function claimSale(uint256 saleId) external;
function addStake(uint32 unstakeDelaySec) external payable;
function pendingSales(uint256 saleId)
external view returns (uint256 amount, address target, address recipient, bytes memory data);
function pendingSaleTotal() external view returns (uint256);| Function | Description |
|---|---|
validateUserOp | EntryPoint only (NotEntryPoint); reverts EnforcedPause while the vault is paused. Decodes abi.encode(Transaction, proof) from op.signature and applies the whole private transaction. Returns 1 (failed signature) for an invalid proof without writing anything, so a placeholder proof can be used to estimate gas. An exit to a target is kept in escrow (pendingSales, keyed by the first nullifier) |
execute4337 | EntryPoint only, nonReentrant, not while paused. Settles the operation's exit, if any: approves the target for exactly the amount and calls IExitTarget(target).onPrivateExit(amount, recipient, data). Whatever the target leaves, read from the remaining allowance, goes to the recipient as ZERO; everything does if the target reverts. The approval is cleared afterwards, and only then does the amount leave pendingSaleTotal. While targetExitsPaused, the target is not called and everything goes to the recipient. Never reverts on a failed target |
claimSale | Anyone, nonReentrant, not while paused. If an exit's execution ran out of gas, transfers its ZERO to the recipient. Reverts NoSuchSale if none is pending |
addStake | Anyone can add EntryPoint stake for the vault. The implementation has no function that unlocks it |
pendingSales | Exits validated but not settled, keyed by first nullifier |
pendingSaleTotal | Sum of the pending exits' ZERO: in the vault, no longer backing any note. An exit is counted from validation until its target has returned |
The operation must satisfy all of these, in this order, or validation reverts:
- the vault is not paused (
EnforcedPause); - the caller is the EntryPoint (
NotEntryPoint); ext.calleris the vault itself (WrongCaller);- no
initCodeand nopaymasterAndData(InvalidUserOp); callDatais exactlyexecute4337(t.nullifiers[0])(InvalidUserOp);nonceisuint192(t.nullifiers[0]) << 64, one nonce key per first nullifier (InvalidUserOp);callGasLimitis at least theminCallGasLimitinext.data(InvalidUserOp);- the maximum cost,
(verificationGasLimit + callGasLimit + preVerificationGas) * maxFeePerGas, is at most the higher ofopCostWeiandpreviousOpCostWei(GasCostAboveLimit); convertToAssets(ext.gasFee)is at least the lower ofnetworkFeeandpreviousNetworkFee(InsufficientGasFee;NoPricewhile no fee is set);- the fee and the cost go together: the operation pays at least
networkFeeand costs at mostopCostWei, or pays at leastpreviousNetworkFeeand costs at mostpreviousOpCostWei(GasCostAboveLimit); - an exit target is not named while
targetExitsPaused(TargetExitsArePaused); - an exit target comes with a non-zero
recipient(ZeroAddress), and exits a non-zero amount (InvalidUserOp).
Validation reads only the vault's own storage: no price is read there. See Gas.
Price average and network fee
function poke() external;
function tokensPerEthEma() external view returns (uint256);
function lastSpot() external view returns (uint192);
function lastPriceBlock() external view returns (uint64);
function networkFee() external view returns (uint128);
function previousNetworkFee() external view returns (uint128);
function networkFeeSetAt() external view returns (uint64);| Function | Description |
|---|---|
poke | Anyone. Reads the live market price (the curve's reserves before graduation, the graduated pool's slot0 after) and records it. The first update of a block folds the previous update's price into the average, clamped to ±10% of the average, with weight 1/8. The first price ever seeds the average. Does nothing while neither venue is live. Also sets the network fee, see below. The router and the harvester call it on every trade |
tokensPerEthEma | Moving average of the price, ZERO per ETH scaled by 1e18. 0 before the first price |
lastSpot / lastPriceBlock | Price at the latest update and its block; it enters the average when a later block is first poked |
networkFee | The network fee in ZERO: opCostWei * tokensPerEthEma / 1e18 (at least 1). 0 before the first price |
previousNetworkFee | The fee it replaced, still accepted until the next update |
networkFeeSetAt | When networkFee was last set |
poke sets the network fee when none is set yet or NETWORK_FEE_INTERVAL (1 hour) has passed since
networkFeeSetAt, and emits NetworkFeeUpdated; setOpCost sets it too, whatever the time. An operation must pay
at least the lower of the two fees, so one signed just before an update still goes through. Every operation pays a
fee worth an operation cost at the price average and may charge the deposit at most that same cost, so filling
bundles with one's own operations does not drain the deposit.
The vault also exposes eip712Domain() (ERC-5267, from OpenZeppelin EIP712), and the constants
TREE_DEPTH, ROOT_HISTORY_SIZE, VIRTUAL_SHARES, NETWORK_FEE_INTERVAL, MAX_PRICE_STEP_BPS,
MIN_OP_COST_WEI and MAX_OP_COST_WEI (values on Constants).
Events
event KeysRegistered(address indexed owner, uint256 opk, bytes32 viewKey);
event NoteAdded(uint256 indexed index, uint256 commitment, bytes ciphertext);
event Shielded(address indexed from, uint256 indexed index, uint256 amount, uint256 shares);
event Exited(uint256 indexed nullifier, address indexed recipient, uint256 amount, uint256 shares);
event NullifierSpent(uint256 indexed nullifier);
event Donation(address indexed from, uint256 amount);
event PriceUpdated(uint256 tokensPerEthEma);
event NetworkFeeUpdated(uint256 networkFee);
event SaleSettled(uint256 indexed saleId, bool swapped);
event VaultUpdated(uint256 totalBacking, uint256 totalShares);
event EntriesPaused(bool paused);
event TargetExitsPaused(bool paused);
event OpCostSet(uint256 opCostWei);
event TreeCompleted(uint256 indexed treeNumber, uint256 finalRoot); // from PoseidonMerkleTree
// from OpenZeppelin
event Paused(address account);
event Unpaused(address account);
event RoleGranted(bytes32 indexed role, address indexed account, address indexed sender);
event RoleRevoked(bytes32 indexed role, address indexed account, address indexed sender);
event Upgraded(address indexed implementation);
event Initialized(uint64 version);| Event | When |
|---|---|
KeysRegistered | register or registerFor |
NoteAdded | A leaf from shield or transact, with its encrypted note data |
Shielded | shield: from is who shielded (the user, or the router for a purchase), index the leaf it created, shares the note's share amount |
Exited | ZERO left the private side to ext.recipient; nullifier is the transaction's first nullifier, shares the exited shares without the fee. Not emitted for an exit to a target, which SaleSettled closes |
NullifierSpent | Twice per private transaction, once per nullifier |
Donation | donate: harvested creator fees, from the harvester; an operation's network fee, from the vault itself; absorb: ZERO sent by plain transfer, from the zero address |
PriceUpdated | The price average changed |
NetworkFeeUpdated | poke or setOpCost set a new network fee |
SaleSettled | An exit to a target settled: swapped is true if the target's call succeeded, false if the ZERO went to the recipient instead (the target reverted, target exits were paused, or claimSale) |
VaultUpdated | totalBacking and totalShares after every change |
EntriesPaused | The guardian paused or resumed entries |
TargetExitsPaused | The guardian paused or resumed exits handed to a target |
OpCostSet | The guardian set the operation cost |
TreeCompleted | A tree filled up; its final root stays valid and a new tree starts at index 0 |
Paused / Unpaused | The guardian paused or resumed every spend; account is the guardian that called |
RoleGranted / RoleRevoked | A role changed hands: sender is the admin that granted or revoked it, or the holder that renounced it. Emitted for each role at initialization |
Upgraded | The proxy points at a new implementation (also at deployment, from the proxy's constructor) |
Initialized | initialize ran on the proxy (version 1) |
ZERO's own Transfer events show every movement into and out of the vault, as for any ERC-20.
Errors
| Error | Cause |
|---|---|
ZeroAddress | Constructor with no ZERO or verifier, initialize with a zero role address, an exit with no recipient, or an exit target with no recipient |
NotAFieldElement | A stub, commitment, nullifier, exit amount or opk at or above the field modulus (or opk == 0) |
ZeroShares | An amount too small to mint a single share |
UnknownRoot | The proof's root is not in the root history nor a final root |
NullifierAlreadySpent / DuplicateNullifier | A note already spent, or the same nullifier twice in one transaction |
InvalidProof | The verifier rejected the proof (direct transact only; ERC-4337 returns a failed signature instead) |
InvalidSignature / SignatureExpired | registerFor signature invalid or past its deadline |
WrongCaller | ext.caller is set and is not msg.sender (or not the vault, for ERC-4337) |
FeeExceedsExit | ext.gasFee > exitShares |
NotEntryPoint | validateUserOp or execute4337 not called by the EntryPoint |
InvalidUserOp | A UserOperation that breaks one of the rules above |
InsufficientGasFee | The network fee paid is below the lower of the current and previous fee |
GasCostAboveLimit | The operation's maximum gas cost is above the operation cost that goes with the fee it pays |
EntriesArePaused | shield while entries are paused |
TargetExitsArePaused | An ERC-4337 operation names an exit target while exits to a target are paused |
OpCostOutOfRange | initialize or setOpCost with a cost outside [MIN_OP_COST_WEI, MAX_OP_COST_WEI] |
NoPrice | No network fee yet: the vault has not read a price |
NoSuchSale | claimSale for an exit that is not pending |
From OpenZeppelin:
| Error | Cause |
|---|---|
AccessControlUnauthorizedAccount(account, neededRole) | A role function called by an address without the role |
AccessControlBadConfirmation | renounceRole with a callerConfirmation that is not the caller |
EnforcedPause / ExpectedPause | A spend, or pause, while paused / unpause while not paused |
InvalidInitialization | initialize called a second time, or on the implementation |
UUPSUnauthorizedCallContext | upgradeToAndCall not called through the proxy, or proxiableUUID called through it |
UUPSUnsupportedProxiableUUID(slot) / ERC1967InvalidImplementation(implementation) | An upgrade to a contract that is not a UUPS implementation |
ReentrancyGuardReentrantCall | A nonReentrant function entered while another is running |
ZERO transfers go through OpenZeppelin SafeERC20, so a missing approval or balance reverts with ZERO's own
ERC-20 error.
PrivateRouter
Buys ZERO straight into a note and sells a note straight to ETH, in one transaction. It trades on the Pons curve
until graduation and on the Pons v4 pool after. It holds no funds between transactions, and is the exit target of
private sales made through the vault's ERC-4337 account. Its vault is the vault's proxy. See
Buy and Sell.
constructor(IPoolManager poolManager_, IPonsFactory ponsFactory_, PrivateVault vault_, address token);
function vault() external view returns (address);
function buy(uint256 stub, uint256 minTokensOut, bytes calldata ciphertext)
external payable returns (uint32 leafIndex, uint256 tokensOut);
function sell(PrivateVault.Transaction calldata t, bytes calldata proof) external returns (uint256 ethOut);
function onPrivateExit(uint256 amount, address ethRecipient, bytes calldata data) external;
function quote(bool isBuy, uint256 amountIn) external returns (uint256 amountOut);
// and everything of PonsSwapper, below| Function | Description |
|---|---|
buy | Spends msg.value ETH on ZERO, shields it into a note completed with stub, and pokes the price. Reverts InsufficientOutput below minTokensOut, and EntriesArePaused from the vault while entries are paused. A buy that crosses graduation can leave ETH unspent: it is returned to the caller |
sell | Spends notes with a proof through the vault's transact, exits the shares to the router and sells the ZERO for ETH sent to ethRecipient. The transaction must name the router as both ext.caller and ext.recipient (NotRoutedHere otherwise), with ext.data = abi.encode(ethRecipient, minEthOut). Reverts EnforcedPause from the vault while it is paused |
onPrivateExit | IExitTarget, vault only (NotVault). Settles an ERC-4337 sale: decodes data as abi.encode(uint256 minEthOut), pulls the amount ZERO the vault has just approved, sells it and sends the ETH to ethRecipient. If it reverts, the vault sends the ZERO to ethRecipient instead |
quote | Output of trading amountIn now (ETH in for a buy, ZERO in for a sale), Pons fees included. On the pool it runs the real swap and reverts it; on the curve it computes from the reserves and fee rates. Not a view: call it with eth_call |
Swaps are exact-input with no price limit; minTokensOut and minEthOut are the only protection. Every trade pokes
the vault's price.
event Bought(uint32 indexed leafIndex, uint256 ethIn, uint256 tokensOut);
event Sold(address indexed ethRecipient, uint256 tokensIn, uint256 ethOut);
error InsufficientOutput();
error NotRoutedHere();
error EthTransferFailed();
error NotVault();FeeHarvesterV3
The vault's harvester (0xe2f2341AE7C0f8f520216001bc8B9087465Cf856), and ZERO's Pons creator fee recipient once the hand-over to it has
executed, so the creator share of every Pons trade fee (0.7% of each trade) comes here in ETH. It splits every ETH it
collects in half: TEAM_SHARE_BPS (50%) is owed to the team's recipient, 0.35% of each trade; the other half is the
private holders', which keeps the vault's gas deposit funded and buys ZERO donated to the vault. A harvester serves
the one vault in its Config. See Gas, The vault and
Deployments.
struct Config {
IPoolManager poolManager;
IPonsFactory ponsFactory;
IPonsFeeEscrow feeEscrow;
IEntryPoint entryPoint;
PrivateVault vault; // the vault's proxy
uint256 targetDeposit; // 0.1 ether, read from the previous harvester at deployment
}
constructor(Config memory config, address token, address owner_, address teamRecipient_);
// token: ZERO, a Pons launch paired with ETH
// owner_: may change the team's recipient and hand the fee recipient over (zero for none)
// teamRecipient_: receives the team's half (zero lets it accrue until one is set)The constructor reads Pons' record of the token, ponsFactory.getLaunchedToken(token), and reverts unless Pons
launched it (NotAPonsLaunch) and pairs it with native ETH (NotAnEthPair). It then records ZERO, its curve and the
graduated pool key, and emits OwnershipTransferred(address(0), owner_) and
TeamRecipientChanged(address(0), teamRecipient_). The token need not pay this contract yet: Pons moves the creator
fee recipient here when the previous harvester hands it over.
function TEAM_SHARE_BPS() external view returns (uint256); // 5_000
function MAX_IMPACT_BPS() external view returns (uint256); // 50
function MAX_PREMIUM_BPS() external view returns (uint256); // 1_500
function CALLER_TIP_BPS() external view returns (uint256); // 50
function GAS_OVERHEAD() external view returns (uint256); // 25_000
function owner() external view returns (address);
function teamRecipient() external view returns (address);
function teamOwed() external view returns (uint256);
function lastBuyBlock() external view returns (uint256);
function entryPoint() external view returns (address);
function feeEscrow() external view returns (address);
function vault() external view returns (address);
function targetDeposit() external view returns (uint256);
function harvest() external returns (uint256 tokensDonated);
function payTeam() external;
function claimable() external view returns (uint256);
function setTeamRecipient(address newRecipient) external;
function handOver(address successor) external;
function transferOwnership(address newOwner) external;
// and everything of PonsSwapper, below| Function | Description |
|---|---|
harvest | Anyone. Collects the creator fees, accrues the team's half, tops up the gas deposit, makes at most one small buy for the vault and pays the team; see below. Returns the ZERO donated |
payTeam | Anyone. Pays teamOwed to teamRecipient. Never reverts: if the recipient is zero or refuses the ETH, the amount stays owed |
claimable | ETH the next harvest would have for the holders: the escrow balance less the team's half, plus ETH held, less teamOwed. Fees Pons has yet to sweep are not counted |
setTeamRecipient | Owner only (NotOwner). Sets who receives the team's half from now on and pays it what is owed |
handOver | Owner only. Makes successor ZERO's creator fee recipient at once, through Pons' transferCreatorFeeRecipient(zero, successor), and emits FeeRecipientHandedOver. Reverts NoSuccessor for address(0). There is no delay and no proposal. Fees already credited here stay claimable by harvest |
transferOwnership | Owner only. address(0) renounces ownership; the team's recipient and the fee recipient can then never change again |
harvest, payTeam and setTeamRecipient are guarded against reentrancy (OpenZeppelin
ReentrancyGuardTransient). harvest() runs in this order:
Collect. Graduates the curve or seeds the pool if that is due, sweeps the fees Pons holds for ZERO
(sweepPoolFees on the hook after graduation, sweepFees on the curve before), and claims the ETH from the fee
escrow. Each sweep is wrapped in try, so none of them can block the harvest.
Team share. TEAM_SHARE_BPS (50%) of the ETH just collected is added to teamOwed (TeamShareAccrued).
The holders' ETH is the balance less teamOwed; the team's share is never spent on gas or ZERO. Then pokes the
price and calls the vault's absorb.
Tip reserve. Sets aside CALLER_TIP_BPS (0.5%) of the holders' ETH for the caller's refund.
Gas deposit. Tops up the vault's EntryPoint deposit to targetDeposit (0.1 ETH), ETH first.
Buy and donate. At most one buy per L1 block (lastBuyBlock). The size starts at the rest of the ETH,
capped at what moves the price by about MAX_IMPACT_BPS (0.5%): on the pool, from its active liquidity; on the
curve, from its ETH reserve. The buy must return at least the larger of two bounds, after Pons fees: the spot
price less half of MAX_IMPACT_BPS, and the vault's price average less MAX_PREMIUM_BPS (15%). A size that does
not fit is halved, over up to 8 sizes. The ZERO is donated to the vault and the price poked again; ETH that does
not fit waits for the next harvest.
Refund and pay. Emits Harvested. If the call put ETH to work (deposited or spent), refunds the caller its
measured gas plus GAS_OVERHEAD (25,000) at min(tx.gasprice, 2 * block.basefee), capped at 0.5% of the ETH
put to work (CallerTipped). Then pays the team (TeamPaid).
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%, for at most the 0.5% it moves the price. A call that does nothing earns nothing, so calling
harvest in a loop pays nobody. ETH sent to the harvester directly, outside the fee escrow, is not split: it counts
for the holders.
event Harvested(uint256 ethAvailable, uint256 ethToDeposit, uint256 ethSpent, uint256 tokensDonated);
event TeamShareAccrued(uint256 amount);
event TeamPaid(address indexed recipient, uint256 amount);
event TeamRecipientChanged(address indexed previousRecipient, address indexed newRecipient);
event CallerTipped(address indexed caller, uint256 amount);
event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);
event FeeRecipientHandedOver(address indexed successor);
error EthTransferFailed(); // the caller refused its refund
error NotOwner();
error NoSuccessor();
error NotAPonsLaunch();
error NotAnEthPair();In Harvested, ethAvailable is the holders' ETH after collecting; ethToDeposit and ethSpent are what the call
put to work, and tokensDonated the ZERO it gave the vault.
Earlier harvesters
Two earlier harvesters exist. Both hand ZERO's creator fee recipient on through a public successor procedure instead
of handOver:
function SUCCESSOR_DELAY() external view returns (uint256); // 24 hours
function pendingSuccessor() external view returns (address);
function successorReadyAt() external view returns (uint256);
function proposeSuccessor(address successor) external; // owner only; executable from now + SUCCESSOR_DELAY
function cancelSuccessor() external; // owner only
function executeSuccessor() external; // anyone, once successorReadyAt has passed
event SuccessorProposed(address indexed successor, uint256 readyAt);
event SuccessorCancelled(address indexed successor);
event FeeRecipientHandedOver(address indexed successor);
error SuccessorNotReady(uint256 readyAt);proposeSuccessor reverts NoSuccessor for address(0), and a new proposal replaces the pending one.
executeSuccessor reverts NoSuccessor with no proposal and SuccessorNotReady(readyAt) before the delay has
passed; it then calls Pons' transferCreatorFeeRecipient and emits FeeRecipientHandedOver. A harvester that has
handed the role on keeps harvesting the fees already credited to it.
FeeHarvesterV2(0x276B8ba2e38a5e1CB43FF3493e620CFF6cEC4878) is otherwise identical toFeeHarvesterV3. Its owner proposedFeeHarvesterV3as its successor when the vault was deployed; it receives ZERO's creator fees until that proposal is executed, 24 hours later.FeeHarvester(0x8416DA7325cc619A5E560D8Ef6f413e94950CAd5), the launch harvester, has the same interface without the team share: noTEAM_SHARE_BPS,teamRecipient,teamOwed,setTeamRecipient,payTeam,TeamShareAccrued,TeamPaidorTeamRecipientChanged, and its constructor is(Config, token, owner_). It is not reentrancy-guarded. It has no per-block or impact limit (nolastBuyBlock,MAX_IMPACT_BPSorMAX_PREMIUM_BPS): its buy must land withinMAX_SLIPPAGE_BPS(300, 3%) of what the price average predicts after Pons fees, halving over up to 8 sizes.Harvestedhas the same signature, withethAvailableall the ETH it holds;claimable()is the escrow balance plus ETH held.
Both serve the earlier vault named in their Config.
NoteRefund
Refunds the notes that were unspent in the earlier vault (0xf3935bec6247170B28e1755c85957A72f243D84D) at its last state, block 86632173,
each once, into notes of the vault. Address: 0x702DF8c7b312b06Fc6947Faf788C5deF7776DBE1, an ERC-1967 proxy (UUPS) with the same three
roles as the vault. See Refund of the earlier vault.
A note of s shares is owed what an exit would have paid at that state:
function refundOf(uint256 shares) public view returns (uint256) {
return shares * (BACKING + 1) / (SHARES + VIRTUAL_SHARES); // VIRTUAL_SHARES = 1e6
}ROOT, BACKING and SHARES are immutables of the implementation: the earlier vault's note-tree root, total backing
and total shares at that block (see Constants).
A claim
A claim is a proof of the transact circuit, checked by the vault's verifier, with the vault's Transaction layout:
| Field | In a claim |
|---|---|
root | ROOT; any other root is refused |
nullifiers | The notes' nullifiers. Each is refunded once (claimed), and none spent in the earlier vault before that state (spentBefore, fixed at initialization) |
commitments | Ignored: nothing is inserted anywhere |
exitShares | The shares refunded: the whole of the input notes |
ext.caller | NoteRefund itself |
ext.gasFee | 0: a claim pays no fee |
ext.data | abi.encode(uint256 minCallGasLimit, uint256 stub, bytes ciphertext): the note to create in the vault |
The proof's EIP-712 domain is NoteRefund's own (name = "zerotrace refund"), so a proof made for the vault is not
valid here, nor one made here on the vault.
ERC-4337 account
function validateUserOp(PackedUserOperation calldata op, bytes32, uint256 missingAccountFunds)
external whenNotPaused returns (uint256);
function execute4337(uint256 claimId) external;
function payout(uint256 claimId) external;validateUserOptakesabi.encode(Transaction, proof)inop.signature;op.callDatamust beexecute4337(nullifiers[0])and the nonce keynullifiers[0]. It checks the claim and the operation's maximum gas cost againstopCostWei, verifies the proof (an invalid one returnsSIG_VALIDATION_FAILEDand writes nothing), marks both nullifiers claimed and records the refund inpending[nullifiers[0]]. The account's EntryPoint deposit pays the gas.execute4337shields the recorded refund into the vault withvault.shield(stub, amount, ciphertext). If the vault refuses it (its entries paused), the refund stays recorded (PayoutDeferred).- A refund above
REVIEW_THRESHOLD(10,000,000 ZERO) is not shielded inexecute4337: it becomes payableREVIEW_DELAY(24 hours) later (PayoutHeld). The delay starts in execution, because ERC-4337 validation may not read the block time. payoutpays a recorded refund: one the vault refused, or one above the threshold once its delay has passed (before that it reverts withPayoutNotDue; on such a refund whose delay has not started, it starts it). Anyone may call it.
ZERO leave the contract only as refunds, except in an emergency: emergencyWithdraw and withdrawDeposit (below).
Roles and initializer
function initialize(uint256 maxOpCostWei_, address admin, address upgrader, address guardian, uint256[] calldata spentBefore_) external;
function pause() external; // GUARDIAN_ROLE
function unpause() external; // GUARDIAN_ROLE
function setOpCost(uint256 newOpCostWei) external; // GUARDIAN_ROLE, within [0.00005, 0.001] ETH
function stopPayout(uint256 claimId) external; // GUARDIAN_ROLE
function resumePayout(uint256 claimId) external; // GUARDIAN_ROLE
function emergencyWithdraw(IERC20 token, address to, uint256 amount) external; // DEFAULT_ADMIN_ROLE, while paused
function withdrawDeposit(address payable to, uint256 amount) external; // DEFAULT_ADMIN_ROLE, while paused
function upgradeToAndCall(address newImplementation, bytes calldata data) external payable; // UPGRADER_ROLEIt starts paused: claims open when the guardian unpauses it. The pause stops validateUserOp, execute4337 and
payout. stopPayout stops one recorded refund until resumePayout: payout reverts with PayoutIsStopped, the
refund stays recorded and its ZERO stay in the contract. Resuming keeps the time the refund's delay started.
Views
| Function | Returns |
|---|---|
refundOf(uint256 shares) | The refund of shares |
claimed(uint256 nullifier) | Whether the nullifier was refunded here |
spentBefore(uint256 nullifier) | Whether it was spent in the earlier vault before that state |
pending(uint256 claimId) | A refund recorded and not paid yet: amount, stub, ciphertext, payableAt (set when a refund above the threshold starts its delay), stopped |
REVIEW_THRESHOLD(), REVIEW_DELAY() | 10,000,000 ZERO and 24 hours |
pendingTotal() | ZERO owed to recorded refunds |
opCostWei() | The most a claim may charge the gas deposit |
publicInputs(Transaction) | The claim's public inputs, in the circuit's order |
extDataHash(ExtData) | uint256(keccak256(abi.encode(ext))) % FIELD, as in the vault |
Events and errors
| Event | When |
|---|---|
Claimed(uint256 indexed claimId, uint256 shares, uint256 amount) | A claim validated; claimId is its first nullifier |
Refunded(uint256 indexed claimId, uint256 amount, uint32 index) | The refund shielded into the vault, at leaf index |
PayoutDeferred(uint256 indexed claimId) | The vault refused the shield; the refund stays recorded |
PayoutHeld(uint256 indexed claimId, uint256 amount, uint256 payableAt) | A refund above the threshold, payable from payableAt |
PayoutStopped(uint256 indexed claimId), PayoutResumed(uint256 indexed claimId) | The guardian stopped or resumed a refund |
OpCostSet(uint256 opCostWei) | The guardian set the cost cap |
EmergencyWithdrawal(address indexed token, address indexed to, uint256 amount) | The admin withdrew tokens |
DepositWithdrawn(address indexed to, uint256 amount) | The admin withdrew from the EntryPoint deposit |
Errors: WrongRoot, DuplicateNullifier, SpentBeforeTheState, AlreadyClaimed, NothingToRefund,
NotAFieldElement, GasCostAboveLimit, OpCostOutOfRange, WrongCaller, InvalidUserOp, NotEntryPoint,
NoSuchPayout, PayoutNotDue, PayoutIsStopped, ZeroAddress, and OpenZeppelin's EnforcedPause and
AccessControlUnauthorizedAccount.
PonsSwapper and PonsMarket
PonsMarket is a library that says which venue is live and what its price is; PonsSwapper is the abstract
contract the router and the harvesters inherit to trade there.
function poolManager() external view returns (address);
function ponsFactory() external view returns (address);
function zero() external view returns (address);
function curve() external view returns (address);
function poolId() external view returns (PoolId);
function poolKey() external view returns (PoolKey memory);
function spotPrice() external view returns (uint256);
function onPool() external view returns (bool);
function unlockCallback(bytes calldata data) external returns (bytes memory);
receive() external payable;| Function | Description |
|---|---|
poolKey / poolId | The graduated pool: native ETH / ZERO, the launch's poolFee and tickSpacing, and ponsFactory.memeHook(). A pool with any other key has another id and is never used |
spotPrice | ZERO per ETH, 1e18 scale, at the live venue: the pool's slot0 after graduation, the curve's reserves before, 0 in between |
onPool | Whether the factory reports ZERO's phase as PoolCreated |
unlockCallback | PoolManager only (NotPoolManager) |
The phases come from factory.getLaunchedToken(zero).phase: 0 not graduated (curve), 1 swept, 2 pool
created. Before every trade, PonsSwapper calls graduate if the curve reports readyToGraduate(), and
createGraduatedPool if the phase is swept. Both are permissionless on the Pons factory.
A curve quote is computed from getReserves(), feeBps(), creatorTaxBps() and, for buys, the opening
currentSnipeTaxBps(recipient), capped at sellableTokens(). A pool quote runs the swap inside unlock and
reverts with Quote(amountOut).
error NotPoolManager();
error Quote(uint256 amountOut); // internal: carries the quote out of the reverted swapInterfaces
// the verifier
interface IVerifier {
function verify(bytes calldata proof, bytes32[] calldata publicInputs) external view returns (bool);
}
// where an ERC-4337 exit goes: implemented by PrivateRouter, called by PrivateVault.execute4337
interface IExitTarget {
function onPrivateExit(uint256 amount, address recipient, bytes calldata data) external;
}
// Pons: lets the current creator fee recipient hand the role on at once (used by the harvesters)
interface IPonsFactoryRecipient {
function transferCreatorFeeRecipient(address token, address newRecipient) external;
}An exit target may pull up to amount ZERO, which the vault has just approved; whatever it leaves, or everything if
it reverts, goes to recipient as ZERO. Any contract can be one: a sale router, or anything the note owner names in
the proof.
The contracts call these parts of Pons V2: on the factory getLaunchedToken, memeHook, graduate,
createGraduatedPool and transferCreatorFeeRecipient; on the curve buy, sell, getReserves,
sellableTokens, feeBps, creatorTaxBps, currentSnipeTaxBps, readyToGraduate and sweepFees; on the meme
hook sweepPoolFees; on the fee escrow claim and balanceOf. getLaunchedToken returns the PonsLaunchedToken
struct.
The ERC-4337 types are those of v0.8 (PackedUserOperation, IAccount, IEntryPoint), with the same ABI.
FallbackHasher is an optional Poseidon2 hasher that tries a Stylus program first and falls back to the EVM hasher.
Deployments do not use it: they use the Yul hasher.
Deployments
Network details, the addresses of the vault, its router and harvester, the Pons contracts ZERO trades on, and the public bundler of ZeroTrace on Robinhood Chain.
Integrations
What aggregators, wallets, exchanges, explorers and analytics tools need to know to support ZERO and the private side of ZeroTrace.