Skip to content
Blink Labs

Key Command Line Guide

Create Keys

Section titled “Create Keys”

Bursa can be used to derive individual keys from a mnemonic.

Key types:
Root Key Account Key Payment Key
Stake Key Pool Cold Key Policy Key
Calidus Key VRF keys KES Key Pair
DRep key Constitutional Committee Cold Key Constitutional Committee Hot Key
Dijkstra BLS Key

Bursa Command Line Guide for Deriving Individual Keys from a Mnemonic.

The mnemonic can be provided via:

  1. —mnemonic flag
  2. MNEMONIC environment variable
  3. —mnemonic-file flag
  4. Default file “seed.txt”

Keys are derived following Cardano CIP standards and output in bech32 format suitable for use with cardano-cli and other tools.

Derivation paths by key type:

  • CIP-1852: root, account, payment, stake (m/1852’/1815’/…)
  • CIP-1853: pool-cold (m/1853’/1815’/…)
  • CIP-1855: policy (m/1855’/1815’/…)
  • CIP-0105: drep, committee-cold, committee-hot (m/1852’/1815’/account’/role/…)
  • CIP-88/151: calidus (m/1852’/1815’/account’/0/index, SPO authentication)

Signing Key File Format

Section titled “Signing Key File Format”

When Bursa exports a signing key derived from an HD path, it writes an extended Ed25519-BIP32 envelope. Root, account, payment, stake, governance, policy, multisig, and Calidus signing files use envelope types such as *_ExtendedSigningKeyShelley_ed25519_bip32 and 128-byte CBOR beginning with 5880. Legacy non-extended files use 32-byte CBOR beginning with 5820.

Pool-cold signing files are the exception. Fresh exports use a standard, non-extended Ed25519 envelope with type StakePoolSigningKey_ed25519; the matching verification envelope uses type StakePoolVerificationKey_ed25519. Bursa accepts the legacy StakePoolSigningKeyShelley_ed25519 and StakePoolVerificationKeyShelley_ed25519 types when loading and leaves those files unchanged. The pool-cold signing seed produces the exported verification key as the standard Ed25519 identity used by pool registration and operational certificates. The optional extended pool-cold representation preserves that same identity.

Bursa loads key inputs only from regular files. On Unix, it rejects symlinked inputs; on Windows, it rejects reparse-point inputs. Bursa limits key-file input to its supported maximum and rejects oversized files before processing. Secret-key files (.skey) must have owner-only access: Unix permissions cannot include group or other bits, and Windows files must use a restrictive DACL scoped to the owner. Bursa applies this permission check only when it loads secret material; it rejects insecure files with ErrInsecureFileMode. When a directory contains only .skey files that fail this permission check, Bursa reports that permission reason for the directory. Public artifacts such as .vkey files and operational certificates remain readable through the public-key loading path and do not use this secret-key permission check.

Do not repair legacy HD-derived signing files that declare a non-extended type by changing only the type field; Bursa does not rewrite them automatically. Regenerate the signing and verification files together from the original mnemonic, then compare the resulting address, key hash, or other existing identity before signing.

Root Key

Section titled “Root Key”

The root key is the master key from which all other keys are derived.
Output is in bech32 format (root_xsk prefix) unless —signing-key-file is specified.

./bursa key root --mnemonic "word1 word2 ..."

Root Key with Signing Key File Example:

⚠️ Please adjust path below.

./bursa key root --signing-key-file /path/root.skey

Account Key

Section titled “Account Key”

The account key follows CIP-1852 path: m/1852’/1815’/account’
Output is in bech32 format (acct_xsk prefix) unless —signing-key-file is specified.

./bursa key account --mnemonic "word1 word2 ..." --index 0

Payment Key

Section titled “Payment Key”

The payment key follows CIP-1852 path: m/1852’/1815’/account’/0/index
Output is in bech32 format (addr_xsk prefix) unless key files are specified.

./bursa key payment --mnemonic "word1 word2 ..." --account-index 0 --index 0

Stake Key

Section titled “Stake Key”

The stake key follows CIP-1852 path: m/1852’/1815’/account’/2/index
Output is in bech32 format (stake_xsk prefix) unless key files are specified.

./bursa key stake --mnemonic "word1 word2 ..." --account-index 0 --index 0

Pool Cold Key

Section titled “Pool Cold Key”

The pool cold key follows CIP-1853 path: m/1853’/1815’/0’/index’
These keys are used as the long-term identity keys for stake pool operators.
Output is in bech32 format (pool_xsk prefix) unless key files are specified.

./bursa key pool-cold --mnemonic "word1 word2 ..." --index 0

Policy Key

Section titled “Policy Key”

The policy key follows CIP-1855 path: m/1855’/1815’/policy_ix’
These keys are used for native asset minting/burning policies.
Output is in bech32 format (policy_xsk prefix) unless key files are specified.

./bursa key policy --mnemonic "word1 word2 ..." --index 0

Calidus Key

Section titled “Calidus Key”

The Calidus key is the SPO on-chain authentication hot key defined by CIP-88/CIP-151. It uses the same derivation path as the payment key:
m/1852’/1815’/account’/0/index

The key is functionally identical to the payment key but uses different bech32 prefixes (calidus_xsk/calidus_xvk) and different cardano-cli text envelope types for SPO identity purposes.

Output is in bech32 format (calidus_xsk prefix) unless key files are specified.

./bursa key calidus --mnemonic "word1 word2 ..." --account-index 0 --index 0

Calidus Key with Key Files Example

⚠️ Please adjust path below.

./bursa key calidus --signing-key-file /path/calidus.skey --verification-key-file /path/calidus.vkey

VRF (Verifiable Random Function) Key Pair

Section titled “VRF (Verifiable Random Function) Key Pair”

VRF keys are used by stake pool operators for leader election in the Praos consensus protocol. The seed is derived deterministically from the mnemonic, allowing for key recovery.

Output includes both signing key (vrf_sk) and verification key (vrf_vk) in bech32 format unless key files are specified.

./bursa key vrf --mnemonic "word1 word2 ..." --index 0

VRF with Key Files Example

⚠️ Please adjust path below.

./bursa key vrf --signing-key-file /path/vrf.skey --verification-key-file /path/vrf.vkey

KES Key Pair

Section titled “KES Key Pair”

KES keys are used by stake pool operators for block signing in the Praos consensus protocol. KES provides forward-secure signatures where compromising the current key does not compromise past signatures.

This implementation uses Cardano’s depth 6, providing 64 time periods.
The seed is derived deterministically from the mnemonic, allowing for key recovery.

Output includes both signing key (kes_sk, 608 bytes) and verification key (kes_vk, 32 bytes) in bech32 format unless key files are specified.

./bursa key kes --mnemonic "word1 word2 ..." --index 0

KES Key with Key Files Example

⚠️ Please adjust path below.

./bursa key kes --signing-key-file /path/kes.skey --verification-key-file /path/kes.vkey

VRF and KES Key Validation

Section titled “VRF and KES Key Validation”

Bursa validates VRF and KES material before exporting or loading it. A VRF verification key must have the expected length. VRF signing material must use an accepted seed or seed-plus-public-key form, and its embedded public key must match the seed when that form is used. A KES verification key must have the expected length. A KES signing key must use Cardano KES depth and the expected secret-key size. Bursa rejects malformed lengths, a mismatched VRF seed and public key, invalid KES depth, and invalid KES secret size instead of producing an envelope.

DRep Key

Section titled “DRep Key”

The DRep key follows CIP-0105 path: m/1852’/1815’/account’/3/index
These keys are used for governance participation as a Delegated Representative.
Output is in bech32 format (drep_xsk prefix) unless key files are specified.

./bursa key drep --mnemonic "word1 word2 ..." --account-index 0 --index 0

DRep Key with Key Files Example

⚠️ Please adjust path below.

./bursa key drep --signing-key-file /path/drep.skey --verification-key-file /path/drep.vkey

Constitutional Committee Cold Key

Section titled “Constitutional Committee Cold Key”

The committee cold key follows CIP-0105 path: m/1852’/1815’/account’/4/index
These keys are used for Constitutional Committee membership (long-term identity).
Output is in bech32 format (cc_cold_xsk prefix) unless key files are specified.

./bursa key committee-cold --mnemonic "word1 word2 ..." --account-index 0 --index 0

Constitutional Committee Cold Key with Key Files Example

⚠️ Please adjust path below.

./bursa key committee-cold --signing-key-file /path/committee-cold.skey --verification-key-file /path/committee-cold.vkey

Constitutional Committee Hot Key

Section titled “Constitutional Committee Hot Key”

The committee hot key follows CIP-0105 path: m/1852’/1815’/account’/5/index
These keys are used for Constitutional Committee voting (operational key).
Output is in bech32 format (cc_hot_xsk prefix) unless key files are specified.

./bursa key committee-hot --mnemonic "word1 word2 ..." --account-index 0 --index 0

Constitutional Committee Cold Key with Key Files Example

⚠️ Please adjust path below.

./bursa key committee-hot --signing-key-file /path/committee-hot.skey --verification-key-file /path/committee-hot.vkey

Dijkstra BLS Key and Registration Material

Section titled “Dijkstra BLS Key and Registration Material”

The BLS command generates cryptographically random BLS12-381 MinSig material for Dijkstra-era Leios and Peras stake-pool registration. It does not use the mnemonic input sources described for the other key commands.

The --signing-key-file <path> option is required. The --verification-key-file and --output-file options are optional:

  • --signing-key-file <path> writes the signing key to the specified file. The command never prints the signing key.
  • --verification-key-file writes the verification key to the specified file.
  • --output-file writes the registration JSON to the specified file. When the command omits this flag, Bursa prints the registration JSON to standard output.
Terminal window
./bursa key bls --signing-key-file bls.skey --verification-key-file bls.vkey --output-file bls-registration.json

The registration JSON contains exactly these fields:

  • publicKey: the 96-byte public key as a lowercase hexadecimal string.
  • possessionProof: the 48-byte proof of possession as a lowercase hexadecimal string.

Bursa verifies the generated proof before it produces the registration output. The required signing key file uses the cardano-cli envelope type BlsSigningKey_bls12-381-BLS-Signature-Minimal-Signature-Size. The optional verification key file uses BlsVerificationKey_bls12-381-BLS-Signature-Minimal-Signature-Size. Bursa writes each generated destination file with owner-only permissions. Protect and back up the signing key file as stake-pool credential material.

The three destination paths must be distinct. Bursa rejects direct path collisions and paths that resolve to the same file through path normalization or symbolic links.

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

Doc Holiday logo

Docs authored by Doc Holiday

Edit page

Last updated: