Skip to content

Commit

Permalink
chore: update QGB docs from source (#1078)
Browse files Browse the repository at this point in the history 
* chore: update QGB docs from source

* docs: update for latest change on orchestrator/relayer
  • Loading branch information
@jcstein
jcstein authored Oct 3, 2023
1 parent a3184d4 commit 00aa3c3
Show file tree
Hide file tree
Showing 3 changed files with 130 additions and 90 deletions.
44 changes: 22 additions & 22 deletions docs/nodes/qgb-keys.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,25 +13,25 @@ The QGB `keys` command allows managing EVM private keys and P2P identities. It i

The `qgb orchestrator keys` command manages keys for the orchestrator. By default, it uses the orchestrator default home directory to store the keys: `~/.orchestrator/keystore`. However, the default home can be changed either by specifying a different directory using the `--home` flag or setting the following environment variable:

| Variable | Explanation | Default value | Required |
| ------------------- | ----------------------------------- | ----------------- | -------- |
| `ORCHESTRATOR_HOME` | Home directory for the orchestrator | `~/.orchestrator` | Optional |
| Variable | Explanation | Default value | Required |
|---------------------|---------------------------------------|-------------------|----------|
| `ORCHESTRATOR_HOME` | Home directory for the orchestrator | `~/.orchestrator` | Optional |

## Relayer command

The `qgb relayer keys` command manages keys for the relayer. By default, it uses the relayer default home directory to store the keys: `~/.relayer/keystore`. However, the default home can be changed either by specifying a different directory using the `--home` flag or setting the following environment variable:

| Variable | Explanation | Default value | Required |
| -------------- | ------------------------------ | ------------- | -------- |
| `RELAYER_HOME` | Home directory for the relayer | `~/.relayer` | Optional |
| Variable | Explanation | Default value | Required |
|---------------------|---------------------------------------|-------------------|----------|
| `RELAYER_HOME` | Home directory for the relayer | `~/.relayer` | Optional |

## Deploy command

The `qgb deploy keys` command manages keys for the deployer. By default, it uses the deployer default home directory to store the keys: `~/.deployer/keystore`. However, the default home can be changed either by specifying a different directory using the `--home` flag or setting the following environment variable:

| Variable | Explanation | Default value | Required |
| --------------- | ------------------------------------- | ------------- | -------- |
| `DEPLOYER_HOME` | Home directory for the deploy command | `~/.deployer` | Optional |
| Variable | Explanation | Default value | Required |
|---------------------|---------------------------------------|-------------------|----------|
| `DEPLOYER_HOME` | Home directory for the deploy command | `~/.deployer` | Optional |

## Store initialization (!)

Expand Down Expand Up @@ -119,7 +119,7 @@ After creating a new key, you will see its corresponding address printed:
qgb orchestrator keys evm add
I[2023-04-13|14:16:11.387] successfully opened store path=/home/midnight/.orchestrator
I[2023-04-13|14:16:11.387] please provide a passphrase for your account
I[2023-04-13|14:16:11.387] please provide a passphrase for your account
I[2023-04-13|14:16:30.533] account created successfully address=0xaF319b70de80232539ad576f88739afD2dF44187
I[2023-04-13|14:16:30.534] successfully closed store path=/home/midnight/.orchestrator
```
Expand All @@ -144,12 +144,12 @@ After running the command, you will be prompted to enter the passphrase for the
Then, you will be prompted to confirm that you want to delete that private key. Make sure to verify if you're deleting the right one because once deleted, it can no longer be recovered!

```ssh
qgb orchestrator keys evm delete 0x27a1F8CE94187E4b043f4D57548EF2348Ed556c7
qgb orchestrator keys evm delete 0x27a1F8CE94187E4b043f4D57548EF2348Ed556c7
I[2023-04-13|15:01:41.308] successfully opened store path=/home/midnight/.orchestrator
I[2023-04-13|15:01:41.309] deleting account address=0x27a1F8CE94187E4b043f4D57548EF2348Ed556c7
I[2023-04-13|15:01:41.309] please provide the address passphrase
I[2023-04-13|15:01:43.268] Are you sure you want to delete your private key? This action cannot be undone and may result in permanent loss of access to your account.
I[2023-04-13|15:01:41.309] please provide the address passphrase
I[2023-04-13|15:01:43.268] Are you sure you want to delete your private key? This action cannot be undone and may result in permanent loss of access to your account.
Please enter 'yes' or 'no' to confirm your decision: yes
I[2023-04-13|15:01:45.532] private key has been deleted successfully address=0x27a1F8CE94187E4b043f4D57548EF2348Ed556c7
I[2023-04-13|15:01:45.534] successfully closed store path=/home/midnight/.orchestrator
Expand All @@ -163,8 +163,8 @@ The `list` subcommand allows listing the existing keys in the keystore:
qgb orchestrator keys evm list
I[2023-04-13|16:08:45.084] successfully opened store path=/home/midnight/.orchestrator
I[2023-04-13|16:08:45.084] listing accounts available in store
I[2023-04-13|16:08:45.084] 0x7Dd8F9CAfe6D25165249A454F2d0b72FD149Bbba
I[2023-04-13|16:08:45.084] listing accounts available in store
I[2023-04-13|16:08:45.084] 0x7Dd8F9CAfe6D25165249A454F2d0b72FD149Bbba
I[2023-04-13|16:08:45.084] successfully closed store path=/home/midnight/.orchestrator
```

Expand All @@ -190,8 +190,8 @@ qgb orchestrator evm update 0x7Dd8F9CAfe6D25165249A454F2d0b72FD149Bbba
I[2023-04-13|16:21:17.139] successfully opened store path=/home/midnight/.orchestrator
I[2023-04-13|16:21:17.140] updating account address=0x7Dd8F9CAfe6D25165249A454F2d0b72FD149Bbba
I[2023-04-13|16:21:17.140] please provide the address passphrase
I[2023-04-13|16:21:18.134] please provide the address new passphrase
I[2023-04-13|16:21:17.140] please provide the address passphrase
I[2023-04-13|16:21:18.134] please provide the address new passphrase
I[2023-04-13|16:21:22.403] successfully updated the passphrase address=0x7Dd8F9CAfe6D25165249A454F2d0b72FD149Bbba
I[2023-04-13|16:21:22.420] successfully closed store path=/home/midnight/.orchestrator
```
Expand Down Expand Up @@ -232,8 +232,8 @@ Example:
qgb orchestrator keys evm import ecdsa da6ed55cb2894ac2c9c10209c09de8e8b9d109b910338d5bf3d747a7e1fc9eb7
I[2023-04-13|17:00:48.617] successfully opened store path=/home/midnight/.orchestrator
I[2023-04-13|17:00:48.617] importing account
I[2023-04-13|17:00:48.617] please provide the address passphrase
I[2023-04-13|17:00:48.617] importing account
I[2023-04-13|17:00:48.617] please provide the address passphrase
I[2023-04-13|17:00:51.989] successfully imported file address=0x6B452Da14195b0aDc3C960E56a078Cf8f50448f8
I[2023-04-13|17:00:51.990] successfully closed store path=/home/midnight/.orchestrator
```
Expand All @@ -257,9 +257,9 @@ For example, if we have a file in the current directory containing a private key
qgb orchestrator keys evm import file UTC--2023-04-13T15-00-50.302148204Z--966e6f22781ef6a6a82bbb4db3df8e225dfd9488
I[2023-04-13|17:31:53.307] successfully opened store path=/home/midnight/.orchestrator
I[2023-04-13|17:31:53.307] importing account
I[2023-04-13|17:31:53.308] please provide the address passphrase
I[2023-04-13|17:31:54.440] please provide the address new passphrase
I[2023-04-13|17:31:53.307] importing account
I[2023-04-13|17:31:53.308] please provide the address passphrase
I[2023-04-13|17:31:54.440] please provide the address new passphrase
I[2023-04-13|17:31:58.436] successfully imported file address=0x966e6f22781EF6a6A82BBB4DB3df8E225DfD9488
I[2023-04-13|17:31:58.437] successfully closed store path=/home/midnight/.orchestrator
```
Expand Down
170 changes: 105 additions & 65 deletions docs/nodes/qgb-orchestrator.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The orchestrator connects to a separate P2P network than the consensus or the da

Bootstrapper for the Blockspace Race is:

- `/dns/bootstr-incent-1.celestia.tools/tcp/30000/p2p/12D3KooWSGZ2LXW2soQFHgU82uLfN7pNW5gMMkTnu1fhMXG43TvP`
* `/dns/bootstr-incent-1.celestia.tools/tcp/30000/p2p/12D3KooWSGZ2LXW2soQFHgU82uLfN7pNW5gMMkTnu1fhMXG43TvP`

Make sure to specify it using the `-b` flag when running the orchestrator.

Expand All @@ -38,6 +38,14 @@ I[2023-04-26|00:04:28.175] waiting for routing table to populate targetnu

## How to run

### Requirements

To run an orchestrator, you will need to have access to the following:

* *Access to your EVM address private key. This latter doesn't need to be funded in any network. If yours is not yet set, check the [register an EVM address](#register-evm-address) section.
* *A list of bootstrappers for the P2P network. These will be shared by the team for every network we plan on supporting.
* *Access to your consensus node RPC and gRPC ports.

### Install the QGB binary

Make sure to have the QGB binary installed. Check [here](https://docs.celestia.org/nodes/qgb-binary) for more details.
Expand All @@ -52,16 +60,16 @@ qgb orchestrator init

By default, the store will be created under `~/.orchestrator`. However, if you want to specify a custom location, you can use the `--home` flag. Or, you can use the following environment variable:

| Variable | Explanation | Default value | Required |
| ------------------- | ----------------------------------- | ----------------- | -------- |
| `ORCHESTRATOR_HOME` | Home directory for the orchestrator | `~/.orchestrator` | Optional |
| Variable | Explanation | Default value | Required |
|---------------------|---------------------------------------|-------------------|----------|
| `ORCHESTRATOR_HOME` | Home directory for the orchestrator | `~/.orchestrator` | Optional |

### Add keys

In order for the orchestrator to start, it will need two private keys:

- \*EVM private key
- \*P2P private key
* *EVM private key
* *P2P private key

The EVM private key is the most important one since it needs to correspond to the EVM address provided when creating the validator.

Expand All @@ -79,6 +87,8 @@ To add an EVM private key, check the next section.

Because EVM keys are important, we provide a keystore that will help manage them. The keystore uses a file system keystore protected by a passphrase to store and open private keys.

To register an EVM address for your validator, check the section [Register EVM Address](#register-evm-address).

To import your EVM private key, there is the `import` subcommand to assist you with that:

```ssh
Expand All @@ -95,14 +105,6 @@ qgb orchestrator keys evm list

For more information about the `keys` command, check the `keys` documentation in [here](https://github.com/celestiaorg/orchestrator-relayer/blob/main/docs/keys.md).

### Requirements

To run an orchestrator, you will need to have access to the following:

- \*Access to your EVM address private key. This latter doesn't need to be funded in any network.
- \*A list of bootstrappers for the P2P network. These will be shared by the team for every network we plan on supporting.
- \*Access to your consensus node RPC and gRPC ports.

### Start the orchestrator

Now that we have the store initialized, we can start the orchestrator. Make sure you have your Celestia-app node RPC and gRPC accessible, and able to connect to the P2P network bootstrappers.
Expand Down Expand Up @@ -141,9 +143,11 @@ In order for the signature propagation to be successful, you will need to expose

If not, then the signatures may not be available to the network and relayers will not be able to query them.

#### Edit validator
#### Register EVM Address

When creating a validator, a random EVM address corresponding to its operator is set in the QGB state. This latter will be used by the orchestrator to sign attestations. And since validators will generally not have access to its corresponding private key, that address needs to be edited with one whose private key is known to the validator operator.

If your validator was created using an EVM address that you don't have access to, you can always edit it using the `edit-validator` command.
To edit an EVM address for a certain validator, its corresponding account needs to send a `RegisterEVMAddress` transaction with the new address.

First, you should get your validator `valoper` address. To do so, run the following:

Expand All @@ -153,71 +157,107 @@ celestia-appd keys show <validator_account> --bech val

This assumes that you're using the default home directory, the default keystore etc. If not, make sure to add the flags that correspond to your situation.

Then, you should get your validator to verify which EVM address is attached to it:
To check which EVM address is registered for your `valoper` address, run the following:

```ssh
celestia-appd query staking validator <validator_valoper_address>
celestia-appd query qgb evm <validator_valoper_address>
```

And check the `evm_address` field if it has an address that you want to use to sign attestations. If not, let's proceed to change it.
Then, to proceed with the edit, run the following command:

Note: Please double-check the parameters of the following command before running it, as it may have persistent effects.

```ssh
celestia-appd tx staking edit-validator --evm-address=<new_evm_address> --from=<validator_account> --fees 210utia
```shell
celestia-appd tx qgb register \
<valoper_address> \
<new_evm_address> \
--fees 30000utia \
--broadcast-mode block \
--yes
```

Example command output:

```ssh
auth_info:
fee:
amount:
- amount: "210"
denom: utia
gas_limit: "210000"
granter: ""
payer: ""
signer_infos: []
tip: null
body:
extension_options: []
memo: ""
messages:
- '@type': /cosmos.staking.v1beta1.MsgEditValidator
commission_rate: null
description:
details: '[do-not-modify]'
identity: '[do-not-modify]'
moniker: '[do-not-modify]'
security_contact: '[do-not-modify]'
website: '[do-not-modify]'
evm_address: 0x27a1F8CE94187E4b043f4D57548EF2348Ed556c7
min_self_delegation: null
validator_address: celestiavaloper1vr6j8mq6aaxr5mw9sld3a75afjr4rytp42zy6h
non_critical_extension_options: []
timeout_height: "0"
signatures: []
confirm transaction before signing and broadcasting [y/N]: y
code: 0
codespace: ""
data: ""
events: []
gas_used: "0"
gas_wanted: "0"
height: "0"
data: 12300A2E2F63656C65737469612E7167622E76312E4D7367526567697374657245564D41646472657373526573706F6E7365
events:
- attributes:
- index: true
key: c3BlbmRlcg==
value: Y2VsZXN0aWExcDkzcmd6Mnl5MG5hMnN5OWc3a3NzanY2MDY2dWxqcWV3cGpwZ2c=
- index: true
key: YW1vdW50
value: MzAwMDB1dGlh
type: coin_spent
- attributes:
- index: true
key: cmVjZWl2ZXI=
value: Y2VsZXN0aWExN3hwZnZha20yYW1nOTYyeWxzNmY4NHoza2VsbDhjNWxwbmpzM3M=
- index: true
key: YW1vdW50
value: MzAwMDB1dGlh
type: coin_received
- attributes:
- index: true
key: cmVjaXBpZW50
value: Y2VsZXN0aWExN3hwZnZha20yYW1nOTYyeWxzNmY4NHoza2VsbDhjNWxwbmpzM3M=
- index: true
key: c2VuZGVy
value: Y2VsZXN0aWExcDkzcmd6Mnl5MG5hMnN5OWc3a3NzanY2MDY2dWxqcWV3cGpwZ2c=
- index: true
key: YW1vdW50
value: MzAwMDB1dGlh
type: transfer
- attributes:
- index: true
key: c2VuZGVy
value: Y2VsZXN0aWExcDkzcmd6Mnl5MG5hMnN5OWc3a3NzanY2MDY2dWxqcWV3cGpwZ2c=
type: message
- attributes:
- index: true
key: ZmVl
value: MzAwMDB1dGlh
- index: true
key: ZmVlX3BheWVy
value: Y2VsZXN0aWExcDkzcmd6Mnl5MG5hMnN5OWc3a3NzanY2MDY2dWxqcWV3cGpwZ2c=
type: tx
- attributes:
- index: true
key: YWNjX3NlcQ==
value: Y2VsZXN0aWExcDkzcmd6Mnl5MG5hMnN5OWc3a3NzanY2MDY2dWxqcWV3cGpwZ2cvMQ==
type: tx
- attributes:
- index: true
key: c2lnbmF0dXJl
value: cE5ZS0pqWEZlOFVTaEZUdDdzRHVETWZNWW55YjZTT01iZnlBSkZGYnZpVk45bGJ2L2tUeXhEWWxHK2VjRE94bFlSajJIMmlWNGJLWVhMNDBQM1F4TUE9PQ==
type: tx
- attributes:
- index: true
key: YWN0aW9u
value: L2NlbGVzdGlhLnFnYi52MS5Nc2dSZWdpc3RlckVWTUFkZHJlc3M=
type: message
gas_used: "66959"
gas_wanted: "210000"
height: "3"
info: ""
logs: []
raw_log: '[]'
logs:
- events:
- attributes:
- key: action
value: /celestia.qgb.v1.MsgRegisterEVMAddress
type: message
log: ""
msg_index: 0
raw_log: '[{"msg_index":0,"events":[{"type":"message","attributes":[{"key":"action","value":"/celestia.qgb.v1.MsgRegisterEVMAddress"}]}]}]'
timestamp: ""
tx: null
txhash: 25864170DDE40F51C0C38BCF5B22BBC015637F56AA1E2DFDA6CE51F2D5860579
txhash: 4199EA959A2CFEFCD4726D8D8F7B536458A46A27318D3483A4E9614F560606BC
```

Now, you can verify that the EVM address has been updated using the following command:

```ssh
celestia-appd query staking validator <validator_valoper_address>
celestia-appd query qgb evm <validator_valoper_address>
```

Now, you can restart the orchestrator, and it should start signing.
Expand All @@ -228,8 +268,8 @@ Note: A validator set change is triggered if more than 5% of the total staking p

If you want to start the orchestrator as a `systemd` service, you could use the following:

- \*Make sure you have the store initialized and the EVM address private key imported. Check the above sections for how to do that.
- \*Put the following configuration under: `/etc/systemd/system/orchestrator.service`:
* *Make sure you have the store initialized and the EVM address private key imported. Check the above sections for how to do that.
* *Put the following configuration under: `/etc/systemd/system/orchestrator.service`:

```text
[Unit]
Expand All @@ -253,13 +293,13 @@ TTYPath=/dev/tty0
WantedBy=multi-user.target
```

- \*Start the orchestrator service using:
* *Start the orchestrator service using:

```shell
sudo systemctl start orchestrator
```

- Follow the logs to see if everything is running correctly:
* Follow the logs to see if everything is running correctly:

```shell
sudo journalctl -f -u orchestrator
Expand Down
6 changes: 3 additions & 3 deletions docs/nodes/qgb-relayer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,9 @@ qgb relayer init

By default, the store will be created un `~/.relayer`. However, if you want to specify a custom location, you can use the `--home` flag. Or, you can use the following environment variable:

| Variable | Explanation | Default value | Required |
| -------------- | ------------------------------ | ------------- | -------- |
| `RELAYER_HOME` | Home directory for the relayer | `~/.relayer` | Optional |
| Variable | Explanation | Default value | Required |
|---------------------|---------------------------------------|-------------------|----------|
| `RELAYER_HOME` | Home directory for the relayer | `~/.relayer` | Optional |

### Add keys

Expand Down

0 comments on commit 00aa3c3

Please sign in to comment.