38. `kortana-cli`

kortana-cli is the authoritative, multi-functional command-line interface engineered in modern C++23 for interacting with the Kortana blockchain network (§28). Designed as a comprehensive administrative and operational suite, kortana-cli provides developers, validator operators, and enterprise integrators with direct command-line control over cryptographic key generation, non-custodial wallet management, native staking operations, on-chain parameter governance, transaction composition, smart contract deployment, and real-time state inspection.

The CLI architecture adheres strictly to a set of core security and operational principles codified in cmd/kortana-cli/main.cpp. First, the tool enforces a strict separation between read-only inspection commands and state-mutating transaction commands; a command that inspects state (such as contract call or account balance) is architecturally incapable of broadcasting state transitions. Second, private credentials and sensitive passwords are never accepted as command-line arguments or flags to prevent secrets from leaking into shell history files, process table listings (ps aux), or system monitoring daemons. Instead, kortana-cli prompts for passwords interactively with terminal echo disabled via prompt.cpp. Every RPC-backed subcommand accepts global flags including --rpc-url (defaulting to http://127.0.0.1:8545), --admin-token (for authenticated administrative endpoints), and --json (which suppresses human-readable formatting in favor of structured JSON streams suitable for shell pipelines and CI automation). Subcommands return standardized POSIX exit codes: 0 (kOk) for success, 1 (kFailed) for protocol/application rejections, and 4 (kUnreachable) when the target node daemon is offline or misconfigured.

38.1 Key Generation

The kortana-cli keygen subcommand creates cryptographically secure public and private key pairs across all cryptographic signature schemes utilized throughout the Kortana network architecture (§29). To eliminate weak entropy vulnerabilities, key generation draws raw entropy directly from the host operating system's cryptographic random number generator (/dev/urandom on POSIX systems or CryptGenRandom on Windows) via Libsodium's constant-time CSPRNG wrappers.

The keygen tool supports three distinct signature algorithms via the --type flag:

bls (BLS12-381): Generates a 32-byte private scalar and an uncompressed 48-byte public key (G1/G2) used exclusively by consensus validators for signing HotStuff view proposals, votes, and aggregated Quorum Certificates (QCs).
secp256k1: Generates an Ethereum-compatible 32-byte ECDSA private key and derived 20-byte EIP-55 checksummed address (0x...), used for standard KEVM transactions, Solidity smart contract interactions, and MetaMask compatibility.
ed25519: Generates a 32-byte Edwards-curve private key and corresponding ktn: address digest for high-speed native protocol interactions, P2P SIGMA handshake certificates, and CLI administration.

# Generate BLS12-381 consensus key pair for validator signing
kortana-cli keygen --type bls --out consensus.key

# Generate secp256k1 key pair for Ethereum-compatible accounts
kortana-cli keygen --type secp256k1 --out eth_wallet.key

# Generate Ed25519 key pair for native ktn: accounts and node identities
kortana-cli keygen --type ed25519 --out native_node.key

Generated key files are written to disk using atomic temporary file renaming and are locked with restrictive POSIX file permissions (0600 / read-write owner only). Output streams display both raw hexadecimal digests and checksummed address formats, ensuring operators can immediately verify public identities before funding accounts.

38.2 Wallet Management

The kortana-cli wallet and account subcommand suites implement hierarchical deterministic (HD) wallet generation and enterprise-grade key storage adhering strictly to BIP-39, BIP-32, BIP-44, and Ethereum Keystore V3 specifications (§29.1, §29.2).

The wallet workflow provides complete lifecycle key management:

wallet new [--words 12|24]: Generates cryptographically secure BIP-39 mnemonic seed phrases (128 bits of entropy for 12 words or 256 bits for 24 words). The tool calculates the SHA-256 entropy checksum, maps bits to the standardized 2,048-word English dictionary, and outputs the seed phrase to stdout while routing security warnings to stderr.
wallet derive --mnemonic "..." [--count N] [--path PATH]: Derives child accounts along standard BIP-44 derivation paths (m/44'/60'/0'/0/index for Ethereum-compatible accounts or m/44'/9002'/0'/0/index for native Kortana accounts). For safety, private key hex export requires the explicit --show-private-keys flag, which issues a prominent stderr warning regarding shell history persistence.
wallet validate --mnemonic "...": Validates mnemonic phrase lengths, dictionary word memberships, and cryptographic checksums, pinpointing exact misspelled words.
account create & account import: Converts seed phrases or raw private keys into password-encrypted Ethereum Keystore V3 JSON documents. Encryption utilizes the memory-hard scrypt Key Derivation Function configured with production parameters (N = 262144, r = 8, p = 1, dklen = 32), requiring 256 MB of RAM and approximately 1.0 second of CPU computation per attempt to defeat GPU/ASIC brute-force dictionary attacks. Keystores are stored in ~/.kortana/keystore/ using atomic writes that strictly refuse to overwrite existing files, protecting operators from accidental key destruction.

# Create new BIP-39 mnemonic wallet (outputs 12-word seed phrase)
kortana-cli wallet new --out operator.key

# Import an existing wallet from a 12 or 24-word seed phrase
kortana-cli wallet import --mnemonic "twelve word secret recovery seed phrase here"

# Export password-encrypted Ethereum Keystore V3 JSON file
kortana-cli wallet export --key operator.key --out keystore.json --password-file pass.txt

Wallets derive addresses deterministically according to standard BIP-44 derivation paths (m/44'/60'/0'/0/0).

38.3 Staking Commands

The kortana-cli staking subcommand family gives validator operators and delegators direct command-line control over all native Proof-of-Stake consensus actions, formatting and broadcasting native protocol transactions (Types 0x30 through 0x36) defined in tx/payloads.hpp (§23, §24):

staking stake (Type 0x30): Bonds native DNR to register a new consensus validator node. The operator supplies the self-stake amount, path to the BLS12-381 public consensus key file, declared commission rate in basis points (e.g. 500 for 5%), and funding keystore account.
staking unstake (Type 0x31): Unbonds validator stake, transitioning funds into the timelocked unbonding queue for the mandatory 168-epoch (~7-day) cooling window.
staking delegate & staking undelegate (Types 0x32, 0x33): Allows token holders to non-custodially delegate liquid DNR voting weight to active validators or withdraw existing delegations without transferring asset ownership.
staking claim-rewards (Type 0x36): Claims accrued staking rewards accumulated in the on-chain reward distributor contract.
staking delegate-poh & staking undelegate-poh: Authorizes or revokes a third-party high-performance compute node to generate continuous SHA-256 dPOH tick streams on behalf of the validator (§8.5).
Read-Only Telemetry: Subcommands staking validators, staking info <addr>, and staking params query the active validator set, individual proposal success rates, consensus voting power distributions, and the global supply conservation ledger without creating on-chain transactions.

# Stake native DNR to register as an active validator
kortana-cli tx stake --amount 100000DNR --bls-key consensus.key --key operator.key --rpc https://poseidon-rpc.testnet.kortana.xyz/

# Initiate unstaking of bonded validator funds (starts 168-epoch unbonding period)
kortana-cli tx unstake --amount 50000DNR --key operator.key

# Delegate voting weight to an active validator
kortana-cli tx delegate --to ktn:validator_addr --amount 1000DNR --key user.key

# Claim accrued staking rewards
kortana-cli tx claim-rewards --key user.key

38.4 Governance Commands

The kortana-cli gov suite enables decentralized on-chain parameter governance (§26), allowing network participants to propose, debate, and vote on adjustments to protocol constants stored in the ParamStore system contract (0x0000000000000000000000000000000000000102):

gov propose (Type 0x34): Submits a formal Kortana Improvement Proposal (KIP). The command accepts the target parameter name (such as min_gas_price, unbonding_delay_epochs, or base_fee_max_change_bps), the proposed integer value, and a required DNR proposal deposit bond (e.g. 1,000 DNR). The bond is escrowed in the governance pool to prevent proposal spam.
gov vote (Type 0x35): Casts a stake-weighted ballot on an active proposal. The voter specifies the numeric proposal ID, funding account, and vote choice (yes, no, or abstain). Voting power is evaluated dynamically based on the account's bonded stake at the proposal's snapshot block height.
gov proposals & gov params: Lists all active, passed, and rejected governance proposals alongside current vote tallies, quorum percentages (40% required), supermajority margins (66.7% required), and execution timelock activation block heights.

# Submit an on-chain parameter change proposal
kortana-cli tx gov propose \
  --param "min_gas_price" \
  --value 2000000000 \
  --deposit 1000DNR \
  --key user.key

# Cast a stake-weighted vote on an active proposal (options: yes, no, abstain)
kortana-cli tx gov vote --proposal 1 --vote yes --key user.key

38.5 Genesis Initialization

The kortana-cli genesis and config command modules manage node bootstrap configurations, database initialization, and operational environment verification (§27, §35):

genesis init: Parses a genesis JSON document (such as genesis.json generated by ops/make-genesis.py), verifies the 10 Billion DNR initial token distribution across ecosystem allocations, validates that the validator set satisfies the N >= 3f + 1 Byzantine fault tolerance invariant, computes the genesis block header (Height 0) and initial state root hash, and writes the baseline database directly into the RocksDB headers, state_trie, and validators column families.
config check <config.toml>: Performs non-destructive static validation of a node configuration file. It verifies TOML syntax, validates IP address and port bindings, checks NVMe disk path permissions, confirms memory cache limits, and tests local IPC socket connectivity to kortana-validator.
config show: Dumps the active runtime configuration with resolved default values, sensitive tokens redacted, and environment variable overrides displayed for operational debugging.

# Initialize local node database from genesis.json
kortana-cli genesis init --chain-id 72511 --file genesis.json --data-dir ~/.kortana/data/

The command parses account allocations, computes the initial state root hash, validates supply conservation, and writes the genesis block (height 0) to disk.

38.6 Transaction Commands

The kortana-cli tx and contract command groups handle the low-level encoding, signing, gas estimation, broadcasting, and debugging of transactions across both execution environments (§22, §25):

tx send: Constructs and broadcasts a standard value transfer. The tool automatically fetches the sender's on-chain nonce, queries current EIP-1559 base fee and priority tip metrics via JSON-RPC, prompts the operator to unlock their keystore, signs the transaction envelope (secp256k1 ECDSA or Ed25519), and transmits the RLP-encoded payload via eth_sendRawTransaction.
tx status <hash> & tx decode <raw_hex>: Inspects execution receipts, confirms block inclusion heights, decodes emitted event logs, and unpacks raw transaction byte streams into human-readable field layouts.
contract deploy --code <path.kvm|hex>: Deploys a compiled KVM module or EVM bytecode payload to the blockchain, calculating the deterministic contract address and displaying gas consumed.
contract call vs contract send: Strictly separates read-only contract queries from state mutations. contract call executes methods in an isolated sandbox via eth_call without gas cost or state updates, whereas contract send drafts, signs, and broadcasts state-mutating transactions.

# Send native DNR value transfer to recipient address
kortana-cli tx send --to 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 --amount 5DNR --key user.key --rpc https://poseidon-rpc.testnet.kortana.xyz/

# Deploy a compiled KVM binary module to the blockchain
kortana-cli tx deploy --code build/Contract.kvm --key deployer.key --rpc https://poseidon-rpc.testnet.kortana.xyz/

38.7 Query Commands

The kortana-cli query, account, and node subcommands provide real-time command-line telemetry and state inspection without requiring external Web3 explorers:

Address Resolution: All query commands utilize canonical_address() in cmd/kortana-cli/main.cpp, seamlessly accepting either Ethereum checksummed hex (0x...) or native Kortana format (ktn:...) and validating checksums prior to querying the node daemon.
Account Inspection: account balance <addr> and account nonce <addr> query the unified Merkle-Patricia State Trie directly, formatting balances simultaneously in human-readable Dinar (DNR), gwei, and raw wei.
Node Telemetry: node status and node peers display current block height, sync stage, dPOH tick rate, consensus view, and authenticated P2P peer tables.
kvm inspect <module.kvm>: Disassembles local KVM binary modules, printing magic headers, version tags, constant pool tables, instruction counts, entry point offsets, and cryptographic module hashes (code_hash).
krs Subcommands: Inspects the on-chain Kortana Resource Standards registry, querying standard lifecycle states (Draft, Review, Active), resource metadata, and token holdings across addresses.

# Query account liquid balance, nonce, and code hash
kortana-cli query balance 0x70997970C51812dc3A010C7d01b50e0d17dc79C8

# Query block metadata by height or hash
kortana-cli query block latest --json

# Query transaction execution receipt and emitted logs
kortana-cli query tx 0x1234abcd...

38. kortana-cli