[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]
bdk_testenv = { path = "../testenv", default-features = false }
criterion = { version = "0.7" }
proptest = "1.2.0"
+serde_json = "1"
[[bench]]
name = "checkpoint_skiplist"
}
}
+/// 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::*;
.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;
/// 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>,
/// 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>,
(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);
+ }
+}
/// 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
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);
+ }
+}