Integrations
What aggregators, wallets, exchanges, explorers and analytics tools need to know to support ZERO and the private side of ZeroTrace.
ZERO is an ordinary ERC-20. It is a Pons V2 token (OpenZeppelin ERC20 and ERC20Burnable, 18 decimals,
1,000,000,000 supply), with no owner, no hook of its own, no transfer rules and no special balance logic. Holding,
sending, trading, listing, bridging and custody need no special handling.
The private side is a separate contract, the PrivateVault, that holders opt into. It runs behind an ERC-1967
proxy: use the proxy's address, which stays the same when the implementation is upgraded. ZERO sent into the vault is
held there against encrypted notes; ZERO taken out is ordinary ZERO again. Integrators only need the vault if they
show private balances, index private activity, or count circulating supply.
Addresses are on Deployments.
Trading ZERO
ZERO trades on its Pons bonding curve until the curve has collected 4.2 ETH, then on the Pons Uniswap v4 pool (native ETH / ZERO, fee 0, tick spacing 200, the Pons meme hook). Both are standard Pons venues:
- Aggregators already route them. 0x and KyberSwap route Pons V2 tokens on Robinhood Chain, on the curve and on graduated pools. Nothing ZeroTrace-specific is needed to buy or sell ZERO.
- Fees are Pons fees. Every trade pays Pons' 1% standard fee, on the curve and on the pool alike; ZERO has no creator tax. Pons keeps 0.3%; the creator share, 0.7%, is paid in ETH to the ZeroTrace harvester, which sends half to the team and turns the other half into gas and ZERO for private holders. See Fees.
- Only the Pons pool counts. Only the Pons factory can initialize a pool with its hook. Other ETH/ZERO pools can exist with another fee, tick spacing or hook; they have another pool id, and ZeroTrace ignores them for trading and pricing.
Quoting and private buys
PrivateRouter.quote gives the output of a trade on whichever venue is live, Pons fees included:
function quote(bool isBuy, uint256 amountIn) external returns (uint256 amountOut);isBuy = true: ETH in, ZERO out. isBuy = false: ZERO in, ETH out. On the pool it runs the real swap and
reverts it, so it is not a view; call it with eth_call:
import { parseAbi, parseEther } from "viem";
const router = "0x…"; // PrivateRouter, see Deployments
const abi = parseAbi(["function quote(bool isBuy, uint256 amountIn) returns (uint256 amountOut)"]);
const { result: tokensOut } = await publicClient.simulateContract({
address: router,
abi,
functionName: "quote",
args: [true, parseEther("0.01")],
});PrivateRouter.buy buys straight into a private note in one transaction. An aggregator that wants to offer that
needs the buyer's note stub and ciphertext, which only the buyer's keys can make; see Notes.
Any other purchase delivers ordinary ZERO, which the holder can shield later.
Wallets and exchanges
A ZERO holder can have two balances:
| Balance | How to read it | Who can read it |
|---|---|---|
| Public | ZERO.balanceOf(address) | Anyone |
| Private (notes) | Rebuild the note tree from the vault's events and decrypt the notes with the user's viewing key | Only the owner |
A standard token integration shows the public balance correctly. Registering privacy keys does not change it:
ZERO only becomes private when the holder shields it (approve the vault, then shield), and becomes public again
when they unshield or sell privately to an address.
To show the private balance, a wallet must derive the user's privacy keys (one signature) and scan the notes. See The note tree and Your balance.
The keys that read the private balance come from a signature over a Sign-In with Ethereum message naming one domain and a vault address (the earlier vault's, so wallets keep their keys). Do not ask users to sign another site's key-derivation message: the result reveals all their notes. See Keys.
Deposits and withdrawals of an exchange are plain ZERO transfers. An unshield or a private sale to an exchange
deposit address arrives as a normal Transfer from the vault (for an unshield) or ETH from the router (for a
sale). A private sale whose swap fails delivers ZERO from the vault instead.
Token metadata: name zerotrace, symbol ZERO, decimals 18.
The private side
Supply
ZERO in the vault is not circulating. It backs the notes, and only the holder of a note can take it out.
ZERO.balanceOf(vault) is the sum of:
totalBacking: ZERO behind all notes, including the seed note locked at deployment, which nobody can spend, and the network fees operations pay, which stay in the vault as a donation to every note;pendingSaleTotal: ZERO of ERC-4337 exits validated but not yet settled (pendingSales). An exit is counted until its target has returned;- ZERO sent to the vault by plain transfer, until the next
absorbadds it tototalBacking.
The share of supply that is private is totalBacking over totalSupply.
Events
All on the vault unless noted. Listen to the vault's harvester, FeeHarvesterV3 (0xe2f2341AE7C0f8f520216001bc8B9087465Cf856), and to
the earlier ones, FeeHarvesterV2 (0x276B8ba2e38a5e1CB43FF3493e620CFF6cEC4878) and the launch harvester (0x8416DA7325cc619A5E560D8Ef6f413e94950CAd5): a
harvester that has handed the role on keeps harvesting the fees already credited to it. Harvested has the same
signature on all.
| Event | Use it for |
|---|---|
VaultUpdated(totalBacking, totalShares) | The share value (B + 1) / (S + 1e6) over time, and how much ZERO is private. Emitted after every vault change |
Donation(from, amount) | ZERO given to private holders: harvested creator fees from a harvester, network fees from the vault itself, and ZERO sent by plain transfer from the zero address (absorb) |
NoteAdded(index, commitment, ciphertext) | Tree size: the set every private balance hides among |
Shielded(from, index, amount, shares) | ZERO entering the vault: from is the user, or the router for a private purchase |
NullifierSpent(nullifier) | Private transactions: two per transaction |
Exited(nullifier, recipient, amount, shares) | ZERO leaving the vault: unshields and router sales |
SaleSettled(saleId, swapped) | ERC-4337 sales and other exits to a target; swapped = false means the ZERO went to the recipient instead |
PriceUpdated(tokensPerEthEma) | The vault's price average |
NetworkFeeUpdated(networkFee) | The network fee in ZERO, reset at most once an hour, and whenever the guardian sets the operation cost |
OpCostSet(opCostWei) | The guardian set what the network fee is worth in ETH, and the gas cap of an operation |
Paused(account), Unpaused(account) | The guardian pausing or resuming every spend of a note |
EntriesPaused(paused) | The guardian pausing or resuming new entries |
TargetExitsPaused(paused) | The guardian pausing or resuming exits handed to a target, such as ERC-4337 sales through the router |
RoleGranted, RoleRevoked | A role of the vault changing hands |
Upgraded(implementation) | The vault's proxy pointing at a new implementation |
KeysRegistered(owner, opk, viewKey) | Addresses that can receive private notes |
Bought, Sold on the router | Private purchases and sales |
Harvested(ethAvailable, ethToDeposit, ethSpent, tokensDonated), CallerTipped on the harvesters | Fee harvests, gas deposit top-ups and ZERO bought for the vault |
TeamShareAccrued, TeamPaid on FeeHarvesterV3 and FeeHarvesterV2 | The team's half of the creator fees |
FeeRecipientHandedOver(successor) on the harvesters | ZERO's creator fee recipient changed. On FeeHarvesterV3 it happens at once, from handOver |
SuccessorProposed, SuccessorCancelled on the earlier harvesters | A proposed change of ZERO's creator fee recipient, executable 24 hours later |
The app computes its headline numbers (notes, private transactions, share of supply that is private, holder yield, ZERO distributed, price, trade and holder fee rates, gas fund) from these events and a few reads.
A private transaction's public inputs are the root, two nullifiers, two new commitments, the exit shares,
extDataHash(ext) and the vault's EIP-712 domain separator in two 128-bit halves. publicInputs(t) on the vault
returns them in circuit order. See Contracts.
What not to assume
- The ERC-4337 sender is not the user. Private transactions are UserOperations whose
senderis the vault, submitted by a bundler. The EntryPoint'sUserOperationEventnames the vault for every one of them. - A transfer into the vault is not a sale or a burn. It is a shield (with
Shielded) or a donation (withDonation). A plain transfer to the vault is counted as a donation by the nextabsorb. - A transfer out of the vault is an exit. An unshield or sale (with
Exited), or a settled or claimed ERC-4337 exit (withSaleSettled). In the current implementation nothing else leaves the vault. - The network fee is not a constant. Read
networkFee()andmaxOpCostWei(); the guardian can set the latter between 0.00005 and 0.001 ETH. - The vault can be paused. While
paused()is true, no note can be spent: no private transfer, sale, unshield or payment-link claim. Shields and private buys still work unlessentriesPaused()is also true. - The vault's code can change. Its address stays the same, but the upgrader can point it at a new
implementation (
Upgraded). Read the ABI from the current implementation. - Holder counts miss private holders. A note does not show its owner or amount, so everything in the vault counts as one address.
- Harvester buys come from fees. Whenever someone calls
harvest, the harvester buys ZERO with the holders' half of the creator fees and donates it to the vault (Harvestedon the harvester,Donationon the vault). It buys at most once per L1 block, each buy sized to move the price by no more than 0.5%. - The team's revenue is half of the creator fees. The harvester pays it in ETH to the team's recipient
(
TeamPaid). Nothing from private operations goes to the team: network fees stay in the vault.
Contracts
Every external function, event, struct and error of PrivateVault, PrivateRouter, FeeHarvesterV3 and the Pons market code they share.
MCP server for agents
Give an AI agent its own private ZERO account. The ZeroTrace MCP server lets agents hold, pay, sell and get paid in ZERO on Robinhood Chain, signing with their own key.