⚡️ The Hemi Network

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

Table of Contents

• ⚡️ The Hemi Network
  • 🔧 Services
  • 🌐 Binaries
• ⚡️ Getting Started
  • 📦 Downloading Release Binaries
  • 🏗 Building from Source
    • 🏁 Prerequisites
    • Building with Makefile
• 🛠 Running the Services
  • ▶️ Running popmd
    • 🏁 Prerequisites
    • CLI
    • Web
  • ▶️ Running bfgd
    • 🏁 Prerequisites
    • Running your own Bitcoin Finality Governor (bfgd)
  • ▶️ Running the Hemi stack
  • ▶️ Running the localnet network
    • 🏁 Prerequisites
    • 📚 Tutorial
  • 📄 License

---

🔧 Services

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.

🌐 Binaries

• bfgd (Bitcoin Finality Governor Daemon): Manages connections and data transfers between the Hemi Network and the Bitcoin blockchain, ensuring finality. 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.24+

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

▶️ 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 **connection to a Bitcoin network source of truth.

Running your own Bitcoin Finality Governor (bfgd)

If you'd like to run your own bfgd and don't want to rely on Hemi Labs (or any third party) for verifying the finality of mined keystones, you may run bfgd and connect it to a trusted op-geth instance, as well as an l2 keystone (l2 keystones represent l2 state and are what are mined in PoP transactions) aware gozer, such as TBC. In this case, your bfgd instance will communicate with op-geth to verify the validity of l2 keystones, and confirm their canonicity and finality status, based on their presence in the bitcoin chain, using the gozer.

BFG is very light-weight, thus only requiring bfgd in order to be run (provided you have a valid op-geth and gozer instance to connect it to).

When running BFG, you'll want the following env variables set:

• BFG_BITCOIN_URL: the TBC's websocket url that you will connect to

More details coming soon!

▶️ 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 build
   
   # set the hvm phase 0 timestamp slightly in the future, but ensure that all op-geths have the same
   HVM_PHASE0_TIMESTAMP=$(date --date='+120 seconds' +%s) docker compose -f ./e2e/docker-compose.yml up

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 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.