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).
If you'd like to run your own bfgd and don't want to rely on Hemi Labs (or any third party) for broadcasting transactions, you may run bfgd and connect it to a trusted bfgd run by a third party to receive l2 keystones only (l2 keystones represent l2 state and are what are mined in PoP transactions). In this case, the third party bfgd will only send you l2 keystones, your bfgd can notify your local pop miner and this will broadcast them to your Electrs+bitcoind setup so you don't rely on Hemi Labs--or any third party--which may be congested.
You'll need the following running to do this:
- bitcoind
- electrs
- postgres
- bfgd
Note: make sure you run all of the *.sql files for bfg in database/bfgd/postgres/scripts
When running BFG, you'll want the following env variables set:
BFG_BFG_URL: the trustedbfgd's websocket url that you will connect toBFG_BTC_PRIVKEY: your btc private key. note that this can be an unfunded private key and you'll still receive l2 keystones to mineBFG_POSTGRES_URI: the connection URI for your postgres instanceBFG_BTC_START_HEIGHT: when your db is empty, bfgd will need a starting point to parse btc blocks at, set this to the tip of the bitcoin chain at first deployBFG_EXBTC_ADDRESS: your electrs rpc address
You may then connect your local popmd to your aforementioned local bfgd via the POPM_BFG_URL env variable
- 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.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
