Skip to content

Commit

Permalink
split up the flow
Browse files Browse the repository at this point in the history
  • Loading branch information
@bengtlofgren
bengtlofgren committed Dec 4, 2023
1 parent 4ae21e9 commit ac0d192
Show file tree
Hide file tree
Showing 3 changed files with 235 additions and 185 deletions.
187 changes: 2 additions & 185 deletions packages/docs/pages/operators/networks/genesis-flow.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,198 +1,15 @@
import { Callout } from 'nextra-theme-docs'

# Setting up a decentarlised Namada network

Setting up a decentralised Namada network requires coordination between two distinct parties:

1. [The network coordinator](#the-network-coordinator)
2. [The pre-genesis network participants](#pre-genesis-network-participants)
1. [The network coordinator](./genesis-flow/coordinator.mdx#the-network-coordinator)
2. [The pre-genesis network participants](./genesis-flow/participants.mdx#pre-genesis-network-participants)

This process is also called the **genesis ceremony**.

## The network coordinator

The network coordinator is responsible for:
0. Setup
1. Collecting pre-genesis public keys
2. Allocating pre-genesis NAM balances
3. Collecting pre-genesis transactions
4. Generating the genesis block

### Setup

The genesis ceremony preperation includes creating a coordinated location for the pre-genesis network participants to submit their public keys. The network coordinator is responsible for setting up this location. Conventionally, the network coordinator will host a github repository that allows the pre-genesis network participants to submit their public keys. The network coordinator must ensure that the github repository is publicly accessible and that the pre-genesis network participants are able to submit their public keys in a secure manner.

Further, the network coordinator is responsible for making clear timelines for the various steps in the genesis ceremony. The network coordinator must ensure that the pre-genesis network participants are aware of the timelines and that they are able to submit their public keys, transactions, and be online in due time.

### Collecting pre-genesis public keys

The ceremony begins by the network coordinator collecting the public keys of the pre-genesis network participants. The network coordinator must ensure that the total number of pre-genesis public keys collected is equal to the total number of pre-genesis network participants.

Conventionally, the network coordinator hosts a github repository that allows the pre-genesis network participants to submit their public keys. The network coordinator must ensure that the github repository is publicly accessible and that the pre-genesis network participants are able to submit their public keys in a secure manner.

### Allocating pre-genesis NAM balances

Once the participants have [submitted their keys and addresses](#submitting-keys-and-addresses) the network coordinator must allocate balances to these addresses/public keys. The coordinaotor must also ensure that the total pre-genesis NAM balances allocated to the pre-genesis network participants is equal to the total NAM supply.

After this is completed, the network coordinator will publish the `balances.toml` file that contains the pre-genesis NAM balances allocated to the pre-genesis network participants. The `balances.toml` file should be published in the same location as the pre-genesis public keys were submitted.

## Pre-genesis network participants


### Generating keys

Before the genesis ceremony begins, the pre-genesis network participants must generate their public and private keys. The pre-genesis network participants must ensure that their private keys are kept secret and that their public keys are submitted to the network coordinator in due time.

This can be done through the namada cli:

```bash
ALIAS="<your-key-alias>"
namadac gen key --alias $ALIAS --pre-genesis
```

After the user has entered their passwords and written down their mnemonic phrase, the namada cli will save the keys to the `pre-genesis` folder inside the [base directory](../ledger/base-directory.mdx).

In order to print the keys, the user can run the following command:

```bash
# Not recommended in production since it will print the private key to the terminal (which can be recovered)
cat $BASE_DIR/pre-genesis/wallet.toml
```

It is the public keys that the pre-genesis network participants must submit to the network coordinator.

```toml
# Example wallet.toml
[public_keys]
bengt = "ED25519_PK_PREFIXtpknam1qq2vscpcvhdwht9tldj9ntxnknandhnerhzd6d42xqzukw2kpcfpudh3dl2"

...

[addresses]
bengt = "tnam1qq97eqvv4lam8ds00j9em2s2f0r8e7r60qw9fdfq"
```

It is then the right hand side of each of these fields that is submitted to the network coordinator, i.e `ED25519_PK_PREFIXtpknam1qq2vscpcvhdwht9tldj9ntxnknandhnerhzd6d42xqzukw2kpcfpudh3dl2` and `tnam1qq97eqvv4lam8ds00j9em2s2f0r8e7r60qw9fdfq` in the example above.

The network coordinator should specify the schema in which the pre-genesis network participants should submit their public keys and addresses. A toml file with the following schema is recommended:

```toml
[<pre-genesis-participant-alias>]
"public-key" = "ED25519_PK_PREFIXtpknam1qpjs6jrjuu5cj508ys7ezee4r40v8as6vz4j3ddc9qm68nfhf5n7clp4xse"
"address" = "tnam1qq5skuga54tfs7422hzz8sqvk3s6lhe2dg32jjhd"
```

### Submitting keys and addresses

After the network coordinator has published the location (conventionally a github repository) for the pre-genesis network participants to submit their public keys, the participants are expected to submit their generated public keys (and their corresponding addresses) to the network coordinator in due time. The deadline will be set by the network coordinator.

### Generating transactions

This can only occur AFTER the network coordinator has published the `balances.toml` that allocates pre-genesis NAM balances to the pre-genesis network participants.

#### Generate an established account

In order to generate a pre-genesis validator account, the pre-genesis network participants must first generate an established account. This can be done through the namada cli:

<Callout>
The `$ALIAS` variable is the alias of the pre-genesis keys that were generated in the [Generating keys](#generating-keys) step.
</Callout>

```bash
#Ensure $BASE_DIR is set to the base directory
TX_FILE_PATH="$BASE_DIR/pre-genesis/transactions.toml"
namadac utils init-genesis-established-account --path $TX_FILE_PATH --alias $ALIAS

# You can change the `--path` argument to any file path, but the recommended is `$BASE_DIR/pre-genesis/transactions.toml`
```

The command will ouptut the generated address of the established account.

```text
Derived established account address: tnam1q8lsztqqhpjxdwzw88mqqc2mun7dvpxvas3v2dxk
```

It is useful to save this address for later use.

```bash
ESTABLISHED_ACCOUNT_ADDRESS=tnam1q8lsztqqhpjxdwzw88mqqc2mun7dvpx
```

This will generate a `transactions.toml` file that contains the pre-genesis transaction that will establish the account. The `transactions.toml` file should look something like this:

```toml
[[established_account]]
vp = "vp_user"
threshold = 1
public_keys = ["tpknam1qr872zwdvw4u4nkpl0ykmvhyvxw7j0u6g7ymz03d7he0jr3szkuwczddjp2"]
```

#### Generate a pre-genesis multisignature account

In order to generate a pre-genesis multisignature account, simply add multiple `--alias` flags to the command:

```bash
# Ensure $BASE_DIR is set to the base directory
# Assuming that the values of $ALIAS1, $ALIAS2, and $ALIAS3 are the aliases of the pre-genesis keys that were generated in the [Generating keys](#generating-keys) step.
TX_FILE_PATH="$BASE_DIR/pre-genesis/transactions.toml"
namadac utils init-genesis-established-account --path $TX_FILE_PATH --alias $ALIAS1 --alias $ALIAS2 --alias $ALIAS3
```

The command will ouptut the generated address of the multisignature account.


```text
Derived established account address: tnam1q8qvns6ndpff03wmszkhgepk2r8f9ws68ugktfml
```

The corresponding `transactions.toml` file should look something like this:

```toml
[[established_account]]
vp = "vp_user"
threshold = 1
public_keys = ["tpknam1qr872zwdvw4u4nkpl0ykmvhyvxw7j0u6g7ymz03d7he0jr3szkuwczddjp2", "tpknam1qpz5n0u49s6s5jx4nyycyw0w288yfq96p3lvwxkedxyw77y0vd53sqmryce"]
```

#### Generate a pre-genesis validator account

Once the pre-genesis network participants have generated respective pre-genesis established accounts, they can generate their pre-genesis validator accounts. This can be done through the namada cli:

```bash
# Ensure $BASE_DIR is set to the base directory
# Ensure $ESTABLISHED_ACCOUNT_ADDRESS is set
# Ensure $TX_FILE_PATH is set

EMAIL="<your-email>"
SELF_BOND_AMOUNT=1000000 # Set this to the amount of NAM you want to self-bond
namadac utils init-genesis-validator \
--address $ESTABLISHED_ACCOUNT_ADDRESS \
--alias "my-validator" \
--net-address "127.0.0.1:26656" \
--commission-rate 0.05 \
--max-commission-rate-change 0.01 \
--self-bond-amount $SELF_BOND_AMOUNT \
--email $EMAIL \
--path $TX_FILE_PATH
```

<Callout>
The SELF_BOND_AMOUNT must be less than or equal to the amount of NAM allocated to the pre-genesis keys in the `balances.toml` that was published by the network coordinator.
</Callout>

The above command will append the necessary transactions to the `transactions.toml` file. The `transactions.toml` file should look something like this:

Successful execution will output the new validator address:

```text
Validator account address: tnam1q8lsztqqhpjxdwzw88mqqc2mun7dvpxvas3v2dxk
```

### Submitting transactions

Once all pre-genesis transactions have been generated, the pre-genesis network participants must submit their transactions to the network coordinator in due time. The deadline will be set by the network coordinator. This will involve simply submitting the `transactions.toml` file to the network coordinator at the agreed upon location.

By convention, a directory for each pre-genesis network participant is created in the github repository. The `transactions.toml` file is then submitted to the respective directory.



47 changes: 47 additions & 0 deletions packages/docs/pages/operators/networks/genesis-flow/coordinator.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
import { Steps } from 'nextra-theme-docs'

## The network coordinator

The network coordinator is responsible for:

0. [Setup](#setup)
1. [Collecting pre-genesis public keys](#collecting-pre-genesis-public-keys)
2. [Allocating pre-genesis NAM balances](#allocating-pre-genesis-nam-balances)
3. [Collecting pre-genesis transactions](#collecting-pre-genesis-transactions)
4. [Generating the genesis block](#generating-the-genesis-block)

<Steps>

### Setup

The genesis ceremony preperation includes creating a coordinated location for the pre-genesis network participants to submit their public keys. The network coordinator is responsible for setting up this location. Conventionally, the network coordinator will host a github repository that allows the pre-genesis network participants to submit their public keys. The network coordinator must ensure that the github repository is publicly accessible and that the pre-genesis network participants are able to submit their public keys in a secure manner.

Further, the network coordinator is responsible for making clear timelines for the various steps in the genesis ceremony. The network coordinator must ensure that the pre-genesis network participants are aware of the timelines and that they are able to submit their public keys, transactions, and be online in due time.

### Collecting pre-genesis public keys

The ceremony begins by the network coordinator collecting the public keys of the pre-genesis network participants. The network coordinator must ensure that the total number of pre-genesis public keys collected is equal to the total number of pre-genesis network participants.

Conventionally, the network coordinator hosts a github repository that allows the pre-genesis network participants to submit their public keys. The network coordinator must ensure that the github repository is publicly accessible and that the pre-genesis network participants are able to submit their public keys in a secure manner.

### Allocating pre-genesis NAM balances

Once the participants have [submitted their keys and addresses](./participants.mdx#submitting-keys-and-addresses) the network coordinator must allocate balances to these addresses/public keys. The coordinaotor must also ensure that the total pre-genesis NAM balances allocated to the pre-genesis network participants is equal to the total NAM supply.

After this is completed, the network coordinator will publish the `balances.toml` file that contains the pre-genesis NAM balances allocated to the pre-genesis network participants. The `balances.toml` file should be published in the same location as the pre-genesis public keys were submitted.


### Collecting pre-genesis transactions

Once the participants have [submitted their keys and addresses](./participants.mdx#submitting-keys-and-addresses) the network coordinator must collect the pre-genesis transactions from the pre-genesis network participants. The network coordinator must ensure that the total number of pre-genesis transaction files collected is equal to the total number of pre-genesis network participants.

The network coordinator then aggregates these transaction files into one file and saves it as the `transactions.toml` file to be used in the generation of the genesis block.

The `transactions.toml` file is validated by the network coordinator to ensure that each transaction has been correctly signed by each pre-genesis network participant. The network coordinator must ensure that the `transactions.toml` file is valid before proceeding to the next step.

### Generating the genesis block

Once the network coordinator has collected the pre-genesis public keys, allocated pre-genesis NAM balances, and collected pre-genesis transactions, the network coordinator is ready to generate the genesis block.


</Steps>
Loading

0 comments on commit ac0d192

Please sign in to comment.