darkfi/blockchain/
header_store.rs

1/* This file is part of DarkFi (https://dark.fi)
2 *
3 * Copyright (C) 2020-2025 Dyne.org foundation
4 *
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU Affero General Public License as
7 * published by the Free Software Foundation, either version 3 of the
8 * License, or (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 * GNU Affero General Public License for more details.
14 *
15 * You should have received a copy of the GNU Affero General Public License
16 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
17 */
18
19use std::{fmt, str::FromStr};
20
21use darkfi_sdk::{
22    blockchain::block_version,
23    crypto::{MerkleNode, MerkleTree},
24    monotree::{Hash as StateHash, EMPTY_HASH},
25};
26#[cfg(feature = "async-serial")]
27use darkfi_serial::{async_trait, FutAsyncWriteExt};
28use darkfi_serial::{deserialize, serialize, Encodable, SerialDecodable, SerialEncodable};
29use sled_overlay::{
30    serial::{parse_record, parse_u32_key_record},
31    sled,
32};
33
34use crate::{util::time::Timestamp, Error, Result};
35
36use super::{monero::MoneroPowData, SledDbOverlayPtr};
37
38/// Struct representing the Proof of Work used in a block.
39#[derive(Clone, Debug, SerialEncodable, SerialDecodable)]
40#[allow(clippy::large_enum_variant)]
41pub enum PowData {
42    /// Native Darkfi PoW
43    Darkfi,
44    /// Monero merge mining PoW
45    Monero(MoneroPowData),
46}
47
48#[derive(Clone, Copy, Debug, Eq, PartialEq, SerialEncodable, SerialDecodable)]
49// We have to introduce a type rather than using an alias so we can restrict API access.
50pub struct HeaderHash(pub [u8; 32]);
51
52impl HeaderHash {
53    pub fn new(data: [u8; 32]) -> Self {
54        Self(data)
55    }
56
57    #[inline]
58    pub fn inner(&self) -> &[u8; 32] {
59        &self.0
60    }
61
62    pub fn as_string(&self) -> String {
63        blake3::Hash::from_bytes(self.0).to_string()
64    }
65}
66
67impl FromStr for HeaderHash {
68    type Err = Error;
69
70    fn from_str(header_hash_str: &str) -> Result<Self> {
71        Ok(Self(*blake3::Hash::from_str(header_hash_str)?.as_bytes()))
72    }
73}
74
75impl fmt::Display for HeaderHash {
76    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
77        write!(f, "{}", self.as_string())
78    }
79}
80
81/// This struct represents a tuple of the form (version, previous, height, timestamp, nonce, merkle_tree).
82#[derive(Clone, Debug, SerialEncodable, SerialDecodable)]
83pub struct Header {
84    /// Block version
85    pub version: u8,
86    /// Previous block hash
87    pub previous: HeaderHash,
88    /// Block height
89    pub height: u32,
90    /// Block creation timestamp
91    pub timestamp: Timestamp,
92    /// The block's nonce. This value changes arbitrarily with mining.
93    pub nonce: u64,
94    /// Merkle tree root of the transactions hashes contained in this block
95    pub transactions_root: MerkleNode,
96    /// Contracts states Monotree(SMT) root this block commits to
97    pub state_root: StateHash,
98    /// Block Proof of Work type
99    pub pow_data: PowData,
100}
101
102impl Header {
103    /// Generates a new header with default transactions and state root,
104    /// using Darkfi native Proof of Work data.
105    pub fn new(previous: HeaderHash, height: u32, timestamp: Timestamp, nonce: u64) -> Self {
106        let version = block_version(height);
107        let transactions_root = MerkleTree::new(1).root(0).unwrap();
108        let state_root = *EMPTY_HASH;
109        let pow_data = PowData::Darkfi;
110        Self {
111            version,
112            previous,
113            height,
114            timestamp,
115            nonce,
116            transactions_root,
117            state_root,
118            pow_data,
119        }
120    }
121
122    /// Compute the header's hash.
123    pub fn hash(&self) -> HeaderHash {
124        let mut hasher = blake3::Hasher::new();
125
126        // Blake3 hasher .update() method never fails.
127        // This call returns a Result due to how the Write trait is specified.
128        // Calling unwrap() here should be safe.
129        self.encode(&mut hasher).expect("blake3 hasher");
130
131        HeaderHash(hasher.finalize().into())
132    }
133
134    /// Compute the header's template hash, which excludes its Proof of Work data.
135    pub fn template_hash(&self) -> HeaderHash {
136        let mut hasher = blake3::Hasher::new();
137
138        // Blake3 hasher .update() method never fails.
139        // This call returns a Result due to how the Write trait is specified.
140        // Calling unwrap() here should be safe.
141        self.version.encode(&mut hasher).expect("blake3 hasher");
142        self.previous.encode(&mut hasher).expect("blake3 hasher");
143        self.height.encode(&mut hasher).expect("blake3 hasher");
144        self.timestamp.encode(&mut hasher).expect("blake3 hasher");
145        self.nonce.encode(&mut hasher).expect("blake3 hasher");
146        self.transactions_root.encode(&mut hasher).expect("blake3 hasher");
147        self.state_root.encode(&mut hasher).expect("blake3 hasher");
148
149        HeaderHash(hasher.finalize().into())
150    }
151}
152
153impl Default for Header {
154    /// Represents the genesis header on current timestamp.
155    fn default() -> Self {
156        Header::new(
157            HeaderHash::new(blake3::hash(b"Let there be dark!").into()),
158            0u32,
159            Timestamp::current_time(),
160            0u64,
161        )
162    }
163}
164
165impl fmt::Display for Header {
166    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
167        let s = format!(
168            "{} {{\n\t{}: {}\n\t{}: {}\n\t{}: {}\n\t{}: {}\n\t{}: {}\n\t{}: {}\n\t{}: {}\n\t{}: {}\n\t{}: {:?}\n}}",
169            "Header",
170            "Hash",
171            self.hash(),
172            "Version",
173            self.version,
174            "Previous",
175            self.previous,
176            "Height",
177            self.height,
178            "Timestamp",
179            self.timestamp,
180            "Nonce",
181            self.nonce,
182            "Transactions Root",
183            self.transactions_root,
184            "State Root",
185            blake3::Hash::from_bytes(self.state_root),
186            "Proof of Work data",
187            self.pow_data,
188        );
189
190        write!(f, "{s}")
191    }
192}
193
194pub const SLED_HEADER_TREE: &[u8] = b"_headers";
195pub const SLED_SYNC_HEADER_TREE: &[u8] = b"_sync_headers";
196
197/// The `HeaderStore` is a structure representing all `sled` trees related
198/// to storing the blockchain's blocks's header information.
199#[derive(Clone)]
200pub struct HeaderStore {
201    /// Main `sled` tree, storing all the blockchain's blocks' headers,
202    /// where the key is the headers' hash, and value is the serialized header.
203    pub main: sled::Tree,
204    /// The `sled` tree storing all the node pending headers while syncing,
205    /// where the key is the height number, and the value is the serialized
206    /// header.
207    pub sync: sled::Tree,
208}
209
210impl HeaderStore {
211    /// Opens a new or existing `HeaderStore` on the given sled database.
212    pub fn new(db: &sled::Db) -> Result<Self> {
213        let main = db.open_tree(SLED_HEADER_TREE)?;
214        let sync = db.open_tree(SLED_SYNC_HEADER_TREE)?;
215        Ok(Self { main, sync })
216    }
217
218    /// Insert a slice of [`Header`] into the store's main tree.
219    pub fn insert(&self, headers: &[Header]) -> Result<Vec<HeaderHash>> {
220        let (batch, ret) = self.insert_batch(headers);
221        self.main.apply_batch(batch)?;
222        Ok(ret)
223    }
224
225    /// Insert a slice of [`Header`] into the store's sync tree.
226    pub fn insert_sync(&self, headers: &[Header]) -> Result<()> {
227        let batch = self.insert_batch_sync(headers);
228        self.sync.apply_batch(batch)?;
229        Ok(())
230    }
231
232    /// Generate the sled batch corresponding to an insert to the main
233    /// tree, so caller can handle the write operation.
234    /// The header's hash() function output is used as the key,
235    /// while value is the serialized [`Header`] itself.
236    /// On success, the function returns the header hashes in the same
237    /// order, along with the corresponding operation batch.
238    pub fn insert_batch(&self, headers: &[Header]) -> (sled::Batch, Vec<HeaderHash>) {
239        let mut ret = Vec::with_capacity(headers.len());
240        let mut batch = sled::Batch::default();
241
242        for header in headers {
243            let headerhash = header.hash();
244            batch.insert(headerhash.inner(), serialize(header));
245            ret.push(headerhash);
246        }
247
248        (batch, ret)
249    }
250
251    /// Generate the sled batch corresponding to an insert to the sync
252    /// tree, so caller can handle the write operation.
253    /// The header height is used as the key, while value is the serialized
254    /// [`Header`] itself.
255    pub fn insert_batch_sync(&self, headers: &[Header]) -> sled::Batch {
256        let mut batch = sled::Batch::default();
257
258        for header in headers {
259            batch.insert(&header.height.to_be_bytes(), serialize(header));
260        }
261
262        batch
263    }
264
265    /// Check if the store's main tree contains a given header hash.
266    pub fn contains(&self, headerhash: &HeaderHash) -> Result<bool> {
267        Ok(self.main.contains_key(headerhash.inner())?)
268    }
269
270    /// Fetch given header hashes from the store's main tree.
271    /// The resulting vector contains `Option`, which is `Some` if the header
272    /// was found in the store's main tree, and otherwise it is `None`, if it
273    /// has not. The second parameter is a boolean which tells the function to
274    /// fail in case at least one header was not found.
275    pub fn get(&self, headerhashes: &[HeaderHash], strict: bool) -> Result<Vec<Option<Header>>> {
276        let mut ret = Vec::with_capacity(headerhashes.len());
277
278        for hash in headerhashes {
279            if let Some(found) = self.main.get(hash.inner())? {
280                let header = deserialize(&found)?;
281                ret.push(Some(header));
282                continue
283            }
284            if strict {
285                return Err(Error::HeaderNotFound(hash.as_string()))
286            }
287            ret.push(None);
288        }
289
290        Ok(ret)
291    }
292
293    /// Retrieve all headers from the store's main tree in the form of a tuple
294    /// (`headerhash`, `header`).
295    /// Be careful as this will try to load everything in memory.
296    pub fn get_all(&self) -> Result<Vec<(HeaderHash, Header)>> {
297        let mut headers = vec![];
298
299        for header in self.main.iter() {
300            headers.push(parse_record(header.unwrap())?);
301        }
302
303        Ok(headers)
304    }
305
306    /// Retrieve all headers from the store's sync tree in the form of a tuple
307    /// (`height`, `header`).
308    /// Be careful as this will try to load everything in memory.
309    pub fn get_all_sync(&self) -> Result<Vec<(u32, Header)>> {
310        let mut headers = vec![];
311
312        for record in self.sync.iter() {
313            headers.push(parse_u32_key_record(record.unwrap())?);
314        }
315
316        Ok(headers)
317    }
318
319    /// Fetch the fisrt header in the store's sync tree, based on the `Ord`
320    /// implementation for `Vec<u8>`.
321    pub fn get_first_sync(&self) -> Result<Option<Header>> {
322        let Some(found) = self.sync.first()? else { return Ok(None) };
323        let (_, header) = parse_u32_key_record(found)?;
324
325        Ok(Some(header))
326    }
327
328    /// Fetch the last header in the store's sync tree, based on the `Ord`
329    /// implementation for `Vec<u8>`.
330    pub fn get_last_sync(&self) -> Result<Option<Header>> {
331        let Some(found) = self.sync.last()? else { return Ok(None) };
332        let (_, header) = parse_u32_key_record(found)?;
333
334        Ok(Some(header))
335    }
336
337    /// Fetch n hashes after given height. In the iteration, if a header
338    /// height is not found, the iteration stops and the function returns what
339    /// it has found so far in the store's sync tree.
340    pub fn get_after_sync(&self, height: u32, n: usize) -> Result<Vec<Header>> {
341        let mut ret = vec![];
342
343        let mut key = height;
344        let mut counter = 0;
345        while counter < n {
346            if let Some(found) = self.sync.get_gt(key.to_be_bytes())? {
347                let (height, hash) = parse_u32_key_record(found)?;
348                key = height;
349                ret.push(hash);
350                counter += 1;
351                continue
352            }
353            break
354        }
355
356        Ok(ret)
357    }
358
359    /// Retrieve store's sync tree records count.
360    pub fn len_sync(&self) -> usize {
361        self.sync.len()
362    }
363
364    /// Check if store's sync tree contains any records.
365    pub fn is_empty_sync(&self) -> bool {
366        self.sync.is_empty()
367    }
368
369    /// Remove a slice of [`u32`] from the store's sync tree.
370    pub fn remove_sync(&self, heights: &[u32]) -> Result<()> {
371        let batch = self.remove_batch_sync(heights);
372        self.sync.apply_batch(batch)?;
373        Ok(())
374    }
375
376    /// Remove all records from the store's sync tree.
377    pub fn remove_all_sync(&self) -> Result<()> {
378        let headers = self.get_all_sync()?;
379        let heights = headers.iter().map(|h| h.0).collect::<Vec<u32>>();
380        let batch = self.remove_batch_sync(&heights);
381        self.sync.apply_batch(batch)?;
382        Ok(())
383    }
384
385    /// Generate the sled batch corresponding to a remove from the store's sync
386    /// tree, so caller can handle the write operation.
387    pub fn remove_batch_sync(&self, heights: &[u32]) -> sled::Batch {
388        let mut batch = sled::Batch::default();
389
390        for height in heights {
391            batch.remove(&height.to_be_bytes());
392        }
393
394        batch
395    }
396}
397
398/// Overlay structure over a [`HeaderStore`] instance.
399pub struct HeaderStoreOverlay(SledDbOverlayPtr);
400
401impl HeaderStoreOverlay {
402    pub fn new(overlay: &SledDbOverlayPtr) -> Result<Self> {
403        overlay.lock().unwrap().open_tree(SLED_HEADER_TREE, true)?;
404        Ok(Self(overlay.clone()))
405    }
406
407    /// Insert a slice of [`Header`] into the overlay.
408    /// The header's hash() function output is used as the key,
409    /// while value is the serialized [`Header`] itself.
410    /// On success, the function returns the header hashes in the same order.
411    pub fn insert(&self, headers: &[Header]) -> Result<Vec<HeaderHash>> {
412        let mut ret = Vec::with_capacity(headers.len());
413        let mut lock = self.0.lock().unwrap();
414
415        for header in headers {
416            let headerhash = header.hash();
417            lock.insert(SLED_HEADER_TREE, headerhash.inner(), &serialize(header))?;
418            ret.push(headerhash);
419        }
420
421        Ok(ret)
422    }
423
424    /// Fetch given headerhashes from the overlay.
425    /// The resulting vector contains `Option`, which is `Some` if the header
426    /// was found in the overlay, and otherwise it is `None`, if it has not.
427    /// The second parameter is a boolean which tells the function to fail in
428    /// case at least one header was not found.
429    pub fn get(&self, headerhashes: &[HeaderHash], strict: bool) -> Result<Vec<Option<Header>>> {
430        let mut ret = Vec::with_capacity(headerhashes.len());
431        let lock = self.0.lock().unwrap();
432
433        for hash in headerhashes {
434            if let Some(found) = lock.get(SLED_HEADER_TREE, hash.inner())? {
435                let header = deserialize(&found)?;
436                ret.push(Some(header));
437                continue
438            }
439            if strict {
440                return Err(Error::HeaderNotFound(hash.as_string()))
441            }
442            ret.push(None);
443        }
444
445        Ok(ret)
446    }
447}
darkfi/blockchain/header_store.rs

darkfi/blockchain/
header_store.rs
