Protocol specificationKing of the HillA Uniswap v4 hook protocol. One wallet at a time holds the throne. While enthroned, that wallet receives 2% in ETH from every swap of the KOTH/ETH pair. Any larger buy replaces them. This document describes the parameters and the lifecycle.

KOTH is an ERC-20 with a fixed maximum supply of 1,000,000 tokens. The full supply is minted once at deploy. The contract has no live admin slot after deploy completes: the deploy script calls renounceAdmin() and zeroes the privileged address.

The token is paired with native ETH in a single Uniswap v4 pool. The pool LP fee is 0%; all fee logic lives in the hook attached to this pool.

A buy crowns its sender if the gross ETH amount exceeds the dethrone threshold. The threshold is derived from the previous king's purchase amount (the record) with linear decay.

On a successful coronation the previous king is dethroned (see Section IV), the new king's address replaces currentKing, the buy's gross ETH amount becomes the new record, and the decay clock resets to the current block.

While reigning, the king accrues 2% of every swap's ETH side into a per-address balance held by the hook. The balance is withdrawable at any time by calling claim(). There is no staking transaction, no claim window, and no schedule.

The yield settles atomically inside the swap that produced it. The king has no pending state to manage between trades.

Each dethrone emits a KingDethroned event with a reason tag. Three reasons exist.

At every dethrone the hook records a Reign struct with the king's address, start and end blocks, ETH earned, the record high, and the reason. The Reign struct is the data layer for the Soul and Scroll NFTs (Section VI).

A dethroned king has 12 hours (3,600 blocks) to call claim() and withdraw their coffer. After this window, any wallet may call forfeit(king). The coffer is then split:

The buyback uses poolManager.unlock() with an in-swap price limit of 50 bps on the square-root price (approximately 1% on the spot price). If the limit clamps the swap, the unused ETH is credited to treasury so the hook's internal accounting remains balanced.

For coffers below 0.001 ETH the entire amount goes to the keeper (the dust path). At that scale a buyback would round down to zero KOTH and produce no burn.

On each dethrone, two NFTs are minted to the deposed king. Both encode the same Reign data on chain; the SVG render and transferability differ.

The Soul and Scroll for a given reign share a token id (the reign number) but live in separate ERC-721 contracts.

When buying KOTH through KOTHRouter, the caller may attach up to three Scrolls they own. The hook validates each Scroll, sums the discount, and lowers the dethrone threshold for that specific purchase only.

durationScore = min(reignBlocks / 3600, 1.0) // cap at 12 h
buyScore = min(recordHigh / 1.5 ether, 1.0) // cap at 1.5 ETH
crownScore = (durationScore + buyScore) / 2

Invalid Scrolls in the stack (not owned, already burned, duplicate id, self-buff) are silently skipped with a ScrollIgnored event. The buy itself never reverts because of Scroll logic.

The protocol ships a minimal escrow marketplace for Scrolls. Payment is in KOTH only; ETH listings are not supported.

toSeller = priceKoth × 90% → seller's wallet
toBurn = priceKoth × 5% → koth.burn()
toTreasury = priceKoth × 5% → treasury (also ERC-2981 royalty)

The marketplace has no admin functions, no fee setters, and no upgrade path; behavior is fixed at deploy. The marketplace address is included in KOTHToken's anti-snipe exemption list at construction so listings above 1% of supply settle during the initial 175-block window.

For the first 175 blocks (~35 minutes) after token deployment, any non-exempt wallet is capped at 1% of total supply (10,000 KOTH). Transfers that would push a wallet above this limit revert with AntiSniperLimit.

The exemption set is fixed at construction: deployer wallet, Uniswap v4 PoolManager, Uniswap v4 PositionManager, the hook contract, and the marketplace. After 175 blocks the cap lifts permanently; no admin call is required.

The fee and crown logic above runs inside each swap, not on the token's transfer(). Three v4 primitives make this possible:

function beforeSwap(address, PoolKey calldata k, SwapParams calldata p, bytes calldata)
 external returns (bytes4, BeforeSwapDelta, uint24)
{
 uint256 amt = uint256(-p.amountSpecified);
 uint256 fee;

 if (p.zeroForOne) { // ETH -> KOTH
 fee = amt * 200 / 10_000; // 2% to king
 poolManager.take(k.currency0, address(this), fee);
 kingBalances[currentKing] += fee;
 } else { // KOTH -> ETH
 fee = amt * 100 / 10_000; // 1% burned
 poolManager.take(k.currency1, address(this), fee);
 koth.burnFromHook(fee);
 }

 return (
 IHooks.beforeSwap.selector,
 toBeforeSwapDelta(int128(int256(fee)), 0),
 0
 );
}

An equivalent protocol on Uniswap v2 or v3, on a Curve-style AMM, or on a wrapper token would require an external taxing mechanism at the token's transfer layer, which traders can route around. v4's hook surface keeps the logic at the pool boundary, where every swap is observable.

All numerical parameters are compiled into contract bytecode and cannot be changed after deploy. There is no governance mechanism.

The protocol does not implement:

The Soul mapping is preserved on chain for potential future applications (airdrops, gated drops, leaderboards). This document does not commit to any specific use.