diff --git a/README.md b/README.md index 91cb008d..1ae783dd 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,194 @@ You can also use `run_tests.sh`, which takes care of building the `fuel-block-co ./run_tests.sh ``` +## Configuration + +The Fuel Block Committer is configured primarily through environment variables. + +### Environment Variables + +#### Ethereum (ETH) Configuration + +- **`COMMITTER__ETH__L1_KEYS__MAIN`** + + - **Description:** The Ethereum key authorized by the L1 fuel chain state contract to post block commitments. + - **Format:** `Kms()` or `Private()` + - **Example:** `Kms(arn:aws:kms:us-east-1:123456789012:key/abcd-1234)` + +- **`COMMITTER__ETH__L1_KEYS__BLOB`** + + - **Description:** (Optional) The Ethereum key for posting L2 state to L1. + - **Format:** `Kms()` or `Private()` + - **Example:** `Kms(arn:aws:kms:us-east-1:123456789012:key/efgh-5678)` + +- **`COMMITTER__ETH__RPC`** + + - **Description:** URL to the Ethereum RPC endpoint. + - **Example:** `https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID` + +- **`COMMITTER__ETH__STATE_CONTRACT_ADDRESS`** + - **Description:** Ethereum address of the Fuel chain state contract. + - **Example:** `0xYourStateContractAddress` + +#### Fuel Configuration + +- **`COMMITTER__FUEL__GRAPHQL_ENDPOINT`** + + - **Description:** URL to a Fuel Core GraphQL endpoint. + - **Example:** `http://localhost:4000/graphql` + +- **`COMMITTER__FUEL__NUM_BUFFERED_REQUESTS`** + - **Description:** Number of concurrent http requests towards the fuel node. + - **Type:** Positive integer + - **Example:** `5` + +#### Database (DB) Configuration + +- **`COMMITTER__APP__DB__HOST`** + + - **Description:** Hostname or IP address of the PostgreSQL server. + - **Example:** `localhost` + +- **`COMMITTER__APP__DB__PORT`** + + - **Description:** Port number on which the PostgreSQL server is listening. + - **Type:** `u16` + - **Example:** `5432` + +- **`COMMITTER__APP__DB__USERNAME`** + + - **Description:** Username for authenticating with the PostgreSQL server. + - **Example:** `username` + +- **`COMMITTER__APP__DB__PASSWORD`** + + - **Description:** Password for authenticating with the PostgreSQL server. + - **Example:** `password` + +- **`COMMITTER__APP__DB__DATABASE`** + + - **Description:** Name of the database to connect to on the PostgreSQL server. + - **Example:** `fuel_db` + +- **`COMMITTER__APP__DB__MAX_CONNECTIONS`** + + - **Description:** Maximum number of connections allowed in the connection pool. + - **Type:** `u32` + - **Example:** `10` + +- **`COMMITTER__APP__DB__USE_SSL`** + - **Description:** Whether to use SSL when connecting to the PostgreSQL server. + - **Type:** `bool` + - **Values:** `true` or `false` + - **Example:** `false` + +#### Application (App) Configuration + +- **`COMMITTER__APP__PORT`** + + - **Description:** Port used by the started server. + - **Type:** `u16` + - **Example:** `8080` + +- **`COMMITTER__APP__HOST`** + + - **Description:** IPv4 address on which the server will listen for connections. + - **Example:** `127.0.0.1` + +- **`COMMITTER__APP__BLOCK_CHECK_INTERVAL`** + + - **Description:** How often to check for new fuel blocks. + - **Format:** Human-readable duration (e.g., `5s`, `1m`) + - **Example:** `5s` + +- **`COMMITTER__APP__TX_FINALIZATION_CHECK_INTERVAL`** + + - **Description:** How often to check for finalized L1 transactions. + - **Format:** Human-readable duration + - **Example:** `5s` + +- **`COMMITTER__APP__NUM_BLOCKS_TO_FINALIZE_TX`** + + - **Description:** Number of L1 blocks that need to pass to accept the transaction as finalized. + - **Type:** `u64` + - **Example:** `3` + +- **`COMMITTER__APP__GAS_BUMP_TIMEOUT`** + + - **Description:** Interval after which to bump a pending transaction. + - **Format:** Human-readable duration + - **Example:** `300s` + +- **`COMMITTER__APP__TX_MAX_FEE`** + + - **Description:** Maximum gas fee permitted for a transaction in wei. + - **Type:** `u64` + - **Example:** `4000000000000000` + +- **`COMMITTER__APP__SEND_TX_REQUEST_TIMEOUT`** + - **Description:** Duration for timeout when sending transaction requests. + - **Format:** Human-readable duration + - **Example:** `10s` + +#### Bundle Configuration + +- **`COMMITTER__APP__BUNDLE__ACCUMULATION_TIMEOUT`** + + - **Description:** Duration to wait for additional fuel blocks before initiating the bundling process. + - **Format:** Human-readable duration + - **Example:** `30s` + +- **`COMMITTER__APP__BUNDLE__BLOCKS_TO_ACCUMULATE`** + + - **Description:** Number of fuel blocks to accumulate before initiating the bundling process. + - **Type:** Positive integer + - **Example:** `5` + +- **`COMMITTER__APP__BUNDLE__OPTIMIZATION_TIMEOUT`** + + - **Description:** Maximum duration allocated for determining the optimal bundle size. + - **Format:** Human-readable duration + - **Example:** `60s` + +- **`COMMITTER__APP__BUNDLE__COMPRESSION_LEVEL`** + + - **Description:** Compression level used for compressing block data before submission. + - **Values:** `"disabled"`, `"min"`, `"level1"`..`"level9"`, `"max"` + - **Example:** `"min"` + +- **`COMMITTER__APP__BUNDLE__OPTIMIZATION_STEP`** + + - **Description:** Size of the optimization step at the start of the optimization process. + - **Type:** Positive integer (`NonZeroUsize`) + - **Example:** `100` + +- **`COMMITTER__APP__BUNDLE__FRAGMENTS_TO_ACCUMULATE`** + + - **Description:** Number of fragments to accumulate before submitting them in a transaction to L1. + - **Type:** Positive integer (`NonZeroUsize`) + - **Example:** `6` + +- **`COMMITTER__APP__BUNDLE__FRAGMENT_ACCUMULATION_TIMEOUT`** + + - **Description:** Duration to wait for additional fragments before submitting them. + - **Format:** Human-readable duration + - **Example:** `30s` + +- **`COMMITTER__APP__BUNDLE__NEW_BUNDLE_CHECK_INTERVAL`** + - **Description:** Duration to wait before checking if a new bundle can be made. + - **Format:** Human-readable duration + - **Example:** `15s` + +### Configuration Validation + +The committer performs validation on the provided configuration to ensure consistency and correctness. For example: + +- **Wallet Keys:** The main wallet key and blob pool wallet key must be different. +- **Fragments to Accumulate:** Must be less than or equal to 6. +- **Block Height Lookback:** Must be greater than or equal to the number of blocks to accumulate. + +If any validation fails, the committer will return an error, preventing it from running with invalid settings. + ## Schema Visualization ![Relationships Diagram](db_preview/pngs/relationships.png)