Genome

The fixed constants GENE runs under, how genomeHash commits to them, what each gene requires and switches on, and the epoch, budget and anchor rules that bind them.

The Genome is the set of compile-time constants in src/Genome.sol that bound everything GENE can do. No function anywhere takes a genome value as input, so none can be changed after deployment (Genome.sol:4-7). genomeHash commits to 43 of them; the four gene ids are labels outside the encoding. Every constant in the encoding is read by GeneHook except two: VERSION identifies the encoding, and GENE_COUNT is matched by a test against the literal length of GeneHook's gene array (Genome.sol:8, 12; GeneHook.sol:192; GenomeHash.t.sol:23).

Three rules have no numeric parameter and are fixed by the bytecode rather than by a constant: every protocol buy is anchored at the all-time-low block-start price, budgets come from net directional flow, and asks are anchored at the all-time-high block-start price (Genome.sol:8-10).

#genomeHash

0x39c130f616c32abfb40f8ab51eb54544cffd3e0d99602c71dc336bc8083c36ae

genomeHash is keccak256(Genome.encode()). GeneHook computes it in its constructor, stores it as an immutable and emits it in the Genesis event (GeneHook.sol:164, 245-247). test/unit/GenomeHash.t.sol:11 pins the value.

Genome.encode() concatenates three encoders in this order (Genome.sol:89-91):

That is nine groups and 43 words of 32 bytes. The order is part of the commitment (Genome.sol:88). The gene ids GENESIS, METABOLISM, REGENERATION and IMMUNITY (0 to 3) are constants but are not in the encoding; GENE_COUNT is (Genome.sol:57-61, 104). GeneLens.genome() returns the same bytes (GeneLens.sol:202-206). To recompute the hash yourself, follow verify the deployment.

GeneHook also uses constants that are not part of the Genome, such as the usable tick range and v4's per-tick liquidity ceiling (GeneHook.sol:157, 631).

#Gene states and the strict chain

Each gene is a state machine: DORMANT, OBSERVING, EXPRESSIBLE, EXPRESSED (GeneHook.sol:65-70). EXPRESSIBLE is transient: an expression moves through it and on to EXPRESSED in one call, emitting two GeneTransition events (GeneHook.sol:937-947). EXPRESSED is final; no code path leaves it (GeneHook.sol:903, 921).

Genes form a strict chain. A gene counts a closed epoch e only when its predecessor is EXPRESSED, the predecessor's expressedEpoch is earlier than e, and e is at least the gene's minimum epoch (GeneHook.sol:896-899).

Closed epochs are folded into the state machines one at a time, in order, by evolve() and by metabolize() (GeneHook.sol:289, 312-329). Each expression stores an evidence hash over the stored records of its evidence range; for IMMUNITY that range is the whole observed window, stressed epochs or not (GeneHook.sol:933, 975-982); see verify evidence hashes.

Revenue, the gene metric. Each closed epoch's record carries revenue: 1% (LP_FEE) of the ETH buyers paid in during the epoch, accumulated in gwei (GeneHook.sol:76, 385-387). It is evidence for gene conditions and for sizing the churn tier. It is not the fees collected: fees are collected by metabolize() into the reserves.

#GENESIS

Activation. Expressed by launch(), in the same transaction that opens the pool (GeneHook.sol:268-271). Its evidence hash is keccak256(abi.encode(GENESIS, genomeHash, launchBlock)) (GeneHook.sol:270).

What it switches on. The canonical pool. launch() initializes the pool at GENESIS_TICK_UPPER and adds the whole SUPPLY as one single-sided GENE position over [GENESIS_TICK_LOWER, GENESIS_TICK_UPPER] (MassAdded kind 0), then burns any GENE dust left in the hook (GeneHook.sol:252-273, 420-435). Only the launcher can call it, once (GeneHook.sol:253-255).

Resource accounting. The genesis position is registry index 0 and is harvested by every metabolize() (GeneHook.sol:431, 674). Its liquidity counts toward massLiquidity (GeneHook.sol:432).

Ticks are log1.0001(GENE per ETH): a higher tick means a cheaper GENE. The opening tick is the band's upper edge, so the band covers GENE prices from the opening price up to the price at GENESIS_TICK_LOWER.

#METABOLISM

Activation. From epoch MET_MIN_EPOCH, after GENESIS. A closed epoch qualifies when its revenue is at least MET_REVENUE. METABOLISM expresses after MET_OBSERVE consecutive qualifying epochs; an epoch that does not qualify resets the count and returns the gene to DORMANT (GeneHook.sol:884, 901-917). Its evidence range is the last MET_OBSERVE epochs (GeneHook.sol:911).

What it switches on. metabolize(), which reverts GeneNotExpressed until then (GeneHook.sol:283). Each call, in order (GeneHook.sol:458-476):

1. Harvest. Pokes the genesis position and up to HARVEST_PER_CALL registry positions, round-robin, with zero-liquidity modifyLiquidity calls that collect only accrued LP fees (GeneHook.sol:669-697).
2. IMMUNITY, if its deployment gate is open (see IMMUNITY).
3. METABOLISM bids (MassAdded kind 1).
4. Churn tier (MassAdded kind 4).
5. Asks (MassAdded kind 3).
6. Settle fees collected against principal added, net, in the hook's ERC-6909 claims (GeneHook.sol:720-725).

Steps 2 to 4 run only when evolution has caught up with the current epoch; asks run either way (GeneHook.sol:465-471).

Resource accounting.

metabolize() returns (ethToBids, ethToImmunity, geneToAsks); ethToBids includes the churn tier (GeneHook.sol:281, 521). ETH beyond the budgets stays in ethReserve.

Every ETH band starts at tick 178,200 or higher, below the opening price, in every state the invariant suite reaches. The suite asserts atlTick >= GENESIS_TICK_UPPER (GenePermanence.t.sol:101), and bids, churn and IMMUNITY start at alignUp(atlTick + GAP, GRID) or above (GeneHook.sol:484, 498-499, 516). In those states _bidRange returns [top, top + NEAR_WIDTH].

Each placement must be single-sided, or _addMass reverts InvariantBroken and the whole call rolls back, including its harvest and its cooldown write (GeneHook.sol:284-286, 655-660).

#REGENERATION

Activation. From epoch REG_MIN_EPOCH, after METABOLISM has expressed in an earlier epoch. A closed epoch qualifies when its revenue is at least REG_REVENUE and its activeBlocks at least REG_ACTIVE_BLOCKS. REGENERATION expresses once REG_OBSERVE consecutive epochs qualify and the expressing epoch's record shows ethCommitted of at least REG_ETH_COMMITTED; a non-qualifying epoch resets the count (GeneHook.sol:885-892, 901-917).

What it switches on.

• A fee share. From then on, REGEN_SHARE_BPS of every ETH fee harvest goes to regenReserve (GeneHook.sol:709-712).
• A smaller bid budget. ethBudget() is reduced by the same share (GeneHook.sol:812-817).
• regenerate(), a bounded buyback and burn (GeneHook.sol:296-309).

Resource accounting.

The churn tier funds no buyback: the allowance is a share of the net-flow bid budget only (GeneHook.sol:565-567). On the genesis curve the price limit binds before the caps.

Buybacks run when someone calls regenerate() while the price is no more than about 1% (REGEN_PREMIUM_TICKS) above the all-time-low price. Otherwise the call spends nothing and the ETH stays in regenReserve (GeneHook.sol:574-577; invariant REGEN).

#IMMUNITY

Activation (expression). From epoch IMM_MIN_EPOCH, after REGENERATION has expressed in an earlier epoch. A closed epoch is stressed when its revenue is at least IMM_REVENUE and its pathTicks at least IMM_PATH_TICKS. IMMUNITY keeps a bitmap of the last IMM_WINDOW processed epochs and expresses when at least IMM_REQUIRED of them are stressed (GeneHook.sol:881, 893, 919-934).

Expression, pressure and deployment are three different facts. IMMUNITY's contract state is one of the four gene states above (GeneHook.sol:65-70); pressure is a view and deployment is an event.

Pressure never implies a deployment. immunityActive() can read true while metabolize() places nothing: before the new epoch's first touch, when this epoch's IMMUNITY cap is spent, when reserves are below the minimum, or when the net-sell budget is used or zero (GeneHook.sol:493-496, 802-805, 828-832). The deployment-stress register shifts for every processed epoch, including epochs before IMMUNITY is expressed (GeneHook.sol:883).

Resource accounting.

#Epochs and evolution

• Numbering. Epoch e = (block.number − launchBlock) / EPOCH_BLOCKS (GeneHook.sol:747).
• First touch of a block. The first swap of a block, or any entry point, runs _newBlock with the price the previous block left (GeneHook.sol:364, 728-733). It finalizes the previous touched block: if that block's ETH volume reached MIN_BLOCK_VOLUME, it adds one active block and min(|net tick move across that block|, PATH_CLAMP) to pathTicks (GeneHook.sol:738-745).
• Closing. When the epoch number has changed, it writes the last touched epoch's record (revenue, activeBlocks, pathTicks, ethCommitted, closed) permanently, emits EpochClosed and computes that epoch's net-flow budget (GeneHook.sol:748-765).
• Untouched epochs get no record and read as all-zero activity, which counts as a non-qualifying epoch for every gene (GeneHook.sol:880).
• Evolution. evolve(maxEpochs) processes closed epochs from the evolution cursor; metabolize() processes up to AUTO_EVOLVE_MAX before spending ETH (GeneHook.sol:289, 312-329). See keepers.
• Views and the first touch. Epoch-dependent views show the last touched epoch until the new epoch's first touch (GeneHook.sol:728-765).

#Net-flow budgets

1. Measure. Each swap adds signed net GENE leaving the curve: buys count the GENE out, sells count the GENE in net of the 1% fee. A round trip that restores the price nets to zero, whoever trades it (GeneHook.sol:378-383).
2. Count once. At an epoch's close, the cumulative net flow nc is compared with its all-time high hwm and the lowest level since that high, lwm. Only flow that takes nc above hwm funds bids; only flow that takes it below lwm funds IMMUNITY. Flow that re-crosses levels that already funded funds nothing (GeneHook.sol:837-858).
3. Value at the cheapest price. The funded GENE is valued in ETH at pLow, the epoch's cheapest price over its block starts and its close (GeneHook.sol:758-761, 860-862).
4. Take 1%. The budget is LP_FEE of that value: a bid budget for net buying or an IMMUNITY budget for net selling, never both (GeneHook.sol:863-872).
5. Spend next epoch only. Epoch e spends only the budgets created by e − 1; nothing carries over (GeneHook.sol:812-832, 526-539).

Because the flow paid at least pLow, a budget never exceeds the fee its own flow paid (GeneHook.sol:834-836; invariant BUD2).

#All-time low and all-time high anchors

A block-start tick is the price the previous touched block left, so intra-block prints are never sampled (GeneHook.sol:732-733). Because atlTick starts at GENESIS_TICK_UPPER and only increases, the all-time-low price is never above the opening price; the invariant suite asserts atlTick >= GENESIS_TICK_UPPER (GenePermanence.t.sol:101).

Every protocol buy is placed against the all-time low (GeneHook.sol:35-38):

• METABOLISM bids and the churn tier start one GAP beyond atlTick (GeneHook.sol:484, 516);
• IMMUNITY starts one GAP beyond max(spot, atlTick) in ticks (GeneHook.sol:498-499);
• the REGENERATION buyback stops at atlTick − REGEN_PREMIUM_TICKS (GeneHook.sol:574).

Asks are placed against the all-time high: below min(spot, athTick) in ticks, that is above the higher of the spot price and the all-time-high price (GeneHook.sol:544-545).

The all-time low is a placement anchor, not a price floor: in a falling market it can sit far below spot.

#Invariants

The RC4 invariants and the suites that enforce them. Enforcement: U unit, F fuzz, I stateful invariant, K mainnet-fork test, S static or bytecode test.

Release rule: zero skipped tests; the fork suite fails when its RPC variable is unset. The full regression on the RC4 code ran 5,920 tests with 0 failed and 0 skipped.

Each entry above is asserted by the suites in its last column, for every state those suites reach.

#Parameters

Pool and placement _encodePool

Caps and timing _encodeCaps

Gene conditions _encodeGenes