Bitcoin-IPC repo

Overview and installation of the bitcoin-ipc repo.

Step 1: 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

Step 2: 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

The repository 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 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" .

Step 3: 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.