feat: subtree dump/restore primitives

grovedb/Cargo.toml

@@ -119,6 +119,17 @@ grovedbg = [
     "zip-extensions",
     "tempfile",
 ]
+# Snapshot-bootstrap primitives — escape hatches that bypass grovedb's normal
+# validation:
+#  - `GroveDb::raw_storage`            (escape hatch to StorageContext)
+#  - `RocksDbStorage::ingest_subtree_sst` (bulk-load SST into a CF)
+#  - `GroveDb::replace_subtree_root`   (caller-provided child hash, no
+#                                       cross-check against actual subtree state)
+# Enable ONLY for build-time tooling that needs to dump+restore a subtree
+# out-of-band (e.g. devnet shielded-pool snapshot bake/apply). Misuse will
+# produce an inconsistent Merk tree — there is no runtime check that the
+# caller-provided hash matches the underlying state.
+unsafe-dump-load = ["grovedb-storage/unsafe-dump-load"]
 
 [build-dependencies]
 hex-literal = "1.1.0"

grovedb/src/lib.rs

@@ -343,6 +343,54 @@ impl GroveDb {
         Ok(())
     }
 
+    /// Reborrow the underlying [`grovedb_storage::rocksdb_storage::RocksDbStorage`]
+    /// for callers that need to use the public [`grovedb_storage::Storage`]
+    /// trait directly — notably to open a [`grovedb_storage::StorageContext`]
+    /// at a path for raw iteration or low-level reads.
+    ///
+    /// This is intended for snapshot/replication tooling that needs to walk
+    /// a subtree's raw RocksDB state without going through GroveDb's typed
+    /// element API. Normal callers should NOT use this — go through GroveDb's
+    /// typed operations (`insert`, `get`, `commitment_tree_*`) instead.
+    ///
+    /// Stability: this is an escape hatch. The exact `RocksDbStorage` shape
+    /// is subject to change as grovedb's internals evolve.
+    ///
+    /// Gated behind the `unsafe-dump-load` feature — production builds should
+    /// leave it off so this escape hatch isn't even compiled in.
+    #[cfg(feature = "unsafe-dump-load")]
+    pub fn raw_storage(&self) -> &grovedb_storage::rocksdb_storage::RocksDbStorage {
+        &self.db
+    }
+
+    /// Bulk-ingest a single SST file (produced by `rocksdb::SstFileWriter`)
+    /// into the named column family of the underlying RocksDB.
+    ///
+    /// Delegates to
+    /// [`grovedb_storage::rocksdb_storage::RocksDbStorage::ingest_subtree_sst`].
+    /// Intended for snapshot-based bootstrap of a single subtree's storage
+    /// state — see that method's docs for safety contract.
+    ///
+    /// CF name for ordinary data storage is the default CF
+    /// (`rocksdb::DEFAULT_COLUMN_FAMILY_NAME`). Aux/roots/meta CFs are also
+    /// valid targets if a snapshot tool happens to cover them.
+    ///
+    /// This call bypasses any open transaction. The caller is responsible for
+    /// transaction semantics at a higher layer (e.g. only call when the
+    /// destination subtree is known empty, and rely on InitChain
+    /// abort = wipe-and-restart for failure recovery).
+    ///
+    /// Gated behind the `unsafe-dump-load` feature.
+    #[cfg(feature = "unsafe-dump-load")]
+    pub fn ingest_subtree_sst(
+        &self,
+        cf_name: &str,
+        sst_path: &std::path::Path,
+    ) -> Result<(), Error> {
+        self.db.ingest_subtree_sst(cf_name, sst_path)?;
+        Ok(())
+    }
+
     /// Opens the transactional Merk at the given path. Returns CostResult.
     fn open_transactional_merk_at_path<'db, 'b, B>(
         &'db self,

grovedb/src/operations/mod.rs

@@ -26,5 +26,11 @@ pub mod bulk_append_tree;
 #[cfg(feature = "minimal")]
 pub mod dense_tree;
 
+/// Caller-driven subtree-root replacement. Bypasses grovedb's normal
+/// "compute child hash from subtree state" invariant — see the module-level
+/// docs in `replace_subtree_root.rs` for the safety contract.
+#[cfg(all(feature = "minimal", feature = "unsafe-dump-load"))]
+pub mod replace_subtree_root;
+
 #[cfg(feature = "minimal")]
 pub use get::{QueryItemOrSumReturnType, MAX_REFERENCE_HOPS};

grovedb/src/operations/replace_subtree_root.rs

@@ -0,0 +1,120 @@
+//! Caller-driven subtree-root replacement.
+//!
+//! Replaces a subtree leaf's child hash + element data inside its parent
+//! Merk with caller-provided values, **without** re-reading the subtree to
+//! compute the hash. This is the tail of every `*_insert` operation
+//! (commitment_tree, mmr_tree, bulk_append_tree, dense_tree) factored out as
+//! a single generic helper, intended for **snapshot-based bootstrap** only.
+//!
+//! # Safety contract
+//!
+//! The caller is responsible for ensuring `new_combined_root` actually
+//! matches the subtree's underlying storage state. Intended pattern:
+//!
+//! 1. Ingest the subtree's raw storage out-of-band (typically via
+//!    [`grovedb_storage::rocksdb_storage::RocksDbStorage::ingest_subtree_sst`]).
+//! 2. Open a `StorageContext` at the subtree path and reconstruct the
+//!    appropriate typed tree (CommitmentTree / Mmr / BulkAppend / Dense).
+//! 3. Compute the post-ingest combined root via that tree's own root fn.
+//! 4. Call [`GroveDb::replace_subtree_root`] with the verified hash and a
+//!    correctly-constructed [`Element`] (e.g. `Element::new_commitment_tree`).
+//!
+//! Mismatches between `new_combined_root` and what re-reading the subtree
+//! would compute produce an inconsistent Merk tree (the parent's recorded
+//! child hash diverges from actual subtree state). This method does NOT
+//! detect such mismatches at runtime; misuse is silent corruption.
+//!
+//! Gated behind the `unsafe-dump-load` Cargo feature.
+
+use std::collections::HashMap;
+
+use grovedb_costs::{
+    cost_return_on_error, cost_return_on_error_into, CostResult, CostsExt, OperationCost,
+};
+use grovedb_merk::element::{
+    insert::ElementInsertToStorageExtensions, tree_type::ElementTreeTypeExtensions,
+};
+use grovedb_path::SubtreePath;
+use grovedb_storage::{Storage, StorageBatch};
+use grovedb_version::version::GroveVersion;
+
+use crate::{util::TxRef, Element, Error, GroveDb, TransactionArg};
+
+impl GroveDb {
+    /// Replace the child hash + element data of a subtree leaf in its parent
+    /// Merk with caller-provided values. See the
+    /// [module-level docs](self) for the safety contract.
+    pub fn replace_subtree_root<'b, B, P>(
+        &self,
+        path: P,
+        key: &[u8],
+        new_element: Element,
+        new_combined_root: [u8; 32],
+        transaction: TransactionArg,
+        grove_version: &GroveVersion,
+    ) -> CostResult<(), Error>
+    where
+        B: AsRef<[u8]> + 'b,
+        P: Into<SubtreePath<'b, B>>,
+    {
+        let mut cost = OperationCost::default();
+
+        // Cheap sanity check: must be a tree-shaped Element (Item / Reference
+        // have no child hash slot). Caller still owns hash-vs-state
+        // correctness.
+        if new_element.tree_type().is_none() {
+            return Err(Error::InvalidInput(
+                "replace_subtree_root: element is not a tree variant",
+            ))
+            .wrap_with_cost(cost);
+        }
+
+        let path: SubtreePath<B> = path.into();
+        let tx = TxRef::new(&self.db, transaction);
+        let batch = StorageBatch::new();
+
+        let mut parent_merk = cost_return_on_error!(
+            &mut cost,
+            self.open_transactional_merk_at_path(
+                path.clone(),
+                tx.as_ref(),
+                Some(&batch),
+                grove_version,
+            )
+        );
+
+        cost_return_on_error_into!(
+            &mut cost,
+            new_element.insert_subtree(
+                &mut parent_merk,
+                key,
+                new_combined_root,
+                None,
+                grove_version,
+            )
+        );
+
+        let mut merk_cache = HashMap::new();
+        merk_cache.insert(path.clone(), parent_merk);
+
+        cost_return_on_error!(
+            &mut cost,
+            self.propagate_changes_with_transaction(
+                merk_cache,
+                path,
+                tx.as_ref(),
+                &batch,
+                grove_version,
+            )
+        );
+
+        cost_return_on_error!(
+            &mut cost,
+            self.db
+                .commit_multi_context_batch(batch, Some(tx.as_ref()))
+                .map_err(Into::into)
+        );
+
+        tx.commit_local().wrap_with_cost(cost)
+    }
+}

storage/Cargo.toml

@@ -26,3 +26,7 @@ thiserror = { workspace = true }
 
 [features]
 rocksdb_storage = ["rocksdb", "num_cpus", "lazy_static", "tempfile", "blake3", "integer-encoding"]
+# See `grovedb`'s `unsafe-dump-load` feature for context. On this crate it
+# gates `RocksDbStorage::ingest_subtree_sst` — the RocksDB IngestExternalFile
+# wrapper used to bulk-load a precomputed subtree SST.
+unsafe-dump-load = ["rocksdb_storage"]

storage/src/rocksdb_storage/storage.rs

@@ -43,6 +43,8 @@ use rocksdb::{
     checkpoint::Checkpoint, ColumnFamily, ColumnFamilyDescriptor, OptimisticTransactionDB,
     Transaction, WriteBatchWithTransaction, DEFAULT_COLUMN_FAMILY_NAME,
 };
+#[cfg(feature = "unsafe-dump-load")]
+use rocksdb::IngestExternalFileOptions;
 
 use super::{PrefixedRocksDbImmediateStorageContext, PrefixedRocksDbTransactionContext};
 use crate::{
@@ -494,6 +496,50 @@ impl RocksDbStorage {
         }
     }
 
+    /// Bulk-ingest a single SST file (produced by `rocksdb::SstFileWriter`)
+    /// into the named column family.
+    ///
+    /// Used by snapshot-based bootstrap (e.g. the shielded-pool genesis
+    /// snapshot) to load a precomputed subtree's keys without paying the
+    /// per-write WAL + fsync cost. The SST must be sorted and its key range
+    /// must NOT overlap with any keys already in the CF — otherwise ingest
+    /// fails. For genesis-time usage this is satisfied by definition (the
+    /// target subtree is empty when this is called).
+    ///
+    /// Security notes (set by this method, not caller-configurable):
+    /// - `allow_global_seqno=false`: rejects ingests that would inject a
+    ///   global sequence number, preventing a malicious snapshot from
+    ///   reordering its writes relative to subsequent transactional writes.
+    /// - `snapshot_consistency=false`: snapshot-based bootstrap runs before
+    ///   any reader could hold a RocksDB snapshot of the empty state.
+    ///
+    /// The ingest happens at the DB level and bypasses any open transaction.
+    /// Callers must arrange for txn semantics at a higher layer.
+    ///
+    /// Gated behind the `unsafe-dump-load` feature — production builds (which
+    /// have no need to bulk-load precomputed subtree state) should leave it
+    /// off so this API isn't even compiled in.
+    #[cfg(feature = "unsafe-dump-load")]
+    pub fn ingest_subtree_sst(&self, cf_name: &str, sst_path: &Path) -> Result<(), Error> {
+        let cf_handle = self
+            .db
+            .cf_handle(cf_name)
+            .ok_or(Error::StorageError(format!(
+                "ingest_subtree_sst: missing CF {cf_name}"
+            )))?;
+        let mut opts = IngestExternalFileOptions::default();
+        opts.set_allow_global_seqno(false);
+        opts.set_snapshot_consistency(false);
+        self.db
+            .ingest_external_file_cf_opts(&cf_handle, &opts, vec![sst_path])
+            .map_err(|e| {
+                Error::StorageError(format!(
+                    "ingest_subtree_sst({cf_name}, {}) failed: {e}",
+                    sst_path.display()
+                ))
+            })
+    }
+
     /// Clears all data from the database using range deletion on each
     /// column family. Uses a single range tombstone per CF instead of
     /// iterating and deleting every key individually.