Skip to content

Latest commit

 

History

History
275 lines (215 loc) · 9.11 KB

manual-setup.adoc

File metadata and controls

275 lines (215 loc) · 9.11 KB
Raw

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

  • Geth (Ethereum client) 1.10.3-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:

Node.js version notice

All modules work with Node v14.

We recommend using nvm to manage node versions easily.

nvm

You can install a specific node version by doing:

$ nvm install 14

And use the specific version:

$ nvm use 14

To change the default node version globally run:

$ nvm alias default 14

brew

On macOS, you can also use brew install node@14 to install Node 14, and use brew link --force node@14 to make it your default local install.

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. Initialize bitcoin using:

    $ ./initialize-bitcoin.sh

    You can skip this step if your local bitcoin is alread initialized.

  4. Run local Bitcoin Core node and ElectrumX using:

    $ ./run-bitcoin.sh

  5. Run Keep & tBTC installation script:

    $ ./install.sh

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

    Keep in mind that coverage-pools depend on tbtc, tbtc depends on keep-ecdsa and keep-ecdsa depends on keep-core.

    If you decide to update coverage-pools, you can run install-coverage-pools.sh.

    If you decide to update tbtc, you can run install-tbtc.sh followed by install-coverage-pools.sh.

    If you decide to update keep-ecdsa, you can run install-keep-ecdsa.sh followed by install-tbtc.sh and install-coverage-pools.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 followed by install-coverage-pools.sh or just run 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)

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

  • If you see The unauthenticated git protocol on port 9418 is no longer supported error or erors like ENOENT: no such file or directory, open '/home/runner/work/local-setup/local-setup/e2e/node_modules/.staging/…​', you can change Git configuration on your local enviroment to always use https:// protocol instaed of git:// to download files. This can be done by executing command: git config --global url."https://".insteadOf git://

E2E tests

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

$ nvm use 14.17.0

Then invoke:

$ ./run-e2e-test.sh