Documentation

Overview

A conceptual guide to ERC-402 and the OBOL collection. For contract interfaces, events and integration code, see Integration.

Introduction

OBOL is a semi-fungible token. It behaves as an ordinary ERC-20 for the purpose of trading, and simultaneously as an ERC-721 collection of one thousand coins. The two are not separate contracts or wrapped positions — they are two views of the same balance.

Hold 0.4 OBOL and you hold fractional exposure and no coin. Cross 1.0 and a specific coin with a specific id becomes yours. Cross back below and it goes away again. This part is inherited unchanged from ERC-404 and works the way you would expect.

What is new is that the coin knows the price at which it was created. That is the entire point of the standard, and everything else on this page follows from it.

Core concepts

Obol	One coin. Also one whole unit of the token. The word is the Greek coin placed with the dead to pay the ferryman.
Strike	The act of creating a coin, and the price recorded when it happens. Coins are struck, in the numismatic sense.
Melt	The reverse. Falling below a whole unit sends the coin to the bank rather than destroying it.
Grade	A condition class derived from the strike price and frozen at issue. Also determines your swap fee.
The bank	The queue of melted ids waiting to be re-issued.
The Hoard	The fee-funded treasury that backs circulating coins.
Exempt	An address that holds the balance but is not issued coins — pools, routers, and burn addresses.

The hybrid mechanic

The contract watches the integer part of your balance. Every transfer compares the whole units you had before against the whole units you have after, and issues or melts the difference.

balance 2.40  →  buy 0.70  →  balance 3.10
whole units    2         →         3        strike 1 coin

balance 3.10  →  sell 0.45 →  balance 2.65
whole units    3         →         2        melt 1 coin

balance 2.65  →  sell 0.10 →  balance 2.55
whole units    2         →         2        nothing happens

Melting takes your most recently acquired coin first. Striking draws a recycled id from the bank if one is available, and only issues a brand-new id when the bank is empty.

Exempt addresses are skipped entirely. A pool holding 898 tokens holds no coins, because issuing NFTs into an AMM is pointless and, at scale, gas-fatal. In ERC-402 the only address that needs this treatment is the v4 PoolManager, and it is exempt in code rather than through a list an owner maintains.

The strike

When a coin is created by a swap, it records the pool price at that exact moment. That number is written once and is never mutable for the life of that coin.

The reason this is unusual is worth being precise about. A token contract's transfer function sees addresses and amounts. It has no access to market price, and any price it tried to read from an external oracle would be manipulable within the same transaction. A Uniswap v4 hook, by contrast, executes inside the swap, after the curve has been walked and before the transaction settles. The price it reads is the realised execution price of the trade that is happening.

Coins created outside a swap — an ordinary wallet-to-wallet transfer that happens to push someone over a whole unit — are struck unpriced, and carry the lowest grade. The price channel is not something a caller can supply or spoof; if it is not a swap, there is no price.

Grading

Coin collectors have graded struck metal for roughly two centuries, and the vocabulary is already precise, so ERC-402 uses it instead of inventing another rarity ladder. Grade is a pure function of the strike price and is assigned once.

Two properties follow that are hard to get any other way. Distribution is emergent — nobody is allocated a Proof, and the population of each band is whatever the market actually produced. And scarcity is one-way: once price leaves a band, no further coins can ever be struck into it, so that population can only shrink through melting.

Grade also sets your swap fee. The pool is opened with the dynamic-fee flag, and the hook reads the best grade in your wallet before pricing your trade. Holding a Proof means paying 0.25% where an ungraded wallet pays the 1.00% base.

The bank

Melted coins are queued rather than burned. The next buyer to cross a whole unit is issued an id from the front of that queue and the coin is re-struck at the current price, receiving a new strike and therefore possibly a new grade. An EIP-4906 metadata event is emitted so indexers refresh it.

This keeps the id space bounded at 1,111 no matter how much trading occurs, and it means circulating supply is a live figure that falls when people sell:

circulating = struck - banked

Earlier hybrids reported a counter that only ever increased, so their published supply drifted permanently away from reality. Ours does not.

The Hoard

A share of every swap fee accrues to a treasury, reported as a per-coin backing figure of hoard / circulating. It is uniform across grades: grade changes what you pay to trade, not what stands behind your coin.

Be clear about what this is. It is floor support funded by activity. It is not redeemable, not a claim, and not a guarantee. It also grows only with volume, which means it is reflexive — if trading stops, the backing stops growing. We are not going to pretend otherwise, because every protocol in this category that has been coy about that has ended up explaining it later under worse circumstances.

The trading gate

tradingEnabled is false at deployment. While it is false, any transfer where both parties are non-exempt reverts. This exists so liquidity can be seeded safely before anyone can trade against a half-built pool.

It is opened exactly once, by an owner-gated call with no counterpart. There is no function to close it again, no pause, and no blacklist. The full sequence is published in advance on the launch page.

Glossary

Hook	A contract Uniswap v4 calls at defined points during a pool operation. Its permissions are encoded in its own address.
PoolManager	The single v4 contract that holds the tokens for every pool on a chain.
Dynamic fee	A pool opened with `fee = 0x800000`, allowing its hook to set the fee per trade.
Transient storage	EIP-1153 storage that lives for one transaction and then vanishes. How the hook hands the strike price to the token.
sqrtPriceX96	Uniswap's fixed-point representation of pool price. The raw source of every strike.
Round lot	Equities term for one whole tradeable unit. The equivalent of one obol.
Flan	Numismatics: the blank metal disc a coin is struck onto, before any design is applied to it.