Documentation · Reference

GeneHook

Every external and public function of GeneHook, with its signature, mutability, caller restrictions, behaviour, reverts and events.

GeneHook is the Uniswap v4 hook of the canonical GENE pool and holds the whole protocol: block-start price references, permanent epoch records, the gene state machines, fee reserves held as ERC-6909 claims at the PoolManager, and every protocol-owned liquidity position (GeneHook.sol:20-23). It has no proxy, no admin role and no upgrade path; no function checks the caller after launch() (GeneHook.sol:25-33).

All line references are to src/GeneHook.sol at tag rc4-audit-candidate (aca5fcd) unless another file is named. Constants are linked to Parameters instead of being restated.

#ABI pinning

The external ABI is exactly 27 functions. test/unit/HookAbi.t.sol reads methodIdentifiers from the forge build artifact and fails if any selector is added, removed or renamed (HookAbi.t.sol:19-62; invariant ABI). Selectors for every function are on Selectors.

There is no fallback and no receive. The five callbacks whose flag bits are clear (afterInitialize, afterAddLiquidity, afterRemoveLiquidity, beforeDonate, afterDonate) are not implemented, so a direct call to any of them reverts (GeneHook.sol:43-45). See Permissions and PoolKey.

#Constructor

constructor(IPoolManager manager, address launcher_)

Under CREATE2 through a deployer contract, msg.sender in the constructor is the deployer, which is why the launcher is a constructor argument (script/Deploy.s.sol:31-33).

#Launch

#launch()

function launch() external

Behaviour, in order:

1. Sets launched = true (GeneHook.sol:255).
2. Calls PoolManager.initialize(poolKey(), sqrtPrice(GENESIS_TICK_UPPER)) (GENESIS_TICK_UPPER). The hook's own beforeInitialize is skipped because the hook is the caller (GeneHook.sol:257-258; v4 Hooks.sol:171-175).
3. Opens an unlock with action ACTION_LAUNCH. Inside it, adds the genesis band [GENESIS_TICK_LOWER, GENESIS_TICK_UPPER] holding SUPPLY of GENE single-sided, transfers and settles the GENE, registers the band as position 0, adds its liquidity to massLiquidity and emits MassAdded(0, ...) (GeneHook.sol:259, GeneHook.sol:420-435).
4. Burns any GENE left in the hook (dust) (GeneHook.sol:262-263).
5. Sets launchBlock, seeds all six BlockState ticks to GENESIS_TICK_UPPER and records the block in EpochAcc.lastBlock (GeneHook.sol:265-267).
6. Sets GENESIS to EXPRESSED with evidenceHash = keccak256(abi.encode(uint8(0), genomeHash, block.number)) (GeneHook.sol:268-270).

Events: MassAdded kind 0 (GeneHook.sol:433), GeneTransition(0, DORMANT, EXPRESSED, 0, evidenceHash) (GeneHook.sol:271), Launched (GeneHook.sol:272). The PoolManager emits its own Initialize and ModifyLiquidity, and GeneToken emits Transfer for the settlement and for any dust burn.

#Keeper entry points

All three are callable by any address after launch and behave the same whatever the caller (GeneHook.sol:33; test/unit/HookAbi.t.sol:11-12). Each first runs _sync(), which calls _newBlock if this is the block's first touch (GeneHook.sol:728-730). At an epoch boundary that first touch writes the closed epoch's record and budgets, so any of the three can emit EpochClosed and FlowBudgets (GeneHook.sol:747-765).

#metabolize()

function metabolize() external returns (uint256 ethToBids, uint256 ethToImmunity, uint256 geneToAsks)

Behaviour, in order:

1. _sync(), then _evolve(AUTO_EVOLVE_MAX): folds up to AUTO_EVOLVE_MAX pending closed epochs into the gene state machines (GeneHook.sol:287-289).

2. Opens an unlock with ACTION_METABOLIZE (GeneHook.sol:290). Inside it, reads spot, atlTick and athTick and resets the per-epoch counters if the epoch changed (GeneHook.sol:452-456, GeneHook.sol:794-800).

3. Harvest. Pokes the genesis position plus up to HARVEST_PER_CALL registry positions round-robin with a zero-liquidity modifyLiquidity, which returns only accrued LP fees (GeneHook.sol:671-697). ETH fees go to ethReserve; once REGENERATION is EXPRESSED, REGEN_SHARE_BPS of them go to regenReserve instead. GENE fees go to geneReserve (GeneHook.sol:707-718).

4. ETH placements, only when evolveCursor equals the current epoch: IMMUNITY first if _immunityActive(), then METABOLISM bids, then the churn tier (GeneHook.sol:465-469). Each draws on its own budget from closed epoch e-1 and its own caps:

   Placement	Amount	Band	Source
   IMMUNITY (kind 2)	min(ethReserve, IMMUNITY budget left, IMMUNITY_CAP_EPOCH - placed, IMMUNITY_CAP_CALL)	lo = alignUp(max(spot, atlTick) + GAP, GRID), width NEAR_WIDTH	GeneHook.sol:493-507
   METABOLISM bid (kind 1)	min(ethReserve, ethBudget() - placed, BID_CAP_EPOCH - placed, BID_CAP_CALL)	top = alignUp(atlTick + GAP, GRID), range from _bidRange(top): [top, top + NEAR_WIDTH] in every state the tests reach (top >= 178,200, GenePermanence.t.sol:101)	GeneHook.sol:479-491, GeneHook.sol:782-786
   Churn tier (kind 4)	min(ethReserve, revenue(e-1) - bid(e-1) - churn placed, BID_CAP_EPOCH - bids - churn, BID_CAP_CALL)	lo = alignUp(atlTick + GAP, GRID), width NEAR_WIDTH	GeneHook.sol:513-539

   A placement below MIN_DEPLOY_ETH is skipped (GeneHook.sol:483, GeneHook.sol:496, GeneHook.sol:515).

5. Asks (kind 3), always attempted: min(geneReserve, ASK_CAP_CALL, ASK_CAP_EPOCH - placed), skipped below MIN_DEPLOY_GENE; band ends at alignDown(min(spot, athTick) - GAP, GRID) (GeneHook.sol:541-552, GeneHook.sol:788-792).

6. Settle. Fees collected are credits and principal added is debt; the net is minted or burned against the hook's own ERC-6909 claims for ETH (id 0) and GENE (id GENE_ID) (GeneHook.sol:474-475, GeneHook.sol:720-725).

Every placement goes through _deploy. If the liquidity would exceed v4's per-tick ceiling, it emits PlacementSkipped and consumes nothing (GeneHook.sol:612-627, GeneHook.sol:644-652). Fees auto-collected when adding to an existing band are credited like harvested fees, but are not included in FeesHarvested (GeneHook.sol:554-559, GeneHook.sol:688).

Audit scope note: reachability of the [top, GENESIS_TICK_UPPER] branch of _bidRange, metabolize() reverting InvariantBroken while the price sits at or beyond the METABOLISM or churn bid band, and whether bids and churn together can exceed BID_CAP_EPOCH (see Security).

Events: EpochClosed, FlowBudgets (first touch at a boundary), GeneTransition (auto-evolve), FeesHarvested (GeneHook.sol:688), MassAdded kinds 1 to 4 (GeneHook.sol:626), PlacementSkipped (GeneHook.sol:620).

#regenerate()

function regenerate() external returns (uint256 ethSpent, uint256 geneBurned)

Behaviour, in order:

1. _sync(), then an unlock with ACTION_REGENERATE (GeneHook.sol:301-303). It does not run _evolve.
2. Allotment: min(regenReserve, REGEN_CAP_CALL, REGEN_CAP_EPOCH - spent this epoch, REGEN_SHARE_BPS of _budgets[e-1].bid - spent this epoch). If it is below MIN_DEPLOY_ETH, returns (0, 0, false) (GeneHook.sol:562-571).
3. Price limit: limitTick = atlTick - REGEN_PREMIUM_TICKS (REGEN_PREMIUM_TICKS). If spot <= limitTick, returns (0, 0, false) (GeneHook.sol:572-577).
4. Swaps ETH for GENE through the PoolManager: zeroForOne, exact input of the allotment, price-limited at limitTick (GeneHook.sol:578-582). Because the hook is the swapper, v4 skips its beforeSwap and afterSwap (v4 Hooks.sol:253, Hooks.sol:293).
5. Pays the ETH by burning the hook's ETH claims, takes the GENE to the hook, debits regenReserve, adds to the epoch's REGENERATION counter and emits Regenerated (GeneHook.sol:583-589).
6. After the unlock, burns the GENE bought with GeneToken.burn (GeneHook.sol:308).

Events: Regenerated (GeneHook.sol:589), GeneToken Transfer to address(0) for the burn, and EpochClosed / FlowBudgets on a first touch at a boundary.

A buyback runs while the price is no more than about 1% above the all-time-low price (step 3). Audit scope note: reachability of that window with supply-faithful balances (see Security).

#evolve(uint256 maxEpochs)

function evolve(uint256 maxEpochs) external returns (uint256 processed)

Each processed epoch reads its stored EpochRecord (an epoch never written reads as all zero), shifts the IMMUNITY deployment-stress register, and steps METABOLISM, REGENERATION and IMMUNITY (GeneHook.sol:879-894). A gene can count an epoch only if its predecessor is EXPRESSED, the predecessor's expressedEpoch is earlier than that epoch, and the epoch is at least the gene's minimum epoch (GeneHook.sol:896-899). Expression emits two GeneTransition events in one call, to EXPRESSIBLE and then to EXPRESSED, and stores the evidence hash (GeneHook.sol:937-947). The predicates are in Genes and the thresholds in Parameters.

#PoolManager callbacks

#unlockCallback(bytes data)

function unlockCallback(bytes calldata data) external returns (bytes memory)

The hook writes the action to transient storage immediately before poolManager.unlock and clears it afterwards (GeneHook.sol:409-418), so the callback accepts only the action the hook itself started.

#beforeInitialize, beforeAddLiquidity, beforeRemoveLiquidity

function beforeInitialize(address, PoolKey calldata, uint160) external pure returns (bytes4)
function beforeAddLiquidity(address, PoolKey calldata, ModifyLiquidityParams calldata, bytes calldata) external pure returns (bytes4)
function beforeRemoveLiquidity(address, PoolKey calldata, ModifyLiquidityParams calldata, bytes calldata) external pure returns (bytes4)

All three are pure and always revert Forbidden() (GeneHook.sol:332-352). v4 does not call a hook's initialize and liquidity callbacks when the hook itself is the caller (v4 Hooks.sol:171-175), so only GeneHook can initialize its pool or add liquidity to it. When the PoolManager calls one of these for another caller, v4 wraps the revert in WrappedError(address,bytes4,bytes,bytes) with HookCallFailed() (v4 Hooks.sol:131-137). See Errors.

#beforeSwap

function beforeSwap(address, PoolKey calldata key, SwapParams calldata, bytes calldata)
    external returns (bytes4, BeforeSwapDelta, uint24)

#afterSwap

function afterSwap(address, PoolKey calldata, SwapParams calldata params, BalanceDelta delta, bytes calldata)
    external returns (bytes4, int128)

#Views

ethBudget() and immunityActive() describe the last touched epoch until the new epoch's first touch by a swap or an entry point (GeneHook.sol:747-765). immunityActive() is a read-only signal: whether metabolize() then places ETH also depends on caps, reserves and the IMMUNITY budget (GeneHook.sol:987-989). Only a mined MassAdded event with kind 2 records an IMMUNITY placement. Typed views of all other state are in GeneLens.