Decode bounded Stratum V1 pool jobs
main-release-gate / verify-and-release (push) Canceled after 0s

This commit is contained in:
2026-10-15 00:05:14 -06:00
parent d3599245f8
commit 5d352139dd
7 changed files with 344 additions and 0 deletions
Generated
+98
View File
@@ -5,3 +5,101 @@ version = 4
[[package]]
name = "alkane-os"
version = "0.1.0"
dependencies = [
"serde_json",
]
[[package]]
name = "itoa"
version = "1.0.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
[[package]]
name = "memchr"
version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
[[package]]
name = "proc-macro2"
version = "1.0.107"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
dependencies = [
"unicode-ident",
]
[[package]]
name = "quote"
version = "1.0.47"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
dependencies = [
"proc-macro2",
]
[[package]]
name = "serde"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
dependencies = [
"serde_core",
]
[[package]]
name = "serde_core"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
dependencies = [
"serde_derive",
]
[[package]]
name = "serde_derive"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
dependencies = [
"proc-macro2",
"quote",
"syn",
]
[[package]]
name = "serde_json"
version = "1.0.154"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
dependencies = [
"itoa",
"memchr",
"serde",
"serde_core",
"zmij",
]
[[package]]
name = "syn"
version = "3.0.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
dependencies = [
"proc-macro2",
"quote",
"unicode-ident",
]
[[package]]
name = "unicode-ident"
version = "1.0.27"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
[[package]]
name = "zmij"
version = "1.0.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
+3
View File
@@ -8,6 +8,9 @@ description = "Portable mining and tuning core for Alkane control boards"
[lib]
name = "alkane_os"
[dependencies]
serde_json = "=1.0.154"
[profile.release]
lto = true
codegen-units = 1
+4
View File
@@ -51,6 +51,10 @@ 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 Stratum V1 decoder now bounds and validates `mining.subscribe` responses
and nine-field Bitcoin `mining.notify` jobs before handing them to the header
builder. It uses the MIT-compatible `serde_json` parser. A live pool client,
target conversion, and job-to-share scheduling are still pending.
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
@@ -8,6 +8,7 @@ pub mod hal_wire;
pub mod miner;
pub mod pow;
pub mod stratum_submit;
pub mod stratum_v1;
pub mod stratum_work;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+145
View File
@@ -0,0 +1,145 @@
// SPDX-License-Identifier: MIT
//! Bounded decoding of Bitcoin Stratum V1 subscription and job messages.
//! The network client must enforce a line limit before passing data here.
use crate::stratum_work::{JobError, Sha256Job};
use serde_json::Value;
const MAX_LINE_BYTES: usize = 131_072;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum PoolMessageError {
TooLarge,
Json,
WrongMessage,
InvalidField,
InvalidHex,
InvalidWork(JobError),
}
pub struct Subscription {
pub extranonce1: Vec<u8>,
pub extranonce2_size: usize,
}
pub struct PoolJob {
pub id: String,
pub clean_jobs: bool,
pub work: Sha256Job,
}
fn parse_json(line: &[u8]) -> Result<Value, PoolMessageError> {
if line.len() > MAX_LINE_BYTES {
return Err(PoolMessageError::TooLarge);
}
serde_json::from_slice(line).map_err(|_| PoolMessageError::Json)
}
fn hex_bytes(text: &str) -> Result<Vec<u8>, PoolMessageError> {
let bytes = text.as_bytes();
if bytes.len() & 1 != 0 {
return Err(PoolMessageError::InvalidHex);
}
let mut result = Vec::with_capacity(bytes.len() / 2);
for pair in bytes.chunks_exact(2) {
let high = (pair[0] as char)
.to_digit(16)
.ok_or(PoolMessageError::InvalidHex)?;
let low = (pair[1] as char)
.to_digit(16)
.ok_or(PoolMessageError::InvalidHex)?;
result.push(((high << 4) | low) as u8);
}
Ok(result)
}
fn hex_fixed<const N: usize>(field: &Value) -> Result<[u8; N], PoolMessageError> {
let text = field.as_str().ok_or(PoolMessageError::InvalidField)?;
if text.len() != N * 2 {
return Err(PoolMessageError::InvalidField);
}
hex_bytes(text)?
.try_into()
.map_err(|_| PoolMessageError::InvalidField)
}
fn hex_u32(field: &Value) -> Result<u32, PoolMessageError> {
let text = field.as_str().ok_or(PoolMessageError::InvalidField)?;
if text.len() != 8 {
return Err(PoolMessageError::InvalidField);
}
u32::from_str_radix(text, 16).map_err(|_| PoolMessageError::InvalidHex)
}
/// Parse the response to a matching `mining.subscribe` request.
pub fn parse_subscription(line: &[u8], request_id: u64) -> Result<Subscription, PoolMessageError> {
let message = parse_json(line)?;
if message.get("id").and_then(Value::as_u64) != Some(request_id)
|| !message.get("error").is_none_or(Value::is_null)
{
return Err(PoolMessageError::WrongMessage);
}
let result = message
.get("result")
.and_then(Value::as_array)
.ok_or(PoolMessageError::InvalidField)?;
if result.len() != 3 || !result[0].is_array() {
return Err(PoolMessageError::InvalidField);
}
let extranonce1 = hex_bytes(result[1].as_str().ok_or(PoolMessageError::InvalidField)?)?;
let extranonce2_size = result[2].as_u64().ok_or(PoolMessageError::InvalidField)?;
if extranonce1.len() > 32 || extranonce2_size > 32 {
return Err(PoolMessageError::InvalidField);
}
Ok(Subscription {
extranonce1,
extranonce2_size: extranonce2_size as usize,
})
}
/// Parse exactly the nine Bitcoin `mining.notify` parameters into work.
pub fn parse_notify(line: &[u8], subscription: &Subscription) -> Result<PoolJob, PoolMessageError> {
let message = parse_json(line)?;
if message.get("method").and_then(Value::as_str) != Some("mining.notify")
|| !message.get("id").is_none_or(Value::is_null)
{
return Err(PoolMessageError::WrongMessage);
}
let params = message
.get("params")
.and_then(Value::as_array)
.ok_or(PoolMessageError::InvalidField)?;
if params.len() != 9 {
return Err(PoolMessageError::InvalidField);
}
let id = params[0].as_str().ok_or(PoolMessageError::InvalidField)?;
if id.is_empty() || id.len() > 128 {
return Err(PoolMessageError::InvalidField);
}
let branches = params[4].as_array().ok_or(PoolMessageError::InvalidField)?;
if branches.len() > 64 {
return Err(PoolMessageError::InvalidField);
}
let mut merkle_branches = Vec::with_capacity(branches.len());
for branch in branches {
merkle_branches.push(hex_fixed::<32>(branch)?);
}
let work = Sha256Job {
prevhash_stratum: hex_fixed::<32>(&params[1])?,
coinb1: hex_bytes(params[2].as_str().ok_or(PoolMessageError::InvalidField)?)?,
coinb2: hex_bytes(params[3].as_str().ok_or(PoolMessageError::InvalidField)?)?,
merkle_branches,
version: hex_u32(&params[5])?,
nbits: hex_u32(&params[6])?,
ntime: hex_u32(&params[7])?,
extranonce1: subscription.extranonce1.clone(),
extranonce2_size: subscription.extranonce2_size,
};
work.validate().map_err(PoolMessageError::InvalidWork)?;
let clean_jobs = params[8].as_bool().ok_or(PoolMessageError::InvalidField)?;
Ok(PoolJob {
id: id.to_owned(),
clean_jobs,
work,
})
}
+23
View File
@@ -3,6 +3,7 @@ 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_v1::{parse_notify, Subscription};
use alkane_os::stratum_work::Sha256Job;
use alkane_os::{power_decision, target_matrix, HardwareBackend};
use std::hint::black_box;
@@ -113,6 +114,28 @@ fn bench_stratum_submission() {
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_notify_parse() {
let line = serde_json::json!({
"id": null,
"method": "mining.notify",
"params": [
"job-1",
"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
"616263", "78797a", [], "20000000", "1d00ffff", "66554433", true
]
})
.to_string();
let subscription = Subscription {
extranonce1: vec![1, 2, 3, 4],
extranonce2_size: 4,
};
measure("stratum_notify_parse", 20_000, || {
black_box(parse_notify(black_box(line.as_bytes()), &subscription).unwrap());
});
}
struct BenchBackend;
impl HardwareBackend for BenchBackend {
+70
View File
@@ -0,0 +1,70 @@
// SPDX-License-Identifier: MIT
use alkane_os::stratum_v1::{parse_notify, parse_subscription, PoolMessageError};
const SUBSCRIBE: &str =
r#"{"id":1,"result":[[["mining.notify","session"]],"01020304",4],"error":null}"#;
fn notify() -> String {
serde_json::json!({
"id": null,
"method": "mining.notify",
"params": [
"job-1",
"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
"616263", "78797a",
["202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f"],
"20000000", "1d00ffff", "66554433", true
]
})
.to_string()
}
#[test]
fn subscribe_and_notify_construct_expected_asic_header() {
let subscription = parse_subscription(SUBSCRIBE.as_bytes(), 1).unwrap();
let line = notify();
let job = parse_notify(line.as_bytes(), &subscription).unwrap();
assert_eq!(job.id, "job-1");
assert!(job.clean_jobs);
let header = job
.work
.nonce_zero_header(&[5, 6, 7, 8], job.work.ntime)
.unwrap();
let hex: String = header.iter().map(|byte| format!("{byte:02x}")).collect();
assert_eq!(
hex,
concat!(
"0000002003020100070605040b0a09080f0e0d0c13121110171615141b1a19181f1e1d1c",
"9b9bc91f078af83ff63d00c6da09b5bc4dd26e2d8c0df8ab16b933a259a05881",
"33445566ffff001d00000000"
)
);
}
#[test]
fn malformed_pool_messages_fail_before_work_issuance() {
assert!(matches!(
parse_subscription(SUBSCRIBE.as_bytes(), 2),
Err(PoolMessageError::WrongMessage)
));
let subscription = parse_subscription(SUBSCRIBE.as_bytes(), 1).unwrap();
let malformed = notify().replace("66554433", "6655443g");
assert!(matches!(
parse_notify(malformed.as_bytes(), &subscription),
Err(PoolMessageError::InvalidHex)
));
let wrong_method = notify().replace("mining.notify", "mining.submit");
assert!(matches!(
parse_notify(wrong_method.as_bytes(), &subscription),
Err(PoolMessageError::WrongMessage)
));
let too_large = vec![b' '; 131_073];
assert!(matches!(
parse_notify(&too_large, &subscription),
Err(PoolMessageError::TooLarge)
));
let too_large_coinbase = notify().replace("616263", &"aa".repeat(65_537));
assert!(matches!(
parse_notify(too_large_coinbase.as_bytes(), &subscription),
Err(PoolMessageError::TooLarge)
));
}