cardano-cli-staking Skill

cardano-cli-staking

This is a guidance skill. Provides templates and explanations. For execution, use cardano-cli-staking-operator.

When to use

Learning stake key registration and delegation
Understanding rewards withdrawal
Getting command templates for staking operations

Operating rules (must follow)

Confirm network before providing commands
Never execute—only provide templates
Include deposit/fee information
Verify pool ID from multiple sources

Docker fallback mode

If cardano-cli is not installed locally, use the wrapper script in this skill folder to run cardano-cli inside Docker (the Cardano node container images include the CLI).

chmod +x {baseDir}/scripts/cardano-cli.sh
{baseDir}/scripts/cardano-cli.sh version

Notes:

The wrapper mounts your current directory into the container as /work so files like pparams.json, tx.body, datum.json work normally.
If you have a local node socket, set CARDANO_NODE_SOCKET_PATH before running so query commands work.
Override the image with CARDANO_DOCKER_IMAGE=ghcr.io/intersectmbo/cardano-node:<tag>.

Key concepts

Stake addresses vs payment addresses

Payment address: Holds funds, used for spending
Stake address: Controls delegation, receives rewards
Base address: Combines both (most common)

Deposits

Stake key registration: ~2 ADA deposit (refundable)
Pool registration: ~500 ADA deposit (refundable)

Workflow templates

Check stake status

# Derive stake address
cardano-cli conway stake-address build \
  --stake-verification-key-file stake.vkey \
  --testnet-magic 1 \
  --out-file stake.addr

# Query status
cardano-cli conway query stake-address-info \
  --testnet-magic 1 \
  --address $(cat stake.addr)

Register stake key

# 1. Create registration certificate
cardano-cli conway stake-address registration-certificate \
  --stake-verification-key-file stake.vkey \
  --out-file stake-reg.cert

# 2. Build transaction with certificate
cardano-cli conway transaction build \
  --testnet-magic 1 \
  --tx-in <utxo>#<index> \
  --change-address <payment-addr> \
  --certificate-file stake-reg.cert \
  --out-file tx.unsigned

# 3. Sign with BOTH keys
cardano-cli conway transaction sign \
  --tx-file tx.unsigned \
  --signing-key-file payment.skey \
  --signing-key-file stake.skey \
  --testnet-magic 1 \
  --out-file tx.signed

# 4. Submit
cardano-cli conway transaction submit \
  --testnet-magic 1 \
  --tx-file tx.signed

Delegate to pool

# 1. Create delegation certificate
cardano-cli conway stake-address stake-delegation-certificate \
  --stake-verification-key-file stake.vkey \
  --stake-pool-id pool1... \
  --out-file delegation.cert

# 2. Build, sign (both keys), submit
# Same pattern as registration

Withdraw rewards

# 1. Check rewards balance
cardano-cli conway query stake-address-info \
  --testnet-magic 1 \
  --address $(cat stake.addr)

# 2. Build withdrawal tx
cardano-cli conway transaction build \
  --testnet-magic 1 \
  --tx-in <utxo>#<index> \
  --withdrawal $(cat stake.addr)+<reward-lovelace> \
  --change-address <payment-addr> \
  --out-file tx.unsigned

# 3. Sign with BOTH keys, submit

De-register stake key (get deposit back)

cardano-cli conway stake-address deregistration-certificate \
  --stake-verification-key-file stake.vkey \
  --out-file stake-dereg.cert

# Build tx with certificate, sign, submit

Examples

Example: Delegate to a pool

User request: "Delegate my stake to pool1abc..."

Response:

# === Delegate to Pool ===

POOL_ID="pool1abc..."
STAKE_VKEY="stake.vkey"
PAYMENT_ADDR=$(cat base.addr)

# 1. Verify pool exists
cardano-cli conway query stake-pools --testnet-magic 1 | grep $POOL_ID

# 2. Create delegation certificate
cardano-cli conway stake-address stake-delegation-certificate \
  --stake-verification-key-file $STAKE_VKEY \
  --stake-pool-id $POOL_ID \
  --out-file delegation.cert

# 3. Build transaction
cardano-cli conway transaction build \
  --testnet-magic 1 \
  --tx-in <your-utxo>#0 \
  --change-address $PAYMENT_ADDR \
  --certificate-file delegation.cert \
  --out-file tx.unsigned

# 4. Sign with both keys
cardano-cli conway transaction sign \
  --tx-file tx.unsigned \
  --signing-key-file payment.skey \
  --signing-key-file stake.skey \
  --testnet-magic 1 \
  --out-file tx.signed

# 5. Submit (use operator skill)
# Delegation takes effect at next epoch boundary

Safety / key handling

Verify pool ID from multiple sources (adapools, cexplorer)
Staking never risks your principal
Delegation can be changed anytime
Rewards accumulate until withdrawn

References

shared/PRINCIPLES.md
cardano-cli-staking-operator (for execution)

Agent Skills: cardano-cli-staking

Install this agent skill to your local

Skill Files