PolkaBTC

About

The PolkaBTC UI connects the Polkadot ecosystem with Bitcoin. It allows the creation of PolkaBTC, a fungible token that represents Bitcoin in the Polkadot ecosystem. PolkaBTC is backed by Bitcoin 1:1 and allows redeeming of the equivalent amount of Bitcoins by relying on a collateralized third-party. In comparison to other bridge constructions (like tBTC, wBTC, or RenVM) anyone can become an intermediary by depositing collateral making PolkaBTC the only truly open system.

The bridge itself follows the detailed specification: Explore the specification »

It is implemented as a collection of open-source Substrate modules using Rust: Explore the implementation »

Built with

• React
• TypeScript
• polkadot-js
• yarn
• docker-compose

You can visit rococo.polkabtc.io for the latest stable version of the website.

Quickstart

Make sure you have docker-compose installed locally.

You can run the UI with a local instance of the BTC-Parachain and in combination with Bitcoin regtest or Bitcoin testnet as follows:

Clone this repository and enter into the root folder.

[email protected]:interlay/polkabtc-ui.git
cd polkabtc-ui

Please make use of the .env.* files to set build variables. The priority of these are defined here.

Regtest

Note: By default use, regtest for local development.

In one terminal, start the BTC-Parachain, Bitcoin regtest, vaults and relayers:

yarn compose:regtest

On another terminal, start the UI:

yarn install && REACT_APP_BITCOIN_NETWORK=regtest yarn start

Testnet

In one terminal, start the BTC-Parachain, Bitcoin regtest, vaults and relayers:

yarn compose:testnet

On another terminal, start the UI:

yarn install && REACT_APP_BITCOIN_NETWORK=testnet yarn start

Detailed Starting Guide

Note: The detailed starting guide requires you to have a Rust installation and requires you to build all the dependencies manually. This will take about two hours if you are doing this the first time. For most people, the docker-compose setup in the Quickstart guide above is recommended.

If you wish to run the BTC-Parachain, its clients and Bitcoin without using docker, follow these steps.

Prerequisites

BTC Parachain

You need to have an instance of the BTC Parachain running. Follow the instructions at the BTC-Parachain repository. Once you have successfully build the BTC Parachain, start a development server from the root folder of the BTC Parachain repository.

./target/release/btc-parachain --dev

If you want to reset the development chain, execute the following command.

./target/release/btc-parachain purge-chain --dev

Clients

In order to automatically submit block headers, run the staked-relayer client software.

staked-relayer --keyring=eve --polka-btc-url 'ws://localhost:9944'

The architecture also relies upon collateralized vaults; use the vault client to register automatically.

vault --keyring=charlie --network=testnet --auto-register-with-collateral 100000000 --polka-btc-url 'ws://localhost:9944'

Issue requests (BTC -> PolkaBTC) can be executed solely through the UI but a vault client is required to redeem (PolkaBTC -> BTC).

Lastly, we require a price oracle to compute the exchange rate (BTC <> DOT), the oracle client can automatically feed this from an integrated data source (e.g. CoinGecko).

oracle --keyring=bob --polka-btc-url 'ws://localhost:9944' --coingecko

Regtest

Bitcoin

Download and start Bitcoin Core.

bitcoind -regtest -server

Electrs

We make heavy use of the Blockstream API in the UI to watch for payments made on Bitcoin.

electrs -vvvv --network regtest --jsonrpc-import --cors "*" --cookie "rpcuser:rpcpassword" --daemon-rpc-addr localhost:18443 --http-addr "[::0]:3002" --index-unspendables

Start the app with:

yarn install
REACT_APP_BITCOIN_NETWORK=regtest yarn start

Testnet

To run against Bitcoin testnet first start your daemon:

bitcoind -testnet -server

Start the app with:

yarn install
REACT_APP_BITCOIN_NETWORK=testnet yarn start

Note: This is only supported on Linux due to issues with network_mode: "host" on Mac.

Docker Installation

Clone this repository and enter into the root folder.

[email protected]:interlay/polkabtc-ui.git
cd polkabtc-ui

Install the required dependencies.

docker build -t polkabtc:ui .

Start the development server. Open http://localhost:3000 to view it in the browser.

docker run -it -p 3000:3000 polkabtc:ui

Test

Test the project.

yarn test

Design System

Visualize the Tailwindcss configuration.

yarn tailwind-config-viewer

Locally Run or build Storybook.

yarn storybook # locally run
yarn build-storybook # build

Help

Bitcoin Regtest

Regtest is a local Bitcoin instance that allows you to practically anything including sending transactions, mining blocks, and generating new addresses. For a full overview, head over to the Bitcoin developer documentation.

Sending Transactions

For the issue process, you need to send a transaction. On regtest this can be achieved with:

bitcoin-cli -regtest -rpcwallet=Alice sendtoaddress VAULT_ADDRESS AMOUNT

Mining Blocks

In regtest, blocks are not automatically produced. After you sent a transaction, you need to mine e.g. 1 block:

bitcoin-cli -regtest generatetoaddress 1 $(bitcoin-cli -regtest getnewaddress)

Getting Balances

You can query the balance of your wallet like so:

bitcoin-cli -regtest -rpcwallet=Alice getbalance

Test Data (Regtest)

For more advanced interactions with the UI, you may also use the testdata-gen toolkit to automated some common actions.

For an overview of actions check the documentation here.

Installation

Note: This requires a local Rust installation.

git clone [email protected]:interlay/polkabtc-clients.git
cd polkabtc-clients
cargo build -p testdata-gen
# environment variables for bitcoind
source .env

Registering a New Vault

For example, to register bob as a vault we can use the following command:

testdata-gen --keyring bob register-vault --btc-address "bcrt1qu0a2tc422uurm39g4p2n5wfpy65fwypnz7p9aw" --collateral 100000000

Issue PolkaBTC

Then when alice wants to issue 0.001 PolkaBTC, we need to send the equivalent number of Satoshis to bob:

testdata-gen --keyring alice send-bitcoin --btc-address "bcrt1qu0a2tc422uurm39g4p2n5wfpy65fwypnz7p9aw" --satoshis 100000

More Options

Print all the available options with:

testdata-gen --help

Docker

You can hard-reset the docker dependency setup with the following commands:

docker kill $(docker ps -q)
docker rm $(docker ps -a -q)
docker rmi $(docker images -q)
docker volume rm $(docker volume ls -q)

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b yourname/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin yourname/AmazingFeature)
5. Open a Pull Request

If you are searching for a place to start or would like to discuss features, reach out to us:

• Discord

License

(C) Copyright 2021 Interlay Ltd

polkabtc-ui is licensed under the terms of the Apache License (Version 2.0). See LICENSE.

Contact

Website: Interlay.io

Twitter: @interlayHQ

Email: [email protected]

Acknowledgements

We would like to thank the following teams for their continuous support:

• Web3 Foundation
• Parity Technologies