zerotracedocs

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.

ContractRole
PrivateVaultShielded ZERO, notes, keys, vault shares, price average, network fee, ERC-4337 account. Behind an ERC1967Proxy (UUPS)
PrivateRouterPrivate buys and sales in one transaction, quotes; the exit target of ERC-4337 sales
FeeHarvesterV3The vault's harvester: half of the creator fees to the team, the other half into gas and ZERO for the vault
FeeHarvesterV2, FeeHarvesterEarlier harvesters, with a 24-hour successor procedure instead of an immediate hand-over
PonsSwapper, PonsMarketTrading and pricing on the Pons curve or the graduated pool, shared by the router and the harvesters
PoseidonMerkleTreeThe 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.callerext.data
address(0)anything; anyone may submit the transaction to transact
PrivateRouterabi.encode(address ethRecipient, uint256 minEthOut) for sell
the vault itselfabi.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);
FunctionDescription
registerRegisters the caller's owner key and viewing key. opk must be non-zero and below the field modulus. Calling it again replaces the keys
registerForSame for owner, with an EIP-712 signature (EOA or ERC-1271) that anyone can submit. Reverts SignatureExpired after deadline, InvalidSignature for a bad signature
keysOfThe registered keys; opk == 0 means not registered
registerNoncesNext 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"
FunctionDescription
hasRoleWhether account holds role
getRoleAdminThe role that grants and revokes role: DEFAULT_ADMIN_ROLE for all three, itself included
grantRole / revokeRoleAdmin only (AccessControlUnauthorizedAccount). Gives or takes a role, to or from any address. A role can be held by several addresses. Emit RoleGranted / RoleRevoked
renounceRoleAny holder gives up its own role; callerConfirmation must be the caller (AccessControlBadConfirmation). Emits RoleRevoked
pauseGuardian 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
unpauseGuardian only. Ends the pause. Emits Unpaused(account); reverts ExpectedPause if not paused
pausedWhether spends are paused
upgradeToAndCallUpgrader 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)
proxiableUUIDThe 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;
FunctionDescription
entriesPausedWhile true, shield reverts EntriesArePaused, and so do private buys through the router
targetExitsPausedWhile 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
opCostWeiThe 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
previousOpCostWeiThe cost that goes with previousNetworkFee. Equal to opCostWei except between a setOpCost and the next fee reset
maxOpCostWeiReturns opCostWei
setEntriesPausedGuardian only (AccessControlUnauthorizedAccount). Pauses or resumes shield. Emits EntriesPaused
setTargetExitsPausedGuardian only. Pauses or resumes exits through a target contract: sales through the router, or any other target. Emits TargetExitsPaused
setOpCostGuardian 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);
FunctionDescription
shieldReverts 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
donatePulls 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
absorbAnyone. 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
transactSpends 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
nullifierSpentWhether a nullifier has been used
publicInputsThe 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
extDataHashkeccak256(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);
FunctionDescription
rootCurrent root
isKnownRootTrue for any of the last 64 roots and for the final root of every full tree; false for 0
nextLeafIndexNext free leaf in the current tree. Leaves are always inserted in pairs, so it is even
treeNumberNumber of full trees before the current one
isFinalRootWhether a root is the final root of a full tree (valid forever)
hasherThe 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);
FunctionDescription
validateUserOpEntryPoint 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)
execute4337EntryPoint 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
claimSaleAnyone, 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
addStakeAnyone can add EntryPoint stake for the vault. The implementation has no function that unlocks it
pendingSalesExits validated but not settled, keyed by first nullifier
pendingSaleTotalSum 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.caller is the vault itself (WrongCaller);
  • no initCode and no paymasterAndData (InvalidUserOp);
  • callData is exactly execute4337(t.nullifiers[0]) (InvalidUserOp);
  • nonce is uint192(t.nullifiers[0]) << 64, one nonce key per first nullifier (InvalidUserOp);
  • callGasLimit is at least the minCallGasLimit in ext.data (InvalidUserOp);
  • the maximum cost, (verificationGasLimit + callGasLimit + preVerificationGas) * maxFeePerGas, is at most the higher of opCostWei and previousOpCostWei (GasCostAboveLimit);
  • convertToAssets(ext.gasFee) is at least the lower of networkFee and previousNetworkFee (InsufficientGasFee; NoPrice while no fee is set);
  • the fee and the cost go together: the operation pays at least networkFee and costs at most opCostWei, or pays at least previousNetworkFee and costs at most previousOpCostWei (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);
FunctionDescription
pokeAnyone. 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
tokensPerEthEmaMoving average of the price, ZERO per ETH scaled by 1e18. 0 before the first price
lastSpot / lastPriceBlockPrice at the latest update and its block; it enters the average when a later block is first poked
networkFeeThe network fee in ZERO: opCostWei * tokensPerEthEma / 1e18 (at least 1). 0 before the first price
previousNetworkFeeThe fee it replaced, still accepted until the next update
networkFeeSetAtWhen 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);
EventWhen
KeysRegisteredregister or registerFor
NoteAddedA leaf from shield or transact, with its encrypted note data
Shieldedshield: from is who shielded (the user, or the router for a purchase), index the leaf it created, shares the note's share amount
ExitedZERO 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
NullifierSpentTwice per private transaction, once per nullifier
Donationdonate: 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
PriceUpdatedThe price average changed
NetworkFeeUpdatedpoke or setOpCost set a new network fee
SaleSettledAn 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)
VaultUpdatedtotalBacking and totalShares after every change
EntriesPausedThe guardian paused or resumed entries
TargetExitsPausedThe guardian paused or resumed exits handed to a target
OpCostSetThe guardian set the operation cost
TreeCompletedA tree filled up; its final root stays valid and a new tree starts at index 0
Paused / UnpausedThe guardian paused or resumed every spend; account is the guardian that called
RoleGranted / RoleRevokedA role changed hands: sender is the admin that granted or revoked it, or the holder that renounced it. Emitted for each role at initialization
UpgradedThe proxy points at a new implementation (also at deployment, from the proxy's constructor)
Initializedinitialize 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

ErrorCause
ZeroAddressConstructor with no ZERO or verifier, initialize with a zero role address, an exit with no recipient, or an exit target with no recipient
NotAFieldElementA stub, commitment, nullifier, exit amount or opk at or above the field modulus (or opk == 0)
ZeroSharesAn amount too small to mint a single share
UnknownRootThe proof's root is not in the root history nor a final root
NullifierAlreadySpent / DuplicateNullifierA note already spent, or the same nullifier twice in one transaction
InvalidProofThe verifier rejected the proof (direct transact only; ERC-4337 returns a failed signature instead)
InvalidSignature / SignatureExpiredregisterFor signature invalid or past its deadline
WrongCallerext.caller is set and is not msg.sender (or not the vault, for ERC-4337)
FeeExceedsExitext.gasFee > exitShares
NotEntryPointvalidateUserOp or execute4337 not called by the EntryPoint
InvalidUserOpA UserOperation that breaks one of the rules above
InsufficientGasFeeThe network fee paid is below the lower of the current and previous fee
GasCostAboveLimitThe operation's maximum gas cost is above the operation cost that goes with the fee it pays
EntriesArePausedshield while entries are paused
TargetExitsArePausedAn ERC-4337 operation names an exit target while exits to a target are paused
OpCostOutOfRangeinitialize or setOpCost with a cost outside [MIN_OP_COST_WEI, MAX_OP_COST_WEI]
NoPriceNo network fee yet: the vault has not read a price
NoSuchSaleclaimSale for an exit that is not pending

From OpenZeppelin:

ErrorCause
AccessControlUnauthorizedAccount(account, neededRole)A role function called by an address without the role
AccessControlBadConfirmationrenounceRole with a callerConfirmation that is not the caller
EnforcedPause / ExpectedPauseA spend, or pause, while paused / unpause while not paused
InvalidInitializationinitialize called a second time, or on the implementation
UUPSUnauthorizedCallContextupgradeToAndCall 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
ReentrancyGuardReentrantCallA 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
FunctionDescription
buySpends 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
sellSpends 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
onPrivateExitIExitTarget, 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
quoteOutput 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
FunctionDescription
harvestAnyone. 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
payTeamAnyone. Pays teamOwed to teamRecipient. Never reverts: if the recipient is zero or refuses the ETH, the amount stays owed
claimableETH 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
setTeamRecipientOwner only (NotOwner). Sets who receives the team's half from now on and pays it what is owed
handOverOwner 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
transferOwnershipOwner 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 to FeeHarvesterV3. Its owner proposed FeeHarvesterV3 as 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: no TEAM_SHARE_BPS, teamRecipient, teamOwed, setTeamRecipient, payTeam, TeamShareAccrued, TeamPaid or TeamRecipientChanged, and its constructor is (Config, token, owner_). It is not reentrancy-guarded. It has no per-block or impact limit (no lastBuyBlock, MAX_IMPACT_BPS or MAX_PREMIUM_BPS): its buy must land within MAX_SLIPPAGE_BPS (300, 3%) of what the price average predicts after Pons fees, halving over up to 8 sizes. Harvested has the same signature, with ethAvailable all 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:

FieldIn a claim
rootROOT; any other root is refused
nullifiersThe notes' nullifiers. Each is refunded once (claimed), and none spent in the earlier vault before that state (spentBefore, fixed at initialization)
commitmentsIgnored: nothing is inserted anywhere
exitSharesThe shares refunded: the whole of the input notes
ext.callerNoteRefund itself
ext.gasFee0: a claim pays no fee
ext.dataabi.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;
  • validateUserOp takes abi.encode(Transaction, proof) in op.signature; op.callData must be execute4337(nullifiers[0]) and the nonce key nullifiers[0]. It checks the claim and the operation's maximum gas cost against opCostWei, verifies the proof (an invalid one returns SIG_VALIDATION_FAILED and writes nothing), marks both nullifiers claimed and records the refund in pending[nullifiers[0]]. The account's EntryPoint deposit pays the gas.
  • execute4337 shields the recorded refund into the vault with vault.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 in execute4337: it becomes payable REVIEW_DELAY (24 hours) later (PayoutHeld). The delay starts in execution, because ERC-4337 validation may not read the block time.
  • payout pays a recorded refund: one the vault refused, or one above the threshold once its delay has passed (before that it reverts with PayoutNotDue; 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_ROLE

It 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

FunctionReturns
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

EventWhen
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;
FunctionDescription
poolKey / poolIdThe 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
spotPriceZERO per ETH, 1e18 scale, at the live venue: the pool's slot0 after graduation, the curve's reserves before, 0 in between
onPoolWhether the factory reports ZERO's phase as PoolCreated
unlockCallbackPoolManager 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 swap

Interfaces

// 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.

On this page