Documentation · Learn

Permanent Mass

What Permanent Mass is, what "permanent" covers and what it does not, and how it grows.

Permanent Mass (a GENE term) is every liquidity position in the canonical pool that GeneHook owns: the genesis band placed at launch, plus every bid and ask band that metabolize() adds later (GeneHook.sol:20-23).

#What is permanent

The liquidity units cannot be withdrawn. "Liquidity units" here means L, the Uniswap v4 measure of a position's liquidity, not an amount of ETH or GENE.

Two facts in the code establish this:

• One call, add-only. _modifyLiquidity is the only call to the PoolManager's modifyLiquidity in GeneHook, and its amount is an unsigned integer cast to a non-negative delta. Protocol positions can only grow, or be poked with zero to collect fees (GeneHook.sol:28-29, :594-608).
• No outside removal. beforeRemoveLiquidity always reverts for every other caller (GeneHook.sol:346-352).

The invariant suite checks the matching properties after every step: each registered protocol position keeps nonzero liquidity, recorded Mass equals those positions, and no other address holds liquidity in the pool (GenePermanence.t.sol:105-130). Positions are raw PoolManager positions owned by the hook, not NFTs (GeneHook.sol:604).

#What is not permanent

• The asset composition changes with trading. A bid band holds ETH while the price is above it. When sellers trade through it, the band ends up holding GENE instead, and a later rise turns it back into ETH. The same applies to ask bands in reverse.
• Mass is measured in liquidity units. Its ETH/GENE mix moves with price. It describes liquidity that stays in the pool; where the price trades, and how much of that liquidity a seller can reach, depend on the market.
• Reachable depth near spot depends on the anchor. Every METABOLISM, churn and IMMUNITY bid sits at or below the all-time-low block-start price (GeneHook.sol:484, :498-499, :516), and REGENERATION's buyback pays at most about 1% above it (GeneHook.sol:574-577). After the price has fallen, the nearest protocol bids sit at that low, below spot. In the falling-market measurements, the protocol ETH a seller could reach within 5%, 10% and 25% below spot was zero in every listed regime. See anchors and limitations explained.

#How Mass grows

metabolize() turns reserves into new bands and emits MassAdded with a kind code (GeneHook.sol:138-141):

ETH bids (kinds 1, 2 and 4) are placed one gap or more beyond the all-time-low reference, on a fixed grid (parameters, grid, width); asks are placed above the higher of the spot price and the all-time-high block-start price (GeneHook.sol:479-552). Each placement must be single-sided, or the call reverts InvariantBroken (GeneHook.sol:655-660). A placement whose liquidity would exceed Uniswap v4's per-tick ceiling is skipped with PlacementSkipped and commits nothing (GeneHook.sol:142-144, :610-627). New ranges join a position registry, deduplicated by their tick bounds, so a placement with the same bounds as an existing band tops that band up (GeneHook.sol:699-705).

Every ETH band starts at tick 178,200 or higher, below the opening price, in every state the tests reach. The invariant suite asserts that the all-time low is never above the opening price (GenePermanence.t.sol:101), and every ETH band starts at alignUp(atlTick + 60, 600) or above (GeneHook.sol:484, :498-499, :516).

Audit scope note: reachability of the wider _bidRange branch (GeneHook.sol:784), which needs a lower edge of 177,480 or less, and metabolize() reverting InvariantBroken when the price sits at or beyond the bid band (see Security).

#How to measure it

The public metrics come from on-chain state:

• Permanent Mass: massLiquidity, the sum of liquidity units ever added. It only increases (GeneHook.sol:186, :432, :665).
• Cumulative ETH and GENE committed: ethCommitted and geneCommitted, historical sums of principal placed. They are not amounts currently held (GeneHook.sol:184-185, :624-625).
• Reachable depth: GeneLens.report() computes the ETH a seller would receive from protocol positions within fixed moves below spot, and the GENE a buyer would receive above it, from current positions at the current price (GeneLens.sol:36-43, :209-227). Show a zero as a zero.

Present Permanent Mass in liquidity units; its ETH and GENE amounts change with price.