Hemi is an EVM-compatible L2 blockchain that combines the security of Bitcoin with the programmability of Ethereum.
Table of Contents
The Hemi Network consists of three key services, each serving a unique and important function within the network:
| Service | Description |
|---|---|
| PoP Miner (popmd) | Mines L2 Keystones into Bitcoin blocks for Proof-of-Proof. |
| Bitcoin Finality Governor (bfgd) | Acts as the gateway to the Bitcoin network. |
| Bitcoin Secure Sequencer (bssd) | Acts as a gateway to the Bitcoin Finality Governor (BFG), managing the consensus mechanisms of the Hemi Network. |
- 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.
Pre-built binaries are available on the Releases Page.
gitmake- Go v1.23+
-
Clone the
heminetworkrepository:git clone https://github.com/hemilabs/heminetwork.git cd heminetwork -
Setup and build binaries:
make deps # Download and install dependencies make install # Build binaries
Output binaries will be written to the bin/ directory.
For any service, you can view configuration options by running:
./bin/popmd --help
./bin/bfgd --help
./bin/bssd --help- 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.
Set up and start popmd using:
./bin/popmdThere 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- 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).
- Connect to a live bfgd instance.
To run the full Hemi stack (non-sequencing), please see NODE_RUNNING.
Warning
This is designed for use in testing and development environments only.
docker
-
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.
- 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-orphansNOTE: 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.
This project is licensed under the MIT License.