The Treatise

— Chapter I — Preamble

$THEORY is a yield-farm-as-a-Uniswap-v4-hook. The token's swap pool is its farm: every buy and every sell pays a tax that is distributed in real time to anyone who has staked, across three pools and four lockup tiers. The whole system is designed to burn brightly for fourteen days and decay to zero — there is no perpetual emission, no v2 reset, and no team allocation.

This page describes the mechanic in full. The register shows it live; the caveat shows what can go wrong.

— Chapter II — The Mechanic

1. Buy $THEORY. The hook charges a 5% buy tax in $THEORY and a 3% sell tax in ETH. Both feed the farm.
2. Stake. Three pools: Seedling (just $THEORY) at 1×, Orchard (full-range LP) at 3×, Cathedral (concentrated LP, ±25% from spot) at 9×.
3. Lock for longer to earn more. 1h = 1×, 6h = 4×, 24h = 16×, 72h = 64×. Multiplies on top of pool tier. Maximum combined weight: 9 × 64 = 576×.
4. Earn three things. ETH from tax, $THEORY emissions on a 14-day decay, LP fees auto-routed to LP-pool stakers.
5. Surge. If 5 ETH of volume passes inside any rolling 5-minute window, emissions triple for the next 15 minutes.
6. Founder slots. First 100 LP-pool stakers in the first hour earn a permanent +25% weight bonus.

— Chapter III — Tokenomics

— Chapter IV — The Three Pools

Seedling — single-stake $THEORY × 1.0

• Stake: deposit $THEORY tokens.
• Earns: ETH stream only (no LP fees, no preferential weight).
• Use case: onboarding · hold-mode users who don't want IL.

Orchard — full-range $THEORY/ETH LP × 3.0

• Stake: deposit a v4 LP NFT (full range, fee tier configurable, default 0.3%).
• Earns: ETH stream + LP fees (auto-routed) + emissions.
• Use case: standard LP farmers.

Cathedral — concentrated LP, ±25% band × 9.0

• Stake: deposit a v4 LP NFT whose range is fully contained within ±25% of the spot tick at stake-time.
• Earns: ETH stream + LP fees (higher density) + emissions.
• Drift penalty: if spot drifts outside the staked band, the position becomes inactive for surge/emissions until restaked. ETH yield continues at 0.5×.

— Chapter V — The Lockups

Combined share weight is pool × lock × (1 + founder_bonus). The maximum attainable weight is Cathedral × 72-hour × founder bonus = 9 × 64 × 1.25 = 720× per token of TVL.

— Chapter VI — The Hook

TheoryHook.sol attaches at flag mask 0x44: afterSwap | afterSwapReturnDelta. There is no beforeSwap path and no onlyPoolManager external entry beyond the standard hook callbacks.

Buy path · zeroForOne

The hook reads the post-swap BalanceDelta and extracts 5% of the THEORY delivered to the swapper. The taxed THEORY is forwarded to Farm.accrueTheory(), which credits the global theoryPerWeight accumulator. The hook returns a delta to the PoolManager so the swapper's settlement reconciles cleanly.

Sell path · oneForZero

The hook extracts 3% of the ETH received by the swapper. ETH is forwarded to Farm.accrueEth(), which credits ethPerWeight. The hook returns the corresponding delta.

Volume tracking

Both directions add |Δcurrency0| (ETH magnitude) to a single-bucket sliding 5-minute window. If the bucket crosses 5 ETH inside the window, the hook calls Emissions.triggerSurge() (access-controlled to the hook), which raises the emission rate by 3× for the next 15 minutes.

— Chapter VII — The Fortnight

TheoryEmissions.sol implements a linear decay from a peak rate PEAK = 2·BUDGET/T at t=0 down to zero at t=T, where T = 14 days and BUDGET = 50,000 THEORY.

// per-second emission rate at unix time `t`
rate(t) = 0                                    , t < launch
        = PEAK · (1 - (t - launch)/T)         , launch ≤ t ≤ launch + T
        = 0                                    , t > launch + T

// trapezoidal integral — total emitted between t=0 and t=t
emitted(t) = PEAK·t - (PEAK / 2T)·t²

Memecoin lifespans are typically 1–2 weeks. Locking emissions to a 14-day decay matches that reality. After day 14 the farm continues running on real yield only — taxes from any residual trading. There is no perpetual inflation and no v2 reset.

— Chapter VIII — The Surge

The hook maintains a single sliding ETH-volume bucket across both swap directions. Each swap adds |Δcurrency0|; if the bucket crosses 5 ETH within any 5-minute window, the hook triggers a 15-minute surge during which the effective emission rate is multiplied by 3.

// surge state machine
if (rolling5MinVolume ≥ 5 ETH && now ≥ surgeUntil)
    surgeUntil = now + 15 minutes;

// effective rate
effective = rate(t) · (now < surgeUntil ? 3 : 1);

The surge does not extend the 14-day budget — it pulls forward emissions, so a surge-heavy first day produces a steeper subsequent decay.

— Chapter IX — The Founders

The first 100 stakers in either Orchard or Cathedral, within the first hour after launch, receive a permanent +25% weight bonus on every position they ever stake — including positions opened after the founder window closes.

• Slot key: tx.origin — one slot per origin EOA. Smart-contract sybil layers do not fork the bonus.
• Window: launch + 1 hour.
• Cap: 100 slots.
• Bonus: +25% applied to the post-multiplier weight: weight = pool × lock × 1.25.

— Chapter X — The Brain

pokeBrain() is a permissionless keeper entry on TheoryFarm. Anyone can call it to crystallise the contract's pending ETH balance into the ethPerWeight accumulator (the act of "feeding the brain"). The first caller after a 30-minute cooldown receives a finder's fee:

fee = min(brainPotEth · 0.001, 0.05 ETH);  // 0.1% of pot, 0.05 ETH cap
require(now ≥ lastBrainPoke + 30 minutes);

Bot competition for the fee is encouraged — it guarantees the farm gets fed even when no human is watching.

— Chapter XI — Anti-game

— Chapter XII — The Contracts

Five contracts. Solidity 0.8.33. Foundry, via_ir, evm cancun.

— Chapter XIII — Accumulator Math

TheoryFarm uses two Synthetix-style 1e18-scaled accumulators: ethPerWeight for the ETH stream and theoryPerWeight for the emission stream. The standard pattern:

// when ETH `amount` enters the farm
if (totalWeight > 0)
    ethPerWeight += (amount · 1e18) / totalWeight;

// pending for one position
pendingEth = (pos.weight · (ethPerWeight - pos.lastEthAcc)) / 1e18;

// claim — settles before any weight change
pos.pendingEth   += pendingEth;
pos.lastEthAcc    = ethPerWeight;

The same pattern, with theoryPerWeight, governs emission distribution. Every stake/unstake/lockup-tier-change settles pending yield before changing weight, which prevents retroactive manipulation of the accumulators.

— Chapter XIV — Claiming & Unstaking

Claim at any time, lock-state agnostic — pending ETH and pending $THEORY are settled and transferred to the position owner.

Unstake only after stakedAt + lockSeconds. For Seedling, unstake bundles principal + accrued $THEORY in a single transfer. For Orchard/Cathedral the LP NFT is returned to the owner along with any pending claims.

— Chapter XV — Stack & Deploy

• Solidity 0.8.33 + 0.8.26 (v4-core compatibility).
• Foundry 1.5.1-stable, via_ir, evm cancun.
• Vendored v4-core + v4-periphery.
• ERC-20 base: solady.
• Frontend: single-file static HTML, ethers v6, Tor-friendly.
• LP seed: 4 single-sided concentrated bands · 30/30/25/15 split · all NFTs burned to 0xdEaD.
• Deployment target: Ethereum mainnet, after Sepolia smoke + $TEST mainnet dry-run.

"Build to burn hot for a fortnight. The only honest emission curve is the one that ends." — author, twixt theory and practice.