heminetwork

README

⚡️ 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 bssd
    • 🏁 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.
Bitcoin Secure Sequencer (bssd)	Acts as a gateway to the Bitcoin Finality Governor (BFG), managing the consensus mechanisms of the Hemi 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 your own Bitcoin Finality Governor (bfgd) and PoP mining with it

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 trusted bfgd's websocket url that you will connect to
• BFG_BTC_PRIVKEY: your btc private key. note that this can be an unfunded private key and you'll still receive l2 keystones to mine
• BFG_POSTGRES_URI: the connection URI for your postgres instance
• BFG_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 deploy
• BFG_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

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

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