seine

External miner for Blocknet with pluggable CPU and NVIDIA GPU backends.

Quick Start

1. Optional: Install and sync Blocknet (daemon mode only)

If this is your first time running daemon mode, use the wrapper-managed flow:

blocknet install latest
blocknet start mainnet

This creates or reuses the managed config under ~/.config/bnt, starts the core, and writes the API cookie under ~/.config/bnt/data/mainnet/api.cookie unless you override data_dir in the Blocknet config.

You will be prompted to set a wallet password if needed. Once the daemon starts, wait for it to fully sync — you'll see [sync] progress messages reach 100%:

When sync is complete, type exit to shut down the daemon.

2. Run the miner

Option A — Pre-built binary (from Releases):

# Download the binary for your platform, then:
./seine

Option B — Build from source:

cargo build --release
./target/release/seine

Zero-argument mode (recommended)

Running ./seine with no flags is the default path. Default mode is pool.

First startup behavior:

• prompts for your Blocknet address
• prompts for pool URL (defaults to stratum+tcp://bntpool.com:3333)
• mining backends (CPU + NVIDIA when available)
• CPU thread count from available cores and RAM

First-run pool setup (visual)

1. Enter your Blocknet payout address when prompted.

2. Confirm the address prompt is filled before continuing.

3. Enter your pool endpoint and worker, then start mining.

These values are cached in:

• ./seine-data/seine.config.json by default (--data-dir changes the base directory)

# Force daemon mode explicitly; wrapper-managed installs need no daemon args
./seine --mode daemon

# Override pool endpoint and worker in pool mode
./seine --pool-url stratum+tcp://pool.example.com:3333 --pool-worker rig-01

Full CLI reference: docs/MINER_FLAGS.md

Requirements

Platform	CPU	GPU (NVIDIA)
Linux x86_64	works out of the box	CUDA driver + NVRTC libs
macOS x86_64	works out of the box	—
macOS ARM	works out of the box (Metal experimental)	—
Windows x86_64	works out of the box	CUDA driver + NVRTC libs

Each CPU thread needs ~2 GB RAM (Argon2id parameters). Seine auto-sizes thread count from available cores and memory. On x86_64, CPU builds include both AVX2 and AVX-512 kernels and dispatch at runtime when the host supports them.

Linux HugePages (CPU Throughput)

For best CPU mining performance on Linux, reserve explicit HugeTLB pages so each worker can map its Argon2 arena with MAP_HUGETLB (the backend falls back to THP if unavailable, which is often slower/inconsistent under fragmentation).

• Sizing rule (2 MB hugepages): nr_hugepages ~= threads * 1024
• Each CPU worker needs about 2 GiB of hugepages (1024 * 2 MB)
• Add small headroom if possible (for example +5%)

Example for --threads 4:

# 4 workers * 1024 pages/worker = 4096 hugepages (~8 GiB)
sudo sysctl -w vm.nr_hugepages=4096

If the kernel cannot allocate enough pages (fragmented memory), compact and retry:

echo 3 | sudo tee /proc/sys/vm/drop_caches
echo 1 | sudo tee /proc/sys/vm/compact_memory
sudo sysctl -w vm.nr_hugepages=4096

Verify reservation:

grep -E 'HugePages_Total|HugePages_Free|Hugepagesize' /proc/meminfo

Persist across reboots:

echo 'vm.nr_hugepages=4096' | sudo tee /etc/sysctl.d/99-seine-hugepages.conf
sudo sysctl --system

If a runtime sysctl -w vm.nr_hugepages=... request only allocates a fraction of the target, keep the value persisted and reboot. Early-boot reservation is much more reliable than trying to carve out tens of GiB of HugeTLB pages after the machine is already fragmented.

Runtime checks:

• Startup warns with exact sizing/commands when HugeTLB is under-provisioned (hugepages | CPU lanes=... need ...).
• Per-backend fallback warnings still appear if a worker falls back from MAP_HUGETLB (MAP_HUGETLB unavailable; hugepage coverage...).
• In practice, once many CPU lanes are active, hugepage coverage usually matters more than ISA-level tuning for backend throughput.

Configuration

All miner flags are documented in docs/MINER_FLAGS.md.

# Set CPU thread count explicitly
./seine --threads 4

# Force a specific backend (auto-detects by default)
./seine --backend cpu
./seine --backend nvidia
./seine --backend cpu,nvidia

# Wallet password (if wallet is encrypted)
./seine --wallet-password-file /path/to/wallet.pass

# Pool mode controls
./seine --address PpkFxY...
./seine --pool-url stratum+tcp://pool.example.com:3333
./seine --pool-worker rig-01

# Force daemon mode with wrapper-managed autodiscovery
./seine --mode daemon

# Custom direct-core layout override
./seine --mode daemon --api-url http://127.0.0.1:8332 --cookie /path/to/api.cookie

# Plain log output instead of TUI
./seine --ui plain

Note: in daemon mode, when --address matches the daemon wallet address, Seine keeps wallet pending/unlocked stats in the TUI. If it differs, TUI balance fields show --- for the override address.

In pool mode, Seine now also checks for a local daemon when daemon auth is available. If one responds, the TUI wallet panel keeps the pool balance and also shows the local daemon wallet balance.

Control API

Seine now supports a local control API for alternative frontends. Full API docs: docs/API.md

Service mode (idle until API start)

./seine --service --api-bind 127.0.0.1:9977

Then start mining via API:

curl -s -X POST http://127.0.0.1:9977/v1/miner/start \
  -H 'content-type: application/json' \
  -d '{
    "mode":"pool",
    "mining_address":"PpkFxY...",
    "pool_url":"stratum+tcp://pool.example.com:3333",
    "pool_worker":"rig-01"
  }'

Embedded mode (mine immediately + expose API)

./seine --api-server --api-bind 127.0.0.1:9977

/v1/miner/start accepts mode-specific fields (mode, pool_url, pool_worker, mining_address) plus optional daemon auth fields (token or cookie_path). In pool mode, daemon auth enables local daemon wallet balance alongside pool figures when a daemon is available.

Key endpoints:

• GET /v1/runtime/state
• POST /v1/miner/start
• POST /v1/miner/stop
• GET /v1/events/stream (SSE)
• GET /metrics

Control API endpoints are open by default; no API key is required.

Password sources (checked in order): --wallet-password, --wallet-password-file, SEINE_WALLET_PASSWORD env var, interactive prompt.

GPU Mining

NVIDIA

Requires CUDA driver and NVRTC libraries on the host. Seine compiles kernels at startup via NVRTC.

Current Blackwell / RTX 5090 tuning notes and measured benchmark frontier: docs/NVIDIA_5090_TUNING.md

# Auto-detect all GPUs
./seine --backend nvidia

# Select specific devices
./seine --backend nvidia --nvidia-devices 0,1

If CUDA initialization fails, NVIDIA backends are quarantined and CPU mining continues.

Metal (macOS ARM)

Metal support is experimental. Pre-built macOS ARM binaries include it. To build from source:

cargo build --release --no-default-features --features metal

Building from Source

Requires Rust and GNU Make.

Using Make:

# Default build (includes NVIDIA support)
make

# CPU-only build (no CUDA dependency)
make build-cpu

# Host-native CPU build (optimized for your specific CPU)
make build-native

# Run tests
make test

# Package a release zip for current platform
make release

# Bump Cargo version + create matching git tag
make tag-release TAG=v0.1.10

Or directly with Cargo:

# Default build (includes NVIDIA support)
cargo build --release

# CPU-only build (no CUDA dependency)
cargo build --release --no-default-features

# Host-native CPU build (optimized for your specific CPU)
./scripts/build_cpu_native.sh --cpu-only

On dedicated local x86_64 miners, build-native can still provide a small extra backend uplift on top of runtime AVX2/AVX-512 dispatch.

Benchmarking

Run offline benchmarks without a daemon connection:

./seine --bench --bench-kind backend --backend cpu --threads 1 --bench-secs 20 --bench-rounds 3

Further Reading

• AGENTS.md — Architecture details, tuning knobs, benchmarking harness
• docs/MINER_FLAGS.md — Complete CLI flag reference
• docs/API.md — Control API guide (REST, SSE, metrics)
• docs/openapi/seine-api-v1.yaml — OpenAPI specification
• CPU_OPTIMIZATION_LOG.md — CPU backend tuning history
• NVIDIA_OPTIMIZATION_LOG.md — NVIDIA backend tuning history