firewood-ffi 0.3.1

C FFI bindings for Firewood, an embedded key-value store optimized for blockchain state.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

// Copyright (C) 2025, Ava Labs, Inc. All rights reserved.
// See the file LICENSE.md for licensing terms.

use crate::metrics::MetricsContextExt;
use crate::reconstructed::ReconstructedHandle;
use crate::{CreateIteratorResult, DatabaseHandle, IteratorHandle};
use firewood::api;
use firewood::api::{ArcDynDbView, BoxKeyValueIter, DbView, HashKey};
use firewood_metrics::MetricsContext;
use firewood_storage::{Committed, FileBacked, NodeStore};
use std::sync::Arc;

#[derive(Debug)]
pub struct RevisionHandle<'db> {
    view: ArcDynDbView,
    historical: Option<Arc<NodeStore<Committed, FileBacked>>>,
    metrics_context: MetricsContext,
    handle: &'db DatabaseHandle,
}

impl<'db> RevisionHandle<'db> {
    /// Creates a new revision handle for the provided database view.
    pub(crate) fn new(
        view: ArcDynDbView,
        historical: Option<Arc<NodeStore<Committed, FileBacked>>>,
        metrics_context: MetricsContext,
        handle: &'db DatabaseHandle,
    ) -> RevisionHandle<'db> {
        RevisionHandle {
            view,
            historical,
            metrics_context,
            handle,
        }
    }

    /// Creates an iterator on the revision starting from the given key.
    #[must_use]
    #[allow(clippy::missing_panics_doc)]
    pub fn iter_from(&self, first_key: Option<&[u8]>) -> CreateIteratorResult<'_> {
        let it = self
            .view
            .iter_option(first_key)
            .expect("infallible; see issue #1329");
        CreateIteratorResult(IteratorHandle::new(
            self.view.clone(),
            it,
            self.metrics_context(),
        ))
    }

    /// Reconstruct this historical revision with a batch of operations.
    ///
    /// # Errors
    ///
    /// Returns an error if reconstruction fails.
    pub fn reconstruct(
        &self,
        values: impl api::IntoBatchIter,
    ) -> Result<ReconstructedHandle<'db>, api::Error> {
        let Some(historical) = self.historical.as_ref() else {
            return Err(api::Error::FeatureNotSupported(
                "reconstruct requires a historical (committed) revision handle".to_string(),
            ));
        };
        let reconstructed = self
            .handle
            .reconstruct_from_view(historical.as_ref(), values)?;
        Ok(ReconstructedHandle::new(reconstructed, self.handle))
    }
}

impl DbView for RevisionHandle<'_> {
    type Iter<'view>
        = BoxKeyValueIter<'view>
    where
        Self: 'view;

    fn root_hash(&self) -> Option<HashKey> {
        self.view.root_hash()
    }

    fn val<K: api::KeyType>(&self, key: K) -> Result<Option<firewood::merkle::Value>, api::Error> {
        self.view.val(key.as_ref())
    }

    fn single_key_proof<K: api::KeyType>(&self, key: K) -> Result<api::FrozenProof, api::Error> {
        self.view.single_key_proof(key.as_ref())
    }

    fn range_proof<K: api::KeyType>(
        &self,
        first_key: Option<K>,
        last_key: Option<K>,
        limit: Option<std::num::NonZeroUsize>,
    ) -> Result<api::FrozenRangeProof, api::Error> {
        self.view.range_proof(
            first_key.as_ref().map(AsRef::as_ref),
            last_key.as_ref().map(AsRef::as_ref),
            limit,
        )
    }

    fn iter_option<K: api::KeyType>(
        &self,
        first_key: Option<K>,
    ) -> Result<Self::Iter<'_>, api::Error> {
        self.view.iter_option(first_key.as_ref().map(AsRef::as_ref))
    }

    fn dump_to_string(&self) -> Result<String, api::Error> {
        self.view.dump_to_string()
    }
}

#[derive(Debug)]
pub struct GetRevisionResult<'db> {
    pub handle: RevisionHandle<'db>,
    pub root_hash: HashKey,
}

impl crate::MetricsContextExt for RevisionHandle<'_> {
    fn metrics_context(&self) -> Option<MetricsContext> {
        Some(self.metrics_context)
    }
}