laconicd-stack/docs/run-validator.md

# Run Validator Node

## Prerequisites

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

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

  - laconicd-stack

  - [ansible](playbooks/README.md#ansible-installation)

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

  - laconicd-stack

  - [ansible](playbooks/README.md#ansible-installation)

- [laconic-so](https://github.com/cerc-io/stack-orchestrator/?tab=readme-ov-file#install) is required in all machines

- To fetch laconicd-stack:

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

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

  ```bash
  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](#create-validator)

- Stop the node for SAPO testnet:

  ```bash
  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:

  ```bash
  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:

  ```bash
  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:

  ```bash
  # 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"
  ```

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

  ```bash
  # 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:

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

### Setup TMKMS (Optional but Recommended)

<!-- Reference: https://docs.osmosis.zone/osmosis-core/keys/tmkms/#setup-tmkms -->

- 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

  ```bash
  # 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`:

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

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

  - Remove the JSON key file

    ```bash
    rm $TMKMS_HOME/secrets/priv_validator_key.json
    ```

- Start TMKMS:

  ```bash
  tmkms start --config $TMKMS_HOME/tmkms.toml
  ```

- Enable TMKMS in the laconicd node configuration:

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

## Start Node

- Start the laconicd node:

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

- Check logs to ensure that node is running:

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

- Get the public key of your node:

  ```bash
  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)](#build-laconicd-to-create-validator)

  This command clones the entire repository into the `~/cerc` folder, which includes the genesis file published by the first validator.

- Copy the example variables file:

  ```bash
  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](#start-node)

  ```bash
  # 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:

  ```bash
  export DATA_DIRECTORY=<data-directory>
  export MAINNET_DEPLOYMENT_DIR=mainnet-validator-deployment
  ```

- Run ansible playbook to create validator on running chain:

  ```bash
  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](#stop-sapo-testnet-node) when prompted

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

  - Check the validator list:

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

  - If TMKMS has been configured, remove the validator key from node deployment as it is no longer required:

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

    NOTE: Store it safely offline in case of an emergency

## Register Your Node

- Get your node's address:

  ```bash
  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