• Rust

• dfx >= 0.8.4

• Bitcoin Core. Mac users are recommended to download the .tar.gz version.

• Mac users need to install homebrew and then use it to install additional packages by running brew install llvm binaryen cmake

The first step would be to setup a local Bitcoin network.

1. Unpack the .tar.gz file.

2. Create a directory named data inside the unpacked folder.

3. Create a file called bitcoin.conf at the root of the unpacked folder and add the following contents:

   # Enable regtest mode. This is required to setup a private bitcoin network.
   regtest=1
   
   # Dummy credentials that are required by `bitcoin-cli`.
   rpcuser=btc-dev-preview
   rpcpassword=Wjh4u6SAjT4UMJKxPmoZ0AN2r9qbE-ksXQ5I2_-Hm4w=
   rpcauth=btc-dev-preview:8555f1162d473af8e1f744aa056fd728$afaf9cb17b8cf0e8e65994d1195e4b3a4348963b08897b4084d210e5ee588bcb

4. Run bitcoind to start the bitcoin client using the following command:

   ./bin/bitcoind -conf=$(pwd)/bitcoin.conf -datadir=$(pwd)/data

5. Create a wallet: ./bin/bitcoin-cli -conf=$(pwd)/bitcoin.conf createwallet mywallet

   If everything is setup correctly, you should see the following output:

   {
     "name": "mywallet",
     "warning": ""
   }

6. Generate a bitcoin address and save it in variable for later reuse:

   export BTC_ADDRESS=$(./bin/bitcoin-cli -conf=$(pwd)/bitcoin.conf getnewaddress)

   This will generate a bitcoin address for your wallet to receive funds.

7. Mine blocks to receive some Bitcoin as a reward.

   ./bin/bitcoin-cli -conf=$(pwd)/bitcoin.conf generatetoaddress 101 $BTC_ADDRESS

   You should see an output that looks similar to, but not exactly like, the following:

   [
     "1625281b2595b77276903868a0fe2fc31cb0c624e9bdc269e74a3f319ceb48de",
     "1cc5ba7e86fc313333c5448af6c7af44ff249eca3c8b681edc3c275efd3a2d38",
     "1d3c85b674497ba08a48d1b955bee5b4dc4505ffe4e9f49b428153e02e3e0764",
     ...
     "0dfd066985dc001ccc1fe6d7bfa53b7ad4944285dc173615792653bbd52151f1",
     "65975f1cd5809164f73b0702cf326204d8fee8b9669bc6bd510cb221cf09db5c",
   ]

Now that bitcoin is setup locally, it is time to run the IC-Bitcoin adapter.

The IC-Bitcoin adapter is a process that fetches headers and blocks from the Bitcoin network and passes them into the Internet Computer. The ic-bitcoin adapter will be integrated into the replica with the main release. For the developer preview, it needs to be launched separately.

Run the following commands to download, build, and run the adapter.

With bitcoind and the adapter running, we can now run a local replica with the Bitcoin canister.

1. Clone this repository.

2. From the root directory of the repository, start the local replica.

   dfx start --clean --background

3. Deploy the Bitcoin canister to the local replica in regtest mode.

   dfx deploy btc --no-wallet

The shim is the final piece that needs to be started up.

From this repository, run the following command:

The shim will start syncing blocks from your local bitcoin setup into the bitcoin canister. Once that’s complete, you’ll be able to query the bitcoin canister about the bitcoin state. See Using the Bitcoin Canister for more details and checkout the example project.

Instead of downloading bitcoin and cloning the ic repository, this repository offers an alternate solution using Docker and docker-compose.

• Rust

• dfx >= 0.8.4

• Mac users need to install homebrew and then use it to install additional packages by running brew install llvm binaryen cmake

• Docker

  • Mac: Docker for Mac

  • Linux: Docker Engine and Docker Compose.

1. docker-compose up -d will start bitcoind in the background and begin building a fresh image for the IC-Bitcoin adapter.

2. Verify that bitcoind is running: docker-compose exec bitcoind bitcoin-cli -conf=/conf/bitcoin.conf getmininginfo

   If everything is setup correctly, you should see the following output:

   {
     "blocks": 0,
     "difficulty": 4.656542373906925e-10,
     "networkhashps": 0,
     "pooledtx": 0,
     "chain": "regtest",
     "warnings": ""
   }

3. Create a wallet: docker-compose exec bitcoind bitcoin-cli -conf=/conf/bitcoin.conf createwallet mywallet

   If everything is setup correctly, you should see the following output:

   {
     "name": "mywallet",
     "warning": ""
   }

4. Generate a bitcoin address and save it in variable for later reuse:

   export BTC_ADDRESS=$(docker-compose exec bitcoind bitcoin-cli -conf=/conf/bitcoin.conf getnewaddress | tr -d '\r')

   This will generate a bitcoin address for your wallet to receive funds.

5. Mine blocks to receive some Bitcoin as a reward.

   docker-compose exec bitcoind bitcoin-cli -conf=/conf/bitcoin.conf generatetoaddress 101 $BTC_ADDRESS

   You should see an output that looks similar to, but not exactly like, the following:

   [
     "1625281b2595b77276903868a0fe2fc31cb0c624e9bdc269e74a3f319ceb48de",
     "1cc5ba7e86fc313333c5448af6c7af44ff249eca3c8b681edc3c275efd3a2d38",
     "1d3c85b674497ba08a48d1b955bee5b4dc4505ffe4e9f49b428153e02e3e0764",
     ...
     "0dfd066985dc001ccc1fe6d7bfa53b7ad4944285dc173615792653bbd52151f1",
     "65975f1cd5809164f73b0702cf326204d8fee8b9669bc6bd510cb221cf09db5c",
   ]

6. Verify the adapter is running: docker-compose logs adapter

   You should an output that looks similar to the following:

Continue with the Getting Started directions from Deploying the Bitcoin Canister to complete setup.

• To view the logs of the bitcoind container: docker-compose logs -f bitcoind

• To view the logs of the adapter container: docker-compose logs -f adapter