fix(bitcoin-blake2b): support Knots 29.4.2 maturity/RPC changes and refresh DATUM compatibility #205

Problem and outcome

Bring Miningcore's XBT / Bitcoin BLAKE2b integration onto the released Knots 29.4.2.knots20260508 consensus and RPC contract, including correct reward-maturity reporting and payout handling. Update the DATUM compatibility requirements in #163 to use this baseline.

Research date: 2026-10-03. Latest published upstream release and default source head checked: 58398baf33e588779685ead478e6397bb28ed3d6, released 2026-09-21. Miningcore inspected at default branch dev, commit fc65ba40a0605c0e8c48f77caa31ff1be97458f0; the older local working branch was not used as the implementation baseline.

This is a compatibility implementation issue, not permission to track arbitrary upstream heads or implement unmerged consensus proposals. Related: #124 / #140 (original mining support), #151 (reviewed daemon upgrades), #163 (DATUM server).

Verified changes: shipped rules versus proposals

Released: temporary long coinbase maturity

Knots #419 shipped in 29.4.2. Mainnet parameters are:

Consensus and wallet policy differ. During the enforcement interval, block validation applies the long maturity to coinbases created at or after 973440; earlier coinbases retain the ordinary 100-block consensus rule. At release height 979920 the long consensus check switches off in this release. Independently, its mempool policy and wallet use 6480 for all coinbases, including older ones, and do not switch back merely because the consensus deployment becomes inactive.

Consequently, “every reward is permanently consensus-locked for 45 days” and “all wallet rewards unlock at 979920” are both incorrect. Forty-five days is only the estimate at 600 seconds per block. Distinguish spend height, block depth and RPC confirmation counts: the wallet uses max(0, maturity + 1 - chain_depth).

getdeploymentinfo.deployments.long_coinbase_maturity exposes type, height, height_end, coinbase_start_height, maturity and active; active refers to the next block. GBT advertises long_coinbase_maturity while active, without the mandatory-rule ! prefix. It continues to require the existing !blake2b contract.

Sources: chain parameters, deployment reporting, consensus/mempool call sites, input checks, wallet maturity, wallet chain interface, upstream boundary test.

Released: RPC difficulty contract changed

Knots #420 removes getdifficulty. Header-v2 responses use difficulty_blake2b instead of difficulty in block/header, blockchain, mining and chainstate information, including the next-block mining information. Historical SHA256d block records retain their own difficulty field.

The new field is expected BLAKE2b hash work, implemented with GetBlockProof(...).getdouble(); it is not a field rename with unchanged units. Miningcore's existing target-derived share/accounting scale and gateway wire difficulty must not be silently replaced with this value.

Sources: RPC implementation, mining/GBT changes, released changes.

Still proposals as of the research date

• Knots #429 is open: longer locks, MTP-based expiration and changed deployment RPC fields; intended divergence from 29.4.2 begins at 979920.
• Knots #434 is open: an alternative phased release schedule.
• Knots #406 remains a draft for P2P share/template commitments and settlement; its description explicitly leaves mainnet disabled.
• Knots #396 is an unmerged address-blacklist proposal.
• Release notes discuss future withholding of rewards from miners who do not run their own node. 29.4.2 does not implement that proposed eligibility rule.

Do not install these proposals as consensus, blacklist payout addresses, promise future eligibility, or delete ordinary Stratum solely on the basis of release-note rhetoric. Recheck upstream status before implementing/merging this issue. Source review establishes the released rules; it does not measure universal network adoption.

Unchanged mining foundation

The net source diff from 29.4.1 to 29.4.2 does not modify the header-v2 primitives, PoW implementation or official header vectors. BLAKE2b/header-v2 remains the mining algorithm. DATUM continues to use gateway-built templates and a separate gateway-to-pool link; the miner-facing Sia-style Stratum transport is still used.

Concrete Miningcore gaps

1. BitcoinBlake2bJobManager.ValidateDaemonIdentity accepts only numeric version 290401. 29.4.2 therefore fails startup/runtime attestation.
2. BitcoinJobManagerBase.PostStartInitAsync makes getdifficulty a required startup-batch call and passes its result to proof-of-stake detection. Merely changing the version pin still fails startup when that RPC is absent.
3. GetMiningInfoResponse has only Difficulty. Audit consumers for absent-field defaults and unit mixing. Current BLAKE2b job/network accounting already derives difficulty from targets; preserve that distinction.
4. BitcoinPayoutHandler uses the wallet's immature/generate categories to unlock custodial rewards. Do not incorrectly report that it unconditionally pays after 100 blocks. Its progress denominator defaults to 102 unless configured, so an immature long-locked block can nevertheless display 100% progress.
5. Loader/catalogue protocol identifier knots-29.4.1-header-v2, documentation and checksum-pinned CI still name 29.4.1. A compatibility transition must cover all of them.
6. feat(bitcoin-blake2b): add DATUM pool support for XBT #163's planned direct-coinbase payouts cannot use “included in a coinbase” as proof of spendability. Maturity and deferred wallet settlements need separate states.

Required implementation

• Audit and add the exact reviewed 29.4.2 source/build to startup and runtime compatibility handling, following hardening(bitcoin-blake2b): define a reviewed emergency daemon-upgrade policy #151. Keep unknown builds, contradictory chain identity and unsupported rules fail-closed. Retire 29.4.1 as the recommended current-mainnet baseline; preserve historical fixtures/provenance where useful.
• Remove the required getdifficulty dependency for the BLAKE2b path, using a typed PoW/chain contract. Preserve legacy Bitcoin-family and PoS behavior that still needs the old RPC.
• Support optional, explicitly typed difficulty_blake2b RPC data and keep network expected-work, assigned-share difficulty and historical accounting units distinct. Use exact GBT bits/target for proof boundaries. Audit API labels, hashrate, PPS pricing and payout-window calculations; no automatic rescaling of stored shares or balances.
• Parse and validate the reviewed long-maturity schedule at startup and runtime, including next-height semantics and GBT rule transitions. A missing deployment, contradictory schedule or unreviewed field contract must not silently become ordinary maturity.
• Separate consensus eligibility from daemon mempool/wallet spendability and operator confirmation policy. Correct immature reward progress/remaining-depth reporting; never unlock just because progress reaches one or the temporary consensus interval ends.
• Reconcile pending rewards after daemon upgrade, revalidation, restart, outage and reorg without losing accepted shares, duplicating payments or automatically reversing already-booked PPS liabilities. Assess PPS reserve/liquidity checks against the longer immature period.
• Update documentation, catalogue/loader compatibility metadata, examples, CI binary checksums/signature-verification instructions and real-daemon fixtures. Preserve the established coin key and ledger identities; a ticker/protocol-display update is not authority to migrate balances.
• Feed these requirements into feat(bitcoin-blake2b): add DATUM pool support for XBT #163: pool and gateways must interoperate on a reviewed node/protocol matrix; direct coinbase allocation, immature receipt, spendability and deferred settlement must be represented separately.
• Recheck open upstream maturity proposals immediately before merge. If one has shipped, review its exact code and activation conditions as additional scope, rather than guessing future heights or converting a proposed MTP rule into a fixed block count.

DATUM baseline refresh for #163

CONVOY head checked: ac9b70c8b361f14e90e2c963b429a9bbb414aecb (2026-09-26), versus the original b9ea7dc... reference. Relevant changes include overflow-safe payout parsing, the large coinbase selection now that header-v2 hashers do not reconstruct the generation transaction, and anti-block-withholding (ABW) lifecycle fixes: initial assignment work refresh, continued submission when the disclosure cache cannot retain a proof, and local submission of revealed blocks before audit-failure handling. Default gateway minimum difficulty also changed; that is configuration, not a chain consensus rule.

Review these for server interoperability and failure tests, not as code to copy blindly. Preserve current block/coinbase budgets despite larger gateway coinbases. Pin a supported DATUM version and test ABW assignments, receipts, reveals, cache exhaustion and reconnects. Do not advertise an audited anti-withholding guarantee for a gateway that does not retain/audit proofs.

RATUM at b3d152d7a5572d95bfbe8a44ce87524ed095b3a8 documents 29.4.2 RPC compatibility and gateway limitations. It is an interoperability reference; review licensing before incorporating implementation code.

Acceptance tests

• Real 29.4.2 daemon startup with getdifficulty returning method-not-found succeeds through the production pool path; unknown/incompatible builds still fail safely.
• Existing header-v2 vectors, all supported ASIC profiles and accepted-block integration tests remain correct.
• Difficulty fixtures include old/new RPC shapes, historical SHA256d blocks, missing/malformed values and unchanged target boundaries; share credit, hashrate and PPS economics remain internally consistent.
• Pinned daemon tests cover coinbases before/at the covered height and spend heights immediately before/at enforcement and release. Independently test all-coinbase wallet/mempool policy, ordinary non-coinbase transactions and confirmation off-by-one boundaries.
• Use reviewed regtest -testcoinbasematuritylong=start:enforce:release fixtures with distinct boundaries. Do not enable those overrides on mainnet.
• An immature reward remains pending with truthful progress; wallet rejection or deployment inactivity cannot mark it paid. Test restart/reorg/upgrade reconciliation and no double credit/payment.
• feat(bitcoin-blake2b): add DATUM pool support for XBT #163's end-to-end gateway/node/miner tests use this consensus/RPC baseline and verify mature versus immature direct rewards.
• Existing SHA256d Bitcoin, other pool families, legacy RPC behavior and historical accounting regressions pass.

Implementation and validation

Implemented in PR #207: exact Knots
29.4.2 build/chain/maturity attestation, header-only reward reconciliation, preserved
accounting units and PPS liabilities, immutable row-lock settlement guards and durable
quarantine of ambiguous PROP/PPLNS allocation history. The packaged metadata-only
operator tool validates independent audit receipts without changing balances, payments
or block status. Shared single/batch RPC decoding rejects structural contradictions,
preserves valid codes/data and keeps private daemon text out of diagnostics.

The compatibility guide
records source/build pins, operator procedures and regression coverage. The
daemon error audit
checks pinned Monero/CryptoNote, Zano, Geth, Beam, Handshake/bweb and Xelis serializers.
Nine source-shaped profiles pass through real single/batch HTTP calls; they are not
live daemon captures or certification of unknown forks/plugins/proxies.

Production source 8616eb0cba58405451237cc962d252a93449b682 passed 899 selected Windows
and 3742 full Linux lab tests, zero failures; Linux skipped one benchmark. The shared
RPC and collection inventory selection at 48ab5fcb4297866f967810d7d73664c51984d807
passed 164 Windows and 164 Linux tests, zero failures/skips. Full CI for 48ab5fcb
passed 3760 tests, zero failed, one benchmark skip; both Ubuntu release test lanes
passed 3691 tests, zero failed, 44 skips each. These results apply to their identified
source heads. Documentation-only head d1955d7986cf6dd7262fa467d038c03fae30b6d0 passed local link/anchor checks for all 40 Markdown files and whitespace checks; its CI is pending.

The immediate pre-merge head/CI/Knots release/proposal recheck and #163 DATUM
end-to-end/direct-reward acceptance remain open. Preserve existing BLAKE2b/header-v2
primitives, vectors, ledger identities and ordinary miner-facing Stratum. No
speculative reward ban, address blacklist or draft P2P settlement is implemented.