index.md

type	index

Documentation

The map into this repository's documentation. Humans start here or at the README; agents start at AGENTS.md. Every fact is authored once and linked, never mirrored.

The docs follow four forms: get-started (learn by doing), guides (accomplish an outcome), reference (look a fact up), and concepts (understand why). A learnings layer (troubleshooting, gotchas, decisions) captures hard-won operational knowledge.

Get started

• Quick start - deploy a token and a pool to a testnet and send a transfer.
• Production checklist - the ordered list to walk before a mainnet launch.
• Prerequisites - layered by whether you deploy, send, or run on a testnet.

Primitives catalog (the building blocks)

• docs/primitives/ - one page per user-facing script and make target: description, modes, safety flags, and inputs. Generated from the scripts so it cannot drift.
• docs/primitives/catalog.json - the machine-readable index for agents.

Guides (outcomes)

How-to guides for a specific outcome live under docs/guides/. Highlights:

• Send, track, and diagnose a transfer.
• Enabling an existing token (adoption).

Workflows (composed, agent-executable)

Multi-step flows with a machine-readable manifest each, under docs/workflows/: greenfield deploy, adopt a token, and the EOA-to-Safe roles handoff.

Reference (look it up)

• Pool versions - how the repo decides what a pool is, and the per-version support matrix.
• Pool-version behavior deltas - rate-limit validation, pause, decimals metering, and fast-finality differences, each fixture-backed.
• Config and project-store schema - every field of config/chains and project/.
• Config architecture - the layering, sync data-flow, and writers.
• The CCIP REST API v2 spec - the source of truth for the script/config/ API callers, and why an omitted filter is a silent wrong answer.
• Deployed addresses - the project store, resolution ladder, and redeploy guard.
• Reading a write script's outcome line - what SENDING and the two NOT SENT lines mean, and what actually confirms the state.

Concepts (understand why)

• Roles - the authority durable store, the two governance axes, and reconciliation.
• Governance modes - EOA and Safe execution, batching, and the signing ceremony.
• Composition - combining primitives into one atomic batch (the ClaimAndAcceptAdmin example).
• The store model - config vs project vs history, token groups, and the redeploy guard.
• Diagnosis - reading a transfer's status and the getExecutionState version footgun.
• Verifiers (CCVs) - required vs optional verifiers, the additional-CCV threshold, and finality.
• Fees - fee composition and the bps-fee observability trap.

Learnings layer

• Decisions (ADRs): signing with a keystore.
• Troubleshooting and gotchas: see docs/troubleshooting/ and docs/gotchas/.