zerotracedocs

Gas and ERC-4337

How the vault pays for its users' gas as its own ERC-4337 account, what validation checks, the flat network fee and the cost cap, how exits to a target such as a sale settle, and how the fee harvester keeps the deposit funded.

A private transaction must not be signed or paid for by the user's address: that would link the address to the spend. So PrivateVault is itself an ERC-4337 account. Anyone's bundler submits the operation, the canonical EntryPoint v0.8 pays the bundler from the vault's deposit, and the user pays a flat network fee in shares out of the notes being spent, which goes to every holder.

The UserOperation

FieldRequired value
senderThe vault
nonceuint256(uint192(nf0)) << 64: key = low 192 bits of the first nullifier, sequence 0
initCode, paymasterAndDataEmpty
callDataabi.encodeCall(execute4337, (nf0))
signatureabi.encode(Transaction, proof)
ext.callerThe vault
ext.dataabi.encode(minCallGasLimit, exitTarget, recipient, exitData); exitTarget = 0 for anything but an exit to a target
ext.recipientReceives a direct exit; ignored when the exit goes to a target (the app sets it to zero)

Any other value of the other fields makes validateUserOp revert (WrongCaller, InvalidUserOp). One nonce key per first nullifier means operations from different users never queue behind each other, and each nullifier is usable once anyway.

Validation does the whole transition

function validateUserOp(PackedUserOperation calldata op, bytes32, uint256 missingAccountFunds)
    external returns (uint256 validationData);

function execute4337(uint256 saleId) external;

validateUserOp, callable only by the EntryPoint (NotEntryPoint), reverts while the vault is paused (EnforcedPause; see The pause). Otherwise, in order:

Decodes the transaction and proof and checks the fields in the table above.

Requires callGasLimit >= minCallGasLimit. The minimum is inside ext.data, bound to the proof, so a bundler cannot starve an exit's execution. The other gas fields are free, because bundlers replace them when estimating.

Checks that the operation's maximum gas cost fits the operation cost and that the fee pays the network fee that goes with it (below).

Refuses an operation that names an exit target while the guardian has paused exits to a target (TargetExitsArePaused).

Runs the private transition: root, nullifiers, proof, nullifiers marked spent, both commitments inserted, the fee's shares burned with its ZERO left to every note, and the exit transferred or, for an exit target, put in escrow.

Execution only settles exits to a target. Because every state change already happened in validation, a failing execution cannot undo it, and nobody can make the deposit pay for an operation that did nothing.

The network fee and the cost cap

maxCost = (verificationGasLimit + callGasLimit + preVerificationGas) * maxFeePerGas        wei
fee     = convertToAssets(ext.gasFee)                                                       ZERO

require   maxCost <= max(opCostWei, previousOpCostWei)                                     else GasCostAboveLimit
require   min(networkFee, previousNetworkFee) != 0                                         else NoPrice
require   fee >= min(networkFee, previousNetworkFee)                                       else InsufficientGasFee
require   (fee >= networkFee         and maxCost <= opCostWei)
       or (fee >= previousNetworkFee and maxCost <= previousOpCostWei)                     else GasCostAboveLimit

The network fee is flat: networkFee is worth the operation cost opCostWei in ZERO at tokensPerEthEma, the moving average of ZERO's market price kept by the vault (see The market). poke() sets it again at most once per NETWORK_FEE_INTERVAL (1 hour), and the fee it replaces, previousNetworkFee, stays accepted until the next update, so an operation signed just before an update still goes through. ERC-7562 forbids reading the curve or the pool during validation, but the vault's own storage is allowed: poke() reads the market outside validation, and validateUserOp reads only the stored fee. With no fee yet (nobody has poked) validation reverts (NoPrice).

opCostWei is 0.0002 ETH at deployment and is read through maxOpCostWei(). The guardian can set it with setOpCost(newOpCostWei) between MIN_OP_COST_WEI (0.00005 ETH) and MAX_OP_COST_WEI (0.001 ETH), or the call reverts (OpCostOutOfRange). setOpCost resets networkFee from the average at once, keeps the fee and the cost it replaced in previousNetworkFee and previousOpCostWei, and emits OpCostSet. Each fee goes with its own cost: until the next fee reset, an operation may pay the replaced fee and is then held to the replaced cost. So an operation signed before the change still goes through, and none can charge the deposit more than it pays. The next hourly reset makes the two costs equal again.

The fee's shares are burned and its ZERO stays in the vault: a donation from the vault itself to every remaining note. The gas itself is paid by the vault's EntryPoint deposit, which the harvester refills with the holders' half of the Pons creator fees (below).

The cap and the fee's value are equal on purpose. The cap uses the operation's actual fields, whatever a bundler sets, so an operation can never charge the deposit more ETH than the ZERO its fee leaves to holders is worth at the price average: filling bundles with one's own operations to empty the deposit does not pay. When gas prices rise so far that an operation's maximum cost no longer fits the cap, the vault refuses it and the user retries later.

Estimating with a placeholder proof

An invalid proof does not revert: validateUserOp returns SIG_VALIDATION_FAILED (1), as ERC-4337 expects of a bad signature, and writes nothing. The EntryPoint refuses to execute such an operation. This lets a wallet ask a bundler for gas estimates with a random 9,152-byte placeholder proof, then have the wallet sign once and prove once with the final gas numbers. The other checks (root, nullifiers, cost cap, fee, fields) still revert, so the estimate is realistic.

The app's defaults: verification gas limit 5,500,000, call gas 650,000 for a sale and 60,000 otherwise.

Exits to a target: escrow, settlement, fallback

An operation can name an exit target, a contract that receives the exit in execution: the router for a private sale, or any contract implementing IExitTarget. The target cannot run in validation, because ERC-7562 forbids touching the curve or the pool there. So:

  1. In validation, the exit amount (after the fee) is stored in pendingSales[nf0] = Sale(amount, exitTarget, recipient, exitData), with nf0 the first nullifier. An amount of zero reverts (InvalidUserOp), and so does a target with no recipient (ZeroAddress).
  2. In execution, execute4337(nf0) deletes the entry, approves the target for exactly amount and calls IExitTarget(target).onPrivateExit(amount, recipient, exitData). The target pulls what it takes with transferFrom. The vault then clears the approval, takes amount out of pendingSaleTotal, sends what the target left to recipient as ZERO and emits SaleSettled(nf0, true).
  3. If the target reverts, its pull is undone with it, and the vault transfers the whole amount to recipient and emits SaleSettled(nf0, false). execute4337 never reverts on a failed target.
  4. If execution ran out of gas, the exit stays pending. Anyone may then call claimSale(nf0), which transfers the ZERO to recipient.

The exit stays in pendingSaleTotal until the target has returned: its ZERO is still in the vault while the target runs, and absorb counts as a donation only the balance above totalBacking + pendingSaleTotal. The target is a contract of the spender's choosing, so shield, donate, absorb, transact, execute4337 and claimSale are nonReentrant (OpenZeppelin ReentrancyGuardTransient) and revert if the target calls them while it runs. poke is not guarded: the router calls it during a sale, and it only moves the price.

The guardian can pause exits to a target with setTargetExitsPaused(true). While they are paused:

  • validation reverts for an operation that names an exit target (TargetExitsArePaused). Nothing is spent;
  • execute4337 does not call the target of an exit validated before the pause: it transfers the whole amount to recipient and emits SaleSettled(nf0, false);
  • an operation with no exit target, such as a send or an unshield, is not affected, and neither is a direct call to transact.

The general pause (pause()) is wider: while it lasts, validateUserOp, execute4337, claimSale and transact all revert (EnforcedPause), so no spend goes through on any path, and an exit already in pendingSales stays there until the pause ends.

interface IExitTarget {
    function onPrivateExit(uint256 amount, address recipient, bytes calldata data) external;
}

function claimSale(uint256 saleId) external;
function pendingSales(uint256 saleId)
    external view returns (uint256 amount, address target, address recipient, bytes memory data);

For a private sale the target is PrivateRouter, recipient is the address that receives the ETH, and the exit data is abi.encode(minEthOut). The router pulls the ZERO, sells it on the live venue and sends the ETH; if the price moved past minEthOut, there is no liquidity or the ETH transfer fails, it reverts and the recipient gets the ZERO instead.

claimSale can also be called by another operation in the same bundle before an exit executes. A sale then arrives at the recipient as public ZERO instead of ETH. The caller gains nothing; the recipient can sell from there. This is an accepted limit: the EntryPoint exposes no "same transaction" signal.

The deposit and the harvester

The EntryPoint deposit pays every operation's gas. Every harvest() first tops it up to targetDeposit (0.1 ETH) from the holders' half of the Pons creator fees, and only then spends what is left on ZERO for the vault (full detail in The vault). The team's half is never spent on gas.

ParameterValue
opCostWei (maxOpCostWei())PrivateVault storage; 0.0002 ETH at deployment: the cost cap, and the network fee's value. Set by the guardian within the two constants below
MIN_OP_COST_WEI, MAX_OP_COST_WEI0.00005 ETH and 0.001 ETH
NETWORK_FEE_INTERVAL1 hour
targetDepositHarvester immutable; 0.1 ETH

Deposit and stake

  • Deposit. DeployV3.s.sol deposits GAS_DEPOSIT (default 0.1 ETH) for the vault. The harvester tops it up; anyone else can with EntryPoint.depositTo(vault). The vault has no function that calls withdrawTo: the deposit only pays for operations.
  • Stake. PrivateVault.addStake(unstakeDelaySec) forwards ETH to EntryPoint.addStake, callable by anyone. The vault has no unlockStake or withdrawStake call.
  • missingAccountFunds. Normally zero, since the deposit pays. If it is not, the vault tries to pay from its own ETH balance; if that fails, the EntryPoint rejects the operation and the bundler drops it.

One sender for everyone

Every private transaction is a UserOperation with the same sender, the vault; the nonce key is the transaction's first nullifier, so operations of different users never queue behind each other. Bundlers limit how many operations of one sender they hold: ERC-7562 allows an unstaked sender 4 in the mempool (SAME_SENDER_MEMPOOL_COUNT), and a staked one has no limit.

Alto, the bundler behind Pimlico's endpoint, was run in front of a fork with a ZeroTrace deployment. It accepted the vault's validation and, with 3-second blocks, took six users' private sends at once, bundling operations of the vault together, with no stake. Traced with the ERC-7562 collector, the validation uses no banned opcode and touches only the vault's own storage, plus the code of the verifier, the hasher and two libraries.

The vault is not staked at deploy: the vault has no call to unlock stake, and the bundler that serves Robinhood Chain does not need it. If a bundler ever does, anyone can stake the vault with addStake.

If the deposit is empty or no bundler serves the vault, users can still submit transact directly or sell through PrivateRouter.sell, paying gas from an address of their choice, unless the vault is paused. See Architecture.

Measured on testnet

MeasureValue
Sale through handleOpsabout 4.76M to 5.25M gas
Gas price on testnet0.01 gwei
End-to-end sale with Pimlico's public bundler9.4 s, one wallet signature

These were measured on the testnet deployment (chain 46630), which predates the Pons model: the same circuit and the same ERC-4337 validation flow, with ZERO held in the token contract itself rather than in a separate vault, a fee priced from each operation's maximum gas rather than the flat network fee, and sales swapped on a ZeroTrace pool. Validation passed Pimlico's ERC-7562 simulation there. Current values are in Constants.

On this page