Merge pull request #50 from gosuda/devin/1786437854-getblockchaininfo-fields

rpc: report real difficulty, time and mediantime from getblockchaininfo

Author: metaphorics

CONCEPTS.md

@@ -49,6 +49,20 @@ Bitcoin Core's C++ consensus engine (`libbitcoinkernel`), compiled into `bitcoin
 ### bitcoinconsensus
 Removed historical script verification backend. Previously linked as an extracted C library for non-taproot script checks before being deleted in favor of `bitcoinkernel`. The library lacked complete-prevout and Taproot script-path verification capabilities required for current mainnet script validation (exposed by block 938344 during mainnet IBD).
 
+### Difficulty-1 target
+The network-independent reference target used by Bitcoin Core's difficulty
+calculation: compact nBits `0x1d00ffff`, rather than the selected network's
+PoW limit. Confusing the two makes every network report difficulty `1.0` at
+its easiest target. See
+`docs/solutions/logic-errors/core-float-parity-is-value-parity-not-json-text-parity.md`.
+
+### Float value/text parity
+The distinction between equal IEEE-754 values and equal serialized spellings.
+Core's UniValue uses `%.16g`, while the live RPC path's sonic-rs serializer
+uses shortest-round-trip formatting, so compatibility means preserving the
+value and operation order, not forcing JSON text to match. See
+`docs/solutions/logic-errors/core-float-parity-is-value-parity-not-json-text-parity.md`.
+
 ### Rust interpreter (portable posture)
 The pure-Rust script verification path maintained alongside the bitcoinkernel default. Enabled under `--no-default-features` without C++ build dependencies. Its non-Taproot path is a stub that accepts only a bare `OP_TRUE` spend with an empty scriptSig and witness, so it cannot validate ordinary spends either, and it has no Taproot script-path support. What it does verify is the Taproot key path, in full. It is retained for differential testing and lightweight non-production environments; a mainnet sync stops early on the first real spend.
 

crates/rpc/src/context.rs

@@ -457,17 +457,29 @@ impl Context {
             .map_or_else(PruneStatus::default, |service| service.status())
     }
 
-    /// Returns the f64 difficulty for `bits`, computed against the network's
-    /// `PoW` limit. Returns `0.0` on any conversion failure.
+    /// Returns the f64 difficulty for `bits` using Bitcoin Core's calculation.
+    ///
+    /// Keep the operation order here in sync with Core's `GetDifficulty`;
+    /// changing the repeated 256 scaling into an equivalent exponentiation can
+    /// change the final floating-point bit.
     #[must_use]
     pub fn difficulty_for_bits(&self, bits: bitcoin::CompactTarget) -> f64 {
-        let params = bitcoin::params::Params::new(bitcoin_network(self.chain_network));
-        let current_target = bitcoin::pow::Target::from_compact(bits);
-        if current_target == bitcoin::pow::Target::ZERO {
+        let consensus_bits = bits.to_consensus();
+        let mantissa = consensus_bits & 0x00ff_ffff;
+        if mantissa == 0 {
             return 0.0;
         }
-
-        target_to_f64(params.max_attainable_target) / target_to_f64(current_target)
+        let mut shift = (consensus_bits >> 24) & 0xff;
+        let mut difficulty = f64::from(0x0000_ffff_u32) / f64::from(mantissa);
+        while shift < 29 {
+            difficulty *= 256.0;
+            shift += 1;
+        }
+        while shift > 29 {
+            difficulty /= 256.0;
+            shift -= 1;
+        }
+        difficulty
     }
 
     /// Publishes a new best-chain tip and wakes getblocktemplate long polls.
@@ -746,13 +758,6 @@ fn bitcoin_network(network: Network) -> bitcoin::Network {
     }
 }
 
-fn target_to_f64(target: bitcoin::pow::Target) -> f64 {
-    target
-        .to_be_bytes()
-        .iter()
-        .fold(0.0_f64, |acc, &byte| acc.mul_add(256.0, f64::from(byte)))
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;

crates/rpc/src/handlers/chain.rs

@@ -2,8 +2,9 @@ use alloc::sync::Arc;
 use bitcoin::consensus::encode::deserialize;
 use bitcoin::hex::{DisplayHex as _, FromHex as _};
 use core::str::FromStr as _;
+use core::{fmt, fmt::Write as _};
 
-use bitcoin_rs_chain::NodeStatus;
+use bitcoin_rs_chain::{NodeStatus, TipSnapshot};
 use bitcoin_rs_primitives::Hash256;
 use bitcoin_rs_pruning::policy::CORE_REORG_SAFETY_MARGIN;
 use sonic_rs::{JsonContainerTrait as _, JsonValueTrait, Value, json};
@@ -14,13 +15,18 @@ use crate::handlers::{ensure_no_params, optional_bool, params_array, required_st
 
 pub(crate) fn getblockchaininfo(ctx: &Arc<Context>, params: &Value) -> Result<Value, RpcError> {
     ensure_no_params(params)?;
-    let applied = ctx.applied_height();
+    let applied_tip = ctx.applied_tip.load_full();
+    let applied = applied_tip.as_ref().map_or(0, |tip| tip.height);
     let headers = ctx.height();
-    let difficulty = ctx.applied_tip.load_full().map_or(0.0, |tip| {
+    let (difficulty, time, mediantime) = applied_tip.as_ref().map_or((0.0, 0_u64, 0_u64), |tip| {
         let tree = ctx.block_tree.read();
-        tree.node(tip.tip_id)
-            .ok()
-            .map_or(0.0, |node| ctx.difficulty_for_bits(node.header.bits))
+        tree.node(tip.tip_id).map_or((0.0, 0, 0), |node| {
+            (
+                ctx.difficulty_for_bits(node.header.bits),
+                u64::from(node.header.time),
+                u64::from(tree.median_time_past_at(tip.tip_id, 11).unwrap_or(0)),
+            )
+        })
     });
     let verification_progress = if headers > 0 {
         f64::from(applied) / f64::from(headers)
@@ -40,16 +46,21 @@ pub(crate) fn getblockchaininfo(ctx: &Arc<Context>, params: &Value) -> Result<Va
         fold_block_records(&blocks, applied, None)
     };
     let prune_status = ctx.prune_status();
-    let bestblockhash = ctx.applied_hash().to_string_be();
-    let chainwork = ctx.chainwork_hex();
+    let bestblockhash = applied_tip
+        .as_ref()
+        .map_or_else(Hash256::default, |tip| tip.hash)
+        .to_string_be();
+    let chainwork = applied_tip
+        .as_deref()
+        .map_or_else(|| ctx.chainwork_hex(), chainwork_hex);
     let mut response = sonic_rs::Object::new();
     let _ = response.insert(&"chain", chain);
     let _ = response.insert(&"blocks", applied);
     let _ = response.insert(&"headers", headers);
     let _ = response.insert(&"bestblockhash", bestblockhash.as_str());
     let _ = response.insert(&"difficulty", json!(difficulty));
-    let _ = response.insert(&"time", 0_u64);
-    let _ = response.insert(&"mediantime", 0_u64);
+    let _ = response.insert(&"time", time);
+    let _ = response.insert(&"mediantime", mediantime);
     let _ = response.insert(&"verificationprogress", json!(verification_progress));
     let _ = response.insert(&"initialblockdownload", applied < headers);
     let _ = response.insert(&"chainwork", chainwork.as_str());
@@ -61,6 +72,15 @@ pub(crate) fn getblockchaininfo(ctx: &Arc<Context>, params: &Value) -> Result<Va
     let _ = response.insert(&"warnings", "");
     Ok(Value::from(response))
 }
+
+fn chainwork_hex(tip: &TipSnapshot) -> String {
+    let bytes: [u8; 32] = tip.chainwork.to_be_bytes();
+    let mut out = String::with_capacity(bytes.len() * 2);
+    for byte in bytes {
+        let _: fmt::Result = write!(&mut out, "{byte:02x}");
+    }
+    out
+}
 pub(crate) fn getdifficulty(ctx: &Arc<Context>, params: &Value) -> Result<Value, RpcError> {
     ensure_no_params(params)?;
     let difficulty = {
@@ -941,10 +961,55 @@ mod tests {
     use core::sync::atomic::{AtomicUsize, Ordering};
 
     use bitcoin::blockdata::constants::genesis_block;
+    use bitcoin::hashes::Hash as _;
+    use bitcoin::{BlockHash, CompactTarget, TxMerkleNode, block::Header, block::Version};
 
     use super::*;
     use bitcoin_rs_chain::{ChainWork, NodeId, TipSnapshot};
 
+    fn context_with_tip(
+        network: bitcoin_rs_primitives::Network,
+        bits: u32,
+        times: &[u32],
+    ) -> Arc<Context> {
+        let mut context = Context::new();
+        context.chain_network = network;
+        let ctx = Arc::new(context);
+        let (tip_id, tip_hash) = {
+            let mut tree = ctx.block_tree.write();
+            let mut parent = None;
+            let mut previous_hash = BlockHash::all_zeros();
+            let mut tip_id = NodeId::new(0);
+            let mut tip_hash = Hash256::default();
+            for (index, time) in times.iter().copied().enumerate() {
+                let header = Header {
+                    version: Version::ONE,
+                    prev_blockhash: previous_hash,
+                    merkle_root: TxMerkleNode::all_zeros(),
+                    time,
+                    bits: CompactTarget::from_consensus(bits),
+                    nonce: u32::try_from(index).unwrap_or(u32::MAX),
+                };
+                previous_hash = header.block_hash();
+                tip_id = tree
+                    .insert_node(parent, header, NodeStatus::Active)
+                    .unwrap_or(tip_id);
+                tip_hash = Hash256::from_le_bytes(previous_hash.as_byte_array());
+                parent = Some(tip_id);
+            }
+            (tip_id, tip_hash)
+        };
+        let tip = TipSnapshot {
+            tip_id,
+            height: u32::try_from(times.len().saturating_sub(1)).unwrap_or(u32::MAX),
+            chainwork: ChainWork::ZERO,
+            hash: tip_hash,
+        };
+        ctx.set_chain_tip(tip.clone());
+        ctx.set_applied_tip(tip);
+        ctx
+    }
+
     #[test]
     fn subsidy_at_height_genesis_is_50_btc() {
         assert_eq!(subsidy_at_height(0), 5_000_000_000);
@@ -1269,6 +1334,90 @@ mod tests {
         );
     }
 
+    #[test]
+    fn difficulty_matches_core_for_mainnet_and_regtest_targets() {
+        let ctx = Context::new();
+        let mainnet = ctx.difficulty_for_bits(CompactTarget::from_consensus(0x1d00_ffff));
+        assert_eq!(mainnet.to_bits(), 1.0_f64.to_bits());
+        let regtest = ctx.difficulty_for_bits(CompactTarget::from_consensus(0x207f_ffff));
+        let expected = 4.656_542_373_906_924_7e-10_f64;
+        assert_eq!(regtest.to_bits(), expected.to_bits());
+    }
+
+    #[test]
+    fn getblockchaininfo_reports_tip_time_and_median_time_past() {
+        let ctx = context_with_tip(
+            bitcoin_rs_primitives::Network::Regtest,
+            0x207f_ffff,
+            &[100, 300, 200],
+        );
+        let result = getblockchaininfo(&ctx, &json!([]))
+            .unwrap_or_else(|err| panic!("getblockchaininfo failed: {err}"));
+
+        assert_eq!(
+            result.get("time").and_then(JsonValueTrait::as_u64),
+            Some(200)
+        );
+        assert_eq!(
+            result.get("mediantime").and_then(JsonValueTrait::as_u64),
+            Some(200)
+        );
+        let difficulty = result
+            .get("difficulty")
+            .and_then(JsonValueTrait::as_f64)
+            .unwrap_or_default();
+        assert_eq!(
+            difficulty.to_bits(),
+            4.656_542_373_906_924_7e-10_f64.to_bits()
+        );
+    }
+
+    #[test]
+    fn getblockchaininfo_uses_one_applied_tip_snapshot() {
+        use bitcoin_rs_chain::ChainWork;
+
+        let ctx = context_with_tip(
+            bitcoin_rs_primitives::Network::Regtest,
+            0x207f_ffff,
+            &[100, 300, 200],
+        );
+        let Some(applied) = ctx.applied_tip.load_full() else {
+            panic!("applied tip missing");
+        };
+        let applied_chainwork = ChainWork::from_be_bytes([1; 32]);
+        ctx.set_applied_tip(TipSnapshot {
+            chainwork: applied_chainwork,
+            ..(*applied).clone()
+        });
+        ctx.set_chain_tip(TipSnapshot {
+            tip_id: applied.tip_id,
+            height: 99,
+            chainwork: ChainWork::from_be_bytes([2; 32]),
+            hash: Hash256::from_le_bytes(&[9; 32]),
+        });
+
+        let result = getblockchaininfo(&ctx, &json!([]))
+            .unwrap_or_else(|err| panic!("getblockchaininfo failed: {err}"));
+        let expected_hash = applied.hash.to_string_be();
+        let expected_chainwork = "01".repeat(32);
+        assert_eq!(
+            result.get("blocks").and_then(JsonValueTrait::as_u64),
+            Some(2)
+        );
+        assert_eq!(
+            result.get("headers").and_then(JsonValueTrait::as_u64),
+            Some(99)
+        );
+        assert_eq!(
+            result.get("bestblockhash").and_then(JsonValueTrait::as_str),
+            Some(expected_hash.as_str())
+        );
+        assert_eq!(
+            result.get("chainwork").and_then(JsonValueTrait::as_str),
+            Some(expected_chainwork.as_str())
+        );
+    }
+
     #[test]
     fn getblockchaininfo_size_on_disk_uses_metadata_body_size() {
         let genesis = genesis_block(bitcoin::Network::Regtest);

docs/solutions/logic-errors/core-float-parity-is-value-parity-not-json-text-parity.md

@@ -0,0 +1,89 @@
+---
+title: Core float parity is value parity, not JSON text parity
+date: 2026-08-11
+category: docs/solutions/logic-errors
+module: crates/rpc/src/context.rs (Core-compatible numeric RPC fields)
+problem_type: logic_error
+component: rpc
+severity: medium
+applies_when:
+  - "A numeric RPC field is compared against Bitcoin Core"
+  - "A floating-point RPC value differs in its serialized spelling from Core"
+  - "A compatibility fix is tempted to nudge an f64 to match another serializer"
+related_components:
+  - bitcoin_core_rpc
+  - floating_point_serialization
+tags:
+  - floating-point
+  - bitcoin-core
+  - rpc-parity
+  - serialization
+  - difficulty
+---
+
+# Core float parity is value parity, not JSON text parity
+
+## Symptom
+
+On a regtest chain, `getblockchaininfo.difficulty` reported `1.0` in
+bitcoin-rs while Bitcoin Core 27.0 reported `4.656542373906925e-10`.
+The same difficulty helper also affected `getblockheader`, `getblock`,
+`getdifficulty`, and `getmininginfo`.
+
+## Cause
+
+The original calculation divided the current target by the network's own
+proof-of-work limit. That makes the easiest target on every network report
+`1.0`, even though Core defines difficulty as a multiple of the
+difficulty-1 target and therefore uses that network-independent reference
+independently of the selected network.
+
+There is a second compatibility trap after the value is corrected. Core's
+`GetDifficulty` performs this exact sequence:
+
+1. Compute `0x0000ffff / (nBits & 0x00ffffff)` as `f64`.
+2. Repeatedly multiply by `256.0` while the nBits exponent is below 29.
+3. Repeatedly divide by `256.0` while the exponent is above 29.
+
+The operation order matters for the final IEEE-754 bit. For
+`0x207fffff`, both implementations produce the double whose bits correspond
+to `4.6565423739069247e-10`.
+
+Core's RPC layer then formats that double with `%.16g` through UniValue, while
+the production RPC path here serializes its `sonic_rs::Value` with
+`sonic_rs::to_string`. sonic-rs delegates finite f64 formatting to its
+shortest-round-trip `zmij` formatter. Consequently, Core prints
+`4.656542373906925e-10` and sonic-rs prints `4.6565423739069247e-10`; these
+are different strings even though the underlying value is the same.
+
+## Fix
+
+Compute difficulty with the Core mantissa ratio and the repeated `256.0`
+scaling loop. Guard a zero mantissa and return `0.0` for that impossible but
+representable header value rather than dividing by zero.
+
+For direct algorithm tests, where both results are still pre-serialization
+doubles, assert compatibility at the value level with `f64::to_bits()`. Once
+either result has crossed the wire, Core's `%.16g` rendering can parse back to
+an adjacent double; compare with an appropriate tolerance or normalize the
+wire representation instead of requiring exact parsed-bit equality. Do not
+add a one-ULP adjustment to make sonic-rs's shortest spelling resemble Core's
+`%.16g` output: that changes the API value and makes it differ from Core's
+value precisely to match Core's formatting.
+
+## Why This Works
+
+The mantissa/exponent loop reproduces Core's `GetDifficulty` operation order,
+so the returned f64 is bit-for-bit equal to Core's result. The JSON spelling
+may still differ because the serializers choose different valid
+representations of the same IEEE-754 number.
+
+## Prevention
+
+- Compare direct cross-node floating-point algorithm results by exact value or
+  `f64::to_bits()` before serialization. For values parsed from RPC text, use
+  a documented tolerance or canonicalize the representation before comparing.
+- Preserve the reference implementation's floating-point operation order;
+  algebraically equivalent target division or `powi` can change the last bit.
+- Treat a rendering mismatch as a serializer issue. Never change a numeric
+  value merely to make its text match another implementation.