fix: snapshot getblockchaininfo tip fields

Author: metaphorics

CONCEPTS.md

@@ -39,6 +39,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/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,21 +15,19 @@ 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, time, mediantime) =
-        ctx.applied_tip
-            .load_full()
-            .map_or((0.0, 0_u64, 0_u64), |tip| {
-                let tree = ctx.block_tree.read();
-                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 (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).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)
     } else {
@@ -47,8 +46,13 @@ 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);
@@ -68,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 = {
@@ -1359,6 +1372,52 @@ mod tests {
         );
     }
 
+    #[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

@@ -35,7 +35,7 @@ The same difficulty helper also affected `getblockheader`, `getblock`,
 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 the mainnet difficulty-1 reference
+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
@@ -49,21 +49,27 @@ 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`, while serde emits the
-shortest round-trip representation. Consequently, Core prints
-`4.656542373906925e-10` and serde prints `4.6565423739069247e-10`; these are
-different strings even though the underlying value is the same.
+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.
 
-Assert compatibility at the value level with `f64::to_bits()`, not by
-comparing JSON text. Do not add a one-ULP adjustment to make serde'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.
+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
 
@@ -74,8 +80,9 @@ representations of the same IEEE-754 number.
 
 ## Prevention
 
-- Compare cross-node floating-point RPC results by exact value or
-  `f64::to_bits()`, not by serialized decimal text.
+- 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