Skip to content

Cert Command Line Guide

Bursa can be used to create certificates for stake pool operations, stake delegation, and Conway era governance.

These Bursa commands can be used for generating various Cardano certificates.

Certificate types:
op-cert - Operational certificate for block production
pool-registration - Pool registration certificate
pool-retirement - Pool retirement certificate
stake-registration - Stake address registration
stake-deregistration - Stake address deregistration
stake-delegation - Stake delegation to a pool
drep-registration - DRep registration (Conway)
drep-deregistration - DRep deregistration (Conway)
vote-delegation - Vote delegation (Conway)
committee-hot-auth - Committee hot key auth (Conway)
committee-cold-resign - Committee cold key resign (Conway)

Create Certificates for Stake Pool Operation

Section titled “Create Certificates for Stake Pool Operation”

The op-cert command can be used to generate an operational certificate, aka node.cert, linking a KES key to a pool cold key. Stake Pools need to create a new node.cert when rotating their KES key. So SPOs can use Bursa to create a new node.cert with their new kes.vkey, cold key and kes period.

When --out is supplied, Bursa writes a cardano-cli compatible JSON text envelope:

{
"type": "NodeOperationalCertificate",
"description": "Operational Certificate",
"cborHex": "<hex>"
}

The hex encoded cborHex value represents the canonical two element CBOR structure:

[[kes_vkey, counter, kes_period, signature], cold_vkey]

The outer array has two elements: the four element certificate tuple and the 32 byte cold_vkey. Bursa derives this cold verification key from the supplied 32 byte seed or 64 byte Ed25519 private key and includes it for verification and round tripping.

Required inputs:
--kes-vkey       KES verification key file (bech32 or hex format)
--cold-skey     Pool cold signing key file (bech32 or hex format)
--counter        Certificate sequence number (must increment with each new cert)
--kes-period   KES period at certificate creation time

✅ The counter value must be incremented each time a new operational certificate is created, if and only if, you minted a block with old KES key. The KES period is the current slot divided by the slots per KES period (typically 129600 slots = ~36 hours on mainnet).

To create node.cert we can run the following command.

⚠️ Please adjust the paths to your kes and cold key. Also please adjust your counter and kes period below.

./bursa cert op-cert --kes-vkey /path/kes.vkey --cold-skey /path/cold.skey --counter 0 --kes-period 200 --out node.cert

The pool registration certificate registers a new stake pool or updates an existing registration on the Cardano blockchain.

Required inputs:

  • --cold-vkey Pool cold verification key file
  • --vrf-vkey VRF verification key file
  • --pledge Pledge amount in lovelace
  • --cost Fixed cost per epoch in lovelace
  • --margin Pool margin must be finite and fall within the inclusive range 0.0 to 1.0. Bursa rejects negative values, values greater than 1, NaN, and positive or negative infinity before generating the pool-registration certificate.
  • --reward-account Reward account address (bech32 stake address)

Optional inputs:

  • --metadata-url Pool metadata URL
  • --metadata-hash Pool metadata hash (hex)
  • --owner-stake-vkey Pool owner stake verification key file (repeatable)
  • --relay-address Relay IP address with port: IPv4:port or [IPv6]:port (repeatable)
  • --relay-host Relay host name with an optional port: name[:port] (repeatable)
  • --relay-multi-host Multi host DNS name (repeatable)

When no --owner-stake-vkey flags are supplied, Bursa derives the pool owner from the stake key in --reward-account. If the reward account is not a stake key address, Bursa requires at least one explicit --owner-stake-vkey file. Each explicit owner file must contain a StakeVerificationKeyShelley_ed25519 envelope; use stake verification key files rather than pool cold key files.

Bursa emits relay values in this order: address, host, then multi host.

Output format is compatible with cardano-cli certificates.

⚠️ Please adjust paths below.

./bursa cert pool-registration \
--cold-vkey /path/cold.vkey --vrf-vkey /path/vrf.vkey \
--pledge 1000000000 --cost 340000000 --margin 0.01 \
--reward-account stake1... \
--owner-stake-vkey /path/owner-1.vkey \
--owner-stake-vkey /path/owner-2.vkey \
--relay-address 203.0.113.10:3001 \
--relay-address '[2001:db8::1]:3001' \
--relay-host relay.example.com:3001 \
--relay-host relay.example.net \
--relay-multi-host multi.example.com \
--relay-multi-host another.example.com \
--metadata-url "https://example.com/pool.json" \
--metadata-hash "abc123..." --out pool-reg.cert

The following command specifies one owner and one relay address.

./bursa cert pool-registration \
--cold-vkey /path/cold.vkey --vrf-vkey /path/vrf.vkey \
--pledge 1000000000 --cost 340000000 --margin 0.01 \
--reward-account stake1... --owner-stake-vkey /path/owner.vkey \
--relay-address 203.0.113.10:3001 --out pool-reg.cert

The pool retirement certificate signals that a stake pool will retire at the specified epoch boundary.

Required inputs:

  • --cold-vkey Pool cold verification key file
  • --epoch Retirement epoch

Output format is compatible with cardano-cli certificates.

⚠️ Please adjust the paths to your cold key.

./bursa cert pool-retirement --cold-vkey /path/cold.vkey \
--epoch 300 --out pool-retire.cert

Create a Stake Address Registration Certificate

Section titled “Create a Stake Address Registration Certificate”

This certificate registers a stake address on-chain, which is required before the stake key can be used for delegation or reward withdrawal.

Optional input:

  • --deposit <lovelace> Deposit amount that selects the Conway registration form

When the command omits --deposit, Bursa writes the Shelley registration form (type 0). When the command includes --deposit, Bursa writes the Conway registration form (type 7) with the specified deposit. An explicit --deposit 0 value also selects the Conway form.

Output format is a cardano-cli compatible JSON text envelope.

Without --deposit, Bursa writes the Shelley registration certificate (type 0). With --deposit <lovelace>, Bursa writes the Conway registration certificate (type 7) and includes the deposit. --deposit 0 still selects the Conway form and includes a zero coin because the flag’s presence selects the certificate form.

Optional input: --deposit <lovelace> Deposit amount in lovelace.

⚠️ Please adjust path below.

./bursa cert stake-registration \
--stake-vkey /path/stake.vkey --out stake-reg.cert

To write the Conway form with an explicit deposit:

./bursa cert stake-registration \
--stake-vkey /path/stake.vkey --deposit 2000000 --out stake-reg.cert

Create a Stake Address Deregistration Certificate

Section titled “Create a Stake Address Deregistration Certificate”

This certificate deregisters a stake address, returning the deposit and removing the stake key from on-chain registration.

Optional input:

  • --deposit-refund <lovelace> Refund amount that selects the Conway deregistration form

When the command omits --deposit-refund, Bursa writes the Shelley deregistration form (type 1). When the command includes --deposit-refund, Bursa writes the Conway deregistration form (type 8) with the specified refund. An explicit --deposit-refund 0 value also selects the Conway form.

Output format is a cardano-cli compatible JSON text envelope.

Without --deposit-refund, Bursa writes the Shelley deregistration certificate (type 1). With --deposit-refund <lovelace>, Bursa writes the Conway deregistration certificate (type 8) and includes the refund. --deposit-refund 0 still selects the Conway form and includes a zero coin because the flag’s presence selects the certificate form.

Optional input: --deposit-refund <lovelace> Deposit refund amount in lovelace.

⚠️ Please adjust path below.

./bursa cert stake-deregistration \
--stake-vkey /path/stake.vkey --out stake-dereg.cert

To write the Conway form with an explicit deposit refund:

./bursa cert stake-deregistration \
--stake-vkey /path/stake.vkey --deposit-refund 2000000 \
--out stake-dereg.cert

This certificate delegates stake from a stake key to a specific stake pool identified by its pool ID (bech32 or hex format).

Output format is a cardano-cli compatible JSON text envelope.

⚠️ Please adjust path below.

./bursa cert stake-delegation \
--stake-vkey /path/stake.vkey \
--pool-id pool1... \
--out stake-deleg.cert

Create a DRep Registration Certificate (Conway)

Section titled “Create a DRep Registration Certificate (Conway)”

This certificate registers a Delegated Representative (DRep) on-chain, which allows the DRep to receive vote delegations and participate in governance actions.

A deposit amount in lovelace is required. An optional anchor URL and hash can be provided for DRep metadata.

Output format is a cardano-cli compatible JSON text envelope.

Register DRep with Anchor Metadata Example

⚠️ Please adjust path below.

./bursa cert drep-registration \
--drep-vkey /path/drep.vkey \
--deposit 500000000 \
--anchor-url https://example.com/drep.json \
--anchor-hash abc123... \
--out drep-reg.cert

Create a DRep Deregistration Certificate (Conway)

Section titled “Create a DRep Deregistration Certificate (Conway)”

This certificate deregisters a DRep from on-chain governance, returning the deposit refund amount.

Output format is a cardano-cli compatible JSON text envelope.

⚠️ Please adjust path below.

./bursa cert drep-deregistration \
--drep-vkey /path/drep.vkey \
--deposit-refund 500000000 \
--out drep-dereg.cert

Create a Vote Delegation Certificate (Conway)

Section titled “Create a Vote Delegation Certificate (Conway)”

This certificate delegates voting power from a stake key to a DRep, or to special voting options (always-abstain or always-no-confidence).

Exactly one delegation target must be specified:
--drep-vkey-hash Delegate to a DRep by key hash (hex)
--drep-id Delegate to a DRep by ID (bech32 or hex)
--always-abstain Always abstain from voting
--always-no-confidence Always vote no confidence

Output format is a cardano-cli compatible JSON text envelope.

⚠️ Please adjust path below.

./bursa cert vote-delegation \
--stake-vkey /path/stake.vkey \
--drep-id drep1... \
--out vote-deleg.cert
./bursa cert vote-delegation \
--stake-vkey /path/stake.vkey \
--always-abstain \
--out vote-deleg.cert

Create a Committee Hot Key Authorization Certificate (Conway)

Section titled “Create a Committee Hot Key Authorization Certificate (Conway)”

This certificate authorizes a hot key to act on behalf of a committee cold key for governance voting. The cold key remains offline while the hot key participates in governance.

Output format is a cardano-cli compatible JSON text envelope.

⚠️ Please adjust paths below.

./bursa cert committee-hot-auth \
--cold-vkey /path/cc-cold.vkey \
--hot-vkey /path/cc-hot.vkey \
--out cc-hot-auth.cert

Create a Committee Cold Key Resignation Certificate (Conway)

Section titled “Create a Committee Cold Key Resignation Certificate (Conway)”

This certificate resigns a committee member by their cold key. An optional anchor URL and hash can be provided to reference a rationale document.

Output format is a cardano-cli compatible JSON text envelope.

⚠️ Please adjust paths below.

./bursa cert committee-cold-resign \
--cold-vkey /path/cc-cold.vkey \
--out cc-resign.cert
./bursa cert committee-cold-resign \
--cold-vkey /path/cc-cold.vkey \
--anchor-url https://example.com/resign.json \
--anchor-hash abc123... \
--out cc-resign.cert

Explore other Bursa Commands

Bursa Command Categories

  1. wallet   - Commands for generating wallet and the files needed to manage a Cardano wallet
  2. api     - Commands for running API
  3. kes-agent     - Commands for running the KES agent daemon
  4. cert    - Commands for generating various Cardano certificates
  5. hash     - Commands for generating cryptographic hashes used in Cardano
  6. script    - Commands for multi-signature operations
  7. address - Commands for working with Cardano addresses
  8. key     - Commands for deriving individual keys from a mnemonic
  9. tx - Offline transaction operations
  10. sign - CIP-8/CIP-30 message signing and verification
  11. signer - Remote signing service


Doc Holiday logo

Docs authored by Doc Holiday