Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: transfer set up from a covenant signer to a covenant emulator #50

Merged
merged 42 commits into from
Dec 17, 2024
Merged
Show file tree
Hide file tree
Changes from 14 commits
Commits
Show all changes
42 commits
Select commit Hold shift + click to select a range
ecf7bf1
Create transfer-setup.md
samricotta Nov 29, 2024
37764a4
Update transfer-setup.md
samricotta Nov 29, 2024
44b4c1e
Update transfer-setup.md
samricotta Nov 29, 2024
6ac5008
Update transfer-setup.md
samricotta Nov 29, 2024
b9f29a5
Update transfer-setup.md
samricotta Nov 29, 2024
fa4f3df
Update transfer-setup.md
samricotta Nov 29, 2024
8d9c94b
Update docs with new flow
samricotta Dec 2, 2024
df33891
Update README.md
samricotta Dec 2, 2024
c17fc3a
Update README.md
samricotta Dec 2, 2024
e0fd704
Update README.md
samricotta Dec 2, 2024
6133297
Update README.md
samricotta Dec 2, 2024
91f44a2
Update README.md
samricotta Dec 2, 2024
934babb
Update README.md
samricotta Dec 2, 2024
30d7c56
updates
samricotta Dec 2, 2024
da0bae2
part 2 updates review
samricotta Dec 3, 2024
9c303ec
Update transition-guide.md
samricotta Dec 3, 2024
024b11b
Update transition-guide.md
samricotta Dec 3, 2024
bb527e4
update toc
samricotta Dec 3, 2024
5e2d29f
last updates for emulator and signer
samricotta Dec 3, 2024
137bc87
add a bit
vitsalis Dec 3, 2024
00b34a2
update docs for signer and emulator
samricotta Dec 4, 2024
79eb0a5
Update transition-from-phase1.md
samricotta Dec 4, 2024
8e22d54
Update transition-from-phase1.md
samricotta Dec 6, 2024
2489ba6
review
samricotta Dec 9, 2024
9b5aa4e
comments
samricotta Dec 11, 2024
2db34ca
chore: add show key command that prints the pub key (#49)
RafilxTenfen Nov 29, 2024
6dd0c8c
feat: Add docker workflows for covenant_signer (#51)
maiquanghiep Dec 3, 2024
cce0e5d
Add cosmos tag for CosmosKeyStoreConfig (#52)
maiquanghiep Dec 3, 2024
7f4c9fe
chore: bump workflows version (#56)
maiquanghiep Dec 5, 2024
17b8e01
chore: bump babylon to v0.18.0 and update min unbonding time blocks (…
RafilxTenfen Dec 5, 2024
3a9ca04
chore: add release to changelog (#58) (#59) (#64)
RafilxTenfen Dec 9, 2024
0627fc2
feat: add babylon address to keys output (#63)
RafilxTenfen Dec 9, 2024
928a690
Update covenant-emulator-setup.md
samricotta Dec 11, 2024
39dc75f
Update covenant-emulator-setup.md
samricotta Dec 11, 2024
227bb8c
Merge branch 'main' of github.com:babylonlabs-io/covenant-emulator in…
RafilxTenfen Dec 11, 2024
3af1b93
Delete emulator-installation.md
samricotta Dec 11, 2024
6a5cfd2
comments
samricotta Dec 12, 2024
667dc80
Update transition-from-phase1.md
samricotta Dec 12, 2024
8bdbee4
restructuring
vitsalis Dec 16, 2024
4c1ed11
wip
samricotta Dec 16, 2024
9068a22
Merge branch 'main' into sam/docs-import
samricotta Dec 17, 2024
c0e65a9
small changes
samricotta Dec 17, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
225 changes: 48 additions & 177 deletions README.md
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.

samricotta marked this conversation as resolved.
Show resolved Hide resolved
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.
samricotta marked this conversation as resolved.
Show resolved Hide resolved
2. A Covenant Signer instance, which securely manages the private key and
samricotta marked this conversation as resolved.
Show resolved Hide resolved
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
samricotta marked this conversation as resolved.
Show resolved Hide resolved
(`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).
samricotta marked this conversation as resolved.
Show resolved Hide resolved

### 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.
samricotta marked this conversation as resolved.
Show resolved Hide resolved

#### Download the code
Previously, private keys were stored in the Bitcoin wallet using PSBT (Partially
samricotta marked this conversation as resolved.
Show resolved Hide resolved
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.
samricotta marked this conversation as resolved.
Show resolved Hide resolved

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.
samricotta marked this conversation as resolved.
Show resolved Hide resolved

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.
samricotta marked this conversation as resolved.
Show resolved Hide resolved
Loading