Skip to content

Latest commit

 

History

History
202 lines (143 loc) · 6.71 KB

README.md

File metadata and controls

202 lines (143 loc) · 6.71 KB
Raw

⚡️ The Hemi Network

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

Table of Contents

🔧 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

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 ElectrumX node on the proper Bitcoin network (testnet or mainnet).

▶️ Running bssd

🏁 Prerequisites

  • Connect to a live bfgd instance.

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