Shorten OS README to scope and release gates
next-build / build (push) Canceled after 0s

This commit is contained in:
2026-10-15 14:37:04 -06:00
parent 6f87f48dca
commit 5d8f14c992
+50 -116
View File
@@ -10,105 +10,52 @@
![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)
Portable mining, tuning, and management logic for Alkane control boards. The
source is MIT licensed. `alkane-sdk` owns the board images and supplies the
hardware backend at build time. This repository has no on-board web frontend;
the intended management surfaces are SSH, cgminer-compatible port 4028, and a
minimal API.
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
This is an early mining core and release tooling, not a complete daemon. A
target in the matrix is an obligation to implement and validate, not a claim
of support. All 64 theoretical same-vendor controller/chip pairings are in
scope: 52 Bitmain and 12 WhatsMiner. For pairings a stock image rejects, the
simulator must record the first genuine rejection gate and Alkane OS must mine.
No live board is required by CI. Bench devices supply captures and independent
validation of the simulator.
This is a library and an early CLI, not a complete mining daemon. The CLI
lists target obligations with `alkane-os --list-targets`; it does not mine or
serve a network API. No production board backend or run loop is installed.
The current executable lists target obligations (`alkane-os --list-targets`)
and its version. It does not start a miner or a network service. The library
now includes a versioned local Unix-socket client for the SDK hardware
backend, with bounded frames, two-second I/O timeouts, and fail-closed
response validation. The matching SDK server framing library exists, but no
board adapter is installed in an image yet.
The library can also verify an ASIC-reported SHA-256d share against an exact
pool target, including BM13xx version rolling. Host probes check captured
BM1362 and BM1366 nonces through the SDK's C/Python HAL replay server. From
this repository, run `cargo run --example simulator_replay_probe -- SOCKET_PATH
BM1362` or use `BM1366` after starting the corresponding SDK server. This
checks shared work/report framing and share validation for those two chips;
it does not initialize a physical chip chain.
The first BM1366 mining session sequences fan, temperature, PSU, reset,
work submission, and nonce polling through the HAL. It rejects stale work IDs,
malformed reports, and hashes above the caller's pool target. A sensor fault
requests PSU shutdown. A transport fault closes the HAL socket; the backend
must end its power lease on disconnect and have an independent hardware
watchdog. No production board backend meets that gate yet. The caller must
provide a board-validated temperature limit.
The library now formats verified shares as Stratum V1 `mining.submit` requests.
For negotiated BIP310 version rolling, it includes the sixth version-bits
parameter and rejects ASIC versions that the current pool mask cannot
represent. The pool transport bounds newline frames and uses absolute socket
deadlines. It can negotiate BIP310 extensions, subscribe, and authorize a
worker over a live TCP connection while retaining early notifications in wire
order. It has loopback tests; no live pool acceptance has been observed yet.
The pool connection applies difficulty and job messages in stream order,
dispatches work to the BM1366 mining session, and tracks up to 32 verified
share submissions by request ID. It counts accepted and rejected pool replies
separately. Continuous scheduling and live pool acceptance remain unverified.
The SDK's strict loopback pool replay test reconstructs 33 cv.106 BM1366
captured jobs from Stratum subscription and notify fields. It delivers those
jobs through the OS pool client and HAL simulator, replays the real ASIC
nonces, verifies each proof of work independently, and receives 33 matching
pool ACCEPT responses. The 33rd job also exercises the chain reset before
hardware work ID reuse. This is host-only evidence, not a stock-firmware
boot or a production board adapter.
The same strict pool fixture reconstructs one BM1362 job with an empty
extranonce2 and independently verifies its captured share before returning
ACCEPT. This extends the host pool path to a second chip family; physical
chain initialization and stock firmware remain unverified. A separate Rust
integration test feeds the pinned BM1362 header and 11-byte report through
the mining controller's work encoder, report decoder, and proof check.
The core also validates a supplied Litecoin Scrypt header using the fixed
N=1024, r=1, p=1 algorithm. Its output matches Litecoin's
[published block 29255 proof-of-work vector](https://github.com/litecoin-project/litecoin/wiki/Scrypt-proof-of-work)
and has a dedicated microbenchmark. This is a
share-verification primitive only; BM1489/BM1491 report decoding, pool
difficulty conventions, physical chain control, and L7/L9 acceptance remain
open.
Its cycle helper reads one pool event, drains up to 256 ASIC reports, and sends
verified shares when present. A share reply unanswered for 30 seconds closes
the connection so a caller can reconnect instead of filling the pending
queue indefinitely. Terminal pool errors request miner shutdown, and pool
reads use 1 ms slices after the handshake so ASIC polling continues. Partial
pool lines have a 2-second deadline and pool writes have a 100 ms deadline.
When the 32 hardware work IDs are exhausted, the client checks temperature,
resets the chain, discards old reports, and only then reuses an ID for the next
job. A reset failure requests PSU shutdown. A host test dispatches 33 jobs
and checks the reset boundary; sustained board operation is still unverified.
The miner also reserves each work ID until a confirmed chain reset or PSU
shutdown, even after a pool clean-jobs message. A failed PSU-off call faults
the miner and blocks further work until a shutdown retry succeeds.
The executable still lacks a board adapter and run loop.
The Stratum V1 decoder bounds and validates `mining.subscribe` responses,
nine-field Bitcoin `mining.notify` jobs, difficulty and extranonce changes,
and negotiated BIP310 version-mask updates. Exact decimal difficulty values
become 256-bit pool targets without floating point rounding. Pool job
bookkeeping keeps earlier work tied to its original target and extranonce,
invalidates old work on `clean_jobs`, and rechecks a reported share before
formatting it for submission. It does not reuse ASIC work IDs until the caller
confirms a hardware reset. Hardware job dispatch and share reply tracking are
library-only so far; continuous mining remains to be implemented.
The exact Rust dependency sources are under `vendor/` with Cargo checksums,
so SDK board builds can compile offline. Dependencies retain the license terms
in their vendored manifests and license files.
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.
The `main` branch has full tests and a conformance gate; releases are created
only after every required cell passes. `next` runs a build check and produces
release candidates. `ci/version-x.txt` is the manually edited major version.
For this repository, Y changes when the mining protocol, HAL contract, tuning
policy or API changes; Z changes for compatible fixes and packaging updates.
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.
## 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. 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 benchmark deltas compare results from the same CPU class. They
do not certify board images or the pairing matrix.
## Local checks
@@ -116,29 +63,16 @@ policy or API changes; Z changes for compatible fixes and packaging updates.
export CARGO_TARGET_DIR=/var/tmp/alkane-os-target
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo test --locked
cargo build --release --locked
GITHUB_RUN_ID=123 python3 ci/check-conformance.py
```
Use an executable local `CARGO_TARGET_DIR` when the workspace mount strips
executable bits. Replace `123` with the numeric ID of the CI run that
generated its evidence. The last command currently fails because simulator
and device evidence are still pending. It cross-checks the matrix against the built binary's
targets and requires per-cell reports from the current CI run, bound to the
source commit and binary digest. Referenced artifacts are opened and hashed;
SHA-256 captured shares must satisfy a difficulty-one-or-harder target and
carry a matching pool ACCEPT response. Scrypt and Equihash verification is
pending. It is a release gate, not a unit test. The simulator
runner that produces this evidence has not yet been implemented.
The required artifact contract is in [ci/CONFORMANCE.md](ci/CONFORMANCE.md).
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.
The badges record measured host-side checks for this initial core. They do
not imply that any board image or mining target has passed conformance.
CI and metric badges are served from a private, machine-maintained branch.
The CI badge shows the last completed attempt for this source branch while
newer runs are queued; main CI refreshes measured metrics before conformance.
Microbenchmarks report the median of seven calibrated samples and compare
only with an earlier commit measured on the same CPU class. The code-quality
letter requires warnings-denied Clippy to pass and uses measured test line
coverage: A at 90%, B at 80%, C at 70%, D at 60%, and F below 60%.
## License
Alkane OS source is [MIT licensed](LICENSE). Vendored dependencies retain
their own licenses.