Installation

This step guides you to install and run all necessary components.

By default, all pages in this guide install the required repos and their dependencies using Docker. A single container called bitcoin-ipc downloads the bitcoin-ipc and ipc repos, installs dependencies and builds the repos, runs bitcoin-core , and runs ipc-cli . The bitcoin wallets and Bitcoin-IPC configuration files also live in the container. Nothing is installed on your local machine (apart from Docker). This is the simplest and the recommended option.

Alternatively, you can clone the repos bitcoin-ipc and ipc, and run bitcoin-core and ipc-cli on your local machine, but then you need to locally install all dependencies. This is setup is described in Alternative: Install on the host machine on this page, and all following pages contain an "Alternative" approach, which you need to follow if you opt for the alternative setup.

In both cases, the validator nodes will run in separate Docker containers on your host machine — the difference is that with the default option these containers will be started from inside the bitcoin-ipc container, while with the alternative option the containers will be started from your host machine.

All pages titled "Optional" describe ways to further parametrize this guide, or additional scripts that can give you more background information.

Background

The bitcoin-ipc repo

The bitcoinscalinglabs/bitcoin-ipc repo contains the following two binaries.

• Monitor: It monitors the Bitcoin network for new blocks and transactions. It processes transactions with IPC-related data. It saves the data in a local database, configurable by the DATABASE_URL environment variable.

• Provider: It exposes an HTTP endpoint with a JSON RPC to interact with Bitcoin, and reads data from the local database. It's primarily intented to be used by the ipc-cli, which we will introduce later. It listens on the port configurable by PROVIDER_PORT, defaulting to 3030. It requires an Authorization header with a bearer token to be match the value of PROVIDER_AUTH_TOKEN env var, defaulting to "validator1_auth_token" .

The ipc repo

The bitcoinscalinglabs/ipc repo is a fork of the standard (Filecoin-based) IPC repo. It contains the consensus and execution engines used by Bitcoin-IPC validators, and a tool call ipc-cli, which helps validators and clients interact with subnets. For information about what ipc-cli is and how to use it, see the ipc docs.

Bitcoin Regtest network

This guide is using Regtest, a local Bitcoin chain created on your local machine (or in a Docker container).

---

Deployment instructions

1. Install Docker on your machine. This guide has been tested with Docker version 29.1.5. We recommend allowing Docker to use at least 12 GB of RAM.

2. Delete the ~/.ipc directory, if it exists (the directory is bind-mounted and auto-generated upon starting the bitcoin-ipc container).

3. Download the bitcoinscalinglabs/bitcoin-ipc repo.

git clone [e-mail]:bitcoinscalinglabs/bitcoin-ipc.git
cd bitcoin-ipc

1. Run the bitcoin-ipc container

# In the bitcoin-ipc directory of your host machine:
make local-up

1. The script starts a Bitcoin Monitor and a Bitcoin Provider instance for four validators (these validators will later in this guide join Bitcoin-IPC subnets), with log files stored in /root/logs/ in the container. See Optional: Helper scripts for more information on the log files.

2. If in the future you need to delete the data generated in the container, you can run:

   # In the bitcoin-ipc directory of your host machine:
   make local-reset-data

   Attention, this will delete:

   - All bitcoin regtest data

   - All non-default Bitcoin-IPC and bitcoin accounts - All Bitcoin-IPC subnets

More information

The bitcoin-ipc container contains/runs:

• Bitcoin Core in regtest mode with the required configuration in /root/.bitcoin/bitcoin.conf.

• The required repos cloned in /workspace/ipc and /workspace/bitcoin-ipc .

• The ipc-cli tool.

• Bitcoin wallets and IPC configuration (under /root/.ipc/) for all 5 validators and 2 users, generated using the src/bin/quickstart.rs script upon container creation — the /root/.ipc/ container directory is bind-mounted to the ~/.ipc host directory, for both technical and debugging purposes.

• The monitor and provider binaries for each validator (validator1–validator5) and user (user1, user2), automatically started upon container creation (in the docker-deploy-local/docker-entrypoint.sh script).

• The captured logs for each monitor and provider instance in the /root/logs/ directory inside the container.

• Sets the required environment variables for the demo (see docker-compose.yml in the bitcoin-ipc repo).

• The script /workspace/bitcoin-ipc/scripts/miner.sh that mines regtest blocks every 10 seconds (started automatically upon container creation).

• A script to quickly create, join, and fund a subnet in /usr/local/bin/bootstrap_subnet_from_container.sh (not run automatically - we will use it in a following step).

• Scripts to spin up docker containers for the validator nodes of two subnets: /usr/local/bin/spin_up_subnet_a_from_container.sh and /usr/local/bin/spin_up_subnet_b_from_container.sh (not run automatically - we will use them in a following step).

• It exposes ports 3030-3034 and 3040-3041, where the Bitcoin provider instances of the validators and users are listening — these will be used by the Docker containers of each validators.

• It persists bitcoin data (directory /root/.bitcoin) and IPC data (directory /root/.ipc) to a Docker volume, so they survive restarts of the container).

• The host Docker socket (`/var/run/docker.sock`) is mounted into this container, so we can later build and run host-managed containers (i.e., the containers cometbft, fendermint, and ethapi for each validator) from inside this container.

More information about the bitcoin-ipc container can be found in the docker-deploy-local/README.md file of the bitcoin-ipc repo.

---

Alternative: Install on the host machine

If you follow this way to install the required repos, in all following steps you must run the commands on your host machine when the instructions ask to run them on the bitcoin-ipc container.

Before we start creating subnets, let's set up the necessary components.

We'll start by setting up a local Bitcoin Regtest network, setting up Bitcoin IPC components, and finally installing the IPC Client that supports Bitcoin.

Step 1: Install, configure, and start Bitcoin Core

Follow the installation instructions for your operating system provided on the Bitcoin Core download page.

To verify the installation: Open a terminal or command prompt and verify that bitcoind and bitcoin-cli are installed correctly:

bitcoind --version
bitcoin-cli --version

Ensure that the Bitcoin data directory exists. The default locations for different operating systems are:

- Linux: ~/.bitcoin/
- macOS: ~/Library/Application\ Support/Bitcoin/
- Windows: %APPDATA%\Bitcoin\

Create or edit the bitcoin.conf file in the Bitcoin data directory and add the following configuration to enable regtest, your own local network. The contents of the bitcoin.conf file should be:

regtest=1
server=1
rpcuser=user
rpcpassword=pass
rpcallowip=127.0.0.1
fallbackfee=0.00003
paytxfee=0.00003
listen=1
txindex=1

You can replace user and pass with your desired username and password (in which case you will have to change these values for each validator and user of this demo — this documentation will guide you). Start Bitcoin Core daemon:

bitcoind --printtoconsole

To verify bitcoind is running:

bitcoin-cli getblockchaininfo

The output should show the chain as regtest.

Step 2: Bitcoin-ipc repo

Install Rust

The project is build on Rust, do first we need to install it. For this, follow the official instructions. We require version at least 1.87.0.

To verify the Rust installation:

cargo version

Download and build the bitcoin-ipc repo

In this step we will download and build the bitcoinscalinglabs/bitcoin-ipc repo. As we will explain, this contains the components that interact with the Bitcoin Network.

git clone [e-mail]:bitcoinscalinglabs/bitcoin-ipc.git
cd bitcoin-ipc
cargo build --release

Add binaries to path

After building the project, both monitor and provider binaries are available in bitcoin-ipc/target/release directory. For ease of use let's add both binaries to our path:

sudo ln -s $(pwd)/target/release/monitor /usr/local/bin/
sudo ln -s $(pwd)/target/release/provider /usr/local/bin/

By default, the monitor and provider read the .env file in the current directory. For a full list of env variables see the .env.example file. You can specify a different file by passing a relative path to the --env flag, like so: monitor --env=custom.env and provider --env=custom.env .

We do not need to run the monitor and provider yet, we will do so in a later step. When running for the first time, make sure to run the monitor before the provider, since the monitor will create the necessary database.

More details on the monitor and provider

The bitcoin monitor connects to a bitcoin chain (variables RPC_USER, RPC_PASS , RPC_URL , and WALLET_NAME in the .env file are used for this). It processes each confirmed block and searches it for IPC-related transactions, such as the creation of a new subnet, validators joining a subnet, sending funds to an L2 subnet, subnet checkpoint transactions, and so on. The monitor stores related information on a local database (variable DATABASE_URL ).

The bitcoin provider exposes RPC endpoints to obtain information about L2 subnets over bitcoin and to create bitcoin transactions for interacting with the subnets, such as create a new subnet, join an existing, transfer funds into and L2 subnet, create a checkpoint given an L2 state, and so on. Variables PROVIDER_PORT and PROVIDER_AUTH_TOKEN are used for this.

In this demo, both validators and users of L2 subnets run one instance of the monitor and one of the provider each. The bitcoin provider can also sign transactions on behalf of the callers, i.e., it functions as a bitcoin wallet. Specifically for validators, the bitcoin provider has access to the secret key of the validator, as it needs to sign bitcoin multisig transactions with it (variable VALIDATOR_SK_PATH is used for this).

With both monitor and provider installed, it's time to setup ipc-cli.

Step 3: IPC repo and ipc-cli

In this step we will download and build the bitcoinscalinglabs/ipc repo.

Download and build the ipc repo

Install the basic requirements for IPC:

Linux

• Install system packages: sudo apt install build-essential clang cmake pkg-config libssl-dev protobuf-compiler git curl.

• Install Rust. See instructions.

• Install cargo-make: cargo install --force cargo-make.

• Install Docker. See instructions.

• Install Node.js. See instructions.

• Install Foundry. See instructions.

Also install the following dependencies (details)

sudo apt update && sudo apt install build-essential libssl-dev mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl clang hwloc libhwloc-dev wget ca-certificates gnupg -y

MacOS

Building the repo:

NOTE: this step may take a while to compile, depending on OS version and hardware build

Linux

# make sure that rust has the wasm32 target & use stable version of rustc
rustup target add wasm32-unknown-unknown
rustup default stable

# add your user to the docker group
sudo usermod -aG docker $USER && newgrp docker

# clone this repo and build
git clone [e-mail]:bitcoinscalinglabs/ipc.git
cd ipc
git checkout bitcoin
make

MacOS

After following the instructions, you should now have the following binaries available:

./target/release/ipc-cli --version
./target/release/fendermint --version

Add the binaries to path

For ease of use we can make aliases for these binaries. You can use

sudo ln -sf "$(pwd)/target/release/ipc-cli" /usr/local/bin/ipc-cli
sudo ln -sf "$(pwd)/target/release/fendermint" /usr/local/bin/fendermint

Build docker images

One final thing is to build the fendermint local docker image:

# in ipc repo, navigate to fendermint subdirectory
cd fendermint
# make sure docker is running
make docker-build
# wait a few minutes

To verify the image is available:

docker images | grep fendermint
# fendermint    latest    c1db79694970   4 seconds ago     236MB

Step 4: Generate wallets and config files

We provide a script that automates the setup for wallets and configuration files for five validators and two users.

Before running it:

• Make sure that ~/.ipc does not exist. The script will not override it.

From within the bitcoin-ipc repo run:

./target/release/quickstart

If you changed the "rpcuser" and/or "rpcpassword" fields in Step 1: Install, configure, and start Bitcoin Core, then you need to update these values in the following files:

• ~/.ipc/validator1/.env

• ~/.ipc/validator2/.env

• ~/.ipc/validator3/.env

• ~/.ipc/validator4/.env

• ~/.ipc/validator5/.env

• ~/.ipc/user1/.env

• ~/.ipc/user2/.env

The script prints the the IPC address (aka ETH address) and the X-Only public key of each validator and user, as well as a whitelist consisting of the first four validators (to be used when creating a subnet).

In the following demo we will use the IPC address to identify users and validators in the L2 subnet, and the X-Only public key to identify validators on the bitcoin chain.

For ease of use, you can extract the IPC address and the whitelist into env variables:

export IPC_ADDRESS_OF_VALIDATOR_1=0x27b60d9f71d6806cca7d5a92b391093fe100f8e8
export IPC_ADDRESS_OF_VALIDATOR_2=0xd9c4c92ca843a53bff146c79b5d32ca4b9321414
export IPC_ADDRESS_OF_VALIDATOR_3=0x646aed5404567ae15648e9b9b0004cbafb126949
export IPC_ADDRESS_OF_VALIDATOR_4=0xbce2f194e9628e6ae06fa0d85dd57cd5579213bf
export IPC_ADDRESS_OF_VALIDATOR_5=0xb628237ff4875b039ec1c3dedcf5fad93430ee4a
export IPC_ADDRESS_OF_USER_1=0x005e05dd763dd125473f8889726f7c305e50fcae
export IPC_ADDRESS_OF_USER_2=0xa78bc5d61e0da3c2d96e29a495f4e358d8d2218d
export WHITELIST="5f0dfed3a527ac740c7d4a594cd3aa1059a936187399fc49e3fc6ea6ae177268,851c1bda327584479e98a7c28ea7adc097d290efd105310bcf714231bb99faf4,b15f99928f2478a10c5739a03f5495d342e77352d624e7cc8ebfbded544f9ac0,b45fd52573e8e6bfe0aff82fb228e887fdd92210fe0952ae65a59080fec7e529"

The ~/.ipc directory should have the following structure:

the ~/.ipc directory after the quickstart script

Step 5: Run Monitor and Provider for each validator

In this step we start the monitor and provider binaries, which we will use throughout the whole demo. Make sure every process is run in a separate terminal window/pane. Also make sure you are in the bitcoin-ipc repo and have run cargo build --release.

We are already starting the monitor and the provider for all validators and users. Some of them will be used in later steps of this demo. This is only done for convenience, it is also possible to start the monitor and provider for each validator later — at the latest before deploying the docker containers for that validator.

Validator 1

./target/release/monitor --env ~/.ipc/validator1/.env

./target/release/provider --env ~/.ipc/validator1/.env

Validator 2

./target/release/monitor --env ~/.ipc/validator2/.env

./target/release/provider --env ~/.ipc/validator2/.env

Validator 3

./target/release/monitor --env ~/.ipc/validator3/.env

./target/release/provider --env ~/.ipc/validator3/.env

Validator 4

./target/release/monitor --env ~/.ipc/validator4/.env

./target/release/provider --env ~/.ipc/validator4/.env

Validator 5

./target/release/monitor --env ~/.ipc/validator5/.env

./target/release/provider --env ~/.ipc/validator5/.env

User 1

./target/release/monitor --env ~/.ipc/user1/.env

./target/release/provider --env ~/.ipc/user1/.env

User 2

./target/release/monitor --env ~/.ipc/user2/.env

./target/release/provider --env ~/.ipc/user2/.env