diff --git a/README.md b/README.md index af29ae0..dcacdd0 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ -# Covenant Emulator +# Covenant Emulation Toolset ## Overview -Covenant emulator is a daemon program run by every member of the covenant -committee of the BTC staking protocol. The role of the covenant committee -is to protect PoS systems against attacks from the BTC stakers and -validators. It achieves this by representing itself as an M-out-of-N +The covenant emulation toolset is a set of programs operated by every member of +the covenant committee of the BTC staking protocol. The role of the covenant +committee is to protect PoS systems against attacks from the BTC stakers and +finality providers. It achieves this by representing itself as an M-out-of-N multi-signature that co-signs BTC transactions with the BTC staker. More specifically, through co-signing, the covenant committee enforces the @@ -57,207 +57,64 @@ code. This committee can be dimissed once such programmability becomes available, e.g., if BTC's covenant proposal [BIP-119](https://github.com/bitcoin/bips/blob/master/bip-0119.mediawiki) is merged. -Covenant emulation committee members are defined in the Babylon parameters and -their public keys are recorded in the genesis file of the Babylon chain. -Changing the covenant committee requires a -[governance proposal](https://docs.cosmos.network/v0.50/build/modules/gov). -Each committee member runs the `covd` daemon (short for -`covenant-emulator-daemon`), which -constantly monitors staking requests on the Babylon chain, verifies the -validity of the Bitcoin transactions that are involved with them, and -sends the necessary signatures if verification is passed. -The staking requests can only become active and receive voting power -if a sufficient quorum of covenant committee members have -verified the validity of the transactions and sent corresponding signatures. - -Upon a pending staking request being found, the covenant emulation daemon -(`covd`), validates it against the spending rules defined in -[Staking Script specification](https://github.com/babylonlabs-io/babylon/blob/main/docs/staking-script.md), -and sends three types of signatures to the Babylon chain: - -1. **Slashing signature**. This signature is an [adaptor signature](https://bitcoinops.org/en/topics/adaptor-signatures/), -which signs over the slashing path of the staking transaction. Due to the -[recoverability](https://github.com/LLFourn/one-time-VES/blob/master/main.pdf) -of the adaptor signature, it also prevents a malicious finality provider from -irrationally slashing delegations. -2. **Unbonding signature**. This signature is a [Schnorr signature](https://en.wikipedia.org/wiki/Schnorr_signature), -which is needed for the staker to unlock their funds before the original -staking time lock expires (on-demand unbonding). -3. **Unbonding slashing signature**. This signature is also an adaptor -signature, which has similar usage to the **slashing signature** but signs over -the slashing path of the unbonding transaction. - -## Installation - -### Prerequisites - -This project requires Go version `1.21` 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. +Covenant emulation committee members are defined in the Babylon parameters and +their public keys are recorded in the genesis file of the Babylon chain. +Changing the covenant committee requires a +[governance proposal](https://docs.cosmos.network/v0.50/build/modules/gov). +Each committee member runs two components: + +1. **Covenant Signer**: The Covenant Signer operates in tandem with the Covenant Emulator and + is purpose-built to securely manage private keys for signing operations. + It prioritizes security through isolation, + ensuring that private key handling is confined to an instance with + minimal connectivity and simpler application logic compared to the + Covenant Emulator daemon. +2. **Covenant Emulator**: The covenant emulator constantly monitors staking + requests on the Babylon chain, verifies the validity of the + Bitcoin transactions that are involved with them, + and if verification is passed, + generates the necessary signatures through a connection to the + covenant-signer and sends them to the Babylon blockchain. Specifically, + it deals with the following signatures: + 1. **Slashing signature**. This signature is an [adaptor signature](https://bitcoinops.org/en/topics/adaptor-signatures/), + which signs over the slashing path of the staking transaction. Due to the + [recoverability](https://github.com/LLFourn/one-time-VES/blob/master/main.pdf) + of the adaptor signature, it also prevents a malicious finality provider from + irrationally slashing delegations. + 2. **Unbonding signature**. This signature is a [Schnorr signature](https://en.wikipedia.org/wiki/Schnorr_signature), + which is needed for the staker to unlock their funds before the original + staking time lock expires (on-demand unbonding). + 3. **Unbonding slashing signature**. This signature is also an adaptor + signature, which has similar usage to the **slashing signature** but signs over + the slashing path of the unbonding transaction. + +The staking requests can only become active and receive voting power if a +sufficient quorum of covenant committee members have verified the validity +of the transactions and sent corresponding signatures. + +## Interaction Between Emulator and Signer + +The Covenant Emulator handles the application logic, including monitoring the +Babylon blockchain and validating transactions. When a signature is needed, it +forwards the request to the Covenant Signer, which processes the signing operation +and returns the necessary cryptographic signature. + +The interaction begins with the Covenant Emulator monitoring the Babylon +blockchain for new staking requests. The emulator then prepares the necessary +signing data, which includes transactions requiring slashing signatures +(adaptor signatures), unbonding signatures (Schnorr signatures), and +unbonding slashing signatures (adaptor signatures). This data is then forwarded +to the Covenant Signer. + +This flow ensures that all private key operations remain isolated within the +secure Covenant Signer while the emulator handles the blockchain interaction +and validation logic. + +![Covenant Architecture](./static/covenant.png) + +## Covenant Emulator Stack Setup +To set up your covenant emulator stack, +please follow the instructions in the following documents +(in sequence): +1. [Covenant Signer Setup](./docs/covenant-signer-setup.md) +2. [Covenant Emulator Setup](./docs/covenant-emulator-setup.md) diff --git a/docs/covenant-emulator-setup.md b/docs/covenant-emulator-setup.md new file mode 100644 index 0000000..c2f370a --- /dev/null +++ b/docs/covenant-emulator-setup.md @@ -0,0 +1,198 @@ +# Covenant Emulator Setup + +This document outlines the setup of the covenant-emulator +daemon program. + +## Table of Contents + +1. [Prerequesites](#1-prerequisites) +2. [Install Covenant Emulator Binary](#2-install-covenant-emulator-binary) +3. [Setting up the Covenant Emulator Program](#3-setting-up-the-covenant-emulator-program) + 1. [Initialize directories](#31-initialize-directories) + 2. [Configure the covenant emulator](#32-configure-the-covenant-emulator) +4. [Generate key pairs](#4-generate-key-pairs) +5. [Start the emulator daemon](#5-start-the-emulator-daemon) + +## 1. Prerequisites + +To successfully complete this guide, you will need: + +1. A running instance of the [covenant signer](../covenant-signer) + with the url that you configured it to. Please follow the + [covenant signer setup guide](./covenant-signer-setup.md) to + complete the setup of the covenant signer with your keys before proceeding. + Note that the phase-2 covenant-signer program is a different one than the one + used doing phase-1 +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/main/bbn-test-5/bbn-test-5/babylon-node/README.md). + +## 2. Install 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 +cd covenant-emulator +git checkout +``` + +Run the following command to build the binaries and +install them to your `$GOPATH/bin` directory: + +```shell +make install +``` + +This command will: +- Build and compile all Go packages +- Install `covd` binary to `$GOPATH/bin` +- Make commands globally accessible from your terminal + +If your shell cannot find the installed binary, make sure `$GOPATH/bin` is in +the `$PATH` of your shell. Use the following command to add it to your profile +depending on your shell. + +```shell +export PATH=$HOME/go/bin:$PATH +echo 'export PATH=$HOME/go/bin:$PATH' >> ~/.profile +``` + +## 3. Setting up the covenant emulator program + +### 3.1. Initialize directories + +Next, we initialize the node and home directory. It should generate all of the +necessary files such as `covd.config`, these files will live in the `` +that you set for the `--home` with the below command. + +```shell +covd init --home +``` + +After initialization, the home directory will have the following structure: + +```shell +$ ls + ├── covd.conf # Covd-specific configuration file. + ├── logs # Covd logs +``` + +### 3.2. Configure the covenant emulator + +As you have already set up the covenant signer, you can now configure the covenant +emulator to use it. + +Use the following parameters to configure the `covd.conf` file. + +``` +# 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 = bbn-test-5 + +# Babylon node RPC endpoint +RPCAddr = https://rpc-euphrates.devnet.babylonlabs.io:443 + +# Babylon node gRPC endpoint +GRPCAddr = https://rpc-euphrates.devnet.babylonlabs.io:443 + +# Name of the key in the keyring to use for signing transactions +Key = covenant-key + +# Type of keyring to use, +# supported backends - (os|file|kwallet|pass|test|memory) +# ref https://docs.cosmos.network/v0.50/run-node/keyring.html#available-backends-for-the-keyring +KeyringBackend = test + +[remotesigner] +; URL of the remote signer +URL = http://127.0.0.1:9792 + +; client when making requests to the remote signer +Timeout = 2s + +; if true, covenant will use the remote signer to sign transactions +RemoteSignerEnabled = true +``` + +Below are brief explanations of the configuration entries: + +- `QueryInterval` - How often to check for new BTC delegations that need processing +- `DelegationLimit` - Maximum number of delegations to process in a single batch +- `BitcoinNetwork` - Which Bitcoin network to connect to (mainnet, testnet, simnet, etc.) +- `ChainID` - Unique identifier of the Babylon blockchain network +- `RPCAddr` - HTTP endpoint for connecting to a Babylon node +- `GRPCAddr` - gRPC endpoint for connecting to a Babylon node +- `Key` - Name of the key in the keyring used for transaction signing +- `KeyringBackend` - Storage backend for the keyring (os, file, kwallet, pass, test, memory) +- `URL` - Endpoint where the remote signing service is running +- `Timeout` - Maximum time to wait for remote signer responses +- `RemoteSignerEnabled` - Whether to use the remote signing service + +Ensure that the covenant signer is running and unlocked before proceeding +otherwise you will be unable to run the emulator. + +## 4. Generate key pairs + +The covenant emulator daemon requires the existence of a Babylon keyring that +signs signatures and interacts with Babylon. Use the following command to generate +the key: + +```bash +covd create-key --key-name --chain-id --keyring-backend +{ + "name": "babylon-tx-key", + "public-key-hex": "6dd4c9415a4091b74f45fdce71f5b8eebe743e5990b547009ff1dce8393d5df2", + "babylon-address": "bbn1gw5ns0kmcjj8y0edu5h4nkkw4aq263eyx2ynnp" +} +``` + +Parameters: +- `--key-name`: Name for the key in the keyring +- `--chain-id`: ID of the Babylon chain (e.g., bbn-test-5) +- `--keyring-backend`: Backend for key storage, we will use `test` + for this guide. + +After executing the above command, the key name will be saved in the config file +created in the last [step](#42-configure-the-covenant-emulator). + +**⚡ 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. + +To check your balance, View your account on the +[Babylon Explorer](https://babylon-testnet.l2scan.co) by searching for your +address. + + +## 5. Start the emulator 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 diff --git a/docs/covenant-signer-setup.md b/docs/covenant-signer-setup.md new file mode 100644 index 0000000..65a2d54 --- /dev/null +++ b/docs/covenant-signer-setup.md @@ -0,0 +1,405 @@ +# Covenant Signer Setup + +> **⚡ Note:** This document is intended for covenant committee members that +> are setting up a phase-2 stack based on an existing phase-1 stack. + +The Covenant Signer is a daemon program in the Covenant Emulator toolset +that is responsible for securely managing the private key of the +covenant committee member and producing the necessary cryptographic +signatures. + +It prioritizes security through isolation, ensuring that private key handling +is confined to an instance with minimal connectivity and simpler application +logic. + +> **⚡ Note:** This program is a separate implementation from the +> [covenant signer](https://github.com/babylonlabs-io/covenant-signer/) +> program used for phase-1. All covenant committee members +> are required to transition their keys to this program to participate +> in phase-2. + +Previously, private keys were stored in the Bitcoin wallet using PSBT (Partially +Signed Bitcoin Transactions) for signing operations. The new design uses a +dedicated Covenant Signer that acts as a remote signing service, storing private +keys in an encrypted Cosmos SDK keyring. This approach not only improves security +through isolation but also enables the creation of both Schnorr signatures and +Schnorr adaptor signatures required for covenant operations. + +## Table of Contents + +1. [Prerequisites](#1-prerequisites) +2. [Installation](#2-installation) +3. [Transitioning your covenant key from phase-1 setup](#3-transitioning-your-covenant-key-from-phase-1-setup) +4. [Operation](#4-operation) + 1. [Configuration](#41-configuration) + 2. [Starting the daemon](#42-starting-the-daemon) + 3. [Unlocking the key](#43-unlocking-the-key) + +## 1. Prerequisites + +This guide requires that: + +1. You have a Bitcoin node setup for the Bitcoin + network you intend to operate your covenant signer on. +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/main/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). + + + +## 2. Installation + +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 +cd covenant-emulator +git checkout +``` + +> ⚡ Note: Replace the checkout tag with the version you want to install. + +Enter the covenant-signer directory, and run the following +command to build the `covenant-signer` binary +and install it to your `$GOPATH/bin` directory: + +```shell +cd covenant-signer +make install +``` + +This command will: +- Build and compile all Go packages +- Install `covenant-signer` binary to `$GOPATH/bin` +- Make it globally accessible from your terminal + +If your shell cannot find the installed binary, make sure `$GOPATH/bin` is in +the `$PATH` of your shell. Use the following command to add it to your profile +depending on your shell. + +```shell +export PATH=$HOME/go/bin:$PATH +echo 'export PATH=$HOME/go/bin:$PATH' >> ~/.profile +``` + +## 3. Transitioning your covenant key from phase-1 setup + +After installing the necessary binaries, we are ready +to transition our covenant private key from the `bitcoind` wallet +into a Cosmos keyring. This is necessary as the `bitcoind` wallet +does not have support for important covenant signer operations, +such as the generation of adaptor signatures. + +To complete this process, you are going to need to have access +to the machine that holds your `bitcoind` wallet and +know the Bitcoin address associated with your covenant's public key. +If you need a refresher on the functionalities supported by your +`bitcoind` wallet or how you previously set it up, you can refer +to the relevant +[phase-1 guide](https://github.com/babylonlabs-io/covenant-signer/blob/main/docs/deployment.md#2-bitcoind-setup). + +In the following, we'll go through all the necessary steps +to transition your wallet. + +#### Step 1: Load wallet + +We start off by loading the wallet holding the covenant keys, +using the `loadwallet` command. It receives as an argument +the wallet directory or `.dat` file. In the below example, +we are loading the wallet named `covenant-wallet`. + +```shell +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. As mentioned above, +you will need access to the Bitcoin key you set up your covenant with. + +```shell +bitcoin-cli -datadir=./1/ getaddressinfo
| \ +jq '.hdkeypath | sub("^m/"; "") | sub("/[^/]+$"; "")' +``` + +In the above command, we use the `jq` utility to extract only the relevant +`hdkeypath` information, which in this example is `84h/1h/0h/0/0` +(the initial `m/` can be ignored). + +Make note of the `hdkeypath` information - you'll need it later when +deriving the covenant private key from the master key for verification purposes. + +#### Step 3: Retrieve the master private key + +In this step, +we are going to retrieve the **base58-encoded master private key** from the +Bitcoin wallet. This key will be used to derive the covenant private key, +which can then be imported directly into the Cosmos keyring. + +The command below will list all descriptors in the wallet with private keys. +This will provide you with the descriptor needed to derive the private key. + +Since Bitcoin wallets typically contain multiple descriptors +(usually 6 by default), we use `jq` to find the specific descriptor that +matches our previously saved `hdkeypath` in this example `(84h/1h/0h/0)` +and extract the master private key from it. + +So, before you run this command you will need to replace the `` below +with the one you retrieved in step 2. + +```shell +bitcoin-cli listdescriptors true | jq -r ' + .descriptors[] | + select(.desc | contains("")) | + .desc +' +The output will be: + +```shell +wpkh(tprv8ZgxMBicQKsPe9aCeUQgMEMy2YMZ6PHnn2iCuG12y5E8oYhYNEvUqUkNy6sJ7ViBmFUMicikHSK2LBUNPx5do5EDJBjG7puwd6azci2wEdq/84h/1h/0h/0/*)#sachkrde +} +``` + +As you can see above there is a concatenated string of your private key and +part of your `hdkeypath`. To extract the private key: + +1. Remove everything outside the parentheses `wpkh(` and `)` +2. Remove the `hdkeypath` after the private key +(everything after and including `/`) + +You'll be left with just the **base58-encoded master private key**, similar to +below: + +``` +tprv8ZgxMBicQKsPe9aCeUQgMEMy2YMZ6PHnn2iCuG12y5E8oYhYNEvUqUkNy6sJ7ViBmFUMicikHSK2LBUNPx5do5EDJBjG7puwd6azci2wEdq +``` +Now you have your **base58-encoded master private key**. +You can now pass the above information to the `covenant-signer` binary to +derive the covenant private key from the master key using **BIP32 derivation**. + +Use the following command to derive the covenant private key: + +```shell +covenant-signer derive-child-key \ + tprv8ZgxMBicQKsPe9aCeUQgMEMy2YMZ6PHnn2iCuG12y5E8oYhYNEvUqUkNy6sJ7ViBmFUMicikHSK2LBUNPx5do5EDJBjG7puwd6azci2wEdq \ + 84h/1h/0h/0/0 +``` + +The output will be: + +```shell +derived_private_key: fe1c56c494c730f13739c0655bf06e615409870200047fc65cdf781837cf7f06 +derived_public_key: 023a79b546c79d7f7c5ff20620d914b5cf7250631d12f6e26427ed9d3f98c5ccb1 +``` + +Parameters: +- ``: The base58-encoded master private key from your +Bitcoin wallet (first parameter) +- ``: The HD derivation path that specifies how to derive +the child key (second parameter) + +To verify, you can execute the following: + +```shell +bitcoin-cli getaddressinfo
| jq .publickey +``` + +If the public key matches the `derived_public_key`s output from the +`derive-child-key` command, the verification is successful. + +#### Step 4: Import the private key into a Cosmos Keyring + +Next, we are going to import the derived private key into the Cosmos keyring. + +```shell +covenant-signer keys import-hex cov fe1c56c494c730f13739c0655bf06e615409870200047fc65cdf781837cf7f06 \ + --keyring-backend file \ + --keyring-dir /path/to/your/keyring/directory +``` + +This command: +- Uses `import-hex` to import the raw private key +- Names the key `cov` in the keyring +- Uses the secure `file` backend which encrypts the key on disk +- Will prompt you for a passphrase to encrypt the key + +Note that the passphrase you set here will be needed later on +to unlock the keyring. + +> **⚡ Note:** While both `os` and `file` backends are supported, the authors +> of the docs have more thoroughly tested the `file` backend across +> different environments. +> The `file` backend stores the private key in encrypted form +> on disk. When running `import-hex` with the `file` backend, you will be +> prompted for a passphrase. This passphrase will be required to unlock the +> signer later. + +To confirm that the import was successful, run: + +```shell +covenant-signer keys show cov +``` + +The output will display the details of the imported key: + +```shell + - address: bbn1azasawj3ard0ffwj04zpxlw2pt9cp7kwjcdqmc + name: cov + pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"Ajp5tUbHnX98X/IGINkUtc9yUGMdEvbiZCftnT+Yxcyx"}' + type: local +``` + +Congratulations! You have successfully imported your key. + +## 4. Operation +### 4.1. Configuration + +Next, we can return to the covenant signer directory +and create your own configuration file. Use the +following command to dump the configuration template: + +```shell +covenant-signer dump-cfg --config +``` + +This will create a configuration file, from the example configuration, +in the specified path. + +Replace the placeholder values with your own +configuration. This configuration can be placed directly in the +`covenant-signer` directory. + +```toml +[keystore] +# Type of keystore to use for managing private keys. Currently only +# "cosmos" is supported, which uses the Cosmos SDK keyring system for +# secure key storage. +keystore-type = "cosmos" + +[keystore.cosmos] +# pointing to the directory where the key is stored, unless specified otherwise +key-directory = "/path/to/keydir" + +# the backend to be used for storing the key, in this case `file` +keyring-backend = "file" + +# the key name you specified when importing your covenant key +key-name = "your-key-name" + +# the chain id of the chain the covenant will connect to +chain-id = "network-chain-id" + +[server-config] +# The IP address where the covenant-signer server will listen +host = "127.0.0.1" +# The TCP port number where the covenant-signer server will listen +port = 9791 + +[metrics] +# The IP address where the Prometheus metrics server will listen +host = "127.0.0.1" +# The TCP port number where the Prometheus metrics server will listen +port = 2113 +``` + +Below are brief explanations of the configuration entries: + +- `keystore-type`: Type of keystore used. Should be set to `"cosmos"` +- `key-directory`: Path where keys are stored. Do not include the keyring + backend type in the path (e.g., use `/path/to/keys` not + `/path/to/keys/keyring-file`). +- `keyring-backend`: Backend system for key management, e.g., "file", "os". +- `key-name`: Name of the key used for signing transactions. +- `chain-id`: The Chain ID of the Babylon network you connect to. +- `host` (server-config): IP address where the server listens, typically "127.0.0.1" for local access. +- `port` (server-config): TCP port number for the server. +- `host` (metrics): IP address for the Prometheus metrics server, typically "127.0.0.1". +- `port` (metrics): TCP port number for the Prometheus metrics server. + +### 4.2. Starting the daemon + +We will then run the following command to start the daemon: + +```shell +covenant-signer start --config ./path/to/config.toml +``` + +The covenant signer must be run in a secure network and only accessible by the +covenant emulator. + +Once the covenant signer is set up and unlocked, you can configure the covenant +emulator to use it. The URL of the covenant signer is configurable (`remotesigner` section) +but in this example we use the default value of +`http://127.0.0.1:9791`. + +### 4.3. Unlocking the key + +Before you can sign transactions with the covenant key, you must unlock the +keyring that stores it. This happens through a `POST` request +on the `v1/unlock` endpoint with a payload containing +the covenant keyring passphrase. + +```shell +curl -X POST http://127.0.0.1:9791/v1/unlock -d '{"passphrase": ""}' +``` + +> ⚡ Note: Even if you provide the passphrase in the curl command to unlock the +> keyring, the CLI configuration for starting the service will still prompt you +> to enter the passphrase interactively. + +You can sign transactions by invoking the `v1/sign-transactions` endpoint, +which expects staking and unbonding transactions in hex format. + +```shell +curl -X POST http://127.0.0.1:9791/v1/sign-transactions \ + -d '{ + "staking_tx_hex": "020000000001", + "slashing_tx_hex": "020000000001...", + "unbonding_tx_hex": "020000000001...", + "slash_unbonding_tx_hex": "020000000001...", + "staking_output_idx": 0, + "slashing_script_hex": "76a914...", + "unbonding_script_hex": "76a914...", + "unbonding_slashing_script_hex": "76a914...", + "fp_enc_keys": [ + "0123456789abcdef..." + ] + }' +``` + + + +The above command will generate a signature for the provided +transactions and return it in JSON format. + +```json +{ + "staking_tx_signature": "", + "unbonding_tx_signature": "" +} +``` + +These signatures can then be used to verify that the transactions were signed by +the covenant key. + +Congratulations! You have successfully set up the covenant signer and are now able +to sign transactions with the covenant key. diff --git a/static/covenant.png b/static/covenant.png new file mode 100644 index 0000000..588cdfd Binary files /dev/null and b/static/covenant.png differ