Events and indexing

Canonical sources

What	Where
Event signatures	`src/lib/Events.sol`
Decoding rules	`docs/analytics/dune-integration-pack-v1.0.0.md`
ABIs	`abis/<network>/*.abi.json`
Addresses	`deployments/<network>.json`

Rule: Filter logs by evt_block_number >= startBlock.

Event codebooks (immutable)

Enum	Values
`ShareholderClaim.mode`	0=ETH, 1=LOCK_FURNACE
`AutoCompoundPaused.reasonCode`	1=NOT_OWNER, 2=LISTED, 3=EXPIRED, 4=INVALID_TOKEN_ID
`FurnaceEnter.mode`	0=ENTER_WITH_ETH, 1=ENTER_WITH_CLAIM, 2=LOCK_FURNACE, 3=ENTER_WITH_TOKEN
`LockDelisted.reason`	0=NORMAL, 1=EMERGENCY, 2=SETTLED_BY_FURNACE, 3=SOLD_TO_FURNACE, 4=EXPIRED

Key event groups

MineCore: EntryTokenRegistrySet, Takeover, ReignFinalized, TakeoversPausedChanged, KingWithdrawal

VeClaimNFT: LockCreated, LockExtended, LockAmountIncreased, LockMerged, LockUnlocked, AutoMaxSet

ShareholderRoyalties: ShareholderTakeoverAllocation, ShareholderFlush, ShareholderClaim, ShareholderAutoCompound*

Furnace: FurnaceEnter, BonusPaid, LpOverflowDripPaid, LockSoldToFurnace, ListingSettled, ReserveCredited, LockingPausedChanged

LpStakingVault7D: LpStaked, LpUnbondStarted, LpUnbondWithdrawn, LpRewardsNotified, LpRewardsClaimed, LpRewardsLocked, AutoCompound*, LpFeesHarvestedToRewards

MarketRouter: LockListed (limit sell / Market listing: minClaimOut + expiresAtTime), LockDelisted, ListingSettled, MarketSellToFurnace, TradingPausedChanged, BonusTargetEscrow* (limit buy / Buy intent: Created, AutoFurnaceExecuted, Expired, Cancelled, Extended)

MaintenanceHub: Poked

Genesis: GenesisFinalized, Locked, LockExtended, WithdrawLp

Decoding notes

Furnace LP stream: BonusPaid.lpTopupClaim and LpOverflowDripPaid.dripAmount fund the stream; LP vault receives via LpRewardsNotified on tick.
enterWithToken: FurnaceEnter doesn’t include tokenIn/amountIn; recover from calldata or ERC20 Transfer logs.
EntryTokenRegistry: MineCore and Furnace emit EntryTokenRegistrySet independently.

Indexing strategy

Use shipped ABIs as single decoding input
Prefer event-driven state (e.g., LockCreated/Extended/Unlocked for lifecycle)
Storage reads only for spot dashboard values
Follow docs/analytics/metrics-canon-v1.0.0.md for metrics
Leaderboards: docs/analytics/indexer-and-dune-implementation-guide-v1.0.0.md

Agent tooling

Repo tooling for offchain agents lives in agents/sdk/. It includes:

getGameStateSnapshot() (AgentLens-first, multicall fallback)
JSONL event streamer (RPC logs, optional subgraph backfill)
subgraph lag/address parity checker

Run the streamer:


RPC_URL=...
npm -C agents/sdk run example:events

Backfill recent history from the subgraph before live RPC logs:


RPC_URL=...
SUBGRAPH_URL=...
npm -C agents/sdk run example:events -- --backfill --backfill-limit 100

Validate subgraph health + address parity:


RPC_URL=...
SUBGRAPH_URL=...
npm -C agents/sdk run example:subgraph-health -- --pretty

Dune integration

Resource	Path
Event decoding + codebooks	`docs/analytics/dune-integration-pack-v1.0.0.md`
Metric meanings	`docs/analytics/metrics-canon-v1.0.0.md`
Leaderboards	`docs/analytics/leaderboards-ui-and-dune-compatible-v1.0.0.md`
SQL templates	`analytics/dune/`

Usage: Get addresses from manifests → decode with ABIs → filter by startBlock → build from templates.

Achievements engine

Cosmetic badges computed offchain in chat worker.

Endpoint: GET /api/achievements?address=0x...&chainId=8453

Config (workers/chat): SUBGRAPH_URL (required), SUBGRAPH_AUTH_TOKEN (optional), ACHIEVEMENTS_SYNC_ENABLED, ACHIEVEMENTS_SYNC_OVERLAP_BLOCKS, ACHIEVEMENTS_SYNC_BATCH_SIZE

Required subgraph entities: Takeover, ReignFinalizedEvent, VeLock*Event, ShareholderClaimEvent, FurnaceEnterEvent, MarketLockListedEvent, MarketSellToFurnaceEvent, BonusTargetEscrowEvent, LpStakedEvent, etc. See subgraph/schema.graphql.