Overview
This document specifies how Cowboy private keys are stored on disk, encoded for transport, and backed up by users. Cowboy uses a self-describing, checksummed PEM envelope as the primary storage format, and BIP-39 mnemonics with BIP-32/44 HD derivation as the human-readable backup and multi-key format. Cowboy uses secp256k1 (ECDSA) for all account keys. This is the same curve used by Ethereum and Bitcoin, which gives Cowboy native Ethereum key compatibility — the same private key can control both a Cowboy account and an EVM address.Protocol signing keys and slots
The on-chainSigningPublicKey and SignatureSlot formats are specified by
CIP-40 §§7.6–7.7.
Stored public keys carry algorithm IDs: secp256k1 1, Ed25519 2, P-256 3 and P-384 4.
A registered algorithm is accepted only by the field’s declared policy. Transaction
slots accept secp256k1 in native or EIP-712 mode at genesis; P-256/P-384 are used only
by the TEE quote policy. Public-key JSON is a lowercase hex string of the tagged
wire bytes. Signature-slot JSON has exactly algorithm, mode, public_key
and signature, with hex byte strings and null for an absent key.
Transaction signing always takes the real chain ID and genesis instance from
/chain-info; other signed objects use the identity-bound codec construction.
These protocol encodings do not change the private-key file envelope below.
Key Format: PEM Envelope
File Format (~/.cowboy/keys/<name>)
The CLI keeps signing keys in its keystore, ~/.cowboy/keys/<name>, one file per key. The primary on-disk format is a PEM-style envelope with base64-encoded key material:
Structure
Specification
1
Header and Footer
The file MUST begin with
-----BEGIN COWBOY PRIVATE KEY----- and end with -----END COWBOY PRIVATE KEY-----, each on their own line. These markers make the format self-describing and prevent accidental use of non-key files.2
Metadata Headers
Between the header and the base64 body come two
Key: Value metadata lines:The parser reads any other line as part of the base64 body, so an unknown header makes the key fail to decode.
3
Body
Standard base64 (RFC 4648) encoding of the raw 32-byte private key. The CLI writes it on one line.
4
Whitespace
The CLI writes no trailing newline after the footer. The parser ignores whitespace around the envelope and around each line, so a newline added by an editor is fine.
Address Derivation
From a secp256k1 private key, the Cowboy address is derived using the Ethereum-standard method:- Compute the uncompressed public key (64 bytes, without the
04prefix). - Hash with Keccak-256.
- Take the last 20 bytes as the address.
0x... address on both chains.
Checksum Calculation
The checksum provides corruption detection:- Decodes the base64 body to get the raw key bytes.
- Computes
SHA-256(raw_key_bytes). - Compares the first 16 hex characters against the
Checksumheader. - If they don’t match, prints an error and refuses to use the key.
Parsing Rules
Example: Full Round-Trip
Output
Backup & Recovery: BIP-39 Mnemonic
For human-readable backup and recovery, Cowboy uses BIP-39 mnemonics as the seed format. Combined with BIP-32/44 hierarchical deterministic (HD) derivation, a single 24-word mnemonic can derive an unlimited number of Cowboy keys.Create
Output
Import
Put the phrase in a file that only you can read, so it stays out of your shell history:Output
cowboy wallet export prints a key as raw hex, for moving one account to another wallet. It can’t print the phrase.
Mnemonic Specification
Encoding (BIP-39)
Encoding (BIP-39)
The mnemonic is generated from 256 bits of cryptographically random entropy:
- Generate 32 bytes (256 bits) of random entropy.
- Compute SHA-256 of the entropy; take the first 8 bits as a checksum.
- Concatenate: 256 bits of entropy + 8 bits of checksum = 264 bits.
- Split into 24 groups of 11 bits.
- Each 11-bit value maps to a word in the BIP-39 English wordlist (2048 words).
"mnemonic" (no user passphrase by default). This seed feeds into BIP-32 HD derivation.Wordlist
Wordlist
Only the BIP-39 English wordlist is supported. The wordlist is well-established, widely available, and avoids internationalization complexity.
HD Derivation (BIP-32/44)
Cowboy uses standard BIP-32/44 hierarchical deterministic derivation to produce account keys from a mnemonic seed. This is the same scheme used by Ethereum wallets (MetaMask, Ledger, Trezor), which means:- A Cowboy mnemonic imported into MetaMask produces the same addresses
- A MetaMask/Ledger mnemonic imported into Cowboy produces the same addresses
Derivation Path
Cowboy uses Ethereum’s coin type (
60') rather than registering a separate coin type. This is intentional — Cowboy accounts are Ethereum addresses, and using the same derivation path means full wallet compatibility.
Deriving Multiple Keys
To keep another account from the same phrase, import it at its index, and list the addresses to check them:Output
Environment Variable Format
When using theCOWBOY_PRIVATE_KEY environment variable, the value is the raw 32-byte key in hex encoding (with or without 0x prefix):
- It’s a single-line value (no PEM headers)
- It’s commonly used for secrets in environment variables across the ecosystem
- It’s easy to set programmatically
CLI Commands
Wallet commands:Security Considerations
File Permissions
File Permissions
The CLI MUST create the keystore folder
~/.cowboy/keys with mode 0700 and each key file in it with mode 0600 (owner read/write only). On load, the CLI MUST refuse a key file that group or others can access, and MUST NOT read ~/.cowboy/keys or a key file in it through a link.Mnemonic Handling
Mnemonic Handling
When displaying mnemonics, the CLI MUST:
- Print a warning about secure storage before showing the words.
- Never write mnemonics to log files or shell history.
- Clear terminal scrollback is recommended but not enforced.
--mnemonic-file, so the phrase stays out of your shell history.When to Use Each Format
Further Reading
- Key Auto-Discovery — How the CLI finds keys
- cowboy wallet — Wallet command reference
- Cowboy Design Decisions — Cryptographic design rationale