Coldstar Documentation

Air-gapped cold wallet that turns any USB drive into secure key storage for Solana.

What is Coldstar?

Coldstar is an open-source cold wallet for Solana. Instead of buying a $200 hardware wallet, you use any standard USB drive as encrypted key storage. Your private key is never stored in plaintext anywhere — it only exists in your computer's RAM for about 100 microseconds while a transaction is being signed, then it's immediately wiped.

It's a CLI tool built for developers, traders, and operators who want to verify their own security — not trust a vendor's firmware.

Installation

You need Python 3.10+ and a USB drive. That's it. Rust is optional but recommended for the secure signer.

# 1. Clone the repo
git clone https://github.com/devsyrem/coldstar
cd coldstar

# 2. Install Python dependencies
pip install -r local_requirements.txt

# 3. Launch — Coldstar guides you through setup
python coldstar.py

On first launch, Coldstar will detect your USB drive and walk you through creating or importing a wallet. If Rust is installed, the secure signer compiles automatically. If not, a Python fallback signer is used.

How It Works

There are three stages: setup, signing, and broadcast. Here's what happens at each step.

1. Setup: You create or import a wallet. Coldstar encrypts your private key with a passphrase you choose and saves it to the USB drive. The plaintext key is immediately wiped from memory.
2. Signing: When you send a transaction, Coldstar reads the encrypted key from USB, decrypts it in locked RAM (memory that can't be swapped to disk), signs the transaction, and wipes the key. The whole process takes about 100 microseconds.
3. Broadcast: Only the transaction signature (public data) leaves the signing process. Your private key never touches the network, never touches disk, and never leaves the signing process.

Encryption & Key Storage

When you create a wallet, here's what happens under the hood:

1. Key generation: A 32-byte private key is created from your system's hardware random number generator (/dev/urandom).
2. Passphrase protection: Your passphrase is run through Argon2id — a memory-hard algorithm that uses 64 MB of RAM and 3 iterations. This makes brute-force attacks extremely slow, even with specialized hardware.
3. Encryption: The private key is encrypted with AES-256-GCM (the same standard used by governments and banks) and saved to your USB drive.
4. Cleanup: The plaintext key is overwritten with zeros in RAM. Nothing sensitive remains in memory.

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"
}

RAM Signing Process

This is the most security-critical part of Coldstar. When you sign a transaction, here's exactly what happens:

1. Read: The encrypted key file is loaded from USB into Python. At this point, it's still encrypted — Python never sees the real key.
2. Handoff: The encrypted data is passed to the Rust signer (a compiled binary, not a script). This is where all sensitive work happens.
3. Decrypt: Inside Rust, your passphrase is used to re-derive the encryption key. This happens in locked memory — memory that the OS cannot swap to disk.
4. Sign: The private key is decrypted, used to sign the transaction (~100 microseconds), then immediately overwritten with zeros.
5. Return: Only the signature (public data) is returned to Python. The private key never leaves the Rust process.

Where your key exists at each stage

Memory Protection

Three mechanisms work together to ensure your private key doesn't leak through memory:

mlock — Preventing Swap

Your OS can move idle memory to disk (swap). If your private key got swapped, it could be recovered later from the disk. Coldstar uses mlock() to tell the OS: "keep this memory in physical RAM, never write it to disk."

Zeroization — Cleaning Up

After signing, all buffers containing key material are overwritten with zeros. This uses Rust's zeroize crate, which guarantees the compiler won't optimize away the cleanup (a common problem in C/C++ where the compiler removes "unnecessary" memory writes).

Panic Safety — Crash Protection

Even if the signing process crashes mid-operation, Rust's Drop trait guarantees the cleanup code still runs. Your key is zeroized in all code paths — success, error, or crash.

Threat Model

No security tool protects against everything. Here's exactly what Coldstar handles and what it doesn't.

What Coldstar protects against

• Key theft from disk: Your private key is never stored in plaintext. Even if your computer is compromised, attackers find only encrypted data.
• Firmware backdoors: There's no proprietary firmware to backdoor. Coldstar is open-source Python + Rust that you can audit yourself.
• Supply-chain attacks: Any $5 USB drive works. No specialized hardware means no supply chain to tamper with.
• Physical seizure: If someone takes your USB, they get encrypted noise. Destroy it and restore from backup.
• Swap file forensics: Memory locking (mlock) prevents your key from being written to swap space on disk.

What Coldstar does NOT protect against

• Compromised OS: If an attacker has root access to your machine while you're signing, they can read RAM directly. Mitigation: use an air-gapped machine.
• Keyloggers: A hardware keylogger can capture your passphrase as you type it. Mitigation: inspect your hardware, use a trusted keyboard.
• Weak passphrases: Argon2id makes brute-force slow but can't save a 4-character password. Use a strong, unique passphrase.
• User error: If you lose all copies of your USB and backup, your key is gone. Keep backups in separate physical locations.

USB Storage Structure

Here's what Coldstar creates on your USB drive:

Every time you plug in your USB, Coldstar checks that your wallet file hasn't been corrupted. If it has, it automatically restores from the latest backup.

Coldstar vs Hardware Wallets

Different security models with different trade-offs. Neither is universally better — it depends on your threat model.

View on GitHub · Build Guide · Back to Home