Format mask-checked Stratum V1 share submissions
main-release-gate / verify-and-release (push) Canceled after 0s

This commit is contained in:
2026-10-15 00:00:19 -06:00
parent d1495ff2d5
commit d3599245f8
6 changed files with 190 additions and 0 deletions
+5
View File
@@ -46,6 +46,11 @@ work submission, and nonce polling through the HAL. It rejects stale work IDs,
malformed reports, and hashes below the caller's pool target. Sensor or HAL
failure stops the PSU. 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. Pool connections, response tracking, and continuous scheduling
remain to be implemented.
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
+1
View File
@@ -7,6 +7,7 @@ pub mod bm1366;
pub mod hal_wire;
pub mod miner;
pub mod pow;
pub mod stratum_submit;
pub mod stratum_work;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+4
View File
@@ -114,6 +114,10 @@ impl VersionMask {
pub fn apply_submission_bits(self, base_version: u32, version_bits: u32) -> Option<u32> {
(version_bits & !self.0 == 0).then_some((base_version & !self.0) | version_bits)
}
pub fn bits(self) -> u32 {
self.0
}
}
/// Check one ASIC-reported nonce against a little-endian 256-bit pool target.
+92
View File
@@ -0,0 +1,92 @@
// SPDX-License-Identifier: MIT
//! Format one verified share for Stratum V1 and negotiated BIP310 submission.
//! Pool I/O and request tracking are owned by the caller.
use crate::pow::VersionMask;
use std::fmt::Write;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum SubmitError {
EmptyWorker,
EmptyJobId,
FieldTooLong,
ExtranonceTooLong,
UnrepresentableVersion,
}
pub struct Submission<'a> {
pub request_id: u64,
pub worker: &'a str,
pub job_id: &'a str,
pub extranonce2: &'a [u8],
pub ntime: u32,
pub nonce: u32,
pub base_version: u32,
pub rolled_version: u32,
/// The last pool mask, only after version rolling was accepted.
pub version_mask: Option<VersionMask>,
}
fn json_string(out: &mut String, value: &str) {
out.push('"');
for ch in value.chars() {
match ch {
'"' => out.push_str("\\\""),
'\\' => out.push_str("\\\\"),
'\n' => out.push_str("\\n"),
'\r' => out.push_str("\\r"),
'\t' => out.push_str("\\t"),
c if c <= '\u{001f}' => {
write!(out, "\\u{:04x}", c as u32).expect("write to String");
}
c => out.push(c),
}
}
out.push('"');
}
/// Emit one newline-terminated JSON request. The caller must have checked the
/// ASIC report against the pool target and retained the original job metadata.
pub fn format_submission(share: &Submission<'_>) -> Result<String, SubmitError> {
if share.worker.is_empty() {
return Err(SubmitError::EmptyWorker);
}
if share.job_id.is_empty() {
return Err(SubmitError::EmptyJobId);
}
if share.worker.len() > 128 || share.job_id.len() > 128 {
return Err(SubmitError::FieldTooLong);
}
if share.extranonce2.len() > 32 {
return Err(SubmitError::ExtranonceTooLong);
}
let version_bits = match share.version_mask {
Some(mask) => {
let bits = share.rolled_version & mask.bits();
if mask.apply_submission_bits(share.base_version, bits) != Some(share.rolled_version) {
return Err(SubmitError::UnrepresentableVersion);
}
Some(bits)
}
None if share.rolled_version == share.base_version => None,
None => return Err(SubmitError::UnrepresentableVersion),
};
let mut out = format!(
"{{\"id\":{},\"method\":\"mining.submit\",\"params\":[",
share.request_id
);
json_string(&mut out, share.worker);
out.push(',');
json_string(&mut out, share.job_id);
out.push_str(",\"");
for byte in share.extranonce2 {
write!(out, "{byte:02x}").expect("write to String");
}
write!(out, "\",\"{:08x}\",\"{:08x}\"", share.ntime, share.nonce).expect("write to String");
if let Some(bits) = version_bits {
write!(out, ",\"{bits:08x}\"").expect("write to String");
}
out.push_str("]}\n");
Ok(out)
}
+21
View File
@@ -1,6 +1,8 @@
use alkane_os::bm1366::{decode_nonce_report, encode_work};
use alkane_os::miner::Bm1366Miner;
use alkane_os::pow::verify_sha256_report;
use alkane_os::pow::VersionMask;
use alkane_os::stratum_submit::{format_submission, Submission};
use alkane_os::stratum_work::Sha256Job;
use alkane_os::{power_decision, target_matrix, HardwareBackend};
use std::hint::black_box;
@@ -92,6 +94,25 @@ fn bench_stratum_header() {
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_submission() {
let share = Submission {
request_id: 1,
worker: "miner.worker",
job_id: "job-123",
extranonce2: &[0; 8],
ntime: 0x680f_6a2e,
nonce: 0xedad_ff38,
base_version: 0x2000_0000,
rolled_version: 0x2096_6000,
version_mask: Some(VersionMask::new(0x1fff_e000).unwrap()),
};
measure("stratum_submission", 20_000, || {
black_box(format_submission(black_box(&share)).unwrap());
});
}
struct BenchBackend;
impl HardwareBackend for BenchBackend {
+67
View File
@@ -0,0 +1,67 @@
// SPDX-License-Identifier: MIT
use alkane_os::pow::VersionMask;
use alkane_os::stratum_submit::{format_submission, Submission, SubmitError};
fn share() -> Submission<'static> {
Submission {
request_id: 7,
worker: "miner.worker",
job_id: "pool-job",
extranonce2: &[0, 1, 0xfe, 0xff],
ntime: 0x680f6a2e,
nonce: 0xedadff38,
base_version: 0x20000000,
rolled_version: 0x20966000,
version_mask: Some(VersionMask::new(0x1fffe000).unwrap()),
}
}
#[test]
fn captured_bm1366_version_is_represented_under_negotiated_mask() {
assert_eq!(
format_submission(&share()).unwrap(),
"{\"id\":7,\"method\":\"mining.submit\",\"params\":[\"miner.worker\",\"pool-job\",\"0001feff\",\"680f6a2e\",\"edadff38\",\"00966000\"]}\n"
);
}
#[test]
fn unnegotiated_or_narrow_mask_rejects_rolled_share() {
let mut value = share();
value.version_mask = None;
assert_eq!(
format_submission(&value),
Err(SubmitError::UnrepresentableVersion)
);
value.version_mask = Some(VersionMask::new(0x0060_0000).unwrap());
assert_eq!(
format_submission(&value),
Err(SubmitError::UnrepresentableVersion)
);
value.rolled_version = value.base_version;
value.version_mask = None;
assert_eq!(
format_submission(&value).unwrap(),
"{\"id\":7,\"method\":\"mining.submit\",\"params\":[\"miner.worker\",\"pool-job\",\"0001feff\",\"680f6a2e\",\"edadff38\"]}\n"
);
}
#[test]
fn pool_fields_are_escaped_and_bounded() {
let mut value = share();
value.worker = "worker\"\\\n";
value.job_id = "job\t\u{0001}";
let wire = format_submission(&value).unwrap();
assert!(wire.contains("\"worker\\\"\\\\\\n\""));
assert!(wire.contains("\"job\\t\\u0001\""));
value.worker = "";
assert_eq!(format_submission(&value), Err(SubmitError::EmptyWorker));
value.worker = "worker";
value.job_id = "";
assert_eq!(format_submission(&value), Err(SubmitError::EmptyJobId));
value.job_id = "job";
value.extranonce2 = &[0; 33];
assert_eq!(
format_submission(&value),
Err(SubmitError::ExtranonceTooLong)
);
}