Coldstar Documentation

The cold signing system for Solana. Transform any USB drive into disposable cold storage.

Introduction

Coldstar is a command-line based cold wallet system that transforms any standard USB drive into a disposable signing medium, with private keys existing in decrypted form only briefly and only in system memory.

Rather than introducing another piece of hardware into an already complex trust landscape, Coldstar proposes a simpler and more verifiable model. It is designed for developers, traders, and security-conscious operators who value transparency, control, and operational flexibility over consumer-oriented convenience.

Why Coldstar?

• RAM-only signing - Keys exist in decrypted form only during signing
• Disposable hardware - Use any USB drive, rotate or destroy at minimal cost
• CLI-first - Scriptable, automation-friendly, CI/CD ready
• Open source - Fully inspectable and verifiable codebase
• No vendor lock-in - No proprietary hardware or secure elements

Installation

Prerequisites

• A Unix-like operating system (Linux, macOS)
• A standard USB drive (any size, any brand)
• Rust toolchain (for building from source)

Install from Source

# Clone the repository
git clone https://github.com/coldstar-wallet/coldstar
cd coldstar

# Build the project
cargo build --release

# Install globally (optional)
cargo install --path .

Verify Installation

coldstar --version
# coldstar 0.1.0

Quick Start

1. Initialize a Cold Wallet

Insert a USB drive and initialize it as a Coldstar wallet:

# Initialize wallet on USB drive
coldstar init /media/usb

# You'll be prompted to create a password
# This password encrypts your keys with AES-256

2. Get Your Public Key

# Export your public key (safe - no secrets exposed)
coldstar pubkey --wallet /media/usb

# Output: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU

3. Sign a Transaction

# Sign a transaction (keys decrypted in RAM only)
coldstar sign --wallet /media/usb --tx transaction.json

# Enter your password when prompted
# Keys are decrypted, transaction signed, keys erased

Architecture

Coldstar's architecture is intentionally simple. It consists of three components:

1. Encrypted Storage (USB) - Your USB drive stores encrypted key material using AES-256
2. Coldstar CLI - The command-line tool that handles encryption, decryption, and signing
3. System RAM - Where keys are briefly decrypted for signing operations

RAM-Only Signing

The core security property of Coldstar is ephemeral RAM-only signing. Here's how it works:

1. User initiates a signing operation via CLI
2. Coldstar reads encrypted key material from USB
3. User enters password; keys are decrypted in RAM only
4. Transaction is signed in memory
5. Decrypted keys are immediately zeroed from memory
6. Signed transaction is output (ready to broadcast)

At no point do plaintext private keys exist on disk. The USB drive contains only encrypted material. This dramatically reduces the attack surface compared to hardware wallets where keys persist for the device's lifetime.

Encryption

Coldstar uses industry-standard cryptographic primitives:

CLI: coldstar init

Initialize a new cold wallet on a USB drive.

coldstar init <path> [options]

Options:
  --import <seed>    Import existing seed phrase
  --force            Overwrite existing wallet
  --help             Show help

CLI: coldstar sign

Sign a transaction with RAM-only key exposure.

coldstar sign [options]

Options:
  --wallet <path>    Path to wallet on USB
  --tx <file>        Transaction file (JSON)
  --output <file>    Output signed transaction
  --help             Show help

CLI: coldstar stake

Stake SOL with cold signing.

coldstar stake [options]

Options:
  --wallet <path>       Path to wallet on USB
  --amount <sol>        Amount of SOL to stake
  --validator <pubkey>  Validator pubkey to delegate to
  --help                Show help

CLI: coldstar pubkey

Export your public key (safe, no secrets exposed).

coldstar pubkey [options]

Options:
  --wallet <path>    Path to wallet on USB
  --help             Show help

Trust Model

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

Comparison

Threat Model

What Coldstar Protects Against

• Remote key extraction (keys not persistently stored)
• Firmware backdoors (no firmware)
• Supply chain attacks (user-supplied USB)
• Physical device seizure (destroy/replace USB cheaply)
• Long-term key exposure (keys exist briefly in RAM)

What Coldstar Does NOT Protect Against

• Compromised operating system at signing time
• Malware with RAM access during signing
• Shoulder surfing / password capture
• User error (weak passwords, lost USBs)

Docker Setup

Coldstar can be run in a Docker container for consistent environments and easy deployment.

Quick Start with Docker

# Clone the repository
git clone https://github.com/ChainLabs-Technologies/coldstar
cd coldstar

# Build and run with the quick script
./docker-run.sh

# Or build manually
docker build -t coldstar .
docker run -it --rm \
    -v $(pwd)/wallet:/wallet \
    -v $(pwd)/transactions:/transactions \
    coldstar

Using Docker Compose

# Start Coldstar (mainnet)
docker-compose run coldstar

# Start development mode (devnet)
docker-compose run coldstar-dev

# Build fresh image
docker-compose build --no-cache

Docker Architecture

The Docker image uses a multi-stage build:

1. Builder stage - Compiles the Rust secure signer with full toolchain
2. Runtime stage - Slim Python image with only runtime dependencies

USB Device Access (Linux)

To access USB devices from within Docker on Linux:

# Run with USB device passthrough
docker run -it --rm \
    --privileged \
    --device=/dev/sdb:/dev/sdb \
    -v $(pwd)/wallet:/wallet \
    coldstar

Automation & CI/CD

Coldstar's CLI-first design makes it ideal for automated workflows:

#!/bin/bash
# Example: Automated signing script

# Build transaction
solana transfer recipient.json 10 --sign-only --output tx.json

# Sign with Coldstar (password from env or secure input)
coldstar sign --wallet /media/usb --tx tx.json --output signed.json

# Broadcast
solana send signed.json

Air-Gapped Setup

For maximum security, use Coldstar on an air-gapped machine:

1. Air-gapped machine - A computer never connected to the internet
2. Build Coldstar - Transfer source code via USB, build on air-gapped machine
3. Initialize wallet - Create wallet on air-gapped machine
4. Sign offline - Transfer unsigned transactions via USB, sign offline
5. Broadcast online - Transfer signed transactions to online machine for broadcast

View on GitHub · Back to Home