# fuellabs/fuel-block-committer architecture

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

- Interactive diagram: https://gitdiagram.com/fuellabs/fuel-block-committer
- Repository: https://github.com/fuellabs/fuel-block-committer

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    FGQL["Fuel Core GraphQL Endpoint"]:::external
    ETHRPC["Ethereum RPC Endpoint"]:::external
    KMS["KMS / Key Management"]:::external
    HELM_CHARTS["Helm Deployment Charts"]:::deployment

    %% Database
    DB[(PostgreSQL Database)]:::database

    %% Metrics
    METRICS["Metrics Exporter / Prometheus"]:::external

    %% Fee Algo Simulator
    SIM["Fee Algo Simulator"]:::internal

    %% Main Binary and its components
    subgraph "Fuel Block Committer Binary" 
        direction TB
        MAIN["committer/src/main.rs"]:::internal

        subgraph Components
            direction TB
            POLLER["Block Poller"]:::internal
            IMPORTER["Block Importer & Storage"]:::internal
            BUNDLER["Bundle Manager & Encoder"]:::internal
            FEE["Fee Algorithm"]:::internal
            TXM["Transaction Manager"]:::internal
            PRUNER["State Pruner"]:::internal
            REPS["Reporters"]:::internal
        end
    end

    %% Relationships
    POLLER -->|"GraphQL query → BlockData[]"| FGQL
    POLLER -->|"BlockData[]"| IMPORTER
    IMPORTER -->|"INSERT BlockMetadata"| DB
    DB -->|"SELECT UnbundledFragments"| BUNDLER
    BUNDLER -->|"RawFragments → EncodedBundleBlob"| BUNDLER_ENCODER
    BUNDLER_ENCODER["Blob & Bundle Encoder"]:::internal
    click BUNDLER_ENCODER "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/encoding/src/blob/encoder.rs"
    BUNDLER_ENCODER -->|"EncodedBundleBlob"| TXM
    FEE -->|"FeeEstimate"| BUNDLER
    TXM -->|"sendRawTransaction → TxHash"| ETHRPC
    TXM -->|"UPDATE CommitmentReceipt"| DB
    PRUNER -->|"DELETE WHERE retention exceeded"| DB
    REPS -->|"gauge/counter metrics"| METRICS

    %% Fee Algo Simulator reuse
    SIM -->|"historic block data"| ETHRPC
    SIM -->|"EncodedBundle sim inputs/outputs"| BUNDLER_ENCODER

    %% Deployment
    HELM_CHARTS -->|"Deploy Fuel Block Committer"| MAIN

    %% Click Events for components
    click MAIN "https://github.com/fuellabs/fuel-block-committer/blob/master/committer/src/main.rs"
    click POLLER "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/adapters/fuel/src/client.rs"
    click IMPORTER "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/services/src/block_importer.rs"
    click IMPORTER "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/adapters/storage/src/postgres.rs"
    click BUNDLER "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/services/src/block_bundler.rs"
    click SIM "https://github.com/fuellabs/fuel-block-committer/blob/master/fee_algo_simulation/src/main.rs"
    click FEE "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/services/src/state_committer/fee_algo.rs"
    click TXM "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/adapters/eth/src/http.rs"
    click TXM "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/adapters/eth/src/websocket/connection.rs"
    click TXM "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/adapters/eth/src/aws.rs"
    click PRUNER "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/services/src/state_pruner.rs"
    click REPS "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/services/src/health_reporter.rs"
    click REPS "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/services/src/status_reporter.rs"
    click REPS "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/services/src/cost_reporter.rs"
    click REPS "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/services/src/wallet_balance_tracker.rs"
    click METRICS "https://github.com/fuellabs/fuel-block-committer/blob/master/packages/metrics/src/lib.rs"
    click HELM_CHARTS "https://github.com/fuellabs/fuel-block-committer/tree/master/helm/fuel-block-committer/templates/"

    %% Styles
    classDef external fill:#d4f4dd,stroke:#2d572c,stroke-width:1px
    classDef internal fill:#d0e1f9,stroke:#035397,stroke-width:1px
    classDef database fill:#ffe0b2,stroke:#ff6f00,stroke-width:1px
    classDef deployment fill:#e0e0e0,stroke:#616161,stroke-width:1px
```
