BRIAN Pool

Run a Stake Pool Part IV — Run Guided mode

Part IV — Run

What comes back: KES, monitoring, rewards, votes, upgrades, the end.

  1. Start hereThe picture, the dangers, how BRIAN runs it4 steps
  2. IInstallMachines, a hardened Ubuntu, the node5 steps
  3. IIConfigureChain, topology, offline machine, service5 steps
  4. IIIRegisterKeys, stake address, the pool5 steps
  5. IVRunKES, rewards, votes, upgrades8 steps
  6. VTipsPayments, files, swap, checklist4 steps

IV-1 Renew the KES key

Every 90 days at the latest.

  • Day 0–80 blocks as usual
  • Day 80–90 renew now
  • After 93 no more blocks

1 KES period = 36 hours · 62 periods ≈ 93 days

KES key lifetime: renew between day 80 and 90; after day 93 no blocks.
Block producer
sudo -u cardano cardano-cli latest query kes-period-info \
  --mainnet \
  --socket-path /run/cardano/node.socket \
  --op-cert-file /var/lib/cardano/keys/node.cert

Current KES period as in Part III, step 3; then on the air-gapped machine:

Air-gapped machine
cd ~/cold-keys
cardano-cli latest node key-gen-KES \
  --verification-key-file kes.vkey \
  --signing-key-file kes.skey
cardano-cli latest node issue-op-cert \
  --kes-verification-key-file kes.vkey \
  --cold-signing-key-file cold.skey \
  --operational-certificate-issue-counter-file cold.counter \
  --kes-period <kes-period> \
  --out-file node.cert
Block producer
sudo install -o cardano -g cardano -m 400 kes.skey node.cert /var/lib/cardano/keys/
shred -u kes.skey
sudo systemctl restart cardano-node

Caution The new certificate's counter may be at most one above the counter in the pool's last block. No block since the last renewal? Reuse that certificate or reset with cardano-cli latest node new-counter.

Check kes-period-info reports the new expiry date and matching counters.

Next: Monitor and the leader schedule →

IV-2 Monitor and the leader schedule

Daily health, and the slots your pool is due for.

gLiveView in the terminal, or Prometheus and Grafana on the node's metrics (port 12798, never public). The next epoch's schedule is known 1.5 days ahead:

Block producer
sudo -u cardano cardano-cli latest query leadership-schedule \
  --mainnet \
  --socket-path /run/cardano/node.socket \
  --genesis /etc/cardano/shelley-genesis.json \
  --stake-pool-id $(cat stakepoolid.txt) \
  --vrf-signing-key-file /var/lib/cardano/keys/vrf.skey \
  --next

Note BRIAN also runs a Mithril signer — see mithril.network.

Next: Delegate your vote →

IV-3 Delegate your vote

Needed before rewards can be withdrawn.

Air-gapped machine
cardano-cli latest stake-address vote-delegation-certificate \
  --stake-verification-key-file stake.vkey \
  --always-abstain \
  --out-file vote-deleg.cert

Build with --certificate-file vote-deleg.cert --witness-override 2, sign with payment.skey and stake.skey, submit. A DRep instead: --drep-key-hash.

Next: Withdraw the rewards →

IV-4 Withdraw the rewards

The whole reward balance into your wallet.

Block producer or relay
rewards=$(cardano-cli latest query stake-address-info --address $(cat stake.addr) | jq -r '.[0].rewardAccountBalance')
cardano-cli latest transaction build \
  --tx-in $(cardano-cli latest query utxo --address $(cat payment.addr) --output-json | jq -r 'keys[0]') \
  --withdrawal "$(cat stake.addr)+${rewards}" \
  --change-address $(cat payment.addr) \
  --witness-override 2 \
  --out-file tx.raw

Sign with payment.skey and stake.skey, submit.

Next: Vote as a pool →

IV-5 Vote as a pool

Hard forks, some parameters, no-confidence, committee changes.

Block producer or relay
cardano-cli latest query proposals --all-proposals \
  | jq '.[] | {id: .actionId, type: .proposalProcedure.govAction.tag, url: .proposalProcedure.anchor.url}'
Air-gapped machine
cardano-cli latest governance vote create \
  --yes \
  --governance-action-tx-id <tx-id> \
  --governance-action-index 0 \
  --cold-verification-key-file cold.vkey \
  --out-file pool.vote
Block producer or relay
cardano-cli latest transaction build \
  --tx-in $(cardano-cli latest query utxo --address $(cat payment.addr) --output-json | jq -r 'keys[0]') \
  --change-address $(cat payment.addr) \
  --vote-file pool.vote \
  --witness-override 2 \
  --out-file tx.raw

Sign with cold.skey and payment.skey, submit. --no or --abstain as you decide.

Next: Change pool parameters →

IV-6 Change pool parameters

Pledge, cost, margin, relays, metadata — no new deposit.

New pool.cert as in Part III, step 4; submit it alone, signed with payment.skey, stake.skey, cold.skey. It takes effect at an epoch boundary.

Next: Upgrade the node →

IV-7 Upgrade the node

Relays first, block producer last — right after a block.

All nodes
VERSION=<new-version>
cd ~
wget https://github.com/IntersectMBO/cardano-node/releases/download/${VERSION}/cardano-node-${VERSION}-linux-amd64.tar.gz
wget https://github.com/IntersectMBO/cardano-node/releases/download/${VERSION}/cardano-node-${VERSION}-sha256sums.txt
sha256sum --ignore-missing -c cardano-node-${VERSION}-sha256sums.txt
tar -xzf cardano-node-${VERSION}-linux-amd64.tar.gz -C ~/.local/
sudo systemctl stop cardano-node
sudo install -m 755 ~/.local/bin/cardano-node ~/.local/bin/cardano-cli /usr/local/bin/
sudo systemctl start cardano-node
cardano-node --version

Read the release notes first; some need new configuration files. Bring the new cardano-cli to the air-gapped machine too.

Next: Retire the pool →

IV-8 Retire the pool

The 500 ADA deposit returns at the epoch you name.

Air-gapped machine
cardano-cli latest stake-pool deregistration-certificate \
  --cold-verification-key-file cold.vkey \
  --epoch <retirement-epoch> \
  --out-file pool.dereg

Submit it signed with payment.skey and cold.skey. Announce it and give delegators two epochs or more.

Sources and license

Text, pictures and order are BRIAN's. Commands for system setup, the firewall, Mithril and the service file are adapted from the Cardano Developer Portal; every cardano-cli command was written for and run against cardano-cli 11.2.3. The node's own documentation always takes precedence.

Developer Portal license (MIT) — Copyright (c) 2021 Cardano Foundation

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.