Getting Started

Go from zero to first build in minutes. This page covers repo setup, local development, and key integration rules.

Integration rules (must follow)

Never hardcode addresses. Load from deployments/<network>.json.
Never invent event signatures. Use src/lib/Events.sol + ABIs in abis/.
Use correct UI verbs. ETH payouts = “Collect” | CLAIM rewards = “Harvest”

Prerequisites

Tool	Version
Foundry	1.6.0 (CI pinned)
Node.js	Use repo `.nvmrc`
Python 3	For lint/sync scripts
Git	Standard

Repo setup


make deps    # Foundry libraries (pinned)
make build   # Build contracts
make test    # Run tests

Run local stack


npm run local

Starts Anvil → deploys contracts → runs the two-step local wiring flow (Wire → MaintenanceHub → Wire) → writes synced manifests → starts frontend dev server. The runner simulates both DeployLocal.s.sol and DeployLocalDexHarness.s.sol before broadcasting so a late local constructor or pool-registration revert cannot leave a partial local stack behind, pins the same local signer into both wire passes, explicitly sets GUARDIAN to that same deployer during those wire passes, pins LOCAL_GENESIS_BURN_GUARDIAN to that same deployer address, and relies on Wire.s.sol preflight simulation so ambient shell keys or stale guardian overrides cannot create partial local wiring / finalize drift. DeployLocalDexHarness.s.sol also checks its freshly deployed WETH / factory / pool roots before success. The standard local finalize helpers also pin that same local deployer into GUARDIAN.

EIP-170 code size limits are enforced by default. To temporarily allow oversized local deploys, run with LOCAL_ALLOW_OVERSIZE=1 (or --allow-oversize).

Variants:

Command	What it does
`npm run local:deploy`	Deploy + write manifests only
`npm run local:frontend`	Frontend only (manifests must exist)

CI-parity gates


make gates

Run before shipping changes. Checks: deployment sync, manifest parity, docs lint, ABI lint/sanity, subgraph lint, Solidity policy lint, analytics SQL lint.

Supported environments

Environment	Network
local	Anvil (Foundry)
base_sepolia	Base Sepolia (staging)
base_mainnet	Base mainnet (production)

Manifests: deployments/<network>.json (canonical) | frontend/public/deployments/<network>.json (UI runtime copy)

Deployed addresses

Type	Path
Canonical	`deployments/<network>.json`
Human-readable	`deployments/<network>.md`

Rule: Filter logs by evt_block_number >= startBlock from manifest.

Repo map

Path	Contents
`src/`	Solidity contracts; `src/lib/Constants.sol`, `src/lib/Events.sol`
`docs/`	Spec, security, analytics, UI notes
`deployments/`	`<network>.json` (canonical manifests)
`abis/`	Versioned exported ABIs for indexers
`frontend/`	Next.js app (proprietary; not released)
`subgraph/`	The Graph mappings + schema
`analytics/`	Dune integration pack + SQL templates
`workers/`	Offchain services (chat, etc)

Key params (v1.0.0)

Quick reference for the most common constants. See Constants Reference for the full list.

Crown pricing (MineCore)

Param	Value
Floor	0.001 ETH
Decay	1 hour
Reference update	`referencePrice = pricePaid * 2`

Emissions

Linear decay over 2 years.

Stream	Start	Floor
Crown (King)	50 CLAIM/s	~5.56 CLAIM/s
Furnace reserve	5 CLAIM/s	~0.56 CLAIM/s

Locks (VeClaimNFT)

Param	Value
Min amount	1,000 CLAIM
Duration	7–365 days
Max per wallet	32

Barons activation (ShareholderRoyalties)

MIN_VE_FLUSH = 100e18 — manual / residual shareholder flushes below the threshold no-op, but takeover allocations are auto-attempted immediately and index as soon as a processed shareholder denominator exists and the ve checkpoint is current in that block.