laconicd-stack/docs/run-first-validator.md

Run First Validator Node

Prerequisites

• Machine 1: Where the SAPO testnet node is already running

  • Install zstd using sudo apt install zstd

• Machine 2: Where the mainnet first validator node is to be setup

• Machine 3: Where the genesis file is to be generated

  • Install zstd using sudo apt install zstd

  • LPS distribution Google spreadsheet URL or CSV file path

• Following tools are required in all machines:

  • ansible

  • laconic-so

  • laconicd-stack

    laconic-so fetch-stack git.vdb.to/cerc-io/laconicd-stack --git-ssh --pull
    

Build laconicd to generate genesis file

• Run the following steps in a secure machine (machine 3) separate from the one where the node is to be setup (machine 2)

• Run playbook to build laconicd container:

  ansible-playbook -i localhost, -c local ~/cerc/laconicd-stack/playbooks/validator/build-laconicd.yml
  

Setup node

• Run the following steps in the machine where the mainnet node is to be setup (machine 2)

• Copy the example variables file if not already done:

  cp ~/cerc/laconicd-stack/playbooks/first-validator/first-validator-vars.example.yml ~/cerc/laconicd-stack/playbooks/first-validator/first-validator-vars.yml
  

• Update ~/cerc/laconicd-stack/playbooks/first-validator/first-validator-vars.yml with required values:

  # Set custom moniker for the node
  cerc_moniker: "LaconicMainnetNode"
  
  # Set desired key name
  key_name: "laconic-validator"
  

• Export the data directory and mainnet deployment directory as environment variables:

  # Parent directory where the deployment directory will live
  export DATA_DIRECTORY=
  
  # Set mainnet deployment directory
  export MAINNET_DEPLOYMENT_DIR=mainnet-laconicd-deployment
  

• Run ansible playbook to setup the node:

  ansible-playbook -i localhost, -c local ~/cerc/laconicd-stack/playbooks/first-validator/setup-first-validator.yml
  

• Get the public key of your node:

    docker run -it \
    -v $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR/data/laconicd-data:/root/.laconicd \
    cerc/laconicd:local bash -c "laconicd tendermint show-validator"
  

  NOTE: This public key is required in next step to generate the genesis file

Export testnet state

• Run the following steps in machine where the testnet node is already running (machine 1)

• Get your private key from testnet deployment:

  laconic-so deployment --dir <testnet-deployment-dir> exec laconicd "laconicd keys export <key-name> --unarmored-hex --unsafe"
  

  NOTE: Store this key securely as it is needed in later steps

• Stop the node for SAPO testnet:

  laconic-so deployment --dir <testnet-deployment-dir> stop
  

• Run script to export state from testnet chain:

  ~/cerc/laconicd-stack/scripts/export-testnet-state.sh <absolute-path-to-testnet-deployment>
  

  • The compressed zst file will be generated at <absolute-path-to-testnet-deployment>/export/testnet-state.zst

Generate mainnet genesis file

• Run the following steps in machine where the genesis file is to be generated (machine 3)

• Copy over compressed testnet-state.zst file to target machine

• Set envs:

  # Path where exported testnet state JSON file will be created
  export EXPORTED_STATE_PATH=<absolute-path-to-be-exported-testnet-state-json>
  
  # Path where LPS distribution JSON file will be created
  export LPS_DISTRIBUTION_PATH=<absolute-path-to-be-generated-distribution-json>
  
  export EARLY_SUPPORTS_ACC_ADDR=<account-address-controlled-by-laconic-foundation>
  
  # Parent directory where the deployment directory will live
  export DATA_DIRECTORY=
  

• Extract the testnet-state JSON file:

  zstd -dc <path-to-compressed-file>/testnet-state.zst > $EXPORTED_STATE_PATH
  
  # Remove zst folder
  rm -rf <path-to-compressed-file>/testnet-state.zst
  

• Generate LPS lockup distribution JSON file

  ~/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 distribution.json file at $LPS_DISTRIBUTION_PATH

• Copy the example variables file:

  cp ~/cerc/laconicd-stack/playbooks/first-validator/first-validator-vars.example.yml ~/cerc/laconicd-stack/playbooks/first-validator/first-validator-vars.yml
  

• Edit ~/cerc/laconicd-stack/playbooks/first-validator/first-validator-vars.yml with required values:

  NOTE: Use the public key exported in previous step

  # Make sure to wrap it with single quotes ('')
  validator_pub_key: '<public-key-of-your-node>'
  

• Run playbook to use exported state for generating mainnet genesis file with gentx:

  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

• Genesis file will be generated in output directory along with a file specifying the staking amount

  # List files in output directory - genesis.json and staking-amount.json
  ls -l output
  

Run node

• Run the following steps in the machine where the mainnet node is setup (machine 2)

Setup TMKMS (Optional but Recommended)

• For integrating existing TMKMS with laconicd, follow steps below in the machine where TMKMS is setup

• Set $TMKMS_HOME to the directory path containing TMKMS config files

  # Contents of tmkms config directory
  ls -l $TMKMS_HOME
  drwxrwxr-x 2 ... schema
  drwx------ 2 ... secrets
  drwxrwxr-x 2 ... state
  -rw-rw-r-- 1 ... tmkms.toml
  

• Update the TMKMS configuration file $TMKMS_HOME/tmkms.toml:

  [[chain]]
  id = "laconic-mainnet"
  key_format = { type = "cosmos-json", account_key_prefix = "laconicpub", consensus_key_prefix = "laconicvalconspub" }
  # Replace <TMKMS_HOME> with absolute path to tmkms config directory
  state_file = "<TMKMS_HOME>/state/priv_validator_state.json"
  
  [[validator]]
  chain_id = "laconic-mainnet"
  # Replace <NODE_IP> with actual IP address of the laconicd node
  addr = "tcp://<NODE_IP>:26659"
  # Replace <TMKMS_HOME> with absolute path to tmkms config directory
  secret_key = "<TMKMS_HOME>/secrets/kms-identity.key"
  protocol_version = "v0.34"
  reconnect = true
  
  [[providers.softsign]]
  key_type = "consensus"
  # Replace <TMKMS_HOME> with absolute path to tmkms config directory
  path = "<TMKMS_HOME>/secrets/priv_validator_key"
  chain_ids = ["laconic-mainnet"]
  

• Copy your validator key to TMKMS:

  • The validator key in laconicd node deployment is present at $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR/data/laconicd-data/config/priv_validator_key.json

  • Place the validator key file in TMKMS config directory at $TMKMS_HOME/secrets/

  • Import the private validator key into tmkms:

    tmkms softsign import $TMKMS_HOME/secrets/priv_validator_key.json $TMKMS_HOME/secrets/priv_validator_key
    

  • Remove the JSON key file

    rm $TMKMS_HOME/secrets/priv_validator_key.json
    

• Start TMKMS:

  tmkms start --config $TMKMS_HOME/tmkms.toml
  

  • Expected example output:

     INFO tmkms::commands::start: tmkms 0.14.0 starting up...
     INFO tmkms::keyring: [keyring:softsign] added consensus Ed25519 key: {"@type":"/cosmos.crypto.ed25519.PubKey","key":"T24No1A1FmetNRVCOSg2G2XAKWh97oBXuELdAD6DFgw="}
     INFO tmkms::connection::tcp: KMS node ID: 7f5fd8dae8953e964e7e56edd4700f597ea0d45c
    ERROR tmkms::client: [laconic-mainnet@tcp://localhost:26659] I/O error: Connection refused (os error 111)
    

    NOTE: The errors dissapear once the laconicd node starts

  • Note the pubkey logged at start for comparing later with validator pubkey on chain

• Enable TMKMS in the laconicd node configuration:

  # Set TMKMS_ENABLED to true in the node's config.env
  echo "TMKMS_ENABLED=true" >> $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR/config.env
  

• Remove the validator key from node deployment as it is no longer required:

  rm $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR/data/laconicd-data/config/priv_validator_key.json
  

  NOTE: Store it safely offline in case of an emergency

Start node

• Copy the genesis file to the mainnet deployment tmp directory:

  cp <absolute-path-to-genesis-json> $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR/data/laconicd-data/tmp/genesis.json
  

• Command to run node:

  laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR start
  

• Check logs to ensure that node is running:

  laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR logs laconicd -f
  

• If TMKMS has been configured verify that validator and TMKMS pubkeys match:

  • Get validator pubkey on chain

    # Check consensus_pubkey in output
    laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR exec laconicd 'laconicd query staking validators -o json | jq .validators'
    

  • Compare it with the pubkey noted from logs in TMKMS

• Check bonds list to confirm that testnet state was transferred properly:

  laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR exec laconicd 'laconicd query bond list'
  

• Check alps and alnt tokens total supply:

  laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR exec laconicd 'laconicd query bank total-supply'
  

• Query the lps_lockup account and view distribution:

  laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR exec laconicd 'laconicd query auth module-account lps_lockup'
  

• Query the lps_lockup and early supports accounts balances:

  lockup_account_address=$(laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR exec laconicd 'laconicd query auth module-account lps_lockup -o json | jq -r .account.value.base_account.address')
  laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR exec laconicd "laconicd query bank balances $lockup_account_address"
  
  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 are generated (machine 3)

  • Copy the genesis file to config folder:

    cp $DATA_DIRECTORY/output/genesis.json ~/cerc/laconicd-stack/config/mainnet-genesis.json
    

  • Copy the staking amount file to config folder:

    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):

  laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR exec laconicd 'echo $(laconicd cometbft show-node-id)@YOUR_PUBLIC_IP_ADDRESS:26656'
  

• Add your node's address to node-addresses.yml

• Submit a PR with this genesis file, staking amount file and node address so that it is available to other validators