The Swap Hook

The canonical BOTCOIN/WETH pool on Uniswap v4 is built around a single custom hook, BotcoinWethFeeHook. The hook is where the protocol's economics live: it prices fees, authenticates rig-holder discounts, guards every protocol conversion behind a manipulation-resistant oracle, defends the pool against extractive liquidity strategies, and runs the protocol's own liquidity, all inside the swap path itself. There is no keeper, no off-chain price feed, and no protocol-initiated swap anywhere in the design.

Fee structure

The pool's static fee is zero; the hook charges input-side fees and routes every component in the same transaction. Current rates:

Exact-input swaps treat the named input as gross; exact-output swaps charge the same rate on the input the pool actually consumed, read back after execution. In both modes the hook retains no inventory: every fee component is taken and routed once, inside the swap.

Sell-side fees fund the mining epoch that is live when the fee settles, and buy-side fees are checkpointed against their origin epoch, so delayed settlement can never redirect value between epochs.

The earned rig discount

A wallet pays the reduced fee while it owns at least one rig that is activated to that wallet and has recorded at least one settled qualifying epoch. Fresh activation alone is insufficient; the discount is earned by operating, and the qualification travels with the rig when it is sold.

Authentication is by router identity rather than by anything the swap can claim about itself. The hook accepts the swapping wallet only from two reviewed sources: the protocol's own RigSwapRouter, and the official Uniswap Universal Router's authenticated initiator. Unsigned hook data and tx.origin are never consulted, so an unknown router cannot spoof a discount, and no swap enumerates NFTs or accepts a caller-selected rig.

The truncated oracle

Every protocol conversion needs a price reference that a single transaction cannot bend. The hook records pre-swap ticks into its own on-chain TWAP oracle, writing at most once per minute with per-write movement clamped to a fixed tick budget. Dragging this oracle requires holding a distorted price across many minutes of real time against arbitrage, rather than flashing it for one block. The oracle fails soft: a consultation problem can never revert a user's swap.

Conversions without protocol swaps

The protocol continuously needs to convert fee WETH into BOTCOIN for bonus campaigns and epoch subsidies. The hook does this without ever placing a swap of its own:

• Passive buffer. Fee BOTCOIN awaiting conversion fills a bounded slice of ordinary WETH-to-BOTCOIN swaps at the swap's own price, and only at or above TWAP value. The trader's execution never worsens, and no protocol swap exists to sandwich. Stale inventory liquidates through a slowly growing, bounded discount that arbitrage collects, so the buffer cannot silt up.
• Bonus campaigns. Each proven bonus epoch's WETH allocation converts in tranches that ride the afterSwap of ordinary trades, each tranche bounded by a TWAP-relative price limit. Campaigns persist until every unit converts; deferrals retry in place, failures revert atomically, and converted BOTCOIN stays escrowed to its exact epoch. There is no cancel, redirect, or timeout path for anyone to abuse.
• Epoch subsidies. The buy-fee subsidy pinned to each epoch converts inside the first eligible ordinary swap after the epoch opens, under the same price guard, and lands directly in the epoch's reward pool.

The result is a fee economy that runs entirely on the gas of ordinary usage. Swappers carry the protocol's conversions a slice at a time, every execution is price-guarded, and a quiet market simply defers work rather than breaking anything.

Liquidity defenses

The hook keys every liquidity position's add-block and rejects removal in the same block, closing zero-risk same-block just-in-time extraction around large swaps while leaving multi-block liquidity provision untouched.

Protocol-owned liquidity

Fee shares routed to liquidity fund a managed pair of single-sided positions: a WETH bid below spot and a BOTCOIN ask above it. The engine never swaps; market trades through its positions perform any inventory conversion. Re-anchoring the pair requires both spot and TWAP to cross the live midpoint, a cooldown, and strictly deeper replacement liquidity, so maintenance cannot be used to bleed the positions. Maintenance rides ordinary swaps with public fallback calls, and an emergency mode can freeze and unwind the engine into accounted protocol buckets, with the fee routing falling back to burns and direct buybacks while disabled.