This commit is contained in:
@@ -10,105 +10,52 @@
|
||||

|
||||

|
||||
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user