How fuel-infrastructure/fuel-hyperlane-integration works
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”)