feat(pruning): block + undo pruner + utreexo-only mode coordinator

Block-file pruner with Core 288-block reorg-safety floor; undo-file pruner
symmetric. Utreexo-only coordinator deletes block bodies after indexing while
retaining headers. PrunePolicy mirrors Core -prune semantics with full/minimal/
utreexo-only presets.

Op: extend

Author: bitcoin-rs

Cargo.lock

@@ -12,3 +12,24 @@ description = "bitcoin-rs :: pruning"
 workspace = true
 
 [dependencies]
+bitcoin-rs-primitives.workspace = true
+bitcoin-rs-storage = { workspace = true, default-features = false }
+bitcoin-rs-utxo.workspace = true
+bitcoin-rs-chain.workspace = true
+bitcoin-rs-utreexo.workspace = true
+bitcoin.workspace = true
+parking_lot.workspace = true
+thiserror.workspace = true
+tracing.workspace = true
+
+[features]
+default = []
+rocksdb = ["bitcoin-rs-storage/rocksdb"]
+fjall = ["bitcoin-rs-storage/fjall"]
+redb = ["bitcoin-rs-storage/redb"]
+mdbx = ["bitcoin-rs-storage/mdbx"]
+
+[dev-dependencies]
+proptest.workspace = true
+serde_json.workspace = true
+tempfile = "3"

crates/pruning/Cargo.toml

@@ -0,0 +1,122 @@
+use alloc::sync::Arc;
+
+use bitcoin_rs_primitives::Hash256;
+use bitcoin_rs_storage::{ColumnFamily, KvStore, WriteBatch};
+
+use crate::{PruneError, PruneOutcome, PrunePolicy, row_len_u64};
+
+const BLOCK_BODY_PREFIX: u8 = b'b';
+const BLOCK_BODY_PREFIX_BYTES: &[u8] = b"b";
+const HEIGHT_START: usize = 1;
+const HEIGHT_END: usize = 5;
+const KEY_LEN: usize = 37;
+
+/// Column family used for block-body rows until storage gains a dedicated block-file CF.
+pub const BLOCK_DATA_CF: ColumnFamily = ColumnFamily::BlockTree;
+
+/// Builds the canonical pruning key for a stored block body.
+#[must_use]
+pub fn block_body_key(height: u32, hash: Hash256) -> [u8; KEY_LEN] {
+    let mut key = [0_u8; KEY_LEN];
+    key[0] = BLOCK_BODY_PREFIX;
+    key[HEIGHT_START..HEIGHT_END].copy_from_slice(&height.to_be_bytes());
+    key[HEIGHT_END..].copy_from_slice(hash.as_byte_array());
+    key
+}
+
+/// Prunes persisted block-body rows according to a [`PrunePolicy`].
+pub struct BlockPruner<S: KvStore> {
+    store: Arc<S>,
+    policy: PrunePolicy,
+}
+
+impl<S: KvStore> BlockPruner<S> {
+    /// Creates a block pruner over `store`.
+    #[must_use]
+    pub const fn new(store: Arc<S>, policy: PrunePolicy) -> Self {
+        Self { store, policy }
+    }
+
+    /// Returns this pruner's policy.
+    #[must_use]
+    pub const fn policy(&self) -> PrunePolicy {
+        self.policy
+    }
+
+    /// Deletes block-body rows below the effective reorg-safety horizon until the target is met.
+    pub fn prune_step(&mut self, current_tip_height: u32) -> Result<PruneOutcome, PruneError> {
+        if self.policy.is_full_node() {
+            return Ok(PruneOutcome::default());
+        }
+
+        prune_prefixed_rows(
+            &*self.store,
+            BLOCK_BODY_PREFIX_BYTES,
+            current_tip_height,
+            self.policy,
+        )
+    }
+}
+
+pub(crate) fn prune_prefixed_rows<S: KvStore>(
+    store: &S,
+    prefix: &[u8],
+    current_tip_height: u32,
+    policy: PrunePolicy,
+) -> Result<PruneOutcome, PruneError> {
+    let target_bytes = policy.target_size_bytes();
+    let prune_below_height = current_tip_height.saturating_sub(policy.retention_depth());
+    let mut total_bytes = 0_u64;
+    let mut candidates = Vec::new();
+
+    for row in store.iter_prefix(BLOCK_DATA_CF, prefix)? {
+        let (key, value) = row?;
+        let row_bytes = row_len_u64(&value)?;
+        total_bytes = total_bytes.saturating_add(row_bytes);
+
+        if let Some(height) = row_height(&key, prefix) {
+            if height < prune_below_height {
+                candidates.push((key, row_bytes));
+            }
+        }
+    }
+
+    if total_bytes <= target_bytes || candidates.is_empty() {
+        return Ok(PruneOutcome::default());
+    }
+
+    let mut remaining_bytes = total_bytes;
+    let mut outcome = PruneOutcome::default();
+    let mut batch = store.new_batch();
+
+    for (key, row_bytes) in candidates {
+        if remaining_bytes <= target_bytes {
+            break;
+        }
+
+        batch.delete(BLOCK_DATA_CF, &key);
+        remaining_bytes = remaining_bytes.saturating_sub(row_bytes);
+        outcome.record_removed(row_bytes);
+    }
+
+    if !outcome.is_empty() {
+        store.write(batch)?;
+        tracing::debug!(
+            bytes_freed = outcome.bytes_freed,
+            blocks_removed = outcome.blocks_removed,
+            "pruned block storage rows"
+        );
+    }
+
+    Ok(outcome)
+}
+
+fn row_height(key: &[u8], prefix: &[u8]) -> Option<u32> {
+    if key.len() != KEY_LEN || !key.starts_with(prefix) {
+        return None;
+    }
+
+    let mut bytes = [0_u8; 4];
+    bytes.copy_from_slice(&key[HEIGHT_START..HEIGHT_END]);
+    Some(u32::from_be_bytes(bytes))
+}

crates/pruning/src/block_pruner.rs

@@ -1,2 +1,62 @@
 #![doc = include_str!("../README.md")]
 #![forbid(unsafe_op_in_unsafe_fn)]
+
+extern crate alloc;
+
+/// Block-body pruning over persisted block rows.
+pub mod block_pruner;
+/// Pruning policy shapes matching Bitcoin Core semantics.
+pub mod policy;
+/// Undo-data pruning over persisted undo rows.
+pub mod undo_pruner;
+/// Utreexo-only block body deletion coordinator.
+pub mod utreexo_only;
+
+pub use block_pruner::{BlockPruner, block_body_key};
+pub use policy::PrunePolicy;
+pub use undo_pruner::{UndoPruner, block_undo_key};
+pub use utreexo_only::{BlockProcessed, UtreexoOnlyCoordinator};
+
+use bitcoin_rs_storage::StorageError;
+use thiserror::Error;
+
+/// Result of one pruning pass.
+#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
+pub struct PruneOutcome {
+    /// Number of payload bytes deleted from storage.
+    pub bytes_freed: u64,
+    /// Number of block or undo rows deleted from storage.
+    pub blocks_removed: u64,
+}
+
+impl PruneOutcome {
+    /// Adds one deleted row to the outcome.
+    pub(crate) fn record_removed(&mut self, bytes: u64) {
+        self.bytes_freed = self.bytes_freed.saturating_add(bytes);
+        self.blocks_removed = self.blocks_removed.saturating_add(1);
+    }
+
+    /// Returns true when no rows were deleted.
+    #[must_use]
+    pub const fn is_empty(self) -> bool {
+        self.blocks_removed == 0
+    }
+}
+
+/// Errors returned while pruning persisted block or undo rows.
+#[derive(Debug, Error)]
+pub enum PruneError {
+    /// A storage backend operation failed.
+    #[error(transparent)]
+    Storage(#[from] StorageError),
+    /// A storage row length could not fit in the pruning byte counter.
+    #[error("storage row length {size} does not fit in u64")]
+    RowSizeOverflow {
+        /// Row length returned by the storage backend.
+        size: usize,
+    },
+}
+
+pub(crate) fn row_len_u64(value: &[u8]) -> Result<u64, PruneError> {
+    u64::try_from(value.len()).map_err(|_| PruneError::RowSizeOverflow { size: value.len() })
+}

crates/pruning/src/lib.rs

@@ -0,0 +1,73 @@
+/// Minimum number of blocks kept below the active tip for Core-compatible reorg safety.
+pub const CORE_REORG_SAFETY_MARGIN: u32 = 288;
+
+const BYTES_PER_MIB: u64 = 1024 * 1024;
+
+/// Block and undo pruning policy.
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub struct PrunePolicy {
+    /// Target serialized block-data footprint in mebibytes.
+    pub target_size_mb: u64,
+    /// Caller-requested number of blocks retained below the active tip.
+    pub keep_below_tip: u32,
+}
+
+impl PrunePolicy {
+    /// Returns a policy that disables pruning.
+    #[must_use]
+    pub const fn full_node() -> Self {
+        Self {
+            target_size_mb: u64::MAX,
+            keep_below_tip: u32::MAX,
+        }
+    }
+
+    /// Returns Bitcoin Core's minimal pruning shape: 550 MiB and 288-block reorg margin.
+    #[must_use]
+    pub const fn minimal() -> Self {
+        Self {
+            target_size_mb: 550,
+            keep_below_tip: CORE_REORG_SAFETY_MARGIN,
+        }
+    }
+
+    /// Returns a Utreexo-only policy that discards block bodies immediately.
+    #[must_use]
+    pub const fn utreexo_only() -> Self {
+        Self {
+            target_size_mb: 0,
+            keep_below_tip: 0,
+        }
+    }
+
+    /// Returns true when this policy disables pruning.
+    #[must_use]
+    pub const fn is_full_node(self) -> bool {
+        self.target_size_mb == u64::MAX
+    }
+
+    /// Returns true when this policy requests immediate Utreexo-only block deletion.
+    #[must_use]
+    pub const fn is_utreexo_only(self) -> bool {
+        self.target_size_mb == 0 && self.keep_below_tip == 0
+    }
+
+    /// Returns the byte target used by pruning passes.
+    #[must_use]
+    pub const fn target_size_bytes(self) -> u64 {
+        self.target_size_mb.saturating_mul(BYTES_PER_MIB)
+    }
+
+    /// Returns the effective retention depth below tip.
+    #[must_use]
+    pub fn retention_depth(self) -> u32 {
+        // SPEC: Core's reorg-safety margin is 288 blocks.
+        self.keep_below_tip.max(CORE_REORG_SAFETY_MARGIN)
+    }
+}
+
+impl Default for PrunePolicy {
+    fn default() -> Self {
+        Self::full_node()
+    }
+}

crates/pruning/src/policy.rs

@@ -0,0 +1,57 @@
+use alloc::sync::Arc;
+
+use bitcoin_rs_primitives::Hash256;
+use bitcoin_rs_storage::KvStore;
+
+use crate::block_pruner::prune_prefixed_rows;
+use crate::{PruneError, PruneOutcome, PrunePolicy};
+
+const BLOCK_UNDO_PREFIX: u8 = b'u';
+const BLOCK_UNDO_PREFIX_BYTES: &[u8] = b"u";
+const HEIGHT_START: usize = 1;
+const HEIGHT_END: usize = 5;
+const KEY_LEN: usize = 37;
+
+/// Builds the canonical pruning key for stored undo data for one block.
+#[must_use]
+pub fn block_undo_key(height: u32, hash: Hash256) -> [u8; KEY_LEN] {
+    let mut key = [0_u8; KEY_LEN];
+    key[0] = BLOCK_UNDO_PREFIX;
+    key[HEIGHT_START..HEIGHT_END].copy_from_slice(&height.to_be_bytes());
+    key[HEIGHT_END..].copy_from_slice(hash.as_byte_array());
+    key
+}
+
+/// Prunes persisted undo rows according to a [`PrunePolicy`].
+pub struct UndoPruner<S: KvStore> {
+    store: Arc<S>,
+    policy: PrunePolicy,
+}
+
+impl<S: KvStore> UndoPruner<S> {
+    /// Creates an undo pruner over `store`.
+    #[must_use]
+    pub const fn new(store: Arc<S>, policy: PrunePolicy) -> Self {
+        Self { store, policy }
+    }
+
+    /// Returns this pruner's policy.
+    #[must_use]
+    pub const fn policy(&self) -> PrunePolicy {
+        self.policy
+    }
+
+    /// Deletes undo rows below the effective reorg-safety horizon until the target is met.
+    pub fn prune_step(&mut self, current_tip_height: u32) -> Result<PruneOutcome, PruneError> {
+        if self.policy.is_full_node() {
+            return Ok(PruneOutcome::default());
+        }
+
+        prune_prefixed_rows(
+            &*self.store,
+            BLOCK_UNDO_PREFIX_BYTES,
+            current_tip_height,
+            self.policy,
+        )
+    }
+}