Coldstar Documentation

CLI-first cold wallet system that transforms any USB drive into a disposable, RAM-only signing medium for Solana.

Introduction

Coldstar is a CLI-first cold wallet system that transforms any standard USB drive into a disposable, RAM-only signing medium. It eliminates long-lived private key exposure by ensuring keys are decrypted only in volatile memory and only for the duration of transaction signing.

Coldstar is designed for developers, traders, and operators who value verifiability, automation, and explicit control over convenience-oriented hardware wallets.

Core Idea

Traditional hardware wallets rely on permanent devices that store private keys for their entire lifetime. This creates persistent trust anchors, supply-chain risk, and physical attack surfaces.

Coldstar challenges this model by removing permanent trusted hardware entirely.

Instead of trusting devices, Coldstar trusts:

• Open-source, auditable software
• User-controlled operating systems
• Extremely short-lived key exposure in RAM

Private keys are:

• Encrypted at rest on user-supplied USB storage
• Decrypted only in system memory
• Explicitly wiped after signing completes

Key Properties

How It Works

1. A standard USB drive is initialized using the Coldstar CLI
2. Cryptographic key pairs are generated and encrypted directly onto the USB
3. When signing is required:
   • Encrypted key material is loaded into memory
   • Decryption occurs only in RAM
   • The transaction is signed
4. Decrypted key material is immediately erased from memory
5. No plaintext keys persist on disk or hardware

Encryption & Key Generation

Coldstar's security model depends on understanding exactly where sensitive data exists in physical hardware and how it's protected at each stage.

Key Generation and Encryption (Initial Setup)

During wallet initialization, the following steps occur:

1. Random Seed Generation: CPU's hardware RNG (/dev/urandom) generates a 32-byte Ed25519 seed
2. Passphrase Entry: User provides a passphrase for encryption
3. Key Derivation (Argon2id): Memory-hard operation (64 MB, 3 iterations) derives a 32-byte AES key
4. AES-256-GCM Encryption: Private key is encrypted with a 12-byte random nonce
5. Immediate Zeroization: All plaintext keys are overwritten with zeros in RAM

Encrypted Container Format

{
  "version": 1,
  "salt": "base64_encoded_32_bytes",
  "nonce": "base64_encoded_12_bytes",
  "ciphertext": "base64_encoded_48_bytes",
  "public_key": "base58_encoded_pubkey"
}

Transaction Signing (Decryption)

When signing a transaction, the following secure process occurs:

1. Read Encrypted Container: Encrypted data read from USB to Python memory space
2. FFI Call to Rust: Encrypted data passed to isolated Rust memory space
3. Key Re-Derivation: Argon2id derives AES key from passphrase in mlock'd RAM
4. AES-256-GCM Decryption: Private key decrypted into locked memory buffer
5. Ed25519 Signing: Transaction signed (~100 microseconds in CPU)
6. Automatic Cleanup: Rust Drop trait zeroizes all sensitive data
7. Return to Python: Only signature (public data) crosses FFI boundary

Memory Protection Mechanisms

mlock() - Preventing Swap to Disk

Private keys are stored in mlock'd memory pages that cannot be swapped to disk by the operating system:

• Normal RAM: OS may swap to disk/SSD
• mlock'd RAM: Locked in physical memory, cannot be swapped

Memory Zeroization

Before deallocation, all sensitive buffers are overwritten with zeros:

• Uses the zeroize crate (constant-time, not optimized out)
• Prevents recovery from heap analysis
• Protects against cold boot attacks (partially)

Panic Safety

Rust's Drop trait guarantees cleanup runs even if the signing operation panics:

• Normal flow: Drop runs, keys zeroized
• Panic flow: Drop STILL runs, keys zeroized

Data States Across Hardware

Threat Model

What Coldstar Protects Against

• Long-lived key exposure
• Firmware backdoors (no firmware)
• Hardware supply-chain manipulation
• Persistent device compromise
• Seizure or fingerprinting of signing hardware
• Physical device seizure (destroy/replace USB cheaply)

What Coldstar Does NOT Protect Against

• Compromised operating system at signing time
• Malware with RAM access during signing (requires root + precise timing)
• Hardware keyloggers capturing passphrase
• Cold boot attacks (if RAM physically extracted within seconds)
• User error (weak passwords, lost USBs)

First Instance Boot Process

Every time you plug your USB cold wallet into a machine, Coldstar automatically:

• Detects if this is the first time on this machine/session
• Verifies all critical wallet files (keypair.json, pubkey.txt)
• Restores missing or corrupted files from backup (if needed)
• Creates/updates backups of valid files
• Updates boot instance markers

This is not a restoration function - it's an intelligent boot detection mechanism that ensures wallet integrity across different machines and reboots.

How First Boot Works

1. Boot Detection: Generates unique boot instance ID from machine hostname + process + timestamp
2. File Verification: Checks critical files for existence and corruption (0-byte detection)
3. Smart Restoration: Only restores files if actually missing or corrupted
4. Automatic Backups: Creates backups in .coldstar/backup/ directory on USB

USB Storage Structure

Supported Use Cases

Coldstar is asset-agnostic and designed to support modern on-chain workflows:

• Native Solana transactions
• SPL tokens
• Stablecoins (USDC, USDT)
• Tokenized commodities (e.g. PAXG)
• Tokenized equities (xStocks)
• Custom program instructions
• Solana staking and delegation
• NFTs and collectibles

System Architecture

Coldstar consists of three main layers:

User Application Layer

• Python CLI (Coldstar)
• Transaction building
• Network communication
• User interface

Integration Layer

• FFI Integration: ctypes bindings, shared library, direct function calls
• CLI Subprocess: JSON stdin/stdout, process isolation

Rust Signing Core

• Public API: sign_transaction(), create_encrypted_container()
• Secure Memory: mlock/VirtualLock, automatic zeroization
• Dependencies: ed25519-dalek, aes-gcm, argon2, zeroize, region

Detailed Signing Flow

The signing process consists of 10 phases:

1. Input Preparation: Load encrypted container, get passphrase, prepare unsigned TX
2. Enter Rust Secure Zone: Encrypted data crosses FFI boundary
3. Key Derivation: Argon2id computes AES key, passphrase zeroized
4. Memory Allocation: SecureKeyBuffer created with mlock()
5. Decryption: AES-256-GCM decryption to temporary buffer
6. Secure Transfer: Copy to locked buffer, zeroize temp buffer
7. Signing: Ed25519 signature generation
8. Result Preparation: Build signed transaction
9. Automatic Cleanup: Drop trait zeroizes all buffers
10. Return to Python: Only public signature crosses boundary

Integration Modes

FFI Mode (Recommended for Production)

• Fastest (~0.1ms overhead)
• Direct function calls via ctypes
• Requires compiled library for platform

CLI Mode (Maximum Isolation)

• Separate process for each signing operation
• Automatic cleanup on process exit
• Slower (~10-50ms overhead)
• Maximum security isolation

Comparison with Hardware Wallets

Trust Model

Coldstar's trust model is fundamentally different from hardware wallets:

View on GitHub · Build Guide · Back to Home