Files
alkane-os/README.md
T
noah 289ad40d86
next-build / build (push) Canceled after 0s
Select BM1362 work encoding for captured replay
2026-10-16 08:11:46 -06:00

4.5 KiB

Alkane OS

CI tests coverage bench bench coverage lines of code dependencies code quality license

Mining and tuning core for Alkane control boards. The SDK builds board images and supplies the hardware backend. Management is planned over SSH, a cgminer-compatible port 4028, and a minimal API; no web frontend runs on the board.

Status

The CLI lists target obligations with alkane-os --list-targets. It can also mine through the SDK simulator HAL and a Stratum V1 pool. No production board backend or network management API is installed.

The library has a versioned Unix-socket HAL client, BM1366 mining-session logic, Stratum V1 job and share handling, SHA-256d share checks for BM1362 and BM1366, and a Litecoin Scrypt proof verifier. Its fault path requests PSU shutdown on a sensor error. Failed shutdown faults the miner until a retry succeeds. Work IDs stay reserved until a confirmed chain reset or PSU shutdown. The backend still needs a power lease, an independent watchdog, and a board-validated temperature limit.

Host tests replayed real captured nonces through the SDK HAL and a strict loopback pool: 33 distinct BM1366 shares and one BM1362 share received matching ACCEPT responses. The 33rd BM1366 job tested safe work-ID reuse after a chain reset. These tests do not establish physical chain control, stock-firmware boot, or production pool acceptance. The Scrypt verifier matches Litecoin's block 29255 vector; BM1489/BM1491 report handling and L7/L9 mining remain open.

For a simulator HAL socket and a Stratum V1 pool, set ALKANE_POOL_PASSWORD and run alkane-os --mine-simulator HAL_SOCKET POOL_ADDRESS WORKER BM1366. Select BM1362 for that chip's captured job format. The optional argument after the chip stops after that many accepted shares. The command uses the simulator's 80 C temperature limit and exits on a pool or hardware fault. The SDK HAL server must cut power when its client stalls or disconnects.

Release gate

All 64 theoretical same-vendor control-board/chip pairings are required: 52 Bitmain and 12 WhatsMiner. A stock image may reject a pairing if the simulator records its first genuine rejection gate; Alkane OS must still mine. CI needs unmodified stock firmware, real captured silicon nonces, pool acceptance at difficulty 1 or higher, and independent bench validation. Bench devices provide captures and validation, not CI execution. The gate is red. See the evidence contract.

main runs tests, benchmarks, and conformance before release. next builds release candidates. Edit ci/version-x.txt for a major release; increment the minor version for mining protocol, HAL, tuning policy, or API changes, and the patch version for compatible fixes.

Badges measure host code only. The CI badge shows the last completed branch attempt and refreshes every 15 minutes when the runner is available. Benchmark deltas compare results from the same CPU class. They do not certify board images or the pairing matrix. The benchmark history is readable without a Gitea login.

Local checks

export CARGO_TARGET_DIR=/var/tmp/alkane-os-target
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --locked
cargo build --release --locked

Use an executable target directory if the source mount is noexec. The conformance checker requires artifacts from a real CI run; its input format is in ci/CONFORMANCE.md. Rust dependencies are vendored for offline SDK builds and keep their upstream licenses.

License

Alkane OS source is MIT licensed. Vendored dependencies retain their own licenses.