Key Command Line Guide
Create Keys
Section titled “Create Keys”Bursa can be used to derive individual keys from a mnemonic.
Bursa Command Line Guide for Deriving Individual Keys from a Mnemonic.
Use --mnemonic-file seed.txt to read the mnemonic from a file, or --mnemonic-file - to read it from standard input. Mnemonic sources are checked in this order: deprecated --mnemonic, MNEMONIC environment variable, --mnemonic-file, then the default seed.txt file. The --mnemonic and --password arguments are deprecated because process arguments are visible to other local users; use --mnemonic-file and --password-file instead. For an optional derivation password, use --password-file <path>; - reads standard input, but both secrets cannot read standard input in the same command.
The examples below write signing keys to explicit files in cardano-cli JSON envelope format. For mnemonic-derived commands, --signing-key-file - explicitly prints bech32 secret material to standard output instead. Omitting the signing destination is an error unless the command supports and receives only --verification-key-file. Root and account commands require a signing destination. Do not combine --signing-key-file - with --verification-key-file.
Keys are derived following Cardano CIP standards. File output uses cardano-cli envelopes; explicitly requested standard output uses bech32.
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, policy, multisig, and Calidus signing files use envelope types such as *_ExtendedSigningKeyShelley_ed25519_bip32 and 128-byte CBOR beginning with 5880. Generated governance signing files use the specific envelope types documented in their sections below. 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.
With --signing-key-file -, standard output uses bech32 format (root_xsk prefix).
./bursa key root --mnemonic-file seed.txt --signing-key-file root.skeyRoot Key with Signing Key File Example:
⚠️ Please adjust path below.
./bursa key root --mnemonic-file seed.txt --signing-key-file /path/root.skeyAccount Key
Section titled “Account Key”The account key follows CIP-1852 path: m/1852’/1815’/account’
With --signing-key-file -, standard output uses bech32 format (acct_xsk prefix).
./bursa key account --mnemonic-file seed.txt --index 0 --signing-key-file account.skeyPayment Key
Section titled “Payment Key”The payment key follows CIP-1852 path: m/1852’/1815’/account’/0/index
With --signing-key-file -, standard output uses bech32 format (addr_xsk prefix).
./bursa key payment --mnemonic-file seed.txt --account-index 0 --index 0 --signing-key-file payment.skey --verification-key-file payment.vkeyStake Key
Section titled “Stake Key”The stake key follows CIP-1852 path: m/1852’/1815’/account’/2/index
With --signing-key-file -, standard output uses bech32 format (stake_xsk prefix).
./bursa key stake --mnemonic-file seed.txt --account-index 0 --index 0 --signing-key-file stake.skey --verification-key-file stake.vkeyPool 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.
With --signing-key-file -, standard output uses bech32 format (pool_xsk prefix).
./bursa key pool-cold --mnemonic-file seed.txt --index 0 --signing-key-file pool-cold.skey --verification-key-file pool-cold.vkeyPolicy 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.
With --signing-key-file -, standard output uses bech32 format (policy_xsk prefix).
./bursa key policy --mnemonic-file seed.txt --index 0 --signing-key-file policy.skey --verification-key-file policy.vkeyCalidus 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.
With --signing-key-file -, standard output uses bech32 format (calidus_xsk prefix).
./bursa key calidus --mnemonic-file seed.txt --account-index 0 --index 0 --signing-key-file calidus.skey --verification-key-file calidus.vkeyCalidus Key with Key Files Example
⚠️ Please adjust path below.
./bursa key calidus --mnemonic-file seed.txt --signing-key-file /path/calidus.skey --verification-key-file /path/calidus.vkeyVRF (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.
With --signing-key-file -, standard output includes both the signing key (vrf_sk) and verification key (vrf_vk) in bech32 format.
Generated verification key files use the envelope type VrfVerificationKey_PraosVRF, and generated signing key files use VrfSigningKey_PraosVRF. The signing key body contains 64 bytes: a 32-byte seed followed by a 32-byte public key. Standard output encodes vrf_sk with the same seed-plus-public-key layout.
./bursa key vrf --mnemonic-file seed.txt --index 0 --signing-key-file vrf.skey --verification-key-file vrf.vkeyVRF with Key Files Example
⚠️ Please adjust path below.
./bursa key vrf --mnemonic-file seed.txt --signing-key-file /path/vrf.skey --verification-key-file /path/vrf.vkeyKES 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.
With --signing-key-file -, standard output includes both the signing key (kes_sk, 608 bytes) and verification key (kes_vk, 32 bytes) in bech32 format.
Generated verification key files use the envelope type KesVerificationKey_ed25519_kes_2^6, and signing key files use KesSigningKey_ed25519_kes_2^6.
./bursa key kes --mnemonic-file seed.txt --index 0 --signing-key-file kes.skey --verification-key-file kes.vkeyKES Key with Key Files Example
⚠️ Please adjust path below.
./bursa key kes --mnemonic-file seed.txt --signing-key-file /path/kes.skey --verification-key-file /path/kes.vkeyVRF 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 either a 32-byte seed or a 64-byte seed-plus-public-key form, and its embedded public key must match the seed when the 64-byte 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.
With --signing-key-file -, standard output uses bech32 format (drep_xsk prefix).
Generated verification key files use the envelope type DRepVerificationKey_ed25519, and signing key files use DRepExtendedSigningKey_ed25519_bip32. Bursa continues to load legacy Shelley-suffixed Bursa envelope names for DRep keys, so existing key files remain usable.
./bursa key drep --mnemonic-file seed.txt --account-index 0 --index 0 --signing-key-file drep.skey --verification-key-file drep.vkeyDRep Key with Key Files Example
⚠️ Please adjust path below.
./bursa key drep --mnemonic-file seed.txt --signing-key-file /path/drep.skey --verification-key-file /path/drep.vkeyConstitutional 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).
With --signing-key-file -, standard output uses bech32 format (cc_cold_xsk prefix).
Generated verification key files use the envelope type ConstitutionalCommitteeColdVerificationKey_ed25519, and signing key files use ConstitutionalCommitteeColdExtendedSigningKey_ed25519_bip32. Bursa continues to load legacy Shelley-suffixed Bursa envelope names for constitutional committee cold keys, so existing key files remain usable.
./bursa key committee-cold --mnemonic-file seed.txt --account-index 0 --index 0 --signing-key-file committee-cold.skey --verification-key-file committee-cold.vkeyConstitutional Committee Cold Key with Key Files Example
⚠️ Please adjust path below.
./bursa key committee-cold --mnemonic-file seed.txt --signing-key-file /path/committee-cold.skey --verification-key-file /path/committee-cold.vkeyConstitutional 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).
With --signing-key-file -, standard output uses bech32 format (cc_hot_xsk prefix).
Generated verification key files use the envelope type ConstitutionalCommitteeHotVerificationKey_ed25519, and signing key files use ConstitutionalCommitteeHotExtendedSigningKey_ed25519_bip32. Bursa continues to load legacy Shelley-suffixed Bursa envelope names for constitutional committee hot keys, so existing key files remain usable.
./bursa key committee-hot --mnemonic-file seed.txt --account-index 0 --index 0 --signing-key-file committee-hot.skey --verification-key-file committee-hot.vkeyConstitutional Committee Hot Key with Key Files Example
⚠️ Please adjust path below.
./bursa key committee-hot --mnemonic-file seed.txt --signing-key-file /path/committee-hot.skey --verification-key-file /path/committee-hot.vkeyDijkstra 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-filewrites the verification key to the specified file.--output-filewrites the registration JSON to the specified file. When the command omits this flag, Bursa prints the registration JSON to standard output.
./bursa key bls --signing-key-file bls.skey --verification-key-file bls.vkey --output-file bls-registration.jsonThe 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
- wallet - Commands for generating wallet and the files needed to manage a Cardano wallet
- api - Commands for running API
- kes-agent - Commands for running the KES agent
- cert - Commands for generating various Cardano certificates
- hash - Commands for generating cryptographic hashes used in Cardano
- script - Commands for multi-signature operations
- address - Commands for working with Cardano addresses
- key - Commands for deriving individual keys from a mnemonic
- tx - Commands for signing transactions and assembling witnesses
- sign - Commands for signing data with CIP-8
- signer - Commands for running the remote signer service
Docs authored by Doc Holiday