]> Untitled Git - bdk/commitdiff
feat(core): allow serialization of SyncResponse and FullScanResponse
authorClaude <noreply@anthropic.com>
Mon, 15 Jun 2026 21:36:20 +0000 (21:36 +0000)
committer志宇 <hello@evanlinjin.me>
Wed, 11 Nov 2026 00:32:41 +0000 (00:32 +0000)
Add serde::Serialize/Deserialize for SyncResponse and FullScanResponse so
a connected device can serialize a scan response and hand it to an
air-gapped device to apply independently.

Both responses hold a TxUpdate and an Option<CheckPoint>:

- TxUpdate gains a plain derive; its fields are flat collections so
  there is nothing self-referential to recurse over.
- CheckPoint is a reference-counted linked list, so a derived impl
  would recurse through prev/skip once per checkpoint and overflow
  the stack on long chains -- the same hazard that forced the
  hand-written Drop (#1634). It is instead serialized iteratively as a
  flat sequence of (height, data) pairs and rebuilt with
  CheckPoint::from_blocks, which re-derives the skip/index
  topology deterministically.

Tests cover round-tripping CheckPoint, TxUpdate, SyncResponse and
FullScanResponse, and assert (de)serialization is not recursive by
round-tripping a long chain on a deliberately small thread stack.

https://claude.ai/code/session_014BXMFRQP8qoGBghJcWzakG

crates/core/Cargo.toml
crates/core/src/checkpoint.rs
crates/core/src/spk_client.rs
crates/core/src/tx_update.rs

index 30f46a7817ca5ce3b7ca94a8af84637b1a8ae3dd..07ac8ac96aabfc48f45dff5fdcf03d3805090d6b 100644 (file)
@@ -12,7 +12,7 @@ readme = "README.md"
 
 [dependencies]
 bitcoin = { version = "0.32", default-features = false }
-serde = { version = "1", optional = true, default-features=false, features = ["derive"] }
+serde = { version = "1", optional = true, default-features = false, features = ["derive", "rc", "alloc"] }
 hashbrown = { version = "0.14.5", optional = true, default-features = false, features = ["ahash", "inline-more"] }
 
 [features]
@@ -25,6 +25,7 @@ bdk_chain = { path = "../chain" }
 bdk_testenv = { path = "../testenv", default-features = false }
 criterion = { version = "0.7" }
 proptest = "1.2.0"
+serde_json = "1"
 
 [[bench]]
 name = "checkpoint_skiplist"
index 02c1f5cd992b6d3d92f297b3ba5294ff7e56991b..7be0b40fe5e79502051bd5f372cedf08f23562c4 100644 (file)
@@ -621,6 +621,55 @@ impl<D> IntoIterator for CheckPoint<D> {
     }
 }
 
+/// Serializes a [`CheckPoint`] as a flat sequence of `(height, data)` pairs, ordered from tip to
+/// base (descending height).
+///
+/// Iterates rather than recursing over the linked list, so long chains can't overflow the stack.
+/// The `skip`/`index` topology isn't serialized; it is rebuilt on deserialization.
+#[cfg(feature = "serde")]
+impl<D> serde::Serialize for CheckPoint<D>
+where
+    D: serde::Serialize,
+{
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        use serde::ser::SerializeSeq;
+        // `index` is the number of checkpoints below the tip, so the chain has `index + 1` nodes.
+        let mut seq = serializer.serialize_seq(Some(self.0.index as usize + 1))?;
+        for cp in self.iter() {
+            seq.serialize_element(&(cp.height(), cp.data_ref()))?;
+        }
+        seq.end()
+    }
+}
+
+/// Deserializes a [`CheckPoint`] from the flat sequence of `(height, data)` pairs produced by its
+/// [`Serialize`](serde::Serialize) implementation.
+///
+/// The chain is rebuilt iteratively with [`CheckPoint::from_blocks`] (which re-derives the
+/// `skip`/`index` topology), so deserialization never recurses regardless of chain length.
+#[cfg(feature = "serde")]
+impl<'de, D> serde::Deserialize<'de> for CheckPoint<D>
+where
+    D: serde::Deserialize<'de> + ToBlockHash + Clone + fmt::Debug,
+{
+    fn deserialize<De>(deserializer: De) -> Result<Self, De::Error>
+    where
+        De: serde::Deserializer<'de>,
+    {
+        use serde::de::Error;
+        // Serialized tip-first (descending height); `from_blocks` expects ascending order.
+        let blocks = Vec::<(u32, D)>::deserialize(deserializer)?;
+        CheckPoint::from_blocks(blocks.into_iter().rev()).map_err(|_| {
+            De::Error::custom(
+                "invalid checkpoint chain: blocks must be non-empty and in ascending height order",
+            )
+        })
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -647,6 +696,65 @@ mod tests {
             .unwrap();
     }
 
+    /// Round-trip a long chain on a small stack: (de)serialization must not recurse.
+    #[cfg(feature = "serde")]
+    #[test]
+    fn checkpoint_serde_is_not_recursive() {
+        let run = || {
+            // A recursive impl needs at least one frame (>= 16 bytes) per checkpoint, so 10,240
+            // checkpoints need >= 160 KiB of stack.
+            let mut cp = CheckPoint::new(0, bitcoin::hashes::Hash::hash(b"genesis"));
+            for height in 1u32..=10_240 {
+                let hash: BlockHash = bitcoin::hashes::Hash::hash(height.to_be_bytes().as_slice());
+                cp = cp.push(height, hash).unwrap();
+            }
+
+            let json = serde_json::to_string(&cp).expect("serialization must not recurse");
+            let restored: CheckPoint =
+                serde_json::from_str(&json).expect("deserialization must not recurse");
+            assert_eq!(cp, restored);
+        };
+        // 32 KiB (as in `checkpoint_drop_is_not_recursive`) is enough for the iterative impl and
+        // well short of what a recursive one needs.
+        std::thread::Builder::new()
+            .stack_size(32 * 1024)
+            .spawn(run)
+            .unwrap()
+            .join()
+            .unwrap();
+    }
+
+    /// Deserialization must reject headers whose `prev_blockhash` doesn't link.
+    #[cfg(feature = "serde")]
+    #[test]
+    fn checkpoint_serde_rejects_unlinked_headers() {
+        use bitcoin::hashes::Hash;
+
+        let mut blocks = Vec::<(u32, Header)>::new();
+        let mut prev_blockhash = BlockHash::all_zeros();
+        for height in 0..3 {
+            let header = Header {
+                version: bitcoin::block::Version::ONE,
+                prev_blockhash,
+                merkle_root: bitcoin::TxMerkleNode::all_zeros(),
+                time: height,
+                bits: bitcoin::CompactTarget::from_consensus(0),
+                nonce: 0,
+            };
+            prev_blockhash = header.block_hash();
+            blocks.push((height, header));
+        }
+        let cp = CheckPoint::from_blocks(blocks.clone()).unwrap();
+        let json = serde_json::to_string(&cp).unwrap();
+        let restored: CheckPoint<Header> = serde_json::from_str(&json).unwrap();
+        assert_eq!(restored, cp);
+
+        // Unlink height 2 from height 1, and serialize tip-first as `CheckPoint` does.
+        blocks[2].1.prev_blockhash = BlockHash::all_zeros();
+        let json = serde_json::to_string(&blocks.iter().rev().collect::<Vec<_>>()).unwrap();
+        assert!(serde_json::from_str::<CheckPoint<Header>>(&json).is_err());
+    }
+
     #[test]
     fn checkpoint_does_not_leak() {
         const CHAIN_LEN: u32 = 1000;
index 36cc076e261b040457e662b48b0748c51ce78799..7da1f86ad29e265eb2c16f1d6b5e118e93de0822 100644 (file)
@@ -447,6 +447,15 @@ impl<I, D> SyncRequest<I, D> {
 /// See also [`SyncRequest`].
 #[must_use]
 #[derive(Debug, Clone, PartialEq)]
+#[cfg_attr(
+    feature = "serde",
+    derive(serde::Serialize, serde::Deserialize),
+    serde(bound(
+        serialize = "A: serde::Serialize, D: serde::Serialize",
+        deserialize = "A: Ord + serde::Deserialize<'de>, \
+                       D: crate::ToBlockHash + Clone + core::fmt::Debug + serde::Deserialize<'de>"
+    ))
+)]
 pub struct SyncResponse<A = ConfirmationBlockTime, D = BlockHash> {
     /// Relevant transaction data discovered during the scan.
     pub tx_update: crate::TxUpdate<A>,
@@ -630,6 +639,15 @@ impl<K: Ord + Clone, D> FullScanRequest<K, D> {
 /// See also [`FullScanRequest`].
 #[must_use]
 #[derive(Debug, Clone, PartialEq)]
+#[cfg_attr(
+    feature = "serde",
+    derive(serde::Serialize, serde::Deserialize),
+    serde(bound(
+        serialize = "K: serde::Serialize, A: serde::Serialize, D: serde::Serialize",
+        deserialize = "K: Ord + serde::Deserialize<'de>, A: Ord + serde::Deserialize<'de>, \
+                       D: crate::ToBlockHash + Clone + core::fmt::Debug + serde::Deserialize<'de>"
+    ))
+)]
 pub struct FullScanResponse<K, A = ConfirmationBlockTime, D = BlockHash> {
     /// Relevant transaction data discovered during the scan.
     pub tx_update: crate::TxUpdate<A>,
@@ -732,3 +750,44 @@ impl<I, D> Iterator for SyncIter<'_, I, D, OutPoint> {
         (remaining, Some(remaining))
     }
 }
+
+#[cfg(all(test, feature = "serde"))]
+mod test {
+    use super::*;
+    use bitcoin::hashes::Hash;
+
+    #[test]
+    fn sync_response_serde_round_trip() {
+        let cp = CheckPoint::new(0, Hash::hash(b"genesis"))
+            .push(1, Hash::hash(b"block"))
+            .unwrap();
+        let response: SyncResponse = SyncResponse {
+            tx_update: crate::TxUpdate::default(),
+            chain_update: Some(cp),
+        };
+
+        let json = serde_json::to_string(&response).expect("serialization must succeed");
+        let restored: SyncResponse =
+            serde_json::from_str(&json).expect("deserialization must succeed");
+
+        assert_eq!(response, restored);
+    }
+
+    #[test]
+    fn full_scan_response_serde_round_trip() {
+        let cp = CheckPoint::new(0, Hash::hash(b"genesis"))
+            .push(1, Hash::hash(b"block"))
+            .unwrap();
+        let response: FullScanResponse<&str> = FullScanResponse {
+            tx_update: crate::TxUpdate::default(),
+            last_active_indices: [("external", 5), ("internal", 2)].into(),
+            chain_update: Some(cp),
+        };
+
+        let json = serde_json::to_string(&response).expect("serialization must succeed");
+        let restored: FullScanResponse<&str> =
+            serde_json::from_str(&json).expect("deserialization must succeed");
+
+        assert_eq!(response, restored);
+    }
+}
index bf4afed2494d544c1ee62afab62f7ed5eb5a6867..0beb52877b84f92acfc02d2d8c63e92877149f93 100644 (file)
@@ -26,6 +26,17 @@ use bitcoin::{OutPoint, Transaction, TxOut, Txid};
 /// The built-in chain-source crates (`bdk_electrum`, `bdk_esplora`, `bdk_bitcoind_rpc`) handle this
 /// automatically. Transactions lacking temporal context are stored but ignored by canonicalization.
 #[derive(Debug, Clone, PartialEq)]
+#[cfg_attr(
+    feature = "serde",
+    derive(serde::Serialize, serde::Deserialize),
+    serde(
+        default,
+        bound(
+            serialize = "A: serde::Serialize",
+            deserialize = "A: Ord + serde::Deserialize<'de>"
+        )
+    )
+)]
 #[non_exhaustive]
 pub struct TxUpdate<A = ()> {
     /// Full transactions. These are transactions that were determined to be relevant to the wallet
@@ -110,3 +121,49 @@ impl<A: Ord> TxUpdate<A> {
         self.evicted_ats.extend(other.evicted_ats);
     }
 }
+
+#[cfg(all(test, feature = "serde"))]
+mod test {
+    use super::*;
+    use crate::{BlockId, ConfirmationBlockTime};
+    use bitcoin::{hashes::Hash, Amount, ScriptBuf};
+
+    #[test]
+    fn tx_update_serde_round_trip() {
+        let tx = Transaction {
+            version: bitcoin::transaction::Version::non_standard(0),
+            lock_time: bitcoin::absolute::LockTime::ZERO,
+            input: Vec::new(),
+            output: Vec::new(),
+        };
+        let txid = tx.compute_txid();
+
+        let mut tx_update = TxUpdate::<ConfirmationBlockTime>::default();
+        tx_update.txs.push(Arc::new(tx));
+        tx_update.txouts.insert(
+            OutPoint::new(txid, 0),
+            TxOut {
+                value: Amount::from_sat(42_000),
+                script_pubkey: ScriptBuf::new(),
+            },
+        );
+        tx_update.anchors.insert((
+            ConfirmationBlockTime {
+                block_id: BlockId {
+                    height: 7,
+                    hash: Hash::hash(b"anchor"),
+                },
+                confirmation_time: 1_700_000_000,
+            },
+            txid,
+        ));
+        tx_update.seen_ats.insert((txid, 1_700_000_001));
+        tx_update.evicted_ats.insert((txid, 1_700_000_002));
+
+        let json = serde_json::to_string(&tx_update).expect("serialization must succeed");
+        let restored: TxUpdate<ConfirmationBlockTime> =
+            serde_json::from_str(&json).expect("deserialization must succeed");
+
+        assert_eq!(tx_update, restored);
+    }
+}