getting started

how it works

the entire protocol is five contracts and one off-chain service. read this page and you'll understand 90% of what lode does.

the path of a single premium

follow one premium from arrival to burn. the path touches four of the five contracts.

1. arbitrageur sends the first swap of a new block

at block n, an mev searcher observes that the pool's price is stale relative to a centralized exchange. they submit an arbitrage swap to be the first transaction in block n. they pay the validator a priority tip to win the slot.

2. lodehook intercepts in beforeSwap

uniswap v4 fires the hook's beforeSwap callback before any pool math runs. lode checks, in order:

  1. global pause and per-pool pause
  2. same-block guard — was this slot already used?
  3. sub-economic floor — is the swap above minAuctionInputSize?
  4. zero-premium short-circuit — is premiumBps > 0?

if all checks pass, the hook computes premium = ⌊swapAmount · premiumBps / 10000⌋, returns a beforeSwapDelta instructing the poolmanager to take the premium from the input currency, transfers it to the pool's splitter, and marks the slot as used.

3. lodesplitter routes the premium three ways

each pool has its own splitter instance with three immutable destinations: protocol vault (20%), builder (0–30%), beneficiary (residual, typically the lp distributor). the splitter accumulates premiums until a keeper calls distribute(token), which transfers in this order: beneficiary → builder → protocol vault.

i
transfer ordering is a security feature

the trusted destination (protocol vault) is paid last to limit reentrancy surface. an untrusted recipient that attempts to reenter is blocked by the nonReentrant guard before reaching the vault.

4. lodeprotocolvault accumulates and bounds risk

the vault holds the protocol's 20% slice across many currencies. every withdrawal is capped per-currency per-day; raising the cap is timelocked 24 hours so a compromised owner cannot drain the vault in one shot.

5. keeper flushes to the buyback executor

once per day, the keeper calls flushToBuyback(token). balances flow to the off-chain buyback executor, which constructs a cowswap intent: sell the token for lode at market with 2% max slippage. on settlement, the lode is sent to 0x00…dead.

what the user sees

regular swappers
no change. the hook only fires on the first swap of each block, which is almost never a retail swap.
arbitrageurs
swap proceeds at uniswap quote + premium. they pay the premium back into the pool instead of paying it as priority tip to validators.
liquidity providers
collect their normal v4 fees plus ~80% of the captured premium, distributed pro-rata to in-range positions.
builders
collect 0–30% of premium for the pool they deployed.
lode holders
watch supply contract as protocol revenue is converted to lode at market and burned.

what's not in the loop

  • no off-chain orderflow auction.
  • no oracle. premium is a fixed bps of swap notional, not derived from a price feed.
  • no validator integration. lode runs entirely inside v4's public hook callbacks.
  • no wallet changes. existing uniswap front-ends route into lode pools without modification.
protocol architecturecomponent diagram and contract responsibilities. buyback & burnthe path from vault to 0x…dead.