Documentation · Learn

What is GENE

What GENE is made of, how its one pool works, and what its contracts can and cannot do.

GENE is a fixed-supply ERC-20 token and one Uniswap v4 hook that together run one canonical ETH/GENE pool. The hook is the pool's only liquidity provider. Every swap in that pool pays the pool's LP fee to the hook's positions, and the hook can turn collected fees, within per-epoch budgets and caps, into more liquidity that no function can withdraw. A fixed set of rules, the Genome, decides when each part of that behaviour switches on.

The code is frozen at tag rc4-audit-candidate. Its supply is fixed at 1,000,000,000 GENE, minted once; no admin key acts after launch, nothing can upgrade it, and no function removes liquidity.

#The parts

• GeneToken is a plain ERC-20. Its constructor mints the whole supply once, to the hook. It has no owner, no further mint, no pause, no blacklist, no transfer fee and no transfer hook; the only addition is burn, which destroys the caller's own balance (GeneToken.sol:6-10, :17, :21-23).
• GeneHook is the Uniswap v4 hook and the whole protocol. It holds the block-start price references, the permanent epoch records, the gene state machines, the fee reserves (held as ERC-6909 claims at the PoolManager) and every protocol-owned liquidity position (GeneHook.sol:20-23).
• Genome is a library of compile-time constants. No function takes a genome value as input, so none can change, and the hook commits to the exact encoding with genomeHash (Genome.sol:4-7; GeneHook.sol:245-246). See Genome.
• GeneLens is an optional, stateless decoder of the hook's storage. The hook never calls it, and anyone can deploy a copy (GeneLens.sol:12-16).

#How it works, in one pass

1. Launch. The launcher calls launch() once. It opens the pool and places the whole supply as GENE-only liquidity in one band that starts at the opening price (GeneHook.sol:252-273). See the pool and the hook.
2. Trading. Swaps go through any router. Uniswap v4 charges the LP fee on the input token, and because outside liquidity is rejected, the whole fee accrues to the hook's positions (GeneHook.sol:337-343). See fee anatomy.
3. Recording. On each block's first touch the hook records the price the previous block left, and it accumulates per-epoch activity into permanent records (GeneHook.sol:728-780). See epochs.
4. Expression. GENESIS is expressed by launch(). The other three genes advance through fixed states when closed epochs' records meet their conditions and someone calls evolve() or metabolize(). Each expressed gene unlocks a behaviour (Genome.sol:57-61; GeneHook.sol:268-271, 289, 312-316). See genes.
5. Metabolism. Once METABOLISM is expressed, anyone can call metabolize(), at most once per cooldown. Each call collects accrued fees from the genesis position and up to eight other positions, then, within per-epoch budgets and caps, adds reserves to the pool as protocol liquidity, often topping up an existing band: ETH as bids at or below the all-time-low block-start price, GENE as asks above the higher of the spot price and the all-time-high block-start price (GeneHook.sol:276-291). That liquidity is Permanent Mass.
6. Regeneration and immunity. Later genes add a bounded buyback-and-burn that buys only while the price is no more than about 1% above the all-time-low price (regeneration; GeneHook.sol:574-577), and a capped bid funded by net selling (immunity).

#What the contracts cannot do

• Change the fee. It is static in the PoolKey, and the hook contains no call that updates it (GeneHook.sol:26-27).
• Take a hook fee. The swap callbacks return zero deltas (GeneHook.sol:365, :389).
• Withdraw liquidity. The only call to modifyLiquidity takes an unsigned amount, so protocol positions can only grow (GeneHook.sol:28-29, :594-608).
• Act for a privileged caller after launch. No function checks the caller afterwards (GeneHook.sol:33).
• Read an outside oracle. The hook uses only its own pool's price (GeneHook.sol:97-105).

#What it does not promise

Every METABOLISM, churn and IMMUNITY bid sits at or below the all-time-low block-start price (GeneHook.sol:484, :498-499, :516). REGENERATION's buyback pays at most about 1% above it (GeneHook.sol:574-577). In a falling market, protocol bids therefore sit below spot. Permanent Mass is measured in liquidity units, and its ETH/GENE mix moves with price; see Permanent Mass. Limitations explained walks through the known limitations, and the known limitations page has the full text.

#Three code properties

A developer reading the code will meet these three properties:

• Every ETH band starts at tick 178,200 or higher, below the opening price, in every state the tests reach (GenePermanence.t.sol:101).
• A metabolize() call reverts as a whole if an ETH placement would need GENE (GeneHook.sol:655-660).
• REGENERATION buys only while the price is no more than about 1% above the all-time-low price (GeneHook.sol:574-577).

Audit scope note: bid-band branch reachability, metabolize() with spot at or beyond the bid band, and REGENERATION window reachability (see Security).

For the full architecture, see Protocol.