How moonbeam-foundation/moonbeam works
Project type and purpose
• This repository is the Moonbeam parachain node: a blockchain node (Rust/FRAME) that is Ethereum-compatible and runs as a Polkadot parachain.
• It provides a Substrate-based node binary, a WASM runtime composed of FRAME pallets (Polkadot-SDK, Frontier, plus Moonbeam-specific pallets), EVM integration, RPC endpoints (Ethereum JSON-RPC and Substrate RPC), developer tooling, TypeScript-based API clients, and end-to-end test suites.
Top-level architecture overview
┌─────────────────────────────┐
│ 1) Client/API & CLI Tools │
├─────────────────────────────┤
│ 2) Node Binary & Service │
├─────────────────────────────┤
│ 3) Runtime (WASM + Pallets) │
├─────────────────────────────┤
│ 4) External Integrations │
└─────────────────────────────┘
Main components and relationships
a. Client / API Layer
– TypeScript-API (typescript-api/, types-bundle/)
• Generates strong-typed JSON-RPC clients from on-chain metadata.
– Tools and CLI (cli-opt/, node/cli/, scripts/, tools/)
• Helpers for spec generation, block tracking, testing, release bots.
– Integration Tests (test/)
• Moonwall harness driving the node via JSON-RPC to exercise EVM, precompiles, XCM, staking, etc.
b. Node Binary & Service
– node/cli/ + node/service/
• Parses CLI flags (chain, dev, sealing), sets up networking, consensus (Cumulus), RPC servers (HTTP, WS, Ethereum JSON-RPC).
• Embeds the compiled WASM runtime and native runtime for block execution.
– client/
• client/rpc-core, client/rpc (trace, dev, finality, debug), client/evm-tracing, client/vrf
• Implements official JSON-RPC methods, tracing subsystems, VRF randomness providers.
c. Runtime (FRAME + Pallets + Precompiles)
– runtime/common, runtime/moonbeam, runtime/moonbase, runtime/moonriver, runtime/evm_tracer, runtime/relay-encoder, …
• FRAME runtime crates split by target network, each defining the same set of pallets with network-specific params (ChainId, origins, weights).
– Polkadot-SDK Pallets (Utility, Balances, Sudo, Timestamp, ParachainInfo, ParachainUpgrade, RandomnessCollectiveFlip)
– Frontier pallets (Ethereum, EVM, EVMChainId)
– Moonbeam-specific pallets (in pallets/): AssetManager, ParachainStaking, XCM-bridge, EVM precompiles in precompiles/
– Precompiles (assets-erc20, balances-erc20, proxy, …) for EVM compatibility
d. External Integrations
– Polkadot Relay Chain (Cumulus): parachain block submission & finality
– Ethereum tooling and wallets via JSON-RPC
– Docker registry for published node images
– GitHub Actions / CI for build, tests, benchmarks
Architectural Patterns & Design Principles
• Modular Rust workspace: each logical component (runtime, node, clients, tools) lives in its own crate.
• Clear separation of concerns:
– Runtime handles state transition logic (WASM VM + pallets).
– Node binary handles networking, consensus, RPC interfaces.
– Clients and tools consume the node’s JSON-RPC surface.
• FRAME / pallet-based extensibility: easy to add or replace pallets.
• Cumulus for parachain integration.
• Frontier for EVM compatibility.
• TypeScript code generation from on-chain metadata for strong typing.
• CI/CD via GitHub Actions and Docker for releases.