zerotracedocs

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:

BalanceHow to read itWho can read it
PublicZERO.balanceOf(address)Anyone
Private (notes)Rebuild the note tree from the vault's events and decrypt the notes with the user's viewing keyOnly 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 absorb adds it to totalBacking.

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.

EventUse 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, RoleRevokedA 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 routerPrivate purchases and sales
Harvested(ethAvailable, ethToDeposit, ethSpent, tokensDonated), CallerTipped on the harvestersFee harvests, gas deposit top-ups and ZERO bought for the vault
TeamShareAccrued, TeamPaid on FeeHarvesterV3 and FeeHarvesterV2The team's half of the creator fees
FeeRecipientHandedOver(successor) on the harvestersZERO's creator fee recipient changed. On FeeHarvesterV3 it happens at once, from handOver
SuccessorProposed, SuccessorCancelled on the earlier harvestersA 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 sender is the vault, submitted by a bundler. The EntryPoint's UserOperationEvent names 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 (with Donation). A plain transfer to the vault is counted as a donation by the next absorb.
  • A transfer out of the vault is an exit. An unshield or sale (with Exited), or a settled or claimed ERC-4337 exit (with SaleSettled). In the current implementation nothing else leaves the vault.
  • The network fee is not a constant. Read networkFee() and maxOpCostWei(); 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 unless entriesPaused() 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 (Harvested on the harvester, Donation on 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.

On this page