Template subcommand improvements #294

Merged

parachemist merged 34 commits from template-improvements into master

2025-12-29 17:02:08 +00:00

parachemist commented

2025-12-04 07:36:04 +00:00

(Migrated from github.com)

Template Subcommand Enhancements

Checklist

Done

Simplify output structure
Fix --raw to output actual protocol format
Address decoding for coinbase outputs
--network flag for address encoding
--quiet mode (significant events only)
Template change detection in watch mode
ASICBoost/version rolling detection
Computed merkle root
Coinbase transaction size field
Better error messages for connection failures
Summary stats in watch mode (templates, blocks, avg interval)
Difficulty history tracking in watch mode

Future Work

Color output for terminal (requires non-JSON mode)
Multi-pool comparison (template-compare subcommand)

Foreword

I was checking out our issues seeing if there was anything I could tackle. Since I originally authored this subcommand, I figured it was especially my responsibility to work on this.

Refactored and extended the template subcommand with simplified output, watch mode improvements, and additional analysis features.

Changes

Output Structure

Flattened verbose nested structs (BlockHeaderInfo, VersionBits, MiningParams) into cleaner top-level fields
--raw now prints actual mining.notify JSON array as received from protocol
Removed --show-coinbase-hex and --show-merkle flags

New Features

--network <bitcoin|testnet|signet|regtest> - Address encoding for coinbase outputs
--quiet - Only show significant events (new blocks, difficulty changes); implies --watch
Computed merkle_root field
version_info with ASICBoost/version rolling detection (BIP320)
Template change detection in watch mode (new_block, difficulty_change, template_update events)
Coinbase size_bytes field
Better error context for connection failures
Watch mode summary stats on shutdown (templates, blocks, avg interval, difficulty range)

Code Cleanup

Removed NotifyData wrapper struct, use stratum::Notify directly
Use stratum::Difficulty instead of manual calculation
Use chrono for timestamp formatting
Added anyhow::Context for better error messages

Example Output

{
  "job_id": "bf",
  "prevhash": "4d16b6f8...",
  "merkle_root": "3a4b5c6d...",
  "coinbase": {
    "size_bytes": 267,
    "input_text": "/Foundry USA Pool/",
    "outputs": [
      { "value_sats": 312500000, "value_btc": 3.125, "address": "bc1q..." },
      { "value_sats": 0, "value_btc": 0.0 }
    ]
  },
  "version": "20000000",
  "version_info": {
    "bits": 536870912,
    "bip9_signaling": true,
    "version_rolling_possible": false
  },
  "difficulty": 92000000000000.0,
  "ntime_human": "2025-12-16T18:30:00Z",
  "clean_jobs": true
}

Non-Goals

Economic censorship detection - Requires mempool data I don't believe we have
Simulated extranonce sweep - Very niche, unclear value
Block reconstruction - Might want to make another subcommand for this one

# Template Subcommand Enhancements ## Checklist ### Done - [x] Simplify output structure - [x] Fix `--raw` to output actual protocol format - [x] Address decoding for coinbase outputs - [x] `--network` flag for address encoding - [x] `--quiet` mode (significant events only) - [x] Template change detection in watch mode - [x] ASICBoost/version rolling detection - [x] Computed merkle root - [x] Coinbase transaction size field - [x] Better error messages for connection failures - [x] Summary stats in watch mode (templates, blocks, avg interval) - [x] Difficulty history tracking in watch mode ### Future Work - [ ] Color output for terminal (requires non-JSON mode) - [ ] Multi-pool comparison (`template-compare` subcommand) ## Foreword I was checking out our issues seeing if there was anything I could tackle. Since I originally authored this subcommand, I figured it was especially my responsibility to work on this. Refactored and extended the `template` subcommand with simplified output, watch mode improvements, and additional analysis features. ## Changes ### Output Structure - Flattened verbose nested structs (`BlockHeaderInfo`, `VersionBits`, `MiningParams`) into cleaner top-level fields - `--raw` now prints actual `mining.notify` JSON array as received from protocol - Removed `--show-coinbase-hex` and `--show-merkle` flags ### New Features - `--network <bitcoin|testnet|signet|regtest>` - Address encoding for coinbase outputs - `--quiet` - Only show significant events (new blocks, difficulty changes); implies `--watch` - Computed `merkle_root` field - `version_info` with ASICBoost/version rolling detection (BIP320) - Template change detection in watch mode (`new_block`, `difficulty_change`, `template_update` events) - Coinbase `size_bytes` field - Better error context for connection failures - Watch mode summary stats on shutdown (templates, blocks, avg interval, difficulty range) ### Code Cleanup - Removed `NotifyData` wrapper struct, use `stratum::Notify` directly - Use `stratum::Difficulty` instead of manual calculation - Use `chrono` for timestamp formatting - Added `anyhow::Context` for better error messages ## Example Output ```json { "job_id": "bf", "prevhash": "4d16b6f8...", "merkle_root": "3a4b5c6d...", "coinbase": { "size_bytes": 267, "input_text": "/Foundry USA Pool/", "outputs": [ { "value_sats": 312500000, "value_btc": 3.125, "address": "bc1q..." }, { "value_sats": 0, "value_btc": 0.0 } ] }, "version": "20000000", "version_info": { "bits": 536870912, "bip9_signaling": true, "version_rolling_possible": false }, "difficulty": 92000000000000.0, "ntime_human": "2025-12-16T18:30:00Z", "clean_jobs": true } ``` --- ## Non-Goals - **Economic censorship detection** - Requires mempool data I don't believe we have - **Simulated extranonce sweep** - Very niche, unclear value - **Block reconstruction** - Might want to make another subcommand for this one

parachemist (Migrated from github.com) reviewed

2025-12-11 15:26:36 +00:00

src/subcommand/template.rs