laconicd-stack/docs/run-validator.md

Run Validator Node

Prerequisites

• To fetch laconicd-stack:

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

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

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

  • laconicd-stack

  • ansible

  • Mainnet genesis file in config folder

• Machine 3: Where the create-validator transaction is to be signed

  • laconicd-stack

  • ansible

  • Staking amount file in config folder

• Machine 4: Where the TMKMS service is to be setup

  • laconicd-stack

  • ansible

• laconic-so is required in all machines

Stop SAPO testnet node

• 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
  

Build laconicd to create validator

• 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 validator node is to be setup (machine 2)

• Copy the example variables file:

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

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

  # Set custom moniker for the node
  cerc_moniker: "<your-moniker>"
  
  # Set persistent peers (comma-separated list of node IDs and addresses)
  # You can find the list of available peers in https://git.vdb.to/cerc-io/laconicd-stack/src/branch/main/node-addresses.yml
  cerc_peers: "<node-id>@<node-host>:26656,<node-id>@<node-host>:26656"
  
  # Enable TMKMS
  tmkms_enabled: true
  

• 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-validator-deployment
  

• Run ansible playbook to set up your validator node deployment:

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

• 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 from where the TMKMS service is to be setup (machine 4)

Setup TMKMS

• For integrating TMKMS with laconicd, follow steps below in the machine where the TMKMS service is to be setup (machine 4)

• Export the data directory as environment variable:

  # Parent directory where the deployment directory will live
  export DATA_DIRECTORY=
  

• Run ansible playbook to setup the TMKMS service:

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

Run Node

Start TMKMS

• Run the following steps in the machine where the TMKMS service is setup (Machine 4)

• Copy the example variables file:

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

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

  NOTE: Use the priv_validator_key.json file copied from the node setup machine (Machine 2) in previous step

  # Absolute path to the node's private validator key file
  priv_validator_key_file_path: "</path/to/priv_validator_key.json>"
  
  # Set the IP address of the machine where the laconicd node is setup
  node_ip: "<NODE_PUBLIC_IP_ADDRESS>"
  
  # Set the port of the laconicd node
  node_port: "26659"
  

• Run ansible playbook to run the TMKMS:

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

• Check logs to ensure that TMKMS is running:

  laconic-so deployment --dir $DATA_DIRECTORY/tmkms-deployment logs tmkms -f
  

  • 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@<node-ip>: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

Start Node

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

• Start the laconicd 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
  

• Get the public key of your node:

  laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR exec laconicd "laconicd tendermint show-validator"
  

  NOTE: This public key is required in next step to create validator

Create Validator

• Run these steps in a machine from where the create-validator transaction is to be signed (machine 3)

• Copy the example variables file:

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

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

  NOTE: Use the public key exported in previous step

  # Same moniker as set above
  cerc_moniker: "<your-moniker>"
  
  # Make sure to wrap it with single quotes ('')
  validator_pub_key: '<public-key-of-your-node>'
  
  # Set the public IP address of the machine where your node is running
  node_url: "tcp://NODE_PUBLIC_IP_ADDRESS:26657"
  

• Export required env vars:

  export DATA_DIRECTORY=<data-directory>
  

• Run ansible playbook to create validator on running chain:

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

  • Input private key of the existing account that was exported in previous steps when prompted

• Run the following commands in the machine where the validator node is running (machine 2)

  • Check the validator list:

    laconic-so deployment --dir $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR exec laconicd 'laconicd query staking validators'
    

  • Remove the validator key from node deployment as TMKMS is configured:

    NOTE: Store it safely offline in case of an emergency

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

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)

• Stop the TMKMS deployment:

  laconic-so deployment --dir $DATA_DIRECTORY/tmkms-deployment stop
  

• Update ~/cerc/laconicd-stack/playbooks/tmkms/tmkms-vars.yml with required values

• Run ansible playbook to run the TMKMS:

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

Node

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

• Stop the node deployment:

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

• Update $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR/config.env with required values

• Start the node deployment:

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

Register Your Node

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

• Get your node's address:

  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 the ~/cerc/laconicd-stack/node-addresses.yml file

• Submit a PR to add your node address to the repository