docs: shorten OS entry guide
main-release-gate / verify-and-release (push) Failing after 3m47s

This commit is contained in:
2026-10-17 01:42:50 -06:00
parent e8faf398f5
commit b9686af9c8
+31 -62
View File
@@ -10,84 +10,53 @@
![code quality](https://gitea.bluefla.re/blueflare/alkane-os/raw/branch/ci-badges/badges/quality.svg)
![license](https://gitea.bluefla.re/blueflare/alkane-os/raw/branch/ci-badges/badges/license.svg)
Mining and tuning core for Alkane control boards. The SDK builds board images
and supplies the hardware backend. Management uses SSH and an optional local,
read-only cgminer-style status endpoint; no web frontend runs on the board.
Rust mining and tuning core for Alkane control boards. The
[SDK](https://gitea.bluefla.re/blueflare/alkane-sdk) builds board images and
provides the hardware backend. The miner has no on-board web frontend.
## 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 is installed.
The host miner supports BM1362 and BM1366 through the SDK's simulator HAL and
Stratum V1. Tests have replayed 33 captured BM1366 shares and one BM1362
share to a loopback pool with matching ACCEPT responses. Production board
control is still under development.
The library has a versioned Unix-socket HAL client, BM1362 and BM1366
host mining sessions, Stratum V1 job and share handling, SHA-256d share
checks, 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.
The HAL client requests PSU shutdown on sensor faults and reserves work IDs
until a confirmed reset or shutdown. A production backend still needs a
power lease, watchdog, and validated temperature limits. SHA-256d and
Litecoin Scrypt proof verification are implemented; Scrypt chip report
handling and mining remain open.
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](https://github.com/litecoin-project/litecoin/wiki/Scrypt-proof-of-work);
BM1489/BM1491 report handling and L7/L9 mining remain open.
Run `alkane-os --list-targets` for the target matrix. Set `POOL_PASSWORD` to
the pool password, then mine with a simulator HAL socket and Stratum V1 pool:
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.
Set `ALKANE_API_LISTEN=127.0.0.1:4028` to expose read-only `summary` and
`version` commands during simulator mining. The endpoint accepts cgminer
JSON requests or plain command names and ends replies with a NUL byte.
It binds only to loopback; access from another machine through SSH. The
summary reports observed accepted/rejected shares and process state, without
an estimated hashrate. Other cgminer API commands are not yet implemented.
```sh
ALKANE_POOL_PASSWORD="$POOL_PASSWORD" alkane-os --mine-simulator HAL_SOCKET POOL_ADDRESS WORKER BM1366
```
Use `BM1362` for that chip. Set `ALKANE_API_LISTEN=127.0.0.1:4028` for
read-only `summary` and `version` commands; reach it remotely through SSH.
## 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](ci/CONFORMANCE.md).
`main` runs tests, benchmarks, and conformance before release; `next` builds
release candidates. The release gate is red. It requires all 64 same-vendor
pairings (52 Bitmain, 12 WhatsMiner), unmodified stock firmware, captured
silicon nonces, difficulty-1 pool acceptance, and bench-validated models.
Stock firmware may faithfully reject a pairing; Alkane OS must mine it.
See the [evidence contract](ci/CONFORMANCE.md).
`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](https://blueflare.gitea.bluefla.re/alkane-benchmarks/os/)
is readable without a Gitea login.
Badges cover host code, not board conformance. See the public
[benchmark history](https://blueflare.gitea.bluefla.re/alkane-benchmarks/os/).
## Local checks
```sh
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
CARGO_TARGET_DIR=/var/tmp/alkane-os-target cargo test --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](ci/CONFORMANCE.md). Rust dependencies are vendored
for offline SDK builds and keep their upstream licenses.
Use an executable target directory if the source mount is `noexec`.
## License
Alkane OS source is [MIT licensed](LICENSE). Vendored dependencies retain
their own licenses.
[MIT](LICENSE). Vendored dependencies keep their own licenses.