# smartcontractkit/chainlink-local architecture

> Architecture diagram of the GitHub repository smartcontractkit/chainlink-local, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smartcontractkit/chainlink-local
- Repository: https://github.com/smartcontractkit/chainlink-local

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment"
        CLI["Foundry / Hardhat / Remix IDE"]:::tool
    end

    %% Scripts & Tests
    subgraph "Scripts & Tests"
        JS_TS_Scripts["JS/TS Scripts & E2E/Smoke Tests"]:::tool
        Forge_Tests["Forge Solidity Tests (unit & integration)"]:::tool
    end

    %% Local Node and Contracts
    subgraph "Local Node (Anvil/Hardhat)" 
        Node["Local EVM Node"]:::node

        subgraph "CCIP Local Contracts"
            CCIP_SIM["CCIPLocalSimulator"]:::contract
            BURN_HELPER["BurnMintERC677Helper"]:::contract
            IR_CLIENT["IRouterClient Interface"]:::interface
            LinkToken["LinkToken"]:::contract
            WETH9["WETH9"]:::contract
        end

        subgraph "Data-Feeds Mocks"
            MOCK_V3["MockV3Aggregator"]:::mock
            MOCK_OFFCHAIN["MockOffchainAggregator"]:::mock
            AGG_IF["AggregatorInterface"]:::interface
        end

        subgraph "Data-Streams Mocks & Simulator"
            DSM["DataStreamsLocalSimulator"]:::mock
            MOCK_REPORT["MockReportGenerator"]:::mock
            MOCK_REWARD["MockRewardManager"]:::mock
            MOCK_VER["MockVerifier & Proxy"]:::mock
            REPORT_VER["ReportVersions"]:::mock
            DS_IF["Data-Streams Interfaces"]:::interface
        end
    end

    %% DApp Under Test
    subgraph "DApp Under Test"
        DAPP["User DApp Contracts"]:::dapp
    end

    %% External Networks
    subgraph "External Networks (Optional)"
        Ext["Live Mainnet/Testnet Routers & Tokens"]:::external
    end

    %% Connections
    CLI --> JS_TS_Scripts
    CLI --> Forge_Tests
    JS_TS_Scripts -->|Deploy & Interact| Node
    Forge_Tests -->|Deploy & Test| Node

    Node --> CCIP_SIM
    CCIP_SIM -->|uses Interface| IR_CLIENT
    CCIP_SIM -->|controls| BURN_HELPER
    BURN_HELPER -->|mints LINK| LinkToken
    BURN_HELPER -->|handles WETH| WETH9

    CCIP_SIM -->|routes messages| DSM
    DSM --> MOCK_REPORT
    DSM --> MOCK_REWARD
    DSM --> MOCK_VER
    DSM --> REPORT_VER
    MOCK_V3 --> AGG_IF
    MOCK_OFFCHAIN --> AGG_IF

    CCIP_SIM -->|sendMessage| IR_CLIENT
    IR_CLIENT -->|invoke callback| DAPP
    DAPP -->|callback execution| CCIP_SIM

    %% Optional External Flow
    DAPP -->|live interaction| Ext
    CCIP_SIM -->|can connect| Ext

    %% Click Events
    click CCIP_SIM "https://github.com/smartcontractkit/chainlink-local/blob/main/src/ccip/CCIPLocalSimulator.sol"
    click BURN_HELPER "https://github.com/smartcontractkit/chainlink-local/blob/main/src/ccip/BurnMintERC677Helper.sol"
    click IR_CLIENT "https://github.com/smartcontractkit/chainlink-local/blob/main/src/ccip/IRouterClient.sol"
    click LinkToken "https://github.com/smartcontractkit/chainlink-local/blob/main/src/shared/LinkToken.sol"
    click WETH9 "https://github.com/smartcontractkit/chainlink-local/blob/main/src/shared/WETH9.sol"
    click MOCK_V3 "https://github.com/smartcontractkit/chainlink-local/blob/main/src/data-feeds/MockV3Aggregator.sol"
    click MOCK_OFFCHAIN "https://github.com/smartcontractkit/chainlink-local/blob/main/src/data-feeds/MockOffchainAggregator.sol"
    click AGG_IF "https://github.com/smartcontractkit/chainlink-local/blob/main/src/data-feeds/interfaces/AggregatorInterface.sol"
    click DSM "https://github.com/smartcontractkit/chainlink-local/blob/main/src/data-streams/DataStreamsLocalSimulator.sol"
    click MOCK_REPORT "https://github.com/smartcontractkit/chainlink-local/blob/main/src/data-streams/MockReportGenerator.sol"
    click MOCK_REWARD "https://github.com/smartcontractkit/chainlink-local/blob/main/src/data-streams/MockRewardManager.sol"
    click MOCK_VER "https://github.com/smartcontractkit/chainlink-local/blob/main/src/data-streams/MockVerifier.sol"
    click REPORT_VER "https://github.com/smartcontractkit/chainlink-local/blob/main/src/data-streams/ReportVersions.sol"
    click DS_IF "https://github.com/smartcontractkit/chainlink-local/tree/main/src/data-streams/interfaces"
    click Forge_Tests "https://github.com/smartcontractkit/chainlink-local/tree/main/src/test"
    click JS_TS_Scripts "https://github.com/smartcontractkit/chainlink-local/tree/main/scripts"

    %% Styles
    classDef tool fill:#d4f1c5,stroke:#333;
    classDef node fill:#f0f0f0,stroke:#333;
    classDef contract fill:#bbdefb,stroke:#333;
    classDef mock fill:#e1bee7,stroke:#333,stroke-dasharray:5 5;
    classDef interface fill:#ffe0b2,stroke:#333,stroke-dasharray:2 2;
    classDef dapp fill:#ffcdd2,stroke:#333;
    classDef external fill:#b3e5fc,stroke:#333;
```
