⚡️ 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
    • 🏁 Prerequisites
  • ▶️ Running a full node
  • ▶️ 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) and PoP mining with it

XXX FIXME

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