diff --git a/README.md b/README.md index fbb2065..1109912 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ 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 -validators. It achieves this by representing itself as an M-out-of-N +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 @@ -63,59 +63,35 @@ 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. The `covenant-signer` daemon, which securely manages the private key and -performs signing operations in an isolated environment. +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. - -## Covenant Emulator Daemon - -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/dev/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. - -For instructions on how to run the Covenant Emulator, please refer to the -[Covenant Emulator](./docs/configure-emulator.md). - -## 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. - -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. - -For instructions on how to run the Covenant Signer, please refer to the -[Covenant Signer](./covenant-signer/README.md). - ## Interaction Between Emulator and Signer The Covenant Emulator handles the application logic, including monitoring the diff --git a/covenant-signer/README.md b/covenant-signer/README.md deleted file mode 100644 index 20cd3fa..0000000 --- a/covenant-signer/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# Covenant Signer - -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 compared to the -Covenant Emulator daemon. - -If you participated in phase-1 as a covenant signer, read this -[document](docs/transition-from-phase1.md) in order to set up -your phase-2 covenant signer. \ No newline at end of file diff --git a/docs/covenant-emulator-setup.md b/docs/covenant-emulator-setup.md index 5fcd9b0..c25b39e 100644 --- a/docs/covenant-emulator-setup.md +++ b/docs/covenant-emulator-setup.md @@ -1,43 +1,30 @@ # Covenant Emulator Setup -## Table of Contents - -1. [Purpose of this guide](#1-purpose-of-this-guide) -2. [Prerequesites](#2-prerequisites) -3. [Install Covenant Emulator Binary](#3-install-covenant-emulator-binary) -4. [Setting up the Covenant Emulator Program](#4-setting-up-the-covenant-emulator-program) - 1. [Initialize directories](#41-initialize-directories) - 2. [Configure the covenant emulator](#42-configure-the-covenant-emulator) -5. [Generate key pairs](#5-generate-key-pairs) -6. [Start the emulator daemon](#6-start-the-emulator-daemon) - -## 1. Purpose of this guide +This document outlines the setup of the covenant-emulator +daemon program. -This guide outlines the transition from solely using the phase-1 covenant signer -to the phase-2 covenant emulator full setup. - -The [phase-1 covenant signer](https://github.com/babylonlabs-io/covenant-signer), -was limited to signing unbonding signatures. Phase-2 requires additional -functionality that is covered by the -[covenant emulator](https://github.com/babylonlabs-io/covenant-emulator), which -retrieves delegations from Babylon chain and signs them by communicating with the -a new [covenant signer daemon](https://github.com/babylonlabs-io/covenant-emulator/tree/main/covenant-signer), specifically focused on phase-2 functionality. +## Table of Contents -In this guide, we will cover exporting the key from the Bitcoin node and importing -it into the new integrated keyring in the covenant signer. +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) -## 2. Prerequisites +## 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/README.md) to + [covenant signer setup guide](./covenant-signer-setup.md) to complete the setup of the covenant signer with your keys before proceeding. 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). -## 3. Install covenant emulator binary +## 2. Install covenant emulator binary If you haven't already, download [Golang 1.23](https://go.dev/dl). @@ -76,9 +63,9 @@ export PATH=$HOME/go/bin:$PATH echo 'export PATH=$HOME/go/bin:$PATH' >> ~/.profile ``` -## 4. Setting up the covenant emulator program +## 3. Setting up the covenant emulator program -### 4.1. Initialize directories +### 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 `` @@ -96,7 +83,7 @@ $ ls ├── logs # Covd logs ``` -### 4.2. Configure the covenant emulator +### 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. @@ -160,7 +147,7 @@ Below are brief explanations of the configuration entries: Ensure that the covenant signer is running and unlocked before proceeding otherwise you will be unable to run the emulator. -## 5. Generate key pairs +## 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 @@ -195,7 +182,7 @@ To check your balance, View your account on the address. -## 6. Start the emulator daemon +## 5. Start the emulator daemon You can start the covenant emulator daemon using the following command: diff --git a/covenant-signer/docs/transition-from-phase1.md b/docs/covenant-signer-setup.md similarity index 95% rename from covenant-signer/docs/transition-from-phase1.md rename to docs/covenant-signer-setup.md index 740d692..a1ea28e 100644 --- a/covenant-signer/docs/transition-from-phase1.md +++ b/docs/covenant-signer-setup.md @@ -1,4 +1,7 @@ -# Covenant Signer +# 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 @@ -15,8 +18,12 @@ logic. > are required to transition their keys to this program to participate > in phase-2. -This document is intended for covenant committee members that -are transitioning their phase-1 setup to the phase-2 one. +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