# Installation

{% hint style="info" %}
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](#alternative-install-on-the-host-machine "mention") 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.
{% endhint %}

## Background

#### The bitcoin-ipc repo

The [bitcoinscalinglabs/bitcoin-ipc repo](https://github.com/bitcoinscalinglabs/bitcoin-ipc) 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](https://github.com/bitcoinscalinglabs/ipc/tree/bitcoin) is a fork of the standard (Filecoin-based) IPC [repo](https://github.com/consensus-shipyard/ipc). 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](https://docs.ipc.space/).

#### 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](https://github.com/bitcoinscalinglabs/bitcoin-ipc).

```sh
git clone git@github.com:bitcoinscalinglabs/bitcoin-ipc.git
cd bitcoin-ipc
```

4. Run the `bitcoin-ipc` container

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

6. 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](https://bitcoin-scaling-labs-docs.gitbook.io/ipc-btc-scaling-docs/user-guide-for-using-subnets/optional-helper-scripts "mention") for more information on the log files.
7. If in the future you need to delete the data generated in the container, you can run:<br>

   ```sh
   # 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

{% hint style="warning" %}
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.
{% endhint %}

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](https://bitcoincore.org/en/download/).&#x20;

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

```sh
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:

```ini
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:

```sh
bitcoind --printtoconsole
```

To verify `bitcoind` is running:

```sh
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](https://www.rust-lang.org/tools/install). We require version at least 1.87.0.

To verify the Rust installation:

```sh
cargo version
```

#### Download and build the bitcoin-ipc repo

In this step we will download and build the [bitcoinscalinglabs/bitcoin-ipc repo](https://github.com/bitcoinscalinglabs/bitcoin-ipc). As we will explain, this contains the components that interact with the Bitcoin Network.&#x20;

```sh
git clone git@github.com: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:

```sh
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` .

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="success" %}
**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).
{% endhint %}

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](https://github.com/bitcoinscalinglabs/ipc/tree/bitcoin).&#x20;

#### Download and build the ipc repo

Install the basic requirements for IPC:

{% tabs %}
{% tab title="Linux" %}

* Install system packages: `sudo apt install build-essential clang cmake pkg-config libssl-dev protobuf-compiler git curl`.
* Install Rust. See [instructions](https://www.rust-lang.org/tools/install).
* Install cargo-make: `cargo install --force cargo-make`.
* Install Docker. See [instructions](https://docs.docker.com/engine/install/ubuntu/).
* Install Node.js. See [instructions](https://nodejs.org/en/download).
* Install Foundry. See [instructions](https://book.getfoundry.sh/getting-started/installation).

Also install the following dependencies ([details](https://lotus.filecoin.io/lotus/install/prerequisites/#supported-platforms))

```
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
```

{% endtab %}

{% tab title="MacOS" %}

* Install Xcode from App Store or terminal: `xcode-select --install`
* Install Homebrew. See [instructions](https://brew.sh/).
* Install dependencies: `brew install jq`
* Install Rust. See [instructions](https://www.rust-lang.org/tools/install). (if you have homebrew installed rust, you may need to uninstall that if you get errors in the build)
* Install Cargo make: `cargo install --force cargo-make`
* Install docker. See [instructions](https://docs.docker.com/desktop/install/mac-install/).
* Install Node.js. See [instructions](https://nodejs.org/en/download).
* Install foundry. See [instructions](https://book.getfoundry.sh/getting-started/installation).
  {% endtab %}
  {% endtabs %}

Building the repo:

{% hint style="info" %}
NOTE: this step may take a while to compile, depending on OS version and hardware build
{% endhint %}

{% tabs %}
{% tab title="Linux" %}

```sh
# 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 git@github.com:bitcoinscalinglabs/ipc.git
cd ipc
git checkout bitcoin
make
```

{% endtab %}

{% tab title="MacOS" %}

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

# clone this repo and build
git clone git@github.com:bitcoinscalinglabs/ipc.git
cd ipc
git checkout bitcoin
make
```

{% endtab %}
{% endtabs %}

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

```sh
./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

```bash
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:

```sh
# 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:

```sh
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:

```bash
./target/release/quickstart
```

{% hint style="warning" %}
If you changed the "rpcuser" and/or "rpcpassword" fields in [#step-1-install-configure-and-start-bitcoin-core](#step-1-install-configure-and-start-bitcoin-core "mention"), then you need to update these values in the following files:

* `~/.ipc/validator1/.env`&#x20;
* `~/.ipc/validator2/.env`&#x20;
* `~/.ipc/validator3/.env`&#x20;
* `~/.ipc/validator4/.env`&#x20;
* `~/.ipc/validator5/.env`&#x20;
* `~/.ipc/user1/.env`&#x20;
* `~/.ipc/user2/.env`&#x20;
  {% endhint %}

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

{% hint style="success" %}
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.
{% endhint %}

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

{% code overflow="wrap" %}

```bash
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"
```

{% endcode %}

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

<figure><img src="https://1145429590-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmgxaMpnA2xFh2rLqMUiS%2Fuploads%2Fd28UlHy0xT2Xs9KQRXHI%2Fipc-dir.png?alt=media&#x26;token=66d4e209-15e6-4473-a5e7-2da3041ab61a" alt="" width="281"><figcaption><p>the <code>~/.ipc</code> directory after the <code>quickstart</code> script </p></figcaption></figure>

### 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`.

{% hint style="success" %}
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.
{% endhint %}

#### Validator 1

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

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

#### Validator 2

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

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

#### Validator 3

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

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

#### Validator 4

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

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

#### Validator 5

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

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

#### User 1

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

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

#### User 2

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

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