Skip to content

Latest commit

 

History

History
242 lines (188 loc) · 8.25 KB

manual-setup.adoc

File metadata and controls

242 lines (188 loc) · 8.25 KB

Manual setup on local machine

Prerequisites

If you’re on macOS, install Homebrew and macos-setup.sh script to setup all necessary tools.

If you are not on macOS or you don’t have Homebrew, you need to install:

  • Go compiler, at least 1.14

  • Geth (Ethereum client) 1.9.9-stable

  • Solidity, at least 0.5.17

  • Protobuf compiler, at least 3.11.4

  • protoc-gen-gogoslick toolchain

  • jq

Regardless you use macos-setup.sh or not, you should also install:

  • Docker & Docker Compose

  • pyenv, at least 1.2.18 (optional - only if testnet relay is used)

  • pipenv, at least 2018.11.26 (optional - only if testnet relay is used)

Node.js version notice

Please use Node v15.8.0 for everything but E2E test script. To run the test script, please use Node v14.3.0.

We recommend using nvm to manage node versions easily. You can install both versions by doing:

$ nvm install 11.15.0
$ nvm install 14.3.0

And use the specific version:

$ nvm use 11.15.0
$ nvm use 14.3.0

Installing the system

  1. Initialize local geth using:

    $ ./initialize-geth.sh

    You can skip this step if your local geth is already initialized. This script clears all Ethereum client data, initilizes genesis block, and funds five accounts. All client data are kept in the working directory of this project so all the data used for other projects stay untouched.

  2. Run local geth node using:

    $ ./run-geth.sh

  3. Run local Bitcoin Core node and ElectrumX using:

    $ ./run-bitcoin.sh

  4. Run Keep & tBTC installation script:

    $ ./install.sh

    This script will fetch keep-core, keep-ecdsa, and tbtc source code, deploy contracts of keep-core, keep-ecdsa, and tbtc. It will also build keep-core and keep-ecdsa off-chain clients.

    Later on, if you decide to update tbtc, you can run just install-tbtc.sh.

    Keep in mind, tbtc depends on keep-ecdsa and keep-ecdsa depends on keep-core so if you decide to update keep-ecdsa, you can run install-keep-ecdsa.sh followed by install-tbtc.sh.

    If you decide to update keep-core, you have to run install-keep-core.sh followed by install-keep-ecdsa.sh followed by install-tbtc.sh or just the entire install.sh again.

Run clients

The above installation script will configure:

  • 1 keep-core client

  • 3 keep-ecdsa clients

To run the keep-core client use:

$ ./run-core-1.sh

It is enough to run one keep-core client to generate a group and produce relay entries. Setting up more than one client locally is possible but consumes more resources.

To run keep-ecdsa clients use:

$ ./run-ecdsa-1.sh
$ ./run-ecdsa-2.sh
$ ./run-ecdsa-3.sh

There are at least 3 keep-ecdsa clients needed to open a keep. Setting up more than three clients locally is possible but consumes more resources.

Beacon genesis

Before the beacon is able to produce a first relay entry, genesis needs to happen. Genesis triggers the first random beacon group selection.

Genesis should be triggered after keep-core client started with:

$ cd keep-core
$ KEEP_ETHEREUM_PASSWORD="password" ./keep-core --config configs/config.local.1.toml relay genesis

Bonded ECDSA keep factory from keep-ecdsa contracts requests for new relay entry to reseed after each signer selection but it is also possible to request for a new relay entry manually with:

$ cd keep-core
$ KEEP_ETHEREUM_PASSWORD="password" ./keep-core --config configs/config.local.1.toml relay request

How to interact with the system

You can interact with the system through the tBTC dApp or automated end-to-end tests. Before you start interacting, make sure you:

  • Installed all system components using install.sh script

  • Have a local Geth instance (run-geth.sh) working

  • Have local Bitcoin Core and ElectrumX instances (run-bitcoin.sh) working

  • Have 1 keep-core and 3 keep-ecdsa clients up and running

Keep Dashboard dApp

To run the Keep Dashboard dApp invoke:

$ ./run-keep-dashboard.sh

tBTC dApp

To run the tBTC dApp against the local Bitcoin network invoke:

$ ./run-tbtc-dapp.sh

Testing the Deposit/Redemption Flow

Now that we have everything in place:

  • Geth, bitcoin, and electrumx running

  • keep-core and 3 ecdsa client running

  • the tBTC dApp running

We want to be able to test the deposit/redemption flow.

First, we need a way to send bitcoins to the deposit address:

$ npm install -g ./bitcoind-wallet

Second, we need an ethereum wallet like metamask (this section will assume that’s what we’re using - it can be installed as a browser extension).

Add a new ethereum network with the following parameters to your wallet:

name: Keep-Local (can be whatever you want)
rpc url: http://localhost:8545
chain id: 1101
currency symbol: ETH

The above is accomplishable in metamask by opening up the browser extension, clicking the 3 dots in the top right, hitting expand view, clicking the network dropdown in the top right, and selecting "Custom RPC".

Switch your wallet to use this network, and then navigate to the tBTC dApp (http://localhost:3000)

In metamask, go to "My Accounts" section (click on the colorful circle in the top-right corner) and choose "Import Account". Choose "JSON File" as type, navigate to file: local-setup/ethereum/data/keystore/UTC—​2019-08-01T13-12-46.081900000Z—​3d373d872b7ba29d92ed47caa8605b4dd6ec84ef, type in "password" as password and click "Import".

Press the deposit button in the dApp, connect your newly imported wallet, and pick a lot size.

Confirm all of the transactions through your wallet, and eventually you will be presented with a prompt to send BTC to an address.

Copy the address and then run:

$ bitcoind-wallet sendToAddress <wallet-address-from-the-website> <lot-size>
# example: bitcoind-wallet sendToAddress bcrt1ra67pwcr96pvv05nt8mhvfanr73lg2zl9w7k5zr 0.5

Confirm all of the ethereum transactions with your wallet until it completes.

Note the TDT ID that the dApp gives you (0x530D37eD3E2194EC1671DD2E153A03FCED5F80cD was mine). This will be used in the redemption flow.

To see how much TBTC you have, add a custom token to your wallet with the address from the result of:

$ cat tbtc/solidity/build/contracts/TBTCToken.json | jq '.networks["1101"].address'

(mine was 0xF355D8f5Dca13CE5019675f5f2b2bD821b9A40b9)

In order to test the redemption flow, you need an amount of TBTC equal to the lot size, which you won’t currently have if you’ve only deposited once (due to fees). So, deposit more BTC using the same process as above. Then, once you have enough TBTC in your wallet to cover a deposit, press the Redeem button, and plug in one of your TDT IDs (mine was 0x530D37eD3E2194EC1671DD2E153A03FCED5F80cD).

Generate a bitcoin wallet address by running:

$ bitcoind-wallet getNewAddress

(mine was bcrt1q2c5ntlx6qddwfppqdk06hzv0hgj36mdk6zpjrt)

Confirm all of the transactions and verify that the TBTC has left your wallet. You did it!

Troubleshooting

  • If you’re getting an error initiating the deposit, try resetting your wallet in metamask (top right → Settings → Advanced → Reset Account)

  • During the keep-ecdsa phase of running install.sh it may complain about sha3. If that happens, cd into keep-ecdsa and run: $ npm install --save-dev sha3

  • If you see an error coming from npm complaining about dependencies (e.g. babel-cli), try deleting package-lock.json (e.g. if npm cannot find file local-setup/tbtc/solidity/node_modules/.staging/@keep-network/keep-ecdsa-64660964/node_modules/@babel/cli, delete package-lock.json file located in local-setup/tbtc/solidity) and run the script again.

  • If you cannot execute commands with bitcoind-wallet, make sure you switched to version 15.8.0 of nvm.

  • If you pressed "Deposit" and got Unhandled Rejection error from dApp, make sure the wallet is connected to your local ethereum network (in metamask go to My Accounts→Settings→Networks, Chain Id for localhost:8545 should be 1101).

E2E tests

To run the automated end-to-end scenario switch to Node 14.3.0:

$ nvm use 14.3.0

Then invoke:

$ ./run-e2e-test.sh