diff --git a/README.md b/README.md index bd2542c..4501826 100644 --- a/README.md +++ b/README.md @@ -57,18 +57,22 @@ 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. +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. 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. +2. A Covenant Signer instance, which securely manages the private key and +performs signing operations in an isolated environment. + +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 @@ -87,177 +91,44 @@ staking time lock expires (on-demand unbonding). signature, which has similar usage to the **slashing signature** but signs over the slashing path of the unbonding transaction. -## Installation +For instructions on how to run the Covenant Emulator, please refer to the +[Covenant Emulator](./docs/configure-emulator.md). -### Prerequisites +## Covenant Signer -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). +The Covenant Signer works alongside the Covenant Emulator. It is designed to +securely handle private keys for signing operations. The signer has been +redesigned to prioritize security through isolation - separating the private key +handling from the more exposed emulator program. -#### Download the code +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. -To get started, clone the repository to your local machine from Github: +For instructions on how to run the Covenant Signer, please refer to the +[Covenant Signer](./covenant-signer/README.md). -```bash -$ git clone git@github.com:babylonlabs-io/covenant-emulator.git -``` +## Interaction Between Emulator and Signer -You can choose a specific version from -the [official releases page](https://github.com/babylonlabs-io/covenant-emulator/releases): +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. -```bash -$ cd covenant-emulator # cd into the project directory -$ git checkout -``` +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. -### Build and install the binary +The Covenant Signer, upon receiving the request, retrieves the private key from +its keyring and performs the signing operations. The generated signatures are +returned to the emulator, which then submits them to the Babylon blockchain. -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. +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. \ No newline at end of file diff --git a/covenant-signer/README.md b/covenant-signer/README.md index b05be6b..897e83f 100644 --- a/covenant-signer/README.md +++ b/covenant-signer/README.md @@ -1,5 +1,11 @@ # Covenant Signer +This program is a separate implementation from the original +[covenant signer](https://github.com/babylonlabs-io/covenant-signer/blob/main/README.md) +and serves as part of the transition to a new architecture. It should not be +confused with the earlier version. + + ## Table of Contents 1. [Prerequisites](#1-prerequisites) @@ -13,9 +19,12 @@ ## 1. Prerequisites -To successfully complete this guide, ensure you have the bitcoin node setup and you -have access to the private Bitcoin key you used previously when you generated your -address as it contains the covenant key. +This guide requires that: + +1. you have a Bitcoin node setup for the Bitcoin +network you intend to operate your covenant signer in and +2. you have access to the the private Bitcoin key you +set up your covenant with. For a refresher on setting up the bitcoin node, refer to the [deployment guide](https://github.com/babylonlabs-io/covenant-signer/blob/main/docs/deployment.md#2-bitcoind-setup). @@ -63,7 +72,8 @@ echo 'export PATH=$HOME/go/bin:$PATH' >> ~/.profile ## 3. Export the key from the Bitcoin node At this stage, you should already have access to the Bitcoin node. -If you need a refresher on setting up `bitcoind`, refer to the [setup guide](https://github.com/babylonlabs-io/covenant-signer/blob/main/docs/deployment.md#2-bitcoind-setup). +If you need a refresher on setting up `bitcoind`, refer to the  +[setup guide](https://github.com/babylonlabs-io/covenant-signer/blob/main/docs/deployment.md#2-bitcoind-setup). Once you have node access, you can proceed with the next steps. Load wallet with your covenant key. @@ -139,22 +149,27 @@ The terminal should produce output similar to the following: } ``` - The most important field to note is the `desc` value: ```json "desc": "wpkh(tprv8ZgxMBicQKsPe9aCeUQgMEMy2YMZ6PHnn2iCuG12y5E8oYhYNEvUqUkNy6sJ7ViBmFUMicikHSK2LBUNPx5do5EDJBjG7puwd6azci2wEdq/84h/1h/0h/0/*)#sachkrde" ``` -Here, you can see the string starting with `tprv8ZgxMBicQKsPe9aCeUQgMEMy2YMZ6PHnn2iCuG12y5E8oYhYNEvUqUkNy6sJ7ViBmFUMicikHSK2LBUNPx5do5EDJBjG7puwd6azci2wEdq`is the **base58-encoded master private key** of the covenant wallet. This key is critical for signing operations and should be securely stored. +Here, you can see the string starting with `tprv8ZgxMBicQKsPe9aCeUQgMEMy2YMZ6PHnn2iCuG12y5E8oYhYNEvUqUkNy6sJ7ViBmFUMicikHSK2LBUNPx5do5EDJBjG7puwd6azci2wEdq` +is the **base58-encoded master private key** of the covenant wallet. +This key is critical for signing operations and should be securely stored. #### Deriving the Covenant Private Key from the Master Key -You can derive the covenant private key from the master key by performing a **BIP32 derivation**. The `covenant-signer`repository includes a command to accomplish this: +You can derive the covenant private key from the master key by performing a  +**BIP32 derivation**. The `covenant-signer`repository includes a command to +accomplish this: ```shell -covenant-signer derive-child-key \ tprv8ZgxMBicQKsPe9aCeUQgMEMy2YMZ6PHnn2iCuG12y5E8oYhYNEvUqUkNy6sJ7ViBmFUMicikHSK2LBUNPx5do5EDJBjG7puwd6azci2wEdq \ 84h/1h/0h/0/0 +covenant-signer derive-child-key \ + tprv8ZgxMBicQKsPe9aCeUQgMEMy2YMZ6PHnn2iCuG12y5E8oYhYNEvUqUkNy6sJ7ViBmFUMicikHSK2LBUNPx5do5EDJBjG7puwd6azci2wEdq \ + 84h/1h/0h/0/0 ``` The output will display the derived private and public keys: @@ -213,7 +228,8 @@ and verified your setup for the covenant emulator. ## 5. Create the 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 file. Then, replace the placeholder values with your own +configuration. ```toml [keystore] @@ -233,14 +249,29 @@ key-name = "your-key-name" chain-id = "your-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" +# This port is used to expose metrics that can be scraped by Prometheus port = 2113 ``` +Parameters: +- `keystore-type`: Type of keystore used, e.g., "cosmos" for Cosmos SDK compatibility. +- `key-directory`: Path where keys are stored on the filesystem. +- `keyring-backend`: Backend system for key management, e.g., "file", "os". +- `key-name`: Name of the key used for signing transactions. +- `chain-id`: Identifier of the blockchain network. +- `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. + ## 6. Running the Covenant Signer The covenant signer can be run using the following command: @@ -249,13 +280,13 @@ The covenant signer can be run using the following command: covenant-signer start --config ./path/to/config.toml ``` -the covenant signer must be run in a secure network and only accessible by the +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, which is http://127.0.0.1:9791, -should be specified in the covenant emulator's configuration file under the -remotesigner section. +emulator to use it. The URL of the covenant signer, which is +http://127.0.0.1:9791, should be specified in the covenant emulator's +configuration file under the `remotesigner` section. It's important to note that the key specified in the covenant emulator's configuration is not the covenant key itself. Instead, it is a @@ -263,24 +294,27 @@ key used for sending Cosmos transactions. ## 7. Using the covenant signer for signing transactions -To enable signing transactions with the covenant key, you need to unlock it first. +Before you can sign transactions with the covenant key, you need to unlock the +keyring that stores it. The passphrase here must match the one you used when +importing the covenant key into the keyring. Once the keyring is unlocked, you +can use the covenant key to sign transactions. ```shell curl -X POST http://127.0.0.1:9791/v1/unlock -d '{"passphrase": ""}' ``` Now that the key is unlocked you can add its url to the covenant emulator's -configuration file. See [here](./docs/transfer-setup.md#42-configure-the-covenant-emulator) +configuration file. See [here](../docs/transfer-setup.md#42-configure-the-covenant-emulator) for more information. You can sign transactions using the following command. However, ensure that both -the staking and unbonding transactions are provided in hex format: +the staking and unbonding transactions are provided in hex format. ```shell curl -X POST http://127.0.0.1:9791/v1/sign-transactions \ -d '{ - "staking_tx_hex": "", - "unbonding_tx_hex": "" + "staking_tx_hex": "", + "unbonding_tx_hex": "" }' ``` diff --git a/docs/transfer-setup.md b/docs/configure-emulator.md similarity index 98% rename from docs/transfer-setup.md rename to docs/configure-emulator.md index b7bc2d7..03d9439 100644 --- a/docs/transfer-setup.md +++ b/docs/configure-emulator.md @@ -1,4 +1,4 @@ -# Transfer your setup from a covenant signer to a covenant emulator +# Configuring the Covenant Emulator ## Table of Contents