Skip to content

Commit

Permalink
updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@samricotta
samricotta committed Dec 2, 2024
1 parent 934babb commit 30d7c56
Show file tree
Hide file tree
Showing 3 changed files with 101 additions and 196 deletions.
225 changes: 48 additions & 177 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 [email protected]: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 <release-tag>
```
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/<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.
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.
Loading

0 comments on commit 30d7c56

Please sign in to comment.