Build Coldstar

Complete guide to building and running Coldstar from source. Transform any USB drive into a secure, disposable cold wallet.

Prerequisites

Before building Coldstar, ensure you have the following installed:

Quick Start

Get up and running in minutes with Docker:

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

# Run with Docker (fastest)
./docker-run.sh

# Or use the quickstart script
./quickstart.sh

Installation from Source

git clone https://github.com/devsyrem/coldstar
cd coldstar

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r local_requirements.txt

cd secure_signer
cargo build --release
cd ..

python main.py

Docker Setup

Docker provides the easiest and most consistent way to run Coldstar.

Quick Start with Docker

# 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

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

Build from Source

Python Application

The main application is written in Python and located in the src/ directory:

• iso_builder.py - USB ISO image building
• network.py - Network communication
• secure_memory.py - Memory security utilities
• transaction.py - Solana transaction handling
• ui.py - User interface components
• usb.py - USB drive handling
• wallet.py - Wallet key management

Rust Secure Signer

The cryptographic signing core is written in Rust for memory safety:

cd secure_signer

# Build release binary
cargo build --release

# Run tests
cargo test

# Build shared library for FFI
cargo build --release --lib

Key Rust modules:

• src/lib.rs - Main library interface
• src/crypto.rs - Cryptographic operations
• src/secure_buffer.rs - Memory-locked buffer management
• src/ffi.rs - Foreign function interface for Python

Initialize Wallet

Create a new cold wallet on a USB drive:

# Initialize wallet on USB drive
python main.py init /media/usb

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

Sign Transactions

Sign transactions with RAM-only key exposure:

# Sign a transaction
python main.py sign --wallet /media/usb --tx transaction.json

# Get public key
python main.py pubkey --wallet /media/usb

# Stake SOL
python main.py stake --wallet /media/usb --amount 10 --validator <pubkey>

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
python main.py 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

Integration Guide

FFI Integration (Python)

Use the Rust signer directly from Python via FFI:

# Import the Python integration layer
from secure_signer.python_integration import sign_transaction

# Sign a transaction
signature = sign_transaction(
    encrypted_container=container_json,
    passphrase="your_passphrase",
    transaction_bytes=tx_bytes
)

CLI Integration

Call the Rust signer as a subprocess for maximum isolation:

# Sign via CLI subprocess
./secure_signer/target/release/solana-signer \
    --container keypair.json \
    --transaction tx.json \
    --output signed.json

View on GitHub · Full Documentation · Back to Home