fuellabs / fuel-block-committer

A standalone service that commits Fuel block data to L1 / DA

fuel-block-committer

The Fuel Block Committer is a standalone service dedicated to uploading Fuel Block metadata to Ethereum.

Building

Building the project doesn't require any special steps beyond the standard Cargo build process.

cargo build

Testing

Testing the committer requires the use of docker-compose to stand-up an e2e environment containing both a fuel-core and ganache container. Setting up the docker environment is automated via the run_tests.sh script. The script will also handle any initial setup and contract deployments required for e2e testing.

Unit tests also require having the correct version of fuel-core installed. To avoid this requirement, enable the fuel-core-lib feature on the fuels-test-helpers dev-dependency to ensure the correct version of fuel-core is selected.

./run_tests.sh

fuel-block-committer's Issues

Update compatibility to fuel-core version 0.20

Helm charts

Periodic update of wallet balance

The metric for wallet balance is currently being updated on every tx submission. If gas bumping is implemented then it might be better to do it periodically to keep a check on the gas bumping expenditure.

Implement logic to watch for new fuel blocks

Following the logic detailed in #1, implement a component capable of polling for fuel blocks, determining if they should be committed and, if so, proceed to broadcast them further into the system.

Committer MVP

The Fuel Block Committer is a standalone service that periodically pushes fuel-core state to Ethereum.

MVP Requirements

• Utilizes the ABI derived from the fuel chain state contract: https://github.com/FuelLabs/fuel-v2-contracts/blob/master/contracts/fuelchain/FuelChainState.sol
• Pushes fuel chain state via Ethereum RPC on a configurable interval
• Provides metrics for monitoring and alerting

Configuration

Config Key	Value Type	Description
ETHEREUM_WALLET_KEY	Secret String (Bytes32 hex)	The secret key authorized by the L1 bridging contracts to post block commitments.
ETHEREUM_RPC	URL	URL to a Ethereum RPC endpoint
FUEL_GRAPHQL_ENDPOINT	URL	URL to a fuel-core graphql endpoint
STATE_CONTRACT_ADDRESS	Bytes20 (Hex)	Ethereum address of the fuel chain state contract
COMMIT_INTERVAL	uint32	The number of fuel blocks between ethereum commits. If set to 1, then every block should be pushed to Ethereum.

APIS

GET /health

Simply returns status code 200 when the service is running. Returns a 500 error if the connection to either fuel-core or ethereum RPC isn't healthy.

GET /status

Returns a JSON response indicating the current status of the service.

Response:

{
  "latestFuelBlock": 0,
  "latestCommittedBlock": 0,
  "status": ["idle", "committing"]
  "ethereumWalletGasBalance": 0
}

GET /metrics

Returns a prometheus response view of the service status

• latest_fuel_block: Gauge
• latest_committed_block: Gauge
• ethereum_wallet_gas_balance: Gauge

These metrics will allow for custom alert manager rules we can feed into pager duty, such as:

• latest_committed_block is too far behind latest_fuel_block (e.g. last_committed_block < latest_fuel_block - 2 * COMMIT_INTERVAL)
• ethereum_wallet_gas_balance below some configurable amount (e.g. ethereum_wallet_gas_balance < 100 * state commit gas cost * current gas price). This allows the operator of the committer to be alerted when the wallet balance needs a top up.

Behavior

stateDiagram-v2
    direction LR
    [*] --> CheckCommittedBlock

    CheckCommittedBlock --> HasEpochDurationPassed
    HasEpochDurationPassed --> CheckCommittedBlock: False
    HasEpochDurationPassed --> CommitFuelBlock: True
    CommitFuelBlock --> CheckCommittedBlock

Tests / Requirements

• Posts every n-th fuel block to ethereum, where n is COMMIT_INTERVAL
• If a commit to ethereum is dropped or cancelled, skip and wait until the next commit interval
• Avoids pushing the same block twice (e.g. due to a restart during a pending txn)

Devops

• Must have a deployable docker image published to ghcr
• Liveness probe should have a 30s or more timeout, to avoid thrashing the pod if either the fuel-core or ethereum rpc endpoints are down and cause the /health api to fail
• Should only allow one container to be running per deployment: Recreate Strategy
• Has a service monitor deployed along with the main service by default for our monitoring infra to ingest prometheus metrics

Deploy fuel-block-committer to a production version

Create fuel-block-committer behavior (state transitions)

Utilizing actor models.

The state transitions / behaviour is explained in #1.

Todo:

• decide on some db / caching mechanism to handle issues like
  "Avoids pushing the same block twice (e.g. due to a restart during a pending txn)" and similar

Deploy Fuel Block Commiter Helm Chart

We need to helmify the fuel block commiter and deploy to DEV cluster

Graceful shutdown

So that when we stop being healthy everything might shut down gracefully.

create API handlers for fuel-block-committer MVP

API endpoints are listed at #1

Since we're going to use Actix Actor model we should use actix_web for this part.
Add Prometheus support

Add sled db support

Our requirements are:

• can lookup by key
• can get entry with the biggest key
• doesn't impact our DX unnecessarily (i.e. preferably an embedded, no system dep, db)

it turns our that sled is perfect. Implement support for it.

Publish docker image on release tags and every workflow run using the git sha

Enable e2e tests in CI

potential: https://github.com/marketplace/actions/docker-compose-action

Prevent recommitting a block upon DB deletion

In the case of the db being deleted, we should query the static view-only methods of the fuel state contract to determine the latest block committed before we try and recommit it.

Implement gas escalation for stuck transactions

ethers-rs offers some gas-bumping middleware.

Upgrade fuel-bridge to work with version 0.19

Pull commit interval config from contract

Since the state contract already has an interval configured, the committee should just use whatever is set in the contract instead of using its own config setting for the interval period. This will reduce the chance of a misconfiguration.

Make service type configurable to avoid always using `NodePort`

          Not everyone wants to use NodePort. If you have nodes only in private networks, those will need to be exposed through a load balancer. Better give the option to the user to specify what the type of service

Originally posted by @liviudm in #35 (comment)

create cli app that would read config values for fuel-block-committer

Config is detailed at #1

use clap library and support both:

• cli
• env var

Catchup for missing blocks

If the committer happens to miss a block on it's interval polling, it will have to wait another epoch period until another block is posted again. We should add some fault tolerance that enables the committer to detect if a block from the most recent epoch got accidentally skipped and post it to ethereum.