Protocol Overview

ClaimRush is an onchain king-of-the-hill game on Base. Two loops drive the protocol — the Crown loop and the Furnace loop — connected by a single value flow called the CLAIM stream. This page explains the architecture from a contract-interaction perspective.

The CLAIM stream (developer view)

The CLAIM stream is the end-to-end value flow through the protocol. ETH enters via takeovers, splits between the King and Barons, CLAIM is mined, locked in the Furnace with a bonus, and veCLAIM earns royalties from future takeovers. Understanding this flow is key to integrating with any part of the protocol.

How to read this:

A player calls MineCore.takeover(maxPrice) (or takeoverWithToken(...) for allowlisted tokens). The ETH splits: 75% to the previous King, 25% to ShareholderRoyalties.onTakeover(reignId).

ShareholderRoyalties records the ETH and auto-attempts indexing against total veCLAIM. If that push reverts, MineCore retains the ETH in shareholderEthPending until retryPushShareholderEth() succeeds. If the push succeeds but the ve checkpoint is stale, the ETH stays queued in pendingShareholderETH until a later flush.

Barons claim via claimShareholder(mode=0, ...) (Collect ETH) or claimShareholder(mode=1, ...) (Collect & Lock → Furnace.lockEthReward(...)).

When a reign is finalized, MineCore settles the dethroned King’s accrued CLAIM — either minting liquid CLAIM to the configured recipient, or routing it through Furnace.enterWithClaimFor(...) if king auto-lock is enabled. A user holding liquid CLAIM can lock later via Furnace.enterWithClaim(...).

Every successful Furnace path creates or tops up veCLAIM through the Furnace-only createLockFor(...) / addToLockFor(...) surfaces, and that veCLAIM earns a share of future royalties.

The two loops

Crown loop (MineCore): A player calls takeover(maxPrice) with ETH to become King. While King, they mine CLAIM via the emission stream. When dethroned, they receive 75% of the next takeover’s ETH. See Core Mechanics for pricing, routing, and emission formulas.

Furnace loop (Furnace + ShareholderRoyalties): A player calls enterWithEth(...), enterWithClaim(...), or enterWithToken(...) on the Furnace to lock CLAIM with a bonus and receive veCLAIM. As a veCLAIM holder (Baron), they earn ETH royalties from every takeover via ShareholderRoyalties. They can compound by claiming in mode 1 (Collect & Lock), which routes ETH back through the Furnace via lockEthReward(...). Existing locks earn additional bonuses when extended (extendWithBonus); AutoMax locks accrue these automatically via claimAutoMaxBonus (keeper-triggered, 24h cooldown). See Furnace and Royalties.

Recommended UI defaults

These are the defaults used by the official app. They are not onchain rules — integrators building their own apps may choose different defaults.

Entry token defaults: Default order is CLAIM if CLAIM balance > 0, else ETH if ETH balance > 0, else WETH if WETH balance > 0, else the first enabled custom token with a positive balance, else CLAIM fallback. Collect & Lock always uses ETH because shareholder rewards enter the Furnace as ETH.

Royalty action defaults: Default to Collect ETH (mode 0) for a liquid payout. Offer Collect & Lock (mode 1) as the optional compounding path when locking is enabled; fall back to Collect ETH when locking is paused.

Takeover entry: Takeovers are priced in ETH. The protocol also supports an optional token entry path (MineCore.takeoverWithToken) which swaps an allowlisted token to ETH before executing the takeover.

Contract map

Core (v1.0.0):

Supporting:

• EntryTokenRegistry — per-surface allowlist + deterministic swap routing
• DexAdapter — Aerodrome v2 router wrapper
• DelegationHub — opt-in bot sessions (EIP-712)
• MaintenanceHub — permissionless upkeep batching
• ClaimAllHelper — stateless bundler for Collect ETH / Collect & Lock + delegation wrappers
• AgentLens — optional onchain snapshot bundler for agents

Genesis:

• LaunchController, GenesisLPVault24M

Data flow (contract-level)

MaintenanceHub.poke(args) also drives Furnace.tick() best-effort, so LP-stream accrual and overflow-drip maintenance can advance even when no user entry or sellback happens in that block.

Launch timeline

Sequence: deploy → wire → stealth launch → ownership finalization (transfer to timelock) → timelock bootstrap → external audit → apply fixes if needed → schedule freeze-and-burn finality → wait timelock delay → execute finality batch.

The protocol is fully playable from launch. ClaimToken and VeClaimNFT are permanent direct roots. MineCore, Furnace, MarketRouter, and ShareholderRoyalties are proxy-backed runtime contracts, so the live game can be repaired without changing its canonical addresses during the governed launch window. ClaimToken freezes at wire time and its ownership is renounced immediately (it has no post-freeze owner knobs). Permanent finality arrives when the timelocked freeze-and-burn batch freezes the remaining four freeze-gated contracts (MineCore, Furnace, VeClaimNFT, ShareholderRoyalties) and burns the four runtime ProxyAdmins. That timelock delay is the public countdown to finality.

During genesis, MineCore.guardian may temporarily be the LaunchController contract for the one-shot finalization path. That is a bounded launch exception, not a reusable long-term guardian power.

Trust boundaries

Direct permanent roots:

• ClaimToken
• VeClaimNFT
• Event schema expectations for indexers still anchor to the canonical runtime addresses

Wiring frozen after finality:

• ClaimToken: setMineCore() permanently locked — only the canonical MineCore can mint CLAIM
• Furnace: setShareholderRoyalties(), setMineCore(), setMineMarket(), setFurnaceQuoter(), setLpRewardsVault() permanently locked
• Furnace: delayed emergency LP-vault recovery (requestEmergencyVaultRewire(address), cancelEmergencyVaultRewire(), executeEmergencyVaultRewire()) remains available after freeze
• MineCore: setFurnace(), setClaimAllHelper() permanently locked
• VeClaimNFT: setFurnace(), setMineMarket() permanently locked
• ShareholderRoyalties: setWiring(), setClaimAllHelper() permanently locked

Upgradeable runtime quartet (before burn only):

• MineCore, Furnace, MarketRouter, and ShareholderRoyalties keep stable proxy addresses
• Code upgrades happen through owned transparent-proxy admins
• freezeConfig() alone does not disable those proxy-admin upgrades
• the freeze-and-burn ceremony is what removes quartet upgrade authority permanently

Owner-managed (timelock governed by the Safe):

• Operational peripherals on core contracts (delegationHub, entryTokenRegistry, guardian) — onlyOwner, not frozen
• Wiring setters on MarketRouter, EntryTokenRegistry — onlyOwner, no freeze gate, governance delay via timelock
• Runtime safeguards constrain in-place changes even without a freeze (e.g., EntryTokenRegistry cannot change router/factory after route surfaces exist; Furnace cannot clear lpRewardsVault while LP liability remains)
• Operational allowlists (settlement keepers, compounding keepers, harvest/compound keepers)
• Guardian rotation on all rotatable surfaces
• MarketRouter owner break-glass settlement during the keeper grace window
• LP fee harvest execution and bounty collection (harvestFeesToRewards)

Guardian-managed (fast incident response):

• Pause/unpause on all pause surfaces (takeovers, locking, trading)
• EntryTokenRegistry emergency token disables (setTokenEnabled(token, false) — guardian can disable only, not re-enable)
• Emergency setGuardian(address) fast rotation on rotatable surfaces

Permissionless:

• MaintenanceHub.poke(args) — bundled upkeep
• Furnace.tick() — direct LP-stream / overflow-drip upkeep
• ShareholderRoyalties.flushPendingShareholderETH() — direct royalty flush retry

Wiring safety model

Protocol contracts do not trust raw stored pointers in isolation. Every state-changing path resolves its dependencies through live cross-checks — verifying that Furnace, MarketRouter, MineCore, VeClaimNFT, ClaimToken, and ShareholderRoyalties still agree on one canonical bundle before proceeding. If any root has drifted, the call reverts (“fails closed on bundle drift”).

This pattern applies to settlement, delegation, royalty checkpointing, auto-compound execution, and MaintenanceHub upkeep. Individual pages note where the check applies; the invariant is always the same: no split-brain deployments can silently mutate accounting.

See also

• Core Mechanics — takeover loop, emission schedule, Baron royalties
• Getting Started — deployed addresses and SDK quick start
• Runtime Proxy Upgrades — live upgrade procedure for the proxy-backed runtime quartet
• Security, Guardian, Pausing — governance model and role hierarchy
• User manual: Core Concepts