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
| Field | Required value |
|---|---|
sender | The vault |
nonce | uint256(uint192(nf0)) << 64: key = low 192 bits of the first nullifier, sequence 0 |
initCode, paymasterAndData | Empty |
callData | abi.encodeCall(execute4337, (nf0)) |
signature | abi.encode(Transaction, proof) |
ext.caller | The vault |
ext.data | abi.encode(minCallGasLimit, exitTarget, recipient, exitData); exitTarget = 0 for anything but an exit to a target |
ext.recipient | Receives 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 GasCostAboveLimitThe 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:
- In validation, the exit
amount(after the fee) is stored inpendingSales[nf0] = Sale(amount, exitTarget, recipient, exitData), withnf0the first nullifier. An amount of zero reverts (InvalidUserOp), and so does a target with norecipient(ZeroAddress). - In execution,
execute4337(nf0)deletes the entry, approves the target for exactlyamountand callsIExitTarget(target).onPrivateExit(amount, recipient, exitData). The target pulls what it takes withtransferFrom. The vault then clears the approval, takesamountout ofpendingSaleTotal, sends what the target left torecipientas ZERO and emitsSaleSettled(nf0, true). - If the target reverts, its pull is undone with it, and the vault transfers the whole amount to
recipientand emitsSaleSettled(nf0, false).execute4337never reverts on a failed target. - If execution ran out of gas, the exit stays pending. Anyone may then call
claimSale(nf0), which transfers the ZERO torecipient.
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; execute4337does not call the target of an exit validated before the pause: it transfers the whole amount torecipientand emitsSaleSettled(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.
| Parameter | Value |
|---|---|
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_WEI | 0.00005 ETH and 0.001 ETH |
NETWORK_FEE_INTERVAL | 1 hour |
targetDeposit | Harvester immutable; 0.1 ETH |
Deposit and stake
- Deposit.
DeployV3.s.soldepositsGAS_DEPOSIT(default 0.1 ETH) for the vault. The harvester tops it up; anyone else can withEntryPoint.depositTo(vault). The vault has no function that callswithdrawTo: the deposit only pays for operations. - Stake.
PrivateVault.addStake(unstakeDelaySec)forwards ETH toEntryPoint.addStake, callable by anyone. The vault has nounlockStakeorwithdrawStakecall. 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
| Measure | Value |
|---|---|
Sale through handleOps | about 4.76M to 5.25M gas |
| Gas price on testnet | 0.01 gwei |
| End-to-end sale with Pimlico's public bundler | 9.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.
The market and the router
Where ZERO trades - its Pons bonding curve, then the Pons Uniswap v4 pool after graduation - how ZeroTrace identifies that pool, the price average the vault keeps, and PrivateRouter's buy, sell and quote.
ZERO on Pons
What ZERO is, the Pons V2 terms it trades under, who receives its fees and how to check them on-chain, and how the ZeroTrace contracts are deployed around it.