v0.1.2.3

Release date: 2026-07-10

Highlights

• Added an opt-in high-difficulty Stratum listener on a separate port for rental-scale and hashrate-marketplace miners, with an independent difficulty floor (default 500000) so stamped jobs advertise a marketplace-verifiable mining.set_difficulty from the first job even while qbit network difficulty sits below the floor (young or test chains); clients may raise — never lower — difficulty within the configured bounds via the d=N,md=N password convention or mining.suggest_difficulty.
• Exposed the high-difficulty endpoint in the public /public/v1/mining-configuration API alongside the default listener.
• Moved block submission to a dedicated submitter thread and accepted-share ledger writes to an async writer thread, so a miner's share acknowledgment no longer waits on submitblock or a Postgres round trip — holding acknowledgment latency low under sustained rental-scale load. A share that meets its target is credited immediately regardless of the block's outcome (standard PPLNS/TIDES semantics), and an orphaned block candidate keeps its share credit.
• Made accepted-share accounting durable: shares that cannot be persisted immediately (ledger outage, writer backlog, or shutdown) are written to an fsync'd recovery file and replayed idempotently on the next start, and the liveness watchdog flushes the queue to that file before a self-inflicted exit.
• Reduced the per-block coordinator lock hold (aggregated evidence statistics and a keep-alive qbitd JSON-RPC connection) so block acceptance no longer stalls concurrent share acknowledgments.
• Anchored the stale-grace window per connection — it opens when a connection first receives new-tip work rather than when a shared refresh pass first observes the tip — so a slow multi-client refresh or an aborted reorg reconcile no longer consumes the grace window before miners receive new work.
• Made idle vardiff step-down retargets re-check idleness and reset the window atomically at commit, so a share accepted mid-retarget is neither stepped down nor dropped; restored the idle-window clock when a step-down send is skipped so a transient send failure does not re-gate an idle miner behind another full retarget interval.
• Rejected pool-closed submits before share accounting, so stop-after-block / max-block runs no longer dilute the stale-share denominator or mark closing clients active for the idle sweep.
• Added scripts/prism-self-check.py (make prism-self-check) and new async-writer metrics — share-append queue depth, shares recovered to disk, replayed shares, and append failures — separated block-candidate abandonment from share rejections, and bounded worker-metric label cardinality.
• Refreshed the PRISM operator guide, rejection reference, ledger-operations, and storage-sizing documentation.

Operator Notes

• This release is recommended for all PRISM operators on v0.1.2.2, especially pools serving rental-scale or hashrate-marketplace hashrate.
• Schema: this release adds a nullable credit_policy column to qbit_share_ledger and updates the reward-window SQL functions. The change is idempotent and backward-compatible (ADD COLUMN IF NOT EXISTS, NOT VALID constraint) and is applied automatically on coordinator startup — no manual migration or downtime — but the coordinator must start once against the ledger before stale-grace crediting and the updated window functions take effect.
• Durability: accepted shares are queued to an async writer before the acknowledgment. Keep PRISM_AUDIT_DIR on persistent storage — the recovery file (PRISM_SHARE_RECOVERY_PATH, default <PRISM_AUDIT_DIR>/prism-unpersisted-shares.jsonl) must survive restarts for the durability guarantee to hold. A SIGKILL / OOM / host failure can still lose shares that are only in the in-memory queue; this window is bounded and surfaced by the queue-depth metric.
• High-diff listener (opt-in): disabled unless PRISM_STRATUM_HIGHDIFF_PORT is set. Configure PRISM_STRATUM_HIGHDIFF_PORT, PRISM_STRATUM_HIGHDIFF_PORT_HOST, PRISM_STRATUM_HIGHDIFF_BIND, PRISM_STRATUM_HIGHDIFF_START_DIFF, PRISM_STRATUM_HIGHDIFF_MIN_DIFF, and PRISM_STRATUM_HIGHDIFF_MAX_DIFF (floor defaults to 500000), and publish the endpoint via PRISM_PUBLIC_STRATUM_HIGHDIFF_URL. Difficulty bounds are independent of the default listener; all other vardiff knobs inherit PRISM_STRATUM_VARDIFF_*. The default listener is unchanged when unset.
• New or changed configuration in .env.example: PRISM_STRATUM_VARDIFF_IDLE_SWEEP_SECONDS (default 15), PRISM_STRATUM_STALE_GRACE_SECONDS (default 3), PRISM_BLOCKWAIT_ENABLED / PRISM_BLOCKWAIT_TIMEOUT_SECONDS, PRISM_WORKER_METRICS_LIMIT (default 100), and the PRISM_STRATUM_HIGHDIFF_* set.
• Monitor the async-writer metrics: qbit_prism_share_append_queue_depth (healthy near 0; a sustained climb means the ledger is falling behind), qbit_prism_shares_recovered_to_disk_total, qbit_prism_share_append_failures_total, and qbit_prism_shares_replayed_total, alongside existing qbit_prism_blocks_accepted_total and qbit_prism_persisted_blocks.
• The public dashboard API remains compatible, adding the high-diff endpoint to /public/v1/mining-configuration. Direct coinbase settlement artifacts, compact audit body refs, and CTV fanout storage remain compatible.
• After upgrading, run make prism-self-check and the PRISM regression tests, and watch coordinator logs for share-writer and recovery messages.