Skip to main content

Configuring the Block Producer

To operate a stake pool, in addition to a wallet you need to generate the following key pairs and related files:

  • Key-evolving Signature (KES) Hot Keys—Used to validate the operational certificate for a stake pool, verifying that the pool has the authority to run. You must generate a new KES key pair and operational certificate every 90 days. Generating an operational certificate uses an incrementing counter file to count how many operational certificates your stake pool uses.
  • Cold Keys—Used to register a stake pool; update registration certificate parameters; rotate KES keys and operational certificates; and, retire a stake pool.
  • Verifiable Random Function (VRF) Hot Keys—Used to determine when a block-producing node is elected to prepare a block

For more details, see Cardano Key Pairs.

The How to Set Up a Cardano Stake Pool guide uses the following file names throughout for the stake pool key pairs and related files:

  • KES Keys—kes.vkey and kes.skey
  • Operational Certificate—node.cert
  • Incrementing Counter File—node.counter
  • Cold Keys—node.vkey and node.skey
  • Stake Pool Registration Certificate—pool.cert
  • VRF Keys—vrf.vkey and vrf.skey

Note
Note

Cardano CLI commands throughout the How to Set Up a Cardano Stake Pool guide may use the ‑‑mainnet option. If you are working in a Testnet environment, then remember to replace each instance of the ‑‑mainnet option with ‑‑testnet‑magic <MagicNumber> where <MagicNumber> is the network magic number for the Testnet that you use.

To generate a KES key pair:

  • On the computer designated as the block-producing node in your stake pool configuration, type the following commands using a terminal window:
    cd $NODE_HOME
    cardano-cli conway node key-gen-KES \
    --verification-key-file kes.vkey \
    --signing-key-file kes.skey

To generate a cold key pair and incrementing counter file:

  1. On your air-gapped, offline computer type the following commands using a terminal window:
    mkdir $HOME/cold-keys
    cd $HOME/cold-keys
    cardano-cli conway node key-gen \
    --cold-verification-key-file $HOME/cold-keys/node.vkey \
    --cold-signing-key-file $HOME/cold-keys/node.skey \
    --operational-certificate-issue-counter $HOME/cold-keys/node.counter

    Important
    Important

    To ensure that your Cardano stake pool operating on Mainnet remains secure, do NOT use or store the node.skey secret signing key file for your stake pool on a computer that connects to a network or the Internet.

  2. Carefully back up the cold keys that you generated in step 1 using a secure and comprehensive backup strategy.

    Important
    Important

    If you lose the cold keys, then you permanently lose access to your stake pool.

  3. Using removable media, copy the $HOME/cold-keys/node.vkey public verification key file to the $NODE_HOME folder on the computer designated as the block-producing node in your stake pool configuration.

To generate an operational certificate:

  1. To verify that the Cardano Node instance designated as the block producer in your stake pool configuration is fully synchronized with the network, confirm that the values of the cardano.node.metrics.epoch.int and cardano.node.metrics.slotInEpoch.int EKG metrics are equal to the current network epoch and slot values available using a Cardano blockchain explorer.
  2. To calculate the current KES period:
    1. On the computer designated as the block-producing node in your stake pool configuration, type the following commands using a terminal window to retrieve the number of slots per KES period for your environment using the Shelley Genesis file:
      slotsPerKESPeriod=$(cat $NODE_HOME/shelley-genesis.json | jq -r '.slotsPerKESPeriod')
      echo slotsPerKESPeriod: ${slotsPerKESPeriod}
    2. To query the slot number of the tip of the local copy of the Cardano blockchain since the beginning of the ledger, type:
      currentSlot=$(cardano-cli conway query tip --mainnet | jq -r '.slot')
      echo "Current Slot: ${currentSlot}"
    3. To divide the current slot tip by the number of slots per KES period, type:
      currentKesPeriod=$(( ${currentSlot} / ${slotsPerKESPeriod} ))
      echo currentKesPeriod: ${currentKesPeriod}
  3. Using removable media, copy the $NODE_HOME/kes.vkey file from the computer designated as the block-producing node in your stake pool configuration to $NODE_HOME/kes.vkey on the air-gapped, offline computer.
  4. On the air-gapped, offline computer, using a terminal window type the following command where <currentKesPeriod> is the value that you calculated in step 2:
    cardano-cli conway node issue-op-cert \
    --kes-verification-key-file $NODE_HOME/kes.vkey \
    --cold-signing-key-file $HOME/cold-keys/node.skey \
    --operational-certificate-issue-counter $HOME/cold-keys/node.counter \
    --kes-period <currentKesPeriod> \
    --out-file $NODE_HOME/node.cert
  5. Using removable media, copy the $NODE_HOME/node.cert file to $NODE_HOME/node.cert on the computer designated as the block-producing node in your stake pool configuration.

For more details, see the topic Issuing a New Operational Certificate.

To generate a VRF key pair:

  1. On the computer designated as the block-producing node in your stake pool configuration, using a terminal window type:
    cd $NODE_HOME
    cardano-cli conway node key-gen-VRF \
    --verification-key-file vrf.vkey \
    --signing-key-file vrf.skey
  2. To secure the secret key file, type:
    chmod 400 vrf.skey
  3. Using removable media, copy the $NODE_HOME/vrf.vkey file to $NODE_HOME/vrf.vkey on the air-gapped, offline computer.

To configure a Cardano Node instance to operate as a block producer:

  1. On the computer designated as the block-producing node in your stake pool configuration, type the following command to stop the Cardano Node instance:
    sudo systemctl stop cardano-node
  2. To retrieve the value of the $NODE_HOME environment variable, type:
    echo $NODE_HOME
  3. Using a text editor, open the $NODE_HOME/startCardanoNode.sh file.
  4. In the startCardanoNode.sh file, add or edit the following lines as needed, where <NodeHomeValue> is the value of your $NODE_HOME environment variable that you retrieved in step 2:
    # Set a variable to indicate the file path to the KES secret key file
    KES=<NodeHomeValue>/kes.skey
    # Set a variable to indicate the file path to the VRF secret key file
    VRF=<NodeHomeValue>/vrf.skey
    # Set a variable to indicate the file path to the operational certificate file
    CERT=<NodeHomeValue>/node.cert
    #
    # Run Cardano Node using the options that you set using variables
    #
    /usr/local/bin/cardano-node run \
    --topology ${TOPOLOGY} \
    --database-path ${DB_PATH} \
    --socket-path ${SOCKET_PATH} \
    --host-addr ${HOSTADDR} \
    --port ${PORT} \
    --config ${CONFIG} \
    --shelley-kes-key ${KES} \
    --shelley-vrf-key ${VRF} \
    --shelley-operational-certificate ${CERT}
  5. Save and close the startCardanoNode.sh file.
  6. To start the block-producing node in your stake pool configuration, type:
    sudo systemctl start cardano-node
  7. To confirm that the Cardano Node instance is operating as a block producer, verify that the cardano.node.metrics.forging_enabled EKG metric displays the value 1

Summarizing Security Considerations

As explained in the procedures above, on the block-producing node in your stake pool configuration store ONLY the following stake pool key and operational certificate files:

  • kes.vkey
  • kes.skey
  • vrf.vkey
  • vrf.skey
  • node.vkey
  • node.cert

Copy NO stake pool key or operational certificate files from the air-gapped, offline computer or block-producing node to computers designated as relay nodes in your stake pool configuration.