How smartcontractkit/chainlink-local works
Project type and purpose
• Chainlink Local is a developer‐tool/library that simulates Chainlink CCIP on a local EVM node (Anvil/Hardhat/Remix/Foundry).
• It exposes smart contracts (CCIPLocalSimulator, helpers, routers, tokens) plus scripts and tests so that DApp developers can prototype cross‐chain flows entirely off‐chain.
File structure
Top‐level directories & roles:
• abi/ → JSON ABIs for CCIP contracts
• api_reference/ → Autogenerated MDX docs for JS & Solidity interfaces
• assets/ → Thumbnails, images
• lib/ → Submodules (chainlink‐brownie‐contracts, forge‐std, etc.)
• scripts/ → Example JS/TS scripts invoking the simulator
• src/ → Solidity modules:
– ccip/ (CCIPLocalSimulator.sol, RouterClient interfaces)
– data-feeds/ (MockV3Aggregator, helpers)
– data-streams/ (MockReportGenerator, Verifier, RewardManager)
– shared/ (LinkToken, WETH9, common interfaces)
– test/ (unit & integration tests in Solidity)
• test/ → E2E & smoke tests in TS/JS
• config files → hardhat.config.ts, foundry.toml, tsconfig.json, GitHub workflows
Key insights from the README
• The central contract is CCIPLocalSimulator.sol
• Developers import it via Forge or npm, then write tests or scripts to:
• deploy the simulator
• request LINK from the faucet
• configure source/destination RouterClients
• simulate CCIP token/message transfers locally or on a forked chain
A. Developer environment
• CLI tools: Foundry (forge/anvil), Hardhat, Remix IDE
• Scripts & tests: TS/JS runners, Forge tests
B. Local EVM node
• Anvil or Hardhat node (or forked mainnet/testnet)
C. CCIP Local Contracts
• CCIPLocalSimulator (facade)
• RouterClient interfaces for on-chain message routing
• BurnMintERC677Helper (LINK mint/burn)
• WETH9, LinkToken
• Mock chains: data-feeds & data-streams modules and mocks
D. User’s Contracts (DApp under test)
• Import CCIPLocalSimulator interfaces → interact via RouterClients
E. External (optional)
• Live testnet/mainnet routers & tokens (used when moving to live networks)
Relationships & data‐flow
1) Developer invokes test/script → deployed to local EVM node
2) CCIPLocalSimulator deploys RouterClient stubs + helpers on the node
3) Test code calls ccipLocalSimulator.requestLinkFromFaucet(...) → LINK minted via BurnMintERC677Helper
4) Test triggers CCIP “send” on source RouterClient → CCIPLocalSimulator routes the call to destination RouterClient
5) Destination RouterClient fires user‐defined callback on DApp contract
6) Tests assert state changes or emitted events
Architectural patterns & design principles
• Modularization by feature (ccip / data-feeds / data-streams / shared)
• Facade pattern in CCIPLocalSimulator to orchestrate multiple helpers/interfaces
• Interface‐based design: RouterClient & data‐streams interfaces allow easy mocking
• Single local node (via Anvil/Hardhat) as the “fabric” for all simulations
Technologies & frameworks to label
• Solidity smart contracts (0.8.x)
• Forge‐Std & Foundry toolchain
• Hardhat (TypeScript)
• MDX documentation (api_reference/)
• GitHub Actions for CI/CD