cerc-io/laconicd-stack
13
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add separate readme for exporting testnet state and generating LPS distribution JSON #24

Merged
nabarun merged 1 commits from ng-export-testnet-readme into main 2025-06-18 09:26:02 +00:00
Conversation 0 Commits 1 Files Changed 3 +163 -101
3 changed files with 163 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@ -8,7 +8,9 @@
- To launch Laconic mainnet, follow these steps:
- **Run the First Validator Node:** Begin by setting up and running the initial validator node as detailed in [run-first-validator.md](docs/run-first-validator.md)
- **Export Testnet State and Prepare Token Distribution:** Begin by exporting SAPO testnet state and preparing requirements for mainnet chain as detailed in [export-testnet.md](docs/export-testnet.md)
- **Run the First Validator Node:** Set up and run the bootstrap validator node as detailed in [run-first-validator.md](docs/run-first-validator.md)
- **Deploy Cosmos Multisig App:** Integrate and run the Cosmos Multisig app using the playbook available at [cosmos-multisig-app playbook](./playbooks/cosmos-multisig-app/README.md)

82
docs/export-testnet.md Normal file
View File

@ -0,0 +1,82 @@
# Export Testnet
## Prerequisites
- Machine where the SAPO testnet validator node is already running
- Install `zstd` using `sudo apt install zstd`
- [laconic-so](https://github.com/cerc-io/stack-orchestrator/?tab=readme-ov-file#install)
- laconicd-stack
```bash
laconic-so fetch-stack git.vdb.to/cerc-io/laconicd-stack --git-ssh --pull
```
## Export testnet state
- Run the following steps in machine where the testnet node is already running (machine 1)
- Export the testnet deployment directory as environment variable:
```bash
export TESTNET_DEPLOYMENT_DIR=<absolute/path/to/testnet/deployment>
```
- Get your private key from testnet deployment (should be available if steps for joining SAPO testnet was followed previously):
```bash
laconic-so deployment --dir $TESTNET_DEPLOYMENT_DIR exec laconicd "laconicd keys export <key-name> --unarmored-hex --unsafe --keyring-backend test"
```
NOTE: Store this key securely as it is needed in later steps for signing bootstrap validator node gentx
- Stop the node for SAPO testnet:
```bash
laconic-so deployment --dir $TESTNET_DEPLOYMENT_DIR stop
```
- Run script to export state from testnet chain:
```bash
~/cerc/laconicd-stack/scripts/export-testnet-state.sh $TESTNET_DEPLOYMENT_DIR
```
- The compressed zst file will be generated at `$TESTNET_DEPLOYMENT_DIR/export/testnet-state.zst`
- The generated state file will be used in later steps for creating genesis.json file for mainnet
## Prepare LPS distribution JSON
- The following steps can be performed in any machine
- Fetch laconicd-stack
```bash
laconic-so fetch-stack git.vdb.to/cerc-io/laconicd-stack --git-ssh --pull
```
- Set envs:
```bash
# File path where LPS distribution JSON file will be created
export LPS_DISTRIBUTION_PATH=<absolute/path/to/distribution.json>
```
- Generate lockup distribution JSON file with LPS distribution Google spreadsheet URL or downloaded CSV file path
```bash
~/cerc/laconicd-stack/scripts/generate-lps-lock.sh -i "<lps-distribution-spreadsheet-url-or-csv-file-path>" -o $LPS_DISTRIBUTION_PATH
```
- This will generate the JSON file at `$LPS_DISTRIBUTION_PATH` which will be later required when creating genesis file
## Requirements for Mainnet Genesis
- Exported testnet state
- LPS distribution JSON
- Account address for early supports
- This account will be allocated 20% of total LPS tokens
- Private key of account which will sign gentx for the bootstrap validator node

178
docs/run-first-validator.md
View File

@ -2,9 +2,7 @@
## Prerequisites
- Machine 1: Where the SAPO testnet node is already running
- Install `zstd` using `sudo apt install zstd`
- Machine 1: Where the TMKMS service is to be setup
- Machine 2: Where the mainnet first validator node is to be setup
@ -14,9 +12,9 @@
- Install `zstd` using `sudo apt install zstd`
- LPS distribution Google spreadsheet URL or CSV file path
- [LSP distribution JSON](./export-testnet.md#prepare-lps-distribution-json)
- Machine 4: Where the TMKMS service is to be setup
- [Exported testnet state](./export-testnet.md#export-testnet-state)
- Following tools are required in all machines:
@ -40,7 +38,7 @@
ansible-playbook -i localhost, -c local ~/cerc/laconicd-stack/playbooks/validator/build-laconicd.yml
```
## Setup node
## Setup bootstrap node deployment
- Run the following steps in the machine where the mainnet node is to be setup (machine 2)
@ -89,16 +87,16 @@
NOTE: This public key is required in [next step to generate the genesis file](#generate-mainnet-genesis-file)
- Copy over the `priv_validator_key.json` located at `$DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR/data/laconicd-data/config/priv_validator_key.json` to the machine where the TMKMS service is to be setup (machine 4)
- Copy over the `priv_validator_key.json` located at `$DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR/data/laconicd-data/config/priv_validator_key.json` to the machine where the TMKMS service is to be setup (machine 1)
```bash
# Example command to transfer file from machine 2 to machine 4 (run on machine 2)
# Example command to transfer file from machine 2 to machine 1 (run on machine 2)
scp -C $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR/data/laconicd-data/config/priv_validator_key.json <user>@<machine-ip-address>:<absolute-path-to-desired-destination-directory>
```
## Setup TMKMS
## Setup TMKMS deployment
- For integrating TMKMS with laconicd, follow steps below in the machine where the TMKMS service is to be setup (machine 4)
- For integrating TMKMS with laconicd, follow steps below in the machine where the TMKMS service is to be setup (machine 1)
- Export the data directory and TMKMS deployment directory as environment variables:
@ -113,37 +111,6 @@
ansible-playbook -i localhost, -c local ~/cerc/laconicd-stack/playbooks/tmkms/setup-tmkms.yml
```
## Export testnet state
- Run the following steps in machine where the testnet node is already running (machine 1)
- Export the testnet deployment directory as environment variable:
```bash
export TESTNET_DEPLOYMENT_DIR=<absolute/path/to/testnet/deployment>
```
- Get your private key from testnet deployment:
```bash
laconic-so deployment --dir $TESTNET_DEPLOYMENT_DIR exec laconicd "laconicd keys export <key-name> --unarmored-hex --unsafe --keyring-backend test"
```
NOTE: Store this key securely as it is needed in later steps
- Stop the node for SAPO testnet:
```bash
laconic-so deployment --dir $TESTNET_DEPLOYMENT_DIR stop
```
- Run script to export state from testnet chain:
```bash
~/cerc/laconicd-stack/scripts/export-testnet-state.sh $TESTNET_DEPLOYMENT_DIR
```
- The compressed zst file will be generated at `$TESTNET_DEPLOYMENT_DIR/export/testnet-state.zst`
## Generate mainnet genesis file
@ -160,14 +127,16 @@
export EARLY_SUPPORTS_ACC_ADDR=<account-address-controlled-by-laconic-foundation>
# Parent directory where the deployment directory will live
# Parent directory where the deployment directory will be setup (required for generating genesis)
export DATA_DIRECTORY=
```
- Copy over the compressed `testnet-state.zst` file:
NOTE: Steps for creating LPS distribution JSON are in [export-testnet.md](./export-testnet.md#prepare-lps-distribution-json)
- Copy over the compressed `testnet-state.zst` file (from [export-testnet.md](./export-testnet.md#export-testnet-state)):
```bash
# Example command to transfer file from machine 1 to machine 3
# Example command to transfer testnet state file
scp -C <user>@<machine-ip-address>:<absolute-path-to-testnet-deployment>/export/testnet-state.zst <absolute-path-to-compressed-file>
```
@ -180,14 +149,6 @@
rm -rf <absolute-path-to-compressed-file>/testnet-state.zst
```
- Generate LPS lockup distribution JSON file
```bash
~/cerc/laconicd-stack/scripts/generate-lps-lock.sh -i "<lps-distribution-spreadsheet-url-or-csv-file-path>" -o $LPS_DISTRIBUTION_PATH
```
- This will generate the file at `$LPS_DISTRIBUTION_PATH`
- Copy the example variables file:
```bash
@ -196,7 +157,7 @@
- Edit `~/cerc/laconicd-stack/playbooks/first-validator/first-validator-vars.yml` with required values:
NOTE: Use the public key exported in [previous step](#setup-node)
NOTE: Use the public key exported in [previous steps](#setup-node)
```bash
# Make sure to wrap it with single quotes ('')
@ -209,13 +170,15 @@
cd $DATA_DIRECTORY
```
- Run playbook to use exported state for generating mainnet genesis file with gentx:
- Run playbook for generating mainnet genesis file with gentx:
```bash
ansible-playbook -i localhost, -c local ~/cerc/laconicd-stack/playbooks/first-validator/generate-genesis.yml -e "exported_state_path=$EXPORTED_STATE_PATH" -e "lps_distribution_path=$LPS_DISTRIBUTION_PATH" -e "early_supports_acc_address=$EARLY_SUPPORTS_ACC_ADDR"
```
- Input private key of the existing account that was exported in previous steps when prompted
- When prompted for private key, use key of the existing account that was exported in [export-testnet.md](./export-testnet.md#export-testnet-state)
- Private key should be of the account which will create the first validator bootstrap node
- Genesis file will be generated in output directory along with a file specifying the staking amount
@ -224,11 +187,14 @@
ls -l output
```
## Run node
NOTE: Staking amount will be used by the playbooks to send create validator txs
## Start Mainnet
### Start TMKMS
- Run these steps in the machine where [the TMKMS service is setup (machine 4)](#setup-tmkms)
- Run these steps in the machine where [the TMKMS service is setup (machine 1)](#setup-tmkms)
- Copy the example variables file:
@ -276,7 +242,7 @@
- Note the pubkey logged at start for comparing later with validator pubkey on chain
### Start node
### Start laconicd node
- Run the following steps in the machine where [the mainnet node is setup (machine 2)](#setup-node)
@ -355,13 +321,65 @@
laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR exec laconicd "laconicd query bank balances $EARLY_SUPPORTS_ACC_ADDR"
```
## Publish required artifacts
- Run the following steps in machine where the genesis file and staking amount files were generated (machine 3)
- Copy the genesis file to [config](./config) folder:
```bash
cp $DATA_DIRECTORY/output/genesis.json ~/cerc/laconicd-stack/config/mainnet-genesis.json
```
- Copy the staking amount file to [config](./config) folder:
```bash
cp $DATA_DIRECTORY/output/staking-amount.json ~/cerc/laconicd-stack/config/staking-amount.json
```
- Check git status of the stack repo
```bash
cd ~/cerc/laconicd-stack
git status
```
The following files should show up with changes:
- config/mainnet-genesis.json
- config/staking-amount.json
- Create a PR with the genesis file and staking amount file so that it is available to other validators
- Run the following steps in machine where the mainnet node is running (machine 2)
- Get your node's address by running the following command:
```bash
laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR exec laconicd 'echo $(laconicd cometbft show-node-id)@laconicd-mainnet.laconic.com:26656'
```
- Add your node's address to [node-addresses.yml](../node-addresses.yml)
- Update the file `~/cerc/laconicd-stack/node-addresses.yml` in machine where genesis file is generated (machine 3)
- Check git status of the stack repo
```bash
cd ~/cerc/laconicd-stack
git status
```
The `node-addresses.yml` file should show up with changes
- Submit a PR with the node address so that it is available to other validators
## Update config
- Run following steps to update the config for TMKMS and node
### TMKMS
- Run these steps in the machine where the TMKMS service is setup (machine 4)
- Run these steps in the machine where the TMKMS service is setup (machine 1)
- Stop the TMKMS deployment:
@ -401,7 +419,7 @@
### TMKMS
- Run these steps in the machine where the TMKMS service is setup (machine 4)
- Run these steps in the machine where the TMKMS service is setup (machine 1)
- Stop the TMKMS deployment:
@ -442,43 +460,3 @@
```bash
laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR start
```
## Publish required artifacts
- Run the following steps in machine where the genesis file and staking amount files are generated (machine 3)
- Copy the genesis file to [config](./config) folder:
```bash
cp $DATA_DIRECTORY/output/genesis.json ~/cerc/laconicd-stack/config/mainnet-genesis.json
```
- Copy the staking amount file to [config](./config) folder:
```bash
cp $DATA_DIRECTORY/output/staking-amount.json ~/cerc/laconicd-stack/config/staking-amount.json
```
- Get your node's address by running following command in the machine where the mainnet node is running (machine 2):
```bash
laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR exec laconicd 'echo $(laconicd cometbft show-node-id)@laconicd-mainnet.laconic.com:26656'
```
- Add your node's address to [node-addresses.yml](../node-addresses.yml)
- Update the file `~/cerc/laconicd-stack/node-addresses.yml` in machine where genesis file is generated (machine 3)
- Check git status of the stack repo
```bash
cd ~/cerc/laconicd-stack
git status
```
The following files should show up:
- node-addresses.yml
- config/mainnet-genesis.json
- config/staking-amount.json
- Submit a PR with the genesis file, staking amount file and node address so that it is available to other validators