cerc-io/laconicd-stack
13
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
4a75025e23
laconicd-stack/docs/run-validator.md
Shreerang Kale 4a75025e23 Remove git-ssh usage
2025-06-19 11:01:34 +05:30

11 KiB
Raw Blame History

Run Validator Node

Prerequisites

  • laconic-so is required in all machines listed below

  • To fetch laconicd-stack:

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

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

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

    • laconicd-stack

    • ansible

    • Install zstd using sudo apt install zstd

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

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

Stop SAPO testnet node

  • Run the following steps in machine where your SAPO testnet validator 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. It should be the private key of the account that was used to create validator in SAPO testnet.

  • 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 TMKMS (Optional)

  • 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

Setup laconicd Node

  • Run the following steps in the machine where the validator node is to be setup for mainnet (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 (Set to true or false)
# NOTE: Enabling TMKMS is optional and can be set to `true` if you are following the optional steps to setup TMKMS
tmkms_enabled:

  • 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

  • To get path to the deployment

    echo $DATA_DIRECTORY/$MAINNET_DEPLOYMENT_DIR

Start Deployments

Start TMKMS (Optional)

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

  • Copy over the priv_validator_key.json from the machine where mainnet laconicd node was setup (machine 2) to a suitable place in the TMKMS machine (path to file needs to be specified in playbook vars in next step)

    # Example command to transfer file from machine 2 (run on machine 2)
scp -C <user>@<machine-2-ip-address>:<path_to_laconicd_deployment_dir>/data/laconicd-data/config/priv_validator_key.json <absolute-path-to-desired-destination-directory>

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

    # Absolute path to the node's private validator key file
# Use the priv_validator_key.json file copied from the node setup machine (Machine 2) in previous step
priv_validator_key_file_path: "<absolute/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 laconicd Node

  • Run the following steps in the machine where the laconicd 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

    NOTE: The node takes a long time to start syncing blocks ~30 seconds

  • 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

    # Set the public IP address of the machine where your node is running
# NOTE: An https URL can also be used
node_url: "tcp://NODE_PUBLIC_IP_ADDRESS:26657"

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

# Same moniker as set during setup of laconicd node
cerc_moniker: "<your-moniker>"

  • Set a directory path required by the playbook to create validator (used temporarily):

    export DATA_DIRECTORY=<data-directory>

  • Run ansible playbook to create a validator in the 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'

    • (Optional) If TMKMS is configured and running, remove the validator key from node deployment:

      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

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 node-addresses.yml file

  • Submit a PR to add your node address to the laconicd-stack repository

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

Rebuild Images

  • Follow these steps to rebuild the images for TMKMS and node in case of any code changes

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

  • Run ansible playbook to rebuild the TMKMS image:

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

  • Start the TMKMS deployment:

    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

  • Run ansible playbook to rebuild the node image:

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

  • Start the node deployment:

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