Skip to main content

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.
Design Principle: Keys should be self-describing, checksummed, and familiar. A developer should be able to cat ~/.cowboy/keys/default and immediately understand what they’re looking at.

Protocol signing keys and slots

The on-chain SigningPublicKey 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:
  1. Compute the uncompressed public key (64 bytes, without the 04 prefix).
  2. Hash with Keccak-256.
  3. Take the last 20 bytes as the address.
This means a Cowboy address is an Ethereum address — the same key produces the same 0x... address on both chains.

Checksum Calculation

The checksum provides corruption detection:
On load, the CLI:
  1. Decodes the base64 body to get the raw key bytes.
  2. Computes SHA-256(raw_key_bytes).
  3. Compares the first 16 hex characters against the Checksum header.
  4. If they don’t match, prints an error and refuses to use the key.
Sixteen hex characters (64 bits) catch accidental corruption. They don’t stop tampering, because anyone who can edit the file can replace both the key and the checksum: file permissions do that job. A file with an older 4-character checksum still loads, with a warning.

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
The CLI shows the phrase only here, so write it down and store it safely. Anyone with these words controls every account derived from them.

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

The mnemonic is generated from 256 bits of cryptographically random entropy:
  1. Generate 32 bytes (256 bits) of random entropy.
  2. Compute SHA-256 of the entropy; take the first 8 bits as a checksum.
  3. Concatenate: 256 bits of entropy + 8 bits of checksum = 264 bits.
  4. Split into 24 groups of 11 bits.
  5. Each 11-bit value maps to a word in the BIP-39 English wordlist (2048 words).
The mnemonic is then converted to a 512-bit seed via PBKDF2-HMAC-SHA512 (2048 rounds) with the passphrase "mnemonic" (no user passphrase by default). This seed feeds into BIP-32 HD derivation.
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.
The default account is index 0. Pass --index to create-mnemonic or import-mnemonic for another.

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 the COWBOY_PRIVATE_KEY environment variable, the value is the raw 32-byte key in hex encoding (with or without 0x prefix):
Hex is the right choice for environment variables because:
  • 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

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.
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.
To import a mnemonic, prefer --mnemonic-file, so the phrase stays out of your shell history.

When to Use Each Format

Further Reading