From 00b34a2c43a736901c52eda71f83edf4515d84d5 Mon Sep 17 00:00:00 2001 From: Sam Ricotta Date: Wed, 4 Dec 2024 11:48:23 +0200 Subject: [PATCH] update docs for signer and emulator --- .../docs/transition-from-phase1.md | 99 ++++++---- ...e-emulator.md => configure-with-signer.md} | 21 ++- docs/emulator-installation.md | 175 ++++++++++++++++++ 3 files changed, 257 insertions(+), 38 deletions(-) rename docs/{configure-emulator.md => configure-with-signer.md} (94%) create mode 100644 docs/emulator-installation.md diff --git a/covenant-signer/docs/transition-from-phase1.md b/covenant-signer/docs/transition-from-phase1.md index 61d225f..0514e74 100644 --- a/covenant-signer/docs/transition-from-phase1.md +++ b/covenant-signer/docs/transition-from-phase1.md @@ -27,7 +27,6 @@ are transitioning their phase-1 set up to the phase-2 one. 1. [Configuration](#41-configuration) 2. [Starting the daemon](#42-starting-the-daemon) 3. [Unlocking the key](#43-unlocking-the-key) - 4. [Testing the setup](#44-testing-the-setup) ## 1. Prerequisites @@ -37,6 +36,8 @@ This guide requires that: network you intend to operate your covenant signer on and 2. you have access to the private Bitcoin key you set up your covenant with. +3. A connection to a Babylon node. To run your own node, please refer to the +[Babylon Node Setup Guide](https://github.com/babylonlabs-io/networks/blob/sam/bbn-test-5/bbn-test-5/babylon-node/README.md). For a refresher on setting up the Bitcoin node, refer to the [deployment guide of your phase-1 covenant signer setup](https://github.com/babylonlabs-io/covenant-signer/blob/main/docs/deployment.md#2-bitcoind-setup). @@ -112,27 +113,24 @@ the wallet directory or `.dat` file. In the below example, we are loading the wallet named `covenant-wallet`. ```shell -$ bitcoin-cli loadwallet "covenant-wallet" +bitcoin-cli loadwallet "covenant-wallet" { "name": "covenant-wallet" } ``` #### Step 2: Extract the covenant address' `hdkeypath` + - - + Next, we are going to retrieve the `hdkeypath` of the Bitcoin address associated with our covenant key. We do this through the usage of the `getaddresssinfo` command which takes your covenant Bitcoin address as a parameter. ```shell -$ bitcoin-cli getaddressinfo bcrt1qazasawj3ard0ffwj04zpxlw2pt9cp7kwmnqyvk | jq .hdkeypath +bitcoin-cli getaddressinfo bcrt1qazasawj3ard0ffwj04zpxlw2pt9cp7kwmnqyvk | jq .hdkeypath "m/84h/1h/0h/0/0" ``` @@ -149,19 +147,44 @@ we are going to retrieve the **base58-encoded master private key** from the Bitc This key will be used to derive the covenant private key, which can then be imported directly into the Cosmos keyring. +What we need you to do is replace the `` with the one you received +in step 2. + List all descriptors in the wallet with private keys included in the output. -This will provide the descriptor needed to derive the private key. +This will provide the descriptor needed to derive the private key. ```shell -$ bitcoin-cli listdescriptors true | jq -r '.descriptors[] | select(.desc | contains("wpkh(")) | .desc | capture("wpkh\\((?.*?)\\)").key | sub("/\\*$"; "")' -tprv8ZgxMBicQKsPe9aCeUQgMEMy2YMZ6PHnn2iCuG12y5E8oYhYNEvUqUkNy6sJ7ViBmFUMicikHSK2LBUNPx5do5EDJBjG7puwd6azci2wEdq/84h/1h/0h/0 -``` +bitcoin-cli listdescriptors true | jq -r ' + .descriptors[] | + select(.desc | contains("/84h/1h/0h/0/")) | + .desc +' descriptors.json +wpkh(tprv8ZgxMBicQKsPe9aCeUQgMEMy2YMZ6PHnn2iCuG12y5E8oYhYNEvUqUkNy6sJ7ViBmFUMicikHSK2LBUNPx5do5EDJBjG7puwd6azci2wEdq/84h/1h/0h/0/*)#sachkrde +``` + + +Since Bitcoin wallets typically contain multiple descriptors +(usually 6 by default), we need to use `jq` to find the specific descriptor that + matches our previously saved `hdkeypath` (84h/1h/0h/0/0) and extract the master + private key from it. + +To extract the private key: +1. Remove everything outside the parentheses `wpkh(` and `)` +2. Remove the derivation path after the private key +(everything after and including `/`) + +You'll be left with just the base58-encoded master private key: + +``` +tprv8ZgxMBicQKsPe9aCeUQgMEMy2YMZ6PHnn2iCuG12y5E8oYhYNEvUqUkNy6sJ7ViBmFUMicikHSK2LBUNPx5do5EDJBjG7puwd6azci2wEdq +``` + The above output contains two key pieces of information as a concatenated string: 1. The **base58-encoded master private key** @@ -174,8 +197,14 @@ to derive the covenant private key from the master key using **BIP32 derivation* + + ```shell -$ covenant-signer derive-child-key \ +covenant-signer derive-child-key \ tprv8ZgxMBicQKsPe9aCeUQgMEMy2YMZ6PHnn2iCuG12y5E8oYhYNEvUqUkNy6sJ7ViBmFUMicikHSK2LBUNPx5do5EDJBjG7puwd6azci2wEdq \ 84h/1h/0h/0/0 Derived private key: fe1c56c494c730f13739c0655bf06e615409870200047fc65cdf781837cf7f06 @@ -186,22 +215,26 @@ The above output displays the derived private and public keys. -Matches the public key derived earlier and seen in the outputs of `getaddressinfo` -and `derive-child-key`. + +You can verify your key derivation was successful by checking that the public +key matches the one shown earlier in both: +- The `getaddressinfo` command output +- The `derive-child-key` command output -Verify that the derived public key matches the one obtained earlier from the -`getaddressinfo` command. +This verification ensures you've extracted the correct master private key from the descriptor. #### Step 4: Import the private key into a Cosmos Keyring - +As mentioned above as a prerequesite, you will need access to a Babylon node, or +one setup on your machine. The reason for this is that we need to access the +`babylond` binary to import the private key into the Cosmos keyring. Currently +the `covenant-signer` does not have support for importing keys. If you need a +guide on how to set up a Babylon node, you can refer to the +[Babylon Node Setup Guide](https://github.com/babylonlabs-io/networks/bbn-test-5/babylon-node/README.md). + -Next, import the derived private key into the Cosmos keyring using the following -command: +Next, navigate to where you have the babylon node running and import the derived +private key into the Cosmos keyring using the following command: ```shell babylond keys import-hex cov fe1c56c494c730f13739c0655bf06e615409870200047fc65cdf781837cf7f06 --keyring-backend file @@ -228,15 +261,17 @@ The output will display the details of the imported key: ``` -Congratulations! You have successfully imported your keys from the prior setup -and verified your setup for the covenant emulator. +Congratulations! You have successfully imported your key. ## 4. Operation ### 4.1. Configuration +Next, we can return to the terminal where you have the covenant signer directory +and create your own configuration file. + Use the example configuration [file](../example/config.toml) to create your own configuration file. Then, replace the placeholder values with your own -configuration. +configuration. This can be placed directly in the `covenant-signer` directory. ```toml [keystore] @@ -282,7 +317,8 @@ Below are brief explanations of the configuration entries: ### 4.2. Starting the daemon -The covenant signer can be run using the following command: +We then will run the following command to start the daemon from the +`covenant-signer` directory: ```shell covenant-signer start --config ./path/to/config.toml @@ -345,4 +381,5 @@ to sign transactions with the covenant key. \ No newline at end of file +* Prometheus metrics and logs --> + \ No newline at end of file diff --git a/docs/configure-emulator.md b/docs/configure-with-signer.md similarity index 94% rename from docs/configure-emulator.md rename to docs/configure-with-signer.md index b93048a..b02e910 100644 --- a/docs/configure-emulator.md +++ b/docs/configure-with-signer.md @@ -1,4 +1,4 @@ -# Configuring the Covenant Emulator +# Configuring the Covenant Emulator with covenant Signer ## Table of Contents @@ -29,10 +29,10 @@ it into the new integrated keyring in the covenant signer. ## 2. Prerequisites -To successfully complete this guide, you will need +To successfully complete this guide, you will need: -1. To successfully complete this guide, you will need a running instance of the -[covenant signer](../covenant-signer) +1. A running instance of the [covenant signer](../covenant-signer) +with the url that you configured it to. 2. A connection to a Babylon node. To run your own node, please refer to the [Babylon Node Setup Guide](https://github.com/babylonlabs-io/networks/blob/sam/bbn-test-5/bbn-test-5/babylon-node/README.md). @@ -41,8 +41,15 @@ complete the setup of the covenant signer with your keys before proceeding. ## 3. Install covenant emulator binary -Once you have the covenant signer running, you can install the covenant emulator -binary. +If you haven't already, download [Golang 1.23](https://go.dev/dl). + +Once installed run: + +```shell +go version +``` + +If you have not yet cloned the repository, run: ```shell git clone git@github.com:babylonlabs-io/covenant-emulator.git @@ -94,7 +101,7 @@ $ ls ### 4.2. Configure the covenant emulator As you have already set up the covenant signer, you can now configure the covenant -emulator to use it. +emulator to use it. Use the following parameters to configure the `covd.conf` file. diff --git a/docs/emulator-installation.md b/docs/emulator-installation.md new file mode 100644 index 0000000..bd77cdd --- /dev/null +++ b/docs/emulator-installation.md @@ -0,0 +1,175 @@ + +# Covenant Emulator Installation + +## Prerequisites + +This project requires Go version `1.23` or later. +Install Go by following the instructions on +the [official Go installation guide](https://golang.org/doc/install). + +### Download the code + +To get started, clone the repository to your local machine from Github: + +```bash +$ git clone git@github.com:babylonlabs-io/covenant-emulator.git +``` + +You can choose a specific version from +the [official releases page](https://github.com/babylonlabs-io/covenant-emulator/releases): + +```bash +$ cd covenant-emulator # cd into the project directory +$ git checkout +``` + +## Build and install the binary + +At the top-level directory of the project + +```bash +$ make install +``` + +The above command will build and install the covenant-emulator daemon (`covd`) +binary to `$GOPATH/bin`: + +If your shell cannot find the installed binaries, make sure `$GOPATH/bin` is in +the `$PATH` of your shell. Usually, these commands will do the job + +```bash +export PATH=$HOME/go/bin:$PATH +echo 'export PATH=$HOME/go/bin:$PATH' >> ~/.profile +``` + +To build without installing, + +```bash +$ make build +``` + +The above command will put the built binaries in a build directory with the +following structure: + +```bash +$ ls build + └── covd +``` + +Another common issue with compiling is that some of the dependencies have +components written in C. If a C toolchain is absent, the Go compiler will throw +errors. (Most likely it will complain about undefined names/types.) Make sure a +C toolchain (for example, GCC or Clang) is available. On Ubuntu, this can be +installed by running + +```bash +sudo apt install build-essential +``` + +## Setting up a covenant emulator + +### Configuration + +The `covd init` command initializes a home directory for the +finality provider daemon. +This directory is created in the default home location or in a +location specified by the `--home` flag. +If the home directory already exists, add `--force` to override the directory if +needed. + +```bash +$ covd init --home /path/to/covd/home/ +``` + +After initialization, the home directory will have the following structure + +```bash +$ ls /path/to/covd/home/ + ├── covd.conf # Covd-specific configuration file. + ├── logs # Covd logs +``` + +If the `--home` flag is not specified, then the default home directory +will be used. For different operating systems, those are: + +- **MacOS** `~/Users//Library/Application Support/Covd` +- **Linux** `~/.Covd` +- **Windows** `C:\Users\\AppData\Local\Covd` + +Below are some important parameters of the `covd.conf` file. + +**Note**: +The configuration below requires to point to the path where this keyring is +stored `KeyDirectory`. This `Key` field stores the key name used for interacting +with the Babylon chain and will be specified along with the `KeyringBackend` +field in the next [step](#generate-key-pairs). So we can ignore the setting of +the two fields in this step. + +```bash +# The interval between each query for pending BTC delegations +QueryInterval = 15s + +# The maximum number of delegations that the covd processes each time +DelegationLimit = 100 + +# Bitcoin network to run on +BitcoinNetwork = simnet + +# Babylon specific parameters + +# Babylon chain ID +ChainID = chain-test + +# Babylon node RPC endpoint +RPCAddr = http://127.0.0.1:26657 + +# Babylon node gRPC endpoint +GRPCAddr = https://127.0.0.1:9090 + +# Name of the key in the keyring to use for signing transactions +Key = + +# Type of keyring to use, +# supported backends - (os|file|kwallet|pass|test|memory) +# ref https://docs.cosmos.network/v0.46/run-node/keyring.html#available-backends-for-the-keyring +KeyringBackend = test + +# Directory where keys will be retrieved from and stored +KeyDirectory = /path/to/covd/home +``` + +To see the complete list of configuration options, check the `covd.conf` file. + +## Generate key pairs + +The covenant emulator daemon requires the existence of a keyring that signs +signatures and interacts with Babylon. Use the following command to generate the +key: + +```bash +$ covd create-key --key-name covenant-key --chain-id chain-test +{ + "name": "cov-key", + "public-key": "9bd5baaba3d3fb5a8bcb8c2995c51793e14a1e32f1665cade168f638e3b15538" +} +``` + +After executing the above command, the key name will be saved in the config file +created in [step](#configuration). +Note that the `public-key` in the output should be used as one of the inputs of +the genesis of the Babylon chain. +Also, this key will be used to pay for the fees due to the daemon submitting +signatures to Babylon. + +## Start the daemon + +You can start the covenant emulator daemon using the following command: + +```bash +$ covd start +2024-01-05T05:59:09.429615Z info Starting Covenant Emulator +2024-01-05T05:59:09.429713Z info Covenant Emulator Daemon is fully active! +``` + +All the available CLI options can be viewed using the `--help` flag. These +options can also be set in the configuration file. \ No newline at end of file