How fuellabs/fuel-block-committer works
Project type and purpose
• This is a backend‐only, monorepo Rust service (“fuel‐block‐committer”) whose sole purpose is to poll Fuel L2 blocks, encode and bundle them, and upload block metadata (and optional state blobs) to an Ethereum L1 contract. It also includes a separate “fee_algo_simulation” binary and full end-to-end tests.
File structure
• Top-level crates and directories:
• committer/ ← main binary (poller, scheduler, orchestrator)
• packages/ ← shared workspace crates:
– adapters/ ← external integrations (Ethereum RPC, Fuel GraphQL, PostgreSQL storage, clock)
– encoding/ ← bundle/blob encoder & decoder
– services/ ← core business logic (block importer, bundler, committer, pruner, reporters)
– metrics/ ← metrics tracking & exports
– test-helpers/ ← e2e test harness support
• fee_algo_simulation/ ← separate simulator binary
• e2e/ ← end-to-end tests (Foundry, Fuel Core)
• helm/ ← Kubernetes deployment charts
• Dockerfile, scripts, CI workflows, env files
README for additional insights
• Poll interval, transaction finalization logic, fee‐algorithm parameters, bundling thresholds and timeouts—all configured via environment variables.
• Database schema is versioned and visualized by SchemaSpy in CI.
• The service validates its configuration on startup (keys, fee multiplier ranges, fragment counts).
• Fuel Block Committer Binary
– Submodules:
· Block Poller (Fuel GraphQL adapter)
· Block Importer & Storage (SQLx/Postgres adapter)
· Bundle Manager & Encoder (encoding crate + bundle config)
· Fee Algorithm (SMA blocks, multipliers)
· Transaction Manager (ETH adapter + KMS)
· State Pruner
· Reporters (health, status, cost, wallet balance)
• PostgreSQL Database
• Ethereum RPC Endpoint + KMS/Key Management
• Fuel Core GraphQL Endpoint
• Metrics Exporter / Prometheus
• Fee Algo Simulator (separate binary)
• Helm Deployment (K8s Deployment, Service, HPA)
• Block Poller → Fuel GraphQL (“GraphQL query → BlockData”)
• Poller → Block Importer → Postgres (“INSERT BlockMetadata”)
• Postgres → Bundle Manager (“SELECT UnbundledFragments”)
• Bundle Manager → Encoder (“RawFragments → EncodedBundleBlob”)
• EncodedBundleBlob → Transaction Manager → Ethereum RPC (“sendRawTransaction → TxHash”)
• Transaction Manager → Postgres (“UPDATE CommitmentReceipt”)
• State Pruner → Postgres (“DELETE WHERE retention exceeded”)
• Reporters → Metrics Exporter (“gauge/counter metrics”)
• Fee Algo Simulator → shared adapters & encoding (inputs: historic block data from Ethereum; outputs: fee estimates)
c. Architectural patterns & principles:
• Hexagonal (Ports & Adapters): services call into adapter crates rather than direct clients.
• Modular Cargo workspace: compile-time isolation of concerns.
• Periodic scheduler/event loop for polling, bundling, pruning.
• Configuration-driven behavior with strong validation on startup.
d. Key technologies & libraries:
• Rust, Cargo workspaces
• sqlx for DB migrations & queries
• Foundry & fuelup for e2e testing
• Helm & Kubernetes for deployment
• AWS KMS (optional) or raw private keys for signing
Details & dependencies
• Asynchronous or buffered interactions (e.g., “NUM_BUFFERED_REQUESTS” toward Fuel endpoint).
• Configuration boundaries (environment variables injected into the committer binary).