diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..8e79302 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,7 @@ +# Hemi Node Documentation + +- [Quick Start](quick-start.md) +- [Setup guide](setup.md) +- [Profiles](profiles.md) + + diff --git a/docs/profiles.md b/docs/profiles.md new file mode 100644 index 0000000..bca4c7e --- /dev/null +++ b/docs/profiles.md @@ -0,0 +1,154 @@ +# Hemi Node Profiles + +The Docker compose files support running multiple different profiles, depending on your use case and requirements. + +> [!TIP] +> For most use cases, the [`hemi-min` profile](#profile-hemi-min) is recommended. + +Each profile runs a different set of components, and has a different use case. + +- [**`full` profile** - Runs every required component](#profile-full) + - Includes all Hemi L2 components + - Includes BFG (used for PoP Mining) and the required `electrs` indexer + - Includes Ethereum L1 nodes + - Includes Bitcoind node (used by `electrs`) + +- [**`hemi` profile** - Runs the Hemi components, using external RPC endpoints](#profile-hemi) + - Includes all Hemi L2 components + - Includes BFG (used for PoP mining) and the required `electrs` indexer + - External RPC endpoints are required for: + - Ethereum L1 nodes (geth and prysm) + - Bitcoind (used by BFG through `electrs`) + +- [**`hemi-min` profile - Lightweight profile**](#profile-hemi-min) + - Includes all Hemi L2 components + - Does not include BFG (and its required `electrs` indexer) + - External RPC endpoints are required for: + - Ethereum L1 nodes (geth and prysm) + +- [**`l1` profile - Ethereum and Bitcoin L1 components only**](#profile-l1) + - Ethereum L1 nodes (geth and prysm) + - Bitcoind node + +| Profile | `full` | `hemi` | `hemi-min` | `l1` | +|--------------------|--------|--------------|--------------|------| +| Hemi `op-geth` | ✅ | ✅ | ✅ | | +| Hemi `op-node` | ✅ | ✅ | ✅ | | +| Hemi `bssd` | ✅ | ✅ | ✅ | | +| Hemi `bfgd` | ✅ | ✅ | | | +| Ethereum `prysm` | ✅ | RPC required | RPC required | ✅ | +| Ethereum `geth` | ✅ | RPC required | RPC required | ✅ | +| Bitcoin `bitcoind` | ✅ | RPC required | | ✅ | +| Bitcoin `electrs` | ✅ | ✅ | | | + +> [!IMPORTANT] +> Each profile has entirely different system requirements. Please +> see [System Requirements](setup.md#system-requirements) for up-to-date requirements for each profile. + +## Profile `full` + +Runs a Hemi L2 node (`op-geth` and `op-node`), Hemi Bitcoin Finality Governor (used by PoP Miners) and Ethereum L1 +components. + +> [!WARNING] +> This profile runs Ethereum L1 components, in addition to the Hemi L2 components. This profile requires significantly +> more disk capacity in order to store L1 data. +> +> In most cases, it is preferable to use the `hemi` or `hemi-min` profile and provide RPC endpoints for external +> Ethereum L1 nodes. + +**Services** + +| Service | Description | +|-----------------|-----------------------------------------------------| +| `bfgd` | Hemi Bitcoin Finality Governor (used by PoP Miners) | +| `bfgd-postgres` | PostgreSQL database for `bfgd` | +| `bitcoind` | Bitcoin full node (used by `electrs`) | +| `electrs` | Bitcoin indexer (used by `bfgd`) | +| `bssd` | Hemi Bitcoin Secure Sequencer | +| `op-geth-l2` | Hemi L2 op-geth node | +| `op-node` | Hemi L2 op-node | +| `geth-l1` | Ethereum L1 geth node | +| `prysm` | Prysm (L1) | + +**Init containers** + +| Service | Description | +|-----------------------|---------------------------------------------------------------| +| `op-geth-l2-init` | Fixes directory ownership for `op-geth-l2` data directory | +| `op-geth-l2-init-tbc` | Fixes directory ownership for `op-geth-l2` TBC data directory | + +## Profile `hemi` + +Runs a Hemi L2 node (`op-geth` and `op-node`) and a Hemi Bitcoin Finality Governor (used by PoP Miners). + +> [!TIP] +> This profile runs the services necessary for use with a `popmd` (PoP Miner) daemon: +> - Bitcoin Finality Governor (RPC used by `popmd`) +> - Electrs (used by `bfgd`) + +**Requires** + +- Ethereum L1 RPC URL (must be set as `GETHL1ENDPOINT` environment variable) +- Ethereum Prysm RPC URL (must be set as `PRYSMENDPOINT` environment variable) +- Bitcoind RPC URL (must be set as `BITCOINENDPOINT` environment variable) + +**Services** + +| Service | Description | +|-----------------|-----------------------------------------------------| +| `bfgd` | Hemi Bitcoin Finality Governor (used by PoP Miners) | +| `bfgd-postgres` | PostgreSQL database for `bfgd` | +| `electrs` | Bitcoin indexer (used by `bfgd`) | +| `bssd` | Hemi Bitcoin Secure Sequencer | +| `op-geth-l2` | Hemi L2 op-geth node | +| `op-node` | Hemi L2 op-node | + +**Init containers** + +| Service | Description | +|-----------------------|---------------------------------------------------------------| +| `op-geth-l2-init` | Fixes directory ownership for `op-geth-l2` data directory | +| `op-geth-l2-init-tbc` | Fixes directory ownership for `op-geth-l2` TBC data directory | + +## Profile `hemi-min` + +Runs a Hemi L2 node (`op-geth` and `op-node`). + +> [!TIP] +> This profile is recommended for most use cases, and is the most lightweight profile. +> +> This profile does not run the components necessary to run `popmd` (PoP Miner). See the [`hemi` profile](#profile-hemi) +> if you require the Bitcoin Finality Governor to run a PoP Miner. + +**Requires** + +- Ethereum L1 RPC URL (must be set as `GETHL1ENDPOINT` environment variable) +- Ethereum Prysm RPC URL (must be set as `PRYSMENDPOINT` environment variable) + +**Services** + +| Service | Description | +|--------------|-------------------------------| +| `bssd` | Hemi Bitcoin Secure Sequencer | +| `op-geth-l2` | Hemi L2 op-geth node | +| `op-node` | Hemi L2 op-node | + +**Init containers** + +| Service | Description | +|-----------------------|---------------------------------------------------------------| +| `op-geth-l2-init` | Fixes directory ownership for `op-geth-l2` data directory | +| `op-geth-l2-init-tbc` | Fixes directory ownership for `op-geth-l2` TBC data directory | + +## Profile `l1` + +Runs only Ethereum L1 and Bitcoin components. **This does not run any Hemi services.** + +**Services** + +| Service | Description | +|------------|-----------------------| +| `bitcoind` | Bitcoin full node | +| `geth-l1` | Ethereum L1 geth node | +| `prysm` | Prysm (L1) | diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 0000000..703bc4a --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,158 @@ +# Hemi Node Quick Start + +This document is a quick-start guide to set up and run the Hemi stack with P2P nodesÒ and RPC access. *This does not set +up a batcher or sequencer.* + +> [!NOTE] +> This guide is only for users looking to run a node on the Hemi Network, and is not required to use a wallet (e.g. +> Rabby, Metamask, etc.) to interact with the Hemi Network, or run a PoP Miner. + +> [!IMPORTANT] +> **This is the quick-start guide, and glosses over the details of running a node.** +> For more information, please see our [full setup guide](setup.md). + +**Table of Contents** + +* [Prerequisites](#prerequisites) + * [System Requirements](#system-requirements) + * [ulimits](#ulimits) +* [Setup](#setup) + * [Mainnet (snap sync)](#mainnet-snap-sync) + * [Testnet (snap sync)](#testnet-snap-sync) + +--- + +## Prerequisites + +This guide assumes you have the following software installed and are using Ubuntu 24.04 or newer. Running on other +systems is possible, but may not be fully supported. + +- `git` +- `jq` +- `docker` and `docker-compose` (https://docs.docker.com/engine/install/ubuntu/) + +### System Requirements + +> [!IMPORTANT] +> NVMe disks are highly recommended to ensure performance. + +| Profile | CPU Cores | Memory | Disk | +|------------|-----------|--------|------| +| `hemi-min` | 2 | 12GiB | 2TiB | + +> [!WARNING] +> Over time, the amount of disk space required will grow. These values represent the current requirements (as of 2025), +> with a buffer that should be sufficient for at least another year. It is highly recommended to monitor disk usage to +> prevent the node from running out of disk space. + +### ulimits + +Certain components of the network require a very large number of open files. The Docker Compose file will attempt to +change the necessary ulimits automatically. + +--- + +## Setup + +> [!IMPORTANT] +> This guide sets up snap-sync nodes, using the `hemi-min` Docker compose profile. The following components will run: +> +> - `bssd` (Bitcoin Secure Sequencer) +> - `op-geth-l2` (Hemi L2 geth node) +> - `op-node` (Hemi L2 op-node) + +### Mainnet (snap sync) + +1. Clone the repository: + ```sh + git clone https://github.com/hemilabs/hemi-node.git + cd hemi-node + ``` + +2. Prepare the configuration files (**mainnet** with snap sync, hemi-min profile): + ```sh + ./scripts/gen.sh mainnet snap hemi-min + # gen: Generating files for mainnet (sync mode: snap, profile: hemi-min) + # gen: Generated ./mainnet/.env file + # gen: Generated random ./mainnet/jwt.hex file + # gen: Generated random ./mainnet/op-node-priv-key.txt file + # gen: Generated random ./mainnet/cookie file + # gen: Generated ./mainnet/entrypoint.sh + # + # gen: Setup complete! (mainnet, sync mode: snap, profile: hemi-min) + # gen: ./scripts/gen.sh on Tue Oct 14 19:17:41 AEDT 2025 (version=v0.0.0 commit=d929f26 state=clean) + # gen: + # gen: Next steps: + # gen: 1. Configure your Ethereum RPC providers: + # gen: - Edit mainnet/.env and add: + # gen: GETHL1ENDPOINT= + # gen: PRYSMENDPOINT= + # gen: + # gen: 2. Start your node: + # gen: cd mainnet + # gen: docker compose --profile hemi-min up --build -d + # gen: + # gen: 3. Monitor your node: + # gen: ./heminode.sh + ``` + +3. Configure your Ethereum RPC providers: + - Edit `mainnet/.env` and add: + ``` + GETHL1ENDPOINT= + PRYSMENDPOINT= + ``` + +4. Start the node: + ```sh + cd mainnet + docker compose --profile hemi-min up --build -d + ``` + +### Testnet (snap sync) + +1. Clone the repository: + ```sh + git clone https://github.com/hemilabs/hemi-node.git + cd hemi-node + ``` + +2. Prepare the configuration files (**testnet** with snap sync, hemi-min profile): + ```sh + ./scripts/gen.sh testnet snap hemi-min + # gen: Generating files for testnet (sync mode: snap, profile: hemi-min) + # gen: Generated ./testnet/.env file + # gen: Generated random ./testnet/jwt.hex file + # gen: Generated random ./testnet/op-node-priv-key.txt file + # gen: Generated random ./testnet/cookie file + # gen: Generated ./testnet/entrypoint.sh + # + # gen: Setup complete! (testnet, sync mode: snap, profile: hemi-min) + # gen: ./scripts/gen.sh on Tue Oct 14 19:17:41 AEDT 2025 (version=v0.0.0 commit=d929f26 state=clean) + # gen: + # gen: Next steps: + # gen: 1. Configure your Ethereum RPC providers: + # gen: - Edit testnet/.env and add: + # gen: GETHL1ENDPOINT= + # gen: PRYSMENDPOINT= + # gen: + # gen: 2. Start your node: + # gen: cd testnet + # gen: docker compose --profile hemi-min up --build -d + # gen: + # gen: 3. Monitor your node: + # gen: ./heminode.sh + ``` + +3. Configure your Ethereum RPC providers: + - Edit `testnet/.env` and add: + ``` + GETHL1ENDPOINT= + PRYSMENDPOINT= + ``` + +4. Start the node: + ```sh + cd testnet + docker compose --profile hemi-min up --build -d + ``` diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..da8a3b2 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,54 @@ +# Hemi Node Setup + +This document is a guide to set up and run the Hemi stack with P2P nodes and RPC access. *This does not set up a +batcher or sequencer.* + +> [!NOTE] +> This guide is only for users looking to run a node on the Hemi Network, and is not required to use a wallet (e.g. +> Rabby, Metamask, etc.) to interact with the Hemi Network, or run a PoP Miner. + +**Table of Contents** + +* [Hemi Node Setup](#hemi-node-setup) + * [Prerequisites](#prerequisites) + * [System Requirements](#system-requirements) + * [ulimits](#ulimits) + * [Installation and setup](#installation-and-setup) + + +--- + +## Prerequisites + +This guide assumes you have the following software installed and are using Ubuntu 24.04 or newer. Running on other +systems is possible, but may not be fully supported. + +- `git` +- `jq` +- `docker` and `docker-compose-plugin` (https://docs.docker.com/engine/install/ubuntu/) + +### System Requirements + +> [!IMPORTANT] +> NVMe disks are highly recommended to ensure performance. + +| Profile | CPU Cores | Memory | Disk | +|----------------------------------------------|-----------|--------|------| +| [`full`](./profiles.md#profile-full) | 8 | 40GiB | 6TiB | +| [`hemi`](./profiles.md#profile-hemi) | 2 | 16GiB | 3TiB | +| [`hemi-min`](./profiles.md#profile-hemi-min) | 2 | 12GiB | 2TiB | +| [`l1`](./profiles.md#profile-l1) | 6 | 24GiB | 3TiB | + +> [!WARNING] +> Over time, the amount of disk space required will grow. These values represent the current requirements (as of 2025), +> with a buffer that should be sufficient for at least another year. It is highly recommended to monitor disk usage to +> prevent the node from running out of disk space. + +### ulimits + +Certain components of the network require a very large number of open files. The Docker Compose file will attempt to +change the necessary ulimits automatically. + +--- + +## Installation and setup