CCV Starter Kit — On-Chain (Foundry)

Starter Kit for Chainlink Cross-Chain Verifiers (CCVs) on-chain deployment and configuration.

Important

The CCV Starter Kit spans two repositories. This one deploys and configures the on-chain contracts. chainlink-ccv-starter-kit runs the verifier and aggregator services. Operating a CCV requires both.

Note

Building a Cross-Chain Verifier? If you have questions about this kit, about operating a CCV, or about getting your verifier onboarded into the CCIP indexer, contact us at clusersupport@smartcontract.com.

Documentation

The onboarding guide is an mdBook under docs/.

cargo install mdbook   # once
mdbook serve docs --open

Reading order (same as docs/src/SUMMARY.md):

1. Introduction → Getting started
2. Full flow example — the end-to-end commands; each step links to the depth chapter
3. Depth when a step needs it: Configuration, Deploying, Configuring the contracts
4. Governance checks, Handover, Safe batches

JSON schema detail: config/README.md. Stuck on an error: Troubleshooting.

What gets deployed

On every chain, on both sides of every lane:

Contract	How it's deployed	Address determinism
CREATE2Factory	Fresh deployer EOA, first tx (nonce 0)	Same address everywhere (via nonce-0 CREATE)
VersionedVerifierResolver	Via the factory, fixed CREATE2 salt	Same address everywhere (no constructor args)
CommitteeVerifier	Plain CREATE, constructor args	May differ per chain — rotates behind the resolver

Only the resolver needs a deterministic address. Verifiers rotate behind it; a chain can run several at once, each identified by an immutable bytes4 versionTag.

Layout

config/          config-as-data (synced chain reference, operator intent, lanes, deployments)
script/
  deploy/        BootstrapFactory, DeployResolver, DeployVerifier
  configure/     one script per privileged call, for one chain at a time
  config/        sync-ccip-config.sh — sync Chainlink's chain values from the CCIP API
  ownership/     per-target 2-step transfers (owners + storageLocationsAdmin)
  fees/          SweepFees + BalanceReport
  governance/    ValidateConfig, SnapshotOperator, DriftCheck, LaneParityCheck, deployments-report (+ wrappers)
src/lib/         ConfigLib, BaseScript (EOA/Safe switch), Types
artifacts/       forge build output (foundry.toml: out = "artifacts")
out/safe/        generated Safe Transaction Builder JSON, one subdir per chain alias
test/            unit + integration tests

Quick start

Fork this repository and clone your fork. Your config and deployment records live in config/ and belong in your own git history.

make install                # forge 1.8.1 (the version the Makefile and CI pin) + npm ci + git submodules
cp .env.example .env
make seed-operator-config   # config/operator.json from the example, if absent
make build

Then follow the full flow top to bottom — each step links to the chapter that explains it in depth.

Testing

make test          # hermetic; no RPC; seeds config/operator.json if absent
make sync-selftest   # offline config-sync selftest
make drift CHAIN=sepolia RPC_URL=$SEPOLIA_RPC_URL

Deployed addresses

Regenerate from your local deployment records:

make deployments-doc

The page is a placeholder until you deploy and run make deployments-doc — see docs/src/deployments.md.