Merge branch 'main' into rkuris/simple-range-proof-verification

Author: rkuris

ffi/firewood.h

@@ -579,6 +579,10 @@ func getChangeProofFromChangeProofResult(result C.ChangeProofResult) (*ChangePro
 	switch result.tag {
 	case C.ChangeProofResult_NullHandlePointer:
 		return nil, errDBClosed
+	case C.ChangeProofResult_StartRevisionNotFound:
+		return nil, ErrStartRevisionNotFound
+	case C.ChangeProofResult_EndRevisionNotFound:
+		return nil, ErrEndRevisionNotFound
 	case C.ChangeProofResult_Ok:
 		ptr := *(**C.ChangeProofContext)(unsafe.Pointer(&result.anon0))
 		return &ChangeProof{handle: ptr}, nil

ffi/proofs.go

@@ -12,8 +12,9 @@ import (
 )
 
 const (
-	rangeProofLenUnbounded = 0
-	rangeProofLenTruncated = 10
+	rangeProofLenUnbounded  = 0
+	rangeProofLenTruncated  = 10
+	changeProofLenUnbounded = 0
 )
 
 type maybe struct {
@@ -385,3 +386,29 @@ func TestRangeProofFinalizerCleanup(t *testing.T) {
 
 	r.NoError(db.Close(t.Context()), "Database should be closeable after proof is garbage collected")
 }
+
+func TestChangeProofEmptyDB(t *testing.T) {
+	r := require.New(t)
+	db := newTestDatabase(t)
+
+	proof, err := db.ChangeProof(EmptyRoot, EmptyRoot, nothing(), nothing(), changeProofLenUnbounded)
+	r.ErrorIs(err, ErrEndRevisionNotFound)
+	r.Nil(proof)
+}
+
+func TestChangeProofCreation(t *testing.T) {
+	r := require.New(t)
+	db := newTestDatabase(t)
+
+	// Insert first half of data in the first batch
+	_, _, batch := kvForTest(10000)
+	root1, err := db.Update(batch[:5000])
+	r.NoError(err)
+
+	// Insert the rest in the second batch
+	root2, err := db.Update(batch[5000:])
+	r.NoError(err)
+
+	_, err = db.ChangeProof(root1, root2, nothing(), nothing(), changeProofLenUnbounded)
+	r.NoError(err)
+}

ffi/proofs_test.go

@@ -16,8 +16,10 @@ import (
 )
 
 var (
-	ErrDroppedRevision  = errors.New("revision already dropped")
-	errRevisionNotFound = errors.New("revision not found")
+	ErrDroppedRevision       = errors.New("revision already dropped")
+	errRevisionNotFound      = errors.New("revision not found")
+	ErrEndRevisionNotFound   = errors.New("end revision not found")
+	ErrStartRevisionNotFound = errors.New("start revision not found")
 )
 
 // Revision is an immutable view over the state at a specific root hash.

ffi/revision.go

@@ -1,10 +1,16 @@
 // Copyright (C) 2025, Ava Labs, Inc. All rights reserved.
 // See the file LICENSE.md for licensing terms.
 
+use std::num::NonZeroUsize;
+
 use firewood::{
     db::{Db, DbConfig},
     manager::RevisionManagerConfig,
-    v2::api::{self, ArcDynDbView, Db as _, DbView, HashKey, HashKeyExt, IntoBatchIter, KeyType},
+    merkle::Merkle,
+    v2::api::{
+        self, ArcDynDbView, Db as _, DbView, FrozenChangeProof, HashKey, HashKeyExt, IntoBatchIter,
+        KeyType,
+    },
 };
 
 use crate::{BatchOp, BorrowedBytes, CView, CreateProposalResult, arc_cache::ArcCache};
@@ -274,6 +280,56 @@ impl DatabaseHandle {
         })
     }
 
+    /// Create a Change Proof between two revisions specified by the start and end hash.
+    ///
+    /// # Errors
+    ///
+    /// * `api::Error::StartRevisionNotFound` - If the revision for `start_hash` cannot
+    ///   be found. Note that only an `EndRevisionNotFound` is returned when both
+    ///   `start_hash` and `end_hash` cannot be found.
+    ///
+    /// * `api::Error::EndRevisionNotFound` - If the revision for `end_hash` cannot be
+    ///   found. Note that only an `EndRevisionNotFound` is returned when both
+    ///   `start_hash` and `end_hash` cannot be found.
+    ///
+    /// * `api::Error::InvalidRange` - If `start_key` > `end_key` when both are provided.
+    ///   This ensures the range bounds are logically consistent.
+    ///
+    /// * `api::Error` - Various other errors can occur during proof generation, such as:
+    ///   - I/O errors when reading nodes from storage
+    ///   - Corrupted trie structure
+    ///   - Invalid node references
+    pub(crate) fn change_proof(
+        &self,
+        start_hash: HashKey,
+        end_hash: HashKey,
+        start_key: Option<&[u8]>,
+        end_key: Option<&[u8]>,
+        limit: Option<NonZeroUsize>,
+    ) -> Result<FrozenChangeProof, api::Error> {
+        // Convert `RevisionNotFound` to `EndRevisionNotFound`. We get the end merkle
+        // before the start merkle since we want to return an `EndRevisionNotFound` in
+        // the case where both the start and end keys are not available.
+        let end_merkle = Merkle::from(self.db.revision(end_hash).map_err(|err| {
+            if let api::Error::RevisionNotFound { provided } = err {
+                api::Error::EndRevisionNotFound { provided }
+            } else {
+                err
+            }
+        })?);
+
+        // Convert `RevisionNotFound` to `StartRevisionNotFound`.
+        let start_merkle = Merkle::from(self.db.revision(start_hash).map_err(|err| {
+            if let api::Error::RevisionNotFound { provided } = err {
+                api::Error::StartRevisionNotFound { provided }
+            } else {
+                err
+            }
+        })?);
+
+        end_merkle.change_proof(start_key, end_key, start_merkle.nodestore(), limit)
+    }
+
     /// Dumps the Trie structure of the latest revision to a DOT (Graphviz) format string.
     ///
     /// # Errors

ffi/src/handle.rs

@@ -1,14 +1,16 @@
 // Copyright (C) 2025, Ava Labs, Inc. All rights reserved.
 // See the file LICENSE.md for licensing terms.
 
+use std::num::NonZeroUsize;
+
 #[cfg(feature = "ethhash")]
 use firewood::ProofError;
 #[cfg(feature = "ethhash")]
 use firewood_storage::TrieHash;
 #[cfg(feature = "ethhash")]
 use rlp::Rlp;
 
-use firewood::v2::api;
+use firewood::v2::api::{self, FrozenChangeProof};
 
 use crate::{
     BorrowedBytes, CResult, ChangeProofResult, DatabaseHandle, HashKey, HashResult, Maybe,
@@ -28,11 +30,11 @@ const EMPTY_CODE_HASH: [u8; 32] = [
 pub struct CreateChangeProofArgs<'a> {
     /// The root hash of the starting revision. This must be provided.
     /// If the root is not found in the database, the function will return
-    /// [`ChangeProofResult::RevisionNotFound`].
+    /// [`ChangeProofResult::StartRevisionNotFound`].
     pub start_root: HashKey,
     /// The root hash of the ending revision. This must be provided.
     /// If the root is not found in the database, the function will return
-    /// [`ChangeProofResult::RevisionNotFound`].
+    /// [`ChangeProofResult::EndRevisionNotFound`].
     pub end_root: HashKey,
     /// The start key of the range to create the proof for. If `None`, the range
     /// starts from the beginning of the keyspace.
@@ -54,7 +56,7 @@ pub struct VerifyChangeProofArgs<'a> {
     /// The change proof to verify. If null, the function will return
     /// [`VoidResult::NullHandlePointer`]. We need a mutable reference to
     /// update the validation context.
-    pub proof: Option<&'a mut ChangeProofContext>,
+    pub proof: Option<&'a mut ChangeProofContext<'a>>,
     /// The root hash of the starting revision. This must match the starting
     /// root of the proof.
     pub start_root: HashKey,
@@ -73,12 +75,44 @@ pub struct VerifyChangeProofArgs<'a> {
     pub max_length: u32,
 }
 
+/// Tracks the state of a proposal created from a change proof. A proposal is
+/// created after calling `fwd_db_verify_change_proof` and is committed after
+/// calling `fwd_db_verify_and_commit_change_proof`.
+#[derive(Debug)]
+#[expect(dead_code)]
+enum ProposalState<'db> {
+    Immutable(crate::ProposalHandle<'db>),
+    Committed(Option<HashKey>),
+}
+
 /// FFI context for a parsed or generated change proof.
 #[derive(Debug)]
-pub struct ChangeProofContext {
-    _proof: (),              // currently not implemented
-    _validation_context: (), // placeholder for future use
-    _commit_context: (),     // placeholder for future use
+#[expect(dead_code)]
+pub struct ChangeProofContext<'db> {
+    proof: FrozenChangeProof,
+    verification: Option<VerificationContext>,
+    proposal_state: Option<ProposalState<'db>>,
+}
+
+impl From<FrozenChangeProof> for ChangeProofContext<'_> {
+    fn from(proof: FrozenChangeProof) -> Self {
+        Self {
+            proof,
+            verification: None,
+            proposal_state: None,
+        }
+    }
+}
+
+/// FFI context for verifying a change proof
+#[derive(Debug)]
+#[expect(dead_code)]
+struct VerificationContext {
+    start_root: HashKey,
+    end_root: HashKey,
+    start_key: Option<Box<[u8]>>,
+    end_key: Option<Box<[u8]>>,
+    max_length: Option<NonZeroUsize>,
 }
 
 /// A key range that should be fetched to continue iterating through a range
@@ -183,19 +217,37 @@ impl<'a> CodeIteratorHandle<'a> {
 /// # Returns
 ///
 /// - [`ChangeProofResult::NullHandlePointer`] if the caller provided a null pointer.
-/// - [`ChangeProofResult::RevisionNotFound`] if the caller provided a start or end root
+/// - [`ChangeProofResult::StartRevisionNotFound`] if the caller provided a start root
 ///   that was not found in the database. The missing root hash is included in the result.
-///   The start root is checked first, and if both are missing, only the start root is
+///   If both the start root and end root are missing, then only the end root is
+///   reported.
+/// - [`ChangeProofResult::EndRevisionNotFound`] if the caller provided an end root
+///   that was not found in the database. The missing root hash is included in the result.
+///   If both the start root and end root are missing, then only the end root is
 ///   reported.
 /// - [`ChangeProofResult::Ok`] containing a pointer to the `ChangeProofContext` if the proof
 ///   was successfully created.
 /// - [`ChangeProofResult::Err`] containing an error message if the proof could not be created.
 #[unsafe(no_mangle)]
-pub extern "C" fn fwd_db_change_proof(
-    _db: Option<&DatabaseHandle>,
-    _args: CreateChangeProofArgs,
-) -> ChangeProofResult {
-    CResult::from_err("not yet implemented")
+pub extern "C" fn fwd_db_change_proof<'db>(
+    db: Option<&'db DatabaseHandle>,
+    args: CreateChangeProofArgs<'db>,
+) -> ChangeProofResult<'db> {
+    crate::invoke_with_handle(db, |db| {
+        db.change_proof(
+            args.start_root.into(),
+            args.end_root.into(),
+            args.start_key
+                .as_ref()
+                .map(BorrowedBytes::as_slice)
+                .into_option(),
+            args.end_key
+                .as_ref()
+                .map(BorrowedBytes::as_slice)
+                .into_option(),
+            NonZeroUsize::new(args.max_length as usize),
+        )
+    })
 }
 
 /// Verify a change proof and prepare a proposal to later commit or drop.
@@ -351,7 +403,7 @@ pub extern "C" fn fwd_free_change_proof(proof: Option<Box<ChangeProofContext>>)
     crate::invoke_with_handle(proof, drop)
 }
 
-impl crate::MetricsContextExt for ChangeProofContext {
+impl crate::MetricsContextExt for ChangeProofContext<'_> {
     fn metrics_context(&self) -> Option<firewood_metrics::MetricsContext> {
         None
     }