Skip to content

Commit

Permalink
docs: transfer set up from a covenant signer to a covenant emulator (#50
Browse files Browse the repository at this point in the history 
)

* Create transfer-setup.md

* Update transfer-setup.md

* Update transfer-setup.md

* Update transfer-setup.md

* Update transfer-setup.md

* Update transfer-setup.md

* Update docs with new flow

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* updates

* part 2 updates review

* Update transition-guide.md

* Update transition-guide.md

* update toc

* last updates for emulator and signer

* add a bit

* update docs for signer and emulator

* Update transition-from-phase1.md

* Update transition-from-phase1.md

* review

* comments

* chore: add show key command that prints the pub key (#49)

* chore: add show key command that prints the pub key

* chore: address pr comments

* chore: add #49 to changelog

* feat: Add docker workflows for covenant_signer (#51)

* Add cosmos tag for CosmosKeyStoreConfig (#52)

* chore: bump workflows version (#56)

* chore: bump babylon to v0.18.0 and update min unbonding time blocks (#57)

* chore: bump babylon to v0.18.0 and update min unbonding time blocks to just unbonding time blocks, affected one check from '<' to '!='

* chore: add #57 to changelog

* chore: bump bbn v018 in covenant-signer

* fix: flag --min-unbonding-time

* chore: move to UnbondingTimeBlocks higher than ComfirmationTimeBlocks

* chore: add release to changelog (#58) (#59) (#64)

* feat: add babylon address to keys output  (#63)

* feat: add babylon address to keys output and moved public-key to public-key-hex

* fix: Casing on covenant-signer Dockerfile (#65)

* chore: add #63 to changelog

---------

Co-authored-by: Vitalis Salis <[email protected]>

* Update covenant-emulator-setup.md

* Update covenant-emulator-setup.md

* Delete emulator-installation.md

* comments

* Update transition-from-phase1.md

* restructuring

* wip

* small changes

---------

Co-authored-by: Vitalis Salis <[email protected]>
Co-authored-by: RafilxTenfen <[email protected]>
Co-authored-by: maiquanghiep <[email protected]>
  • Loading branch information
@samricotta @vitsalis
@RafilxTenfen @maiquanghiep
4 people authored Dec 17, 2024
1 parent 6919f4a commit 8017988
Show file tree
Hide file tree
Showing 4 changed files with 669 additions and 209 deletions.
275 changes: 66 additions & 209 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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 [email protected]: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 <release-tag>
```

### 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/<username>/Library/Application Support/Covd`
- **Linux** `~/.Covd`
- **Windows** `C:\Users\<username>\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 = <covenant-emulator-key-name>

# 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)
Loading

0 comments on commit 8017988

Please sign in to comment.