Documentation · Reference

Storage layout

GeneHook's fixed storage layout, slot by slot and byte by byte, verified with forge at the frozen RC4 commit.

Verified commit. This layout is the output of forge inspect src/GeneHook.sol:GeneHook storageLayout --json on a detached checkout of tag rc4-audit-candidate, commit aca5fcd3bbc9ecb1026de58bea431d406d8ecfff (verified with git rev-parse HEAD; working tree clean), forge 1.5.1-stable (b0a9dd9c), the toolchain recorded at the freeze.

Citation keys. H = src/GeneHook.sol, L = src/GeneLens.sol, G = src/Genome.sol, all at aca5fcd. Constants are linked to Parameters.

Permanence. GeneHook has no proxy and no upgrade path (H:25-33), so this layout is fixed for the lifetime of a deployment. GeneLens hard-codes the same slot numbers (L:23-34) and test/unit/LensLayout.t.sol checks its decoders (L:17-19).

#How to read a slot

GeneHook exposes one general-purpose read function:

function extsload(bytes32[] calldata slots) external view returns (bytes32[] memory values)

It performs one sload per requested slot and nothing else: no external calls, no writes (H:950-963). The same words are available through eth_getStorageAt(hook, slot, blockTag).

Rules for every reader:

1. Byte offsets count from the least significant byte. A field at offset o bytes with width w bytes is (word >> (8*o)) & ((1 << (8*w)) - 1).
2. Signed fields must be sign-extended. For an int24 field: take the 24-bit value v; if v >= 0x800000, the value is v - 0x1000000. The same rule applies at 56 bits (int56) and 64 bits (int64). GeneLens does this with int24(uint24(w >> off)) (L:276-281) and int64(uint64(...)) (L:197-199).
3. Read every slot of one view at one block tag. All values in one panel must come from the same block.
4. Values describe the last touched block. Slot 0 changes only when a swap, metabolize(), regenerate() or evolve() touches a new block (H:364, H:728-730). Slot 1 also changes on every swap: afterSwap updates revenueGwei, netGeneMicro and blockVolumeGwei (H:376-388). Until a new epoch's first touch, the epoch-dependent fields still describe the previous epoch (H:747-765).

Not in storage:

• Immutables poolManager, token, launcher, genomeHash, poolId, GENE_ID (H:161-166) live in the runtime bytecode. Read the first five through their getters; GENE_ID has no getter and equals uint256(uint160(token())) (H:235).
• The action guard ACTION_SLOT (H:155) is a transient-storage slot (tload/tstore, H:400-417). extsload uses sload and cannot see it; it is zero outside the hook's own unlock.

#Slot map

Unused bytes: slot 0 bytes 19-31; slot 1 bytes 28-31; slot 2 bytes 21-31; slot 5 bytes 16-31; slots 7 and 8 bytes 28-31; slot 22 bytes 16-31; slot 23 bytes 24-31 (from the offsets and widths above).

#Packed structures

#Slot 0: BlockState

GeneLens decoder: L:275-282. All six fields are seeded to GENESIS_TICK_UPPER at launch (H:257, H:266; G:18).

#Slot 1: EpochAcc

GeneLens decoder: L:69-75. To convert: wei = revenueGwei * 1e9; GENE-wei = netGeneMicro * 1e12. The current block is folded into activeBlocks / pathTicks only at the next block's first touch (H:738-745).

#Slots 7, 8 and 22: spend counters

Caps2 has no epoch field. It is reset together with Caps when Caps.epoch differs from the current epoch (H:794-800). A reader must therefore treat slots 7 and 8 as zero for the current epoch whenever Caps.epoch differs from it, and slot 22 as zero whenever Caps3.epoch differs (GeneLens applies the same rule, L:180-184). The counters are rolled only inside metabolize() and regenerate() (H:456, H:562).

GeneLens decoders: L:78-87 (slots 7-8), L:183-184 (slot 22).

#Slot 9: epoch records

Location: keccak256(abi.encode(uint256(e), uint256(9))) (L:262-264).

GeneLens decoder: L:266-273. A record is written only for the epoch that was open at the last touch before an epoch boundary (H:748-756). An epoch with no touch is never written and reads as all zero (H:880).

#Slots 10 to 17: gene status

Gene g (0 GENESIS, 1 METABOLISM, 2 REGENERATION, 3 IMMUNITY; G:57-60) occupies slots 10 + 2g and 11 + 2g (L:47).

GeneLens decoder: L:46-56. State 2 (EXPRESSIBLE) is never stored at rest: _express writes EXPRESSED directly and only emits the EXPRESSIBLE step as an event (H:937-947).

#Slot 18: position registry

• Slot 18 holds the array length (L:89-91).
• Element i is at uint256(keccak256(abi.encode(uint256(18)))) + i (L:95).
• Each element packs int24 lower at bits 0-23 and int24 upper at bits 24-47 (H:92-95; L:96-97).
• Index 0 is the genesis band [GENESIS_TICK_LOWER, GENESIS_TICK_UPPER] (H:420-431).
• Entries are deduplicated by (lower, upper) through slot 19 (H:699-705), so adding to an existing band does not append.

Liquidity per position is not in GeneHook storage. Read it from the PoolManager with getPositionInfo(poolId, hook, lower, upper, bytes32(0)); every protocol position uses salt 0 (H:604; L:239).

#Slot 21: net-flow budgets

Location: keccak256(abi.encode(uint256(e), uint256(21))) (L:161).

At most one of bid / imm is non-zero (H:866-872). Spending in epoch e reads _budgets[e - 1] only (H:815, H:830, H:531, H:567).

GeneLens decoder: L:160-165.

#Slot 23: cumulative flow

Updated only when a closing epoch has non-zero net flow (H:838). GeneLens decoder: L:195-200.

#Worked decode

# Pseudocode: sload(i) is eth_getStorageAt(hook, i) or hook.extsload([i])
def field(word, off_bytes, width_bytes, signed=False):
    v = (word >> (8 * off_bytes)) & ((1 << (8 * width_bytes)) - 1)
    if signed and v >= 1 << (8 * width_bytes - 1):
        v -= 1 << (8 * width_bytes)
    return v

w0 = sload(0)
atl_tick = field(w0, 16, 3, signed=True)        # BlockState.atlTick
w2 = sload(2)
launched = field(w2, 5, 1) != 0
evolve_cursor = field(w2, 6, 4)

rec_slot = keccak256(abi_encode(uint256(e), uint256(9)))
r = sload(rec_slot)
revenue_wei = field(r, 0, 12)
closed = field(r, 31, 1) != 0

The offsets are those in the tables above; each is cross-checked against the GeneLens decoder cited in the same row.

#Changes from RC3

• Slot 0 dropped prevMaxTick, prevMinTick, prev2MaxTick and added atlTick (H:98-105).
• Slot 1 field volumeGwei became int56 netGeneMicro in the same bits (H:113).
• Slot 2 no longer holds floorTick or immFloorTick (forge layout above ends slot 2 at lastRegenerateBlock, offset 16).
• Slots 21-23 are new (H:198-221).

Material describing the RC3 layout is historical; this page describes RC4.