# fuel-infrastructure/fuel-hyperlane-integration architecture

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

- Interactive diagram: https://gitdiagram.com/fuel-infrastructure/fuel-hyperlane-integration
- Repository: https://github.com/fuel-infrastructure/fuel-hyperlane-integration

## Overview

##### Project type and purpose
- This is a blockchain‐integration project: a collection of Sway smart contracts (“contracts/”) implementing the Hyperlane Protocol on Fuel, accompanied by off-chain Rust programs (“deploy/”, “e2e/”, “demo/”) and shell scripts/configs (“infra/”) to spin up local/testnet environments, deploy contracts, run agents, and execute tests or demos.

##### File structure
- Top-level directories:
- contracts/ – all on-chain Sway modules (interfaces, ISMs, hooks, libs, mailbox core, mocks, tests)
- deploy/ – Rust binary to deploy & initialize contracts to Fuel (LOCAL or TESTNET)
- e2e/ – Rust binary for end-to-end tests against local Fuel & EVM nodes
- demo/ – Rust binary illustrating live testnet usage across Fuel and Base Sepolia
- infra/ – shell scripts and YAML/JSON configs to start local Fuel node, Anvil (EVM), and Hyperlane relayer/validator agents
- test-utils/ – common Rust utilities used by tests
- Config files: Forc.toml/Cargo.toml define build and dependency metadata for each module.
- Scripts: infra/run.sh, infra/run-val.sh orchestrate environment startup; contracts/**/*.sw are Sway source files.

##### README for architectural insights
- Describes on-chain components: Mailbox, Interchain Gas Paymaster, Gas Oracle, various ISMs, post‐dispatch hooks, ValidatorAnnounce, WarpRoutes
- Off-chain workflows: deployment script (deploy), E2E test suite (e2e), demo orchestration (demo), infrastructure setup (infra)

- Interfaces module
- Core contracts: Mailbox, IGP, GasOracle, WarpRoute, ValidatorAnnounce
- ISMs: MessageIdMultisigISM, MerkleRootMultisigISM, DomainRoutingISM, DefaultFallbackDomainRoutingISM, PausableISM, AggregatedISM
- Hooks: AggregationHook, FallbackDomainRoutingHook, MerkleTreeHook, PausableHook, ProtocolFeeHook, GasPaymasterHook
- Libraries: checkpoint, merkle, message, std-hook-metadata, std-lib-extended
- Mocks & Test contracts
- deploy.rs – Deploy & initialize contracts on Fuel (LOCAL/TESTNET) and dump addresses
- e2e.rs – Run end-to-end test cases against a local Fuel node + Anvil (EVM) node
- demo.rs – Demo execution on live testnets (FuelTestnet + BaseSepolia)
- test-utils – Shared Rust library for test logic
- infra/run.sh – Launch local fuel-core, anvil, Hyperlane relayer
- infra/run-val.sh – Launch validator agents
- infra/configs/* – Chain configs, agent configs, warp-route configs, local fuel snapshot
- Local Fuel node (fuel-core)
- Local EVM node (anvil)
- Hyperlane CLI / Hyperlane Relayer Agents
- Testnet RPC endpoints (for demo)

1. Developer → “forc build” → compiles Sway contracts → outputs ABI & bytecode
2. deploy.rs ⟶ Fuel node + Anvil (via hyperlane-cli) → deploy on-chain contracts & Hyperlane contracts on EVM
3. infra/run.sh ──► starts fuel-core & anvil ──► relayer agent connects to both nodes using infra/configs/*.json
4. e2e.rs ⟶ sends cross-chain messages (Mailbox calls, IGP payments, hooks) → Fuel & EVM nodes → verifies state transitions and events
5. demo.rs ⟶ connects to live FuelTestnet & BaseSepolia via RPC → demonstrates WarpRoutes, message delivery, gas payments

##### Architectural patterns
- Modular on-chain design: each ISM/hook is its own contract, enabling plug-and-play security modules or post-dispatch behaviors
- Clear separation of concerns:
- On-chain business logic in Sway contracts
- Deployment & orchestration in Rust binaries
- Environment setup in shell scripts + config files
- Microservice‐style off-chain tools communicating over JSON-RPC with chain nodes

- Labels: exact directory or script names (e.g., “contracts/mailbox”, “deploy/src/main.rs”)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "On-Chain Contracts"
        InterfacesModule["contracts/interfaces"]:::onchain
        Mailbox["contracts/mailbox"]:::onchain
        GasOracle["contracts/gas-oracle"]:::onchain
        WarpRoute["contracts/warp-route"]:::onchain
        ValidatorAnnounce["contracts/validator-announce"]:::onchain
        subgraph ISMs
            AggregatedISM["AggregatedISM"]:::onchain
            MerkleRootMultisigISM["MerkleRootMultisigISM"]:::onchain
            MessageIdMultisigISM["MessageIdMultisigISM"]:::onchain
            PausableISM["PausableISM"]:::onchain
            DomainRoutingISM["DomainRoutingISM"]:::onchain
            DefaultFallbackDomainRoutingISM["DefaultFallbackDomainRoutingISM"]:::onchain
        end
        subgraph Hooks
            AggregationHook["AggregationHook"]:::onchain
            FallbackDomainRoutingHook["FallbackDomainRoutingHook"]:::onchain
            MerkleTreeHook["MerkleTreeHook"]:::onchain
            PausableHook["PausableHook"]:::onchain
            ProtocolFeeHook["ProtocolFeeHook"]:::onchain
            GasPaymasterHook["GasPaymasterHook"]:::onchain
        end
        subgraph "Libraries"
            Checkpoint["checkpoint"]:::onchain
            MerkleLib["merkle"]:::onchain
            MessageLib["message"]:::onchain
            StdHookMetadata["std-hook-metadata"]:::onchain
            StdLibExtended["std-lib-extended"]:::onchain
        end
        MocksTests["Mocks & Test Contracts"]:::onchain
    end

    subgraph "Off-Chain Services"
        Deploy["deploy/src/main.rs"]:::offchain
        E2E["e2e/src/main.rs"]:::offchain
        Demo["demo/src/main.rs"]:::offchain
        TestUtils["test-utils/src/lib.rs"]:::offchain
    end

    subgraph "Infrastructure"
        InfraScripts["infra/run.sh & infra/run-val.sh"]:::infra
        InfraConfigs["infra/configs"]:::infra
    end

    subgraph "External Nodes/Services"
        FuelNode["Local Fuel Node (fuel-core)"]:::external
        EVMNode["Local EVM Node (anvil)"]:::external
        Relayer["Hyperlane Relayer Agents"]:::external
        TestnetRPC["Testnet RPC Endpoints"]:::external
    end

    Developer((Developer)):::external

    Developer -->|"forc build"| InterfacesModule
    Deploy -->|"hyperlane-cli deploy & JSON-RPC"| Mailbox
    InfraScripts -->|"starts"| FuelNode
    InfraScripts -->|"starts"| EVMNode
    InfraScripts -->|"uses configs"| InfraConfigs
    InfraScripts -->|"launches"| Relayer
    Relayer -->|"monitors events"| FuelNode
    Relayer -->|"monitors events"| EVMNode
    E2E -->|"JSON-RPC"| FuelNode
    E2E -->|"JSON-RPC"| EVMNode
    Demo -->|"RPC connect"| TestnetRPC

    classDef onchain fill:#ADD8E6,stroke:#0000FF,color:#0000FF
    classDef offchain fill:#90EE90,stroke:#008000,color:#008000
    classDef infra fill:#D3D3D3,stroke:#666666,color:#666666
    classDef external fill:#FFA500,stroke:#FF4500,color:#FF4500

    click InterfacesModule "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/interfaces"
    click Mailbox "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/mailbox"
    click GasOracle "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/gas-oracle"
    click WarpRoute "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/warp-route"
    click ValidatorAnnounce "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/validator-announce"
    click AggregatedISM "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/ism/aggregation-ism"
    click MerkleRootMultisigISM "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/ism/multisig/merkle-root-multisig-ism"
    click MessageIdMultisigISM "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/ism/multisig/message-id-multisig-ism"
    click PausableISM "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/ism/pausable-ism"
    click DomainRoutingISM "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/ism/routing/domain-routing-ism"
    click DefaultFallbackDomainRoutingISM "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/ism/routing/default-fallback-domain-routing-ism"
    click AggregationHook "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/hooks/aggregation"
    click FallbackDomainRoutingHook "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/hooks/fallback-domain-routing-hook"
    click MerkleTreeHook "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/hooks/merkle-tree-hook"
    click PausableHook "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/hooks/pausable-hook"
    click ProtocolFeeHook "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/hooks/protocol-fee"
    click GasPaymasterHook "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/hooks/gas-paymaster"
    click Checkpoint "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/libs/checkpoint"
    click MerkleLib "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/libs/merkle"
    click MessageLib "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/libs/message"
    click StdHookMetadata "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/libs/std-hook-metadata"
    click StdLibExtended "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/libs/std-lib-extended"
    click MocksTests "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/contracts/mocks"
    click Deploy "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/blob/master/deploy/src/main.rs"
    click E2E "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/blob/master/e2e/src/main.rs"
    click Demo "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/blob/master/demo/src/main.rs"
    click TestUtils "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/blob/master/test-utils/src/lib.rs"
    click InfraScripts "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/blob/master/infra/run.sh"
    click InfraConfigs "https://github.com/fuel-infrastructure/fuel-hyperlane-integration/tree/master/infra/configs"
```
