⚡️ The Hemi Network

Hemi is an EVM-compatible L2 blockchain that combines the security of Bitcoin with the programmability of Ethereum.

🔧 Services

The Hemi Network consists of three key services, each serving a unique and important function within the network:

🌐 Binaries

• bfgd (Bitcoin Finality Governor Daemon): Manages connections and data transfers between the Hemi Network and the Bitcoin blockchain, ensuring finality.
• bssd (Bitcoin Secure Sequencer Daemon): Coordinates and sequences blockchain operations, serving as a bridge to the Bitcoin Finality Governor.
• extool: A utility tool for extracting and processing data from various file formats, tailored for blockchain data analysis.
• hemictl: The command-line interface for controlling and managing all Hemi Network services.
• keygen: Generates and manages cryptographic keys used within the Hemi network, ensuring secure operations.
• popmd (Proof-of-Proof Miner Daemon): Embeds L2 Keystones into Bitcoin blocks for proof-of-proof, integral to the network's security.
• tbcd (Tiny Bitcoin Daemon): A minimal Bitcoin block downloader and indexer daemon.

⚡️ Getting Started

📦 Downloading Release Binaries

Pre-built binaries are available on the Releases Page.

🏗 Building from Source

🏁 Prerequisites

• git
• make
• Go v1.23+

Building with Makefile

1. Clone the heminetwork repository:

   git clone https://github.com/hemilabs/heminetwork.git
   cd heminetwork

2. Setup and build binaries:

   make deps    # Download and install dependencies
   make install # Build binaries

Output binaries will be written to the bin/ directory.

🛠 Running the Services

For any service, you can view configuration options by running:

./bin/popmd --help
./bin/bfgd --help
./bin/bssd --help

▶️ Running popmd

🏁 Prerequisites

• A funded BTC private key. This can be a testnet address if configured for test environments.
• A BFG URL to establish a connection.

Once properly configured and running, popmd will start mining L2 Keystones by adding them to Bitcoin blocks that make it into the chain.

CLI

Set up and start popmd using:

./bin/popmd

Web

There is also a web interface that can be used to run a PoP miner. Build and run the web interface with:

[!NOTE] The web PoP Miner is currently a proof-of-concept.

cd ./web
make
go run ./integrationtest

▶️ Running bfgd

🏁 Prerequisites

• A PostgreSQL database, bfgd expects the sql scripts in ./database/bfgd/scripts/ to be run to set up your schema.
• A connection to an Electrs node on the proper Bitcoin network (testnet or mainnet).

▶️ Running bssd

🏁 Prerequisites

• Connect to a live bfgd instance.

▶️ Running the Hemi stack

To run the full Hemi stack (non-sequencing), please see NODE_RUNNING.

▶️ Running the localnet network

[!WARNING] This is designed for use in testing and development environments only.

🏁 Prerequisites

• docker

📚 Tutorial

1. Start the Network: Launch the entire Hemi network locally using Docker, which will generate L2 Keystones and BTC Blocks at a high rate:

   docker compose -f ./e2e/docker-compose.yml up --build

[!NOTE] The --build flag is optional and should only be used if you want to rebuild the binaries.

2. Manage Caching: This initial build may take some time, but subsequent builds should benefit from caching.

[!NOTE] During rebuilding, popmd, bssd, and bfgd may force a rebuild due to the COPY command, which can break the cache. If you need to deliberately break the cache for the op-stack, use the following arguments:

• For op-geth + optimism (op-node):

   docker compose -f ./e2e/docker-compose.yml build --build-arg OP_GETH_CACHE_BREAK="$(date)"

• For optimism cache break only:

   docker compose -f ./e2e/docker-compose.yml build --build-arg OPTIMISM_CACHE_BREAK="$(date)"

[!IMPORTANT] Make sure you run the cleanup command to remove data and ensure a fresh start.

docker compose -f ./e2e/docker-compose.yml down -v --remove-orphans

NOTE: The --remove-orphans flag should remove other containers not defined in the docker compose file. This is mainly here to help ensure you start with a clean environment. It can be omitted.

📄 License

This project is licensed under the MIT License.