darkfi/blockchain/
mod.rs

Help
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::sync::{Arc, Mutex};
20
21use darkfi_sdk::tx::TransactionHash;
22use log::debug;
23use sled_overlay::{sled, sled::Transactional};
24
25use crate::{tx::Transaction, util::time::Timestamp, Error, Result};
26
27/// Block related definitions and storage implementations
28pub mod block_store;
29pub use block_store::{
30    Block, BlockDifficulty, BlockInfo, BlockStore, BlockStoreOverlay, SLED_BLOCK_DIFFICULTY_TREE,
31    SLED_BLOCK_ORDER_TREE, SLED_BLOCK_STATE_INVERSE_DIFF_TREE, SLED_BLOCK_TREE,
32};
33
34/// Header definition and storage implementation
35pub mod header_store;
36pub use header_store::{
37    Header, HeaderHash, HeaderStore, HeaderStoreOverlay, SLED_HEADER_TREE, SLED_SYNC_HEADER_TREE,
38};
39
40/// Transactions related storage implementations
41pub mod tx_store;
42pub use tx_store::{
43    TxStore, TxStoreOverlay, SLED_PENDING_TX_ORDER_TREE, SLED_PENDING_TX_TREE,
44    SLED_TX_LOCATION_TREE, SLED_TX_TREE,
45};
46
47/// Contracts and Wasm storage implementations
48pub mod contract_store;
49pub use contract_store::{
50    ContractStore, ContractStoreOverlay, SLED_BINCODE_TREE, SLED_CONTRACTS_TREE,
51};
52
53/// Structure holding all sled trees that define the concept of Blockchain.
54#[derive(Clone)]
55pub struct Blockchain {
56    /// Main pointer to the sled db connection
57    pub sled_db: sled::Db,
58    /// Headers sled tree
59    pub headers: HeaderStore,
60    /// Blocks sled tree
61    pub blocks: BlockStore,
62    /// Transactions related sled trees
63    pub transactions: TxStore,
64    /// Contracts related sled trees
65    pub contracts: ContractStore,
66}
67
68impl Blockchain {
69    /// Instantiate a new `Blockchain` with the given `sled` database.
70    pub fn new(db: &sled::Db) -> Result<Self> {
71        let headers = HeaderStore::new(db)?;
72        let blocks = BlockStore::new(db)?;
73        let transactions = TxStore::new(db)?;
74        let contracts = ContractStore::new(db)?;
75
76        Ok(Self { sled_db: db.clone(), headers, blocks, transactions, contracts })
77    }
78
79    /// Insert a given [`BlockInfo`] into the blockchain database.
80    /// This functions wraps all the logic of separating the block into specific
81    /// data that can be fed into the different trees of the database.
82    /// Upon success, the functions returns the block hash that
83    /// were given and appended to the ledger.
84    pub fn add_block(&self, block: &BlockInfo) -> Result<HeaderHash> {
85        let mut trees = vec![];
86        let mut batches = vec![];
87
88        // Store header
89        let (headers_batch, _) = self.headers.insert_batch(&[block.header.clone()]);
90        trees.push(self.headers.main.clone());
91        batches.push(headers_batch);
92
93        // Store block
94        let blk: Block = Block::from_block_info(block);
95        let (bocks_batch, block_hashes) = self.blocks.insert_batch(&[blk]);
96        let block_hash = block_hashes[0];
97        let block_hash_vec = [block_hash];
98        trees.push(self.blocks.main.clone());
99        batches.push(bocks_batch);
100
101        // Store block order
102        let blocks_order_batch =
103            self.blocks.insert_batch_order(&[block.header.height], &block_hash_vec);
104        trees.push(self.blocks.order.clone());
105        batches.push(blocks_order_batch);
106
107        // Store transactions
108        let (txs_batch, txs_hashes) = self.transactions.insert_batch(&block.txs);
109        trees.push(self.transactions.main.clone());
110        batches.push(txs_batch);
111
112        // Store transactions_locations
113        let txs_locations_batch =
114            self.transactions.insert_batch_location(&txs_hashes, block.header.height);
115        trees.push(self.transactions.location.clone());
116        batches.push(txs_locations_batch);
117
118        // Perform an atomic transaction over the trees and apply the batches.
119        self.atomic_write(&trees, &batches)?;
120
121        Ok(block_hash)
122    }
123
124    /// Check if the given [`BlockInfo`] is in the database and all trees.
125    pub fn has_block(&self, block: &BlockInfo) -> Result<bool> {
126        let blockhash = match self.blocks.get_order(&[block.header.height], true) {
127            Ok(v) => v[0].unwrap(),
128            Err(_) => return Ok(false),
129        };
130
131        // Check if we have all transactions
132        let txs: Vec<TransactionHash> = block.txs.iter().map(|tx| tx.hash()).collect();
133        if self.transactions.get(&txs, true).is_err() {
134            return Ok(false)
135        }
136
137        // Check provided info produces the same hash
138        Ok(blockhash == block.hash())
139    }
140
141    /// Retrieve [`BlockInfo`]s by given hashes. Fails if any of them is not found.
142    pub fn get_blocks_by_hash(&self, hashes: &[HeaderHash]) -> Result<Vec<BlockInfo>> {
143        let blocks = self.blocks.get(hashes, true)?;
144        let blocks: Vec<Block> = blocks.iter().map(|x| x.clone().unwrap()).collect();
145        let ret = self.get_blocks_infos(&blocks)?;
146
147        Ok(ret)
148    }
149
150    /// Retrieve all [`BlockInfo`] for given slice of [`Block`].
151    /// Fails if any of them is not found
152    fn get_blocks_infos(&self, blocks: &[Block]) -> Result<Vec<BlockInfo>> {
153        let mut ret = Vec::with_capacity(blocks.len());
154        for block in blocks {
155            let headers = self.headers.get(&[block.header], true)?;
156            // Since we used strict get, its safe to unwrap here
157            let header = headers[0].clone().unwrap();
158
159            let txs = self.transactions.get(&block.txs, true)?;
160            let txs = txs.iter().map(|x| x.clone().unwrap()).collect();
161
162            let info = BlockInfo::new(header, txs, block.signature);
163            ret.push(info);
164        }
165
166        Ok(ret)
167    }
168
169    /// Retrieve [`BlockInfo`]s by given heights. Does not fail if any of them are not found.
170    pub fn get_blocks_by_heights(&self, heights: &[u32]) -> Result<Vec<BlockInfo>> {
171        debug!(target: "blockchain", "get_blocks_by_heights(): {:?}", heights);
172        let blockhashes = self.blocks.get_order(heights, false)?;
173
174        let mut hashes = vec![];
175        for i in blockhashes.into_iter().flatten() {
176            hashes.push(i);
177        }
178
179        self.get_blocks_by_hash(&hashes)
180    }
181
182    /// Retrieve n headers before given block height.
183    pub fn get_headers_before(&self, height: u32, n: usize) -> Result<Vec<Header>> {
184        debug!(target: "blockchain", "get_headers_before(): {} -> {}", height, n);
185        let hashes = self.blocks.get_before(height, n)?;
186        let headers = self.headers.get(&hashes, true)?;
187        Ok(headers.iter().map(|h| h.clone().unwrap()).collect())
188    }
189
190    /// Retrieve stored blocks count
191    pub fn len(&self) -> usize {
192        self.blocks.len()
193    }
194
195    /// Retrieve stored txs count
196    pub fn txs_len(&self) -> usize {
197        self.transactions.len()
198    }
199
200    /// Check if blockchain contains any blocks
201    pub fn is_empty(&self) -> bool {
202        self.blocks.is_empty()
203    }
204
205    /// Retrieve genesis (first) block height and hash.
206    pub fn genesis(&self) -> Result<(u32, HeaderHash)> {
207        self.blocks.get_first()
208    }
209
210    /// Retrieve genesis (first) block info.
211    pub fn genesis_block(&self) -> Result<BlockInfo> {
212        let (_, hash) = self.genesis()?;
213        Ok(self.get_blocks_by_hash(&[hash])?[0].clone())
214    }
215
216    /// Retrieve the last block height and hash.
217    pub fn last(&self) -> Result<(u32, HeaderHash)> {
218        self.blocks.get_last()
219    }
220
221    /// Retrieve the last block info.
222    pub fn last_block(&self) -> Result<BlockInfo> {
223        let (_, hash) = self.last()?;
224        Ok(self.get_blocks_by_hash(&[hash])?[0].clone())
225    }
226
227    /// Retrieve the last block difficulty. If the tree is empty,
228    /// returns `BlockDifficulty::genesis` difficulty.
229    pub fn last_block_difficulty(&self) -> Result<BlockDifficulty> {
230        if let Some(found) = self.blocks.get_last_difficulty()? {
231            return Ok(found)
232        }
233
234        let genesis_block = self.genesis_block()?;
235        Ok(BlockDifficulty::genesis(genesis_block.header.timestamp))
236    }
237
238    /// Check if block order for the given height is in the database.
239    pub fn has_height(&self, height: u32) -> Result<bool> {
240        let vec = match self.blocks.get_order(&[height], true) {
241            Ok(v) => v,
242            Err(_) => return Ok(false),
243        };
244        Ok(!vec.is_empty())
245    }
246
247    /// Insert a given slice of pending transactions into the blockchain database.
248    /// On success, the function returns the transaction hashes in the same order
249    /// as the input transactions.
250    pub fn add_pending_txs(&self, txs: &[Transaction]) -> Result<Vec<TransactionHash>> {
251        let (txs_batch, txs_hashes) = self.transactions.insert_batch_pending(txs);
252        let txs_order_batch = self.transactions.insert_batch_pending_order(&txs_hashes)?;
253
254        // Perform an atomic transaction over the trees and apply the batches.
255        let trees = [self.transactions.pending.clone(), self.transactions.pending_order.clone()];
256        let batches = [txs_batch, txs_order_batch];
257        self.atomic_write(&trees, &batches)?;
258
259        Ok(txs_hashes)
260    }
261
262    /// Retrieve all transactions from the pending tx store.
263    /// Be careful as this will try to load everything in memory.
264    pub fn get_pending_txs(&self) -> Result<Vec<Transaction>> {
265        let txs = self.transactions.get_all_pending()?;
266        let indexes = self.transactions.get_all_pending_order()?;
267        if txs.len() != indexes.len() {
268            return Err(Error::InvalidInputLengths)
269        }
270
271        let mut ret = Vec::with_capacity(txs.len());
272        for index in indexes {
273            ret.push(txs.get(&index.1).unwrap().clone());
274        }
275
276        Ok(ret)
277    }
278
279    /// Remove a given slice of pending transactions from the blockchain database.
280    pub fn remove_pending_txs(&self, txs: &[Transaction]) -> Result<()> {
281        let txs_hashes: Vec<TransactionHash> = txs.iter().map(|tx| tx.hash()).collect();
282        self.remove_pending_txs_hashes(&txs_hashes)
283    }
284
285    /// Remove a given slice of pending transactions hashes from the blockchain database.
286    pub fn remove_pending_txs_hashes(&self, txs: &[TransactionHash]) -> Result<()> {
287        let indexes = self.transactions.get_all_pending_order()?;
288        // We could do indexes.iter().map(|x| txs.contains(x.1)).collect.map(|x| x.0).collect
289        // but this is faster since we don't do the second iteration
290        let mut removed_indexes = vec![];
291        for index in indexes {
292            if txs.contains(&index.1) {
293                removed_indexes.push(index.0);
294            }
295        }
296
297        let txs_batch = self.transactions.remove_batch_pending(txs);
298        let txs_order_batch = self.transactions.remove_batch_pending_order(&removed_indexes);
299
300        // Perform an atomic transaction over the trees and apply the batches.
301        let trees = [self.transactions.pending.clone(), self.transactions.pending_order.clone()];
302        let batches = [txs_batch, txs_order_batch];
303        self.atomic_write(&trees, &batches)?;
304
305        Ok(())
306    }
307
308    /// Auxiliary function to write to multiple trees completely atomic.
309    fn atomic_write(&self, trees: &[sled::Tree], batches: &[sled::Batch]) -> Result<()> {
310        if trees.len() != batches.len() {
311            return Err(Error::InvalidInputLengths)
312        }
313
314        trees.transaction(|trees| {
315            for (index, tree) in trees.iter().enumerate() {
316                tree.apply_batch(&batches[index])?;
317            }
318
319            Ok::<(), sled::transaction::ConflictableTransactionError<sled::Error>>(())
320        })?;
321
322        Ok(())
323    }
324
325    /// Retrieve all blocks contained in the blockchain in order.
326    /// Be careful as this will try to load everything in memory.
327    pub fn get_all(&self) -> Result<Vec<BlockInfo>> {
328        let order = self.blocks.get_all_order()?;
329        let order: Vec<HeaderHash> = order.iter().map(|x| x.1).collect();
330        let blocks = self.get_blocks_by_hash(&order)?;
331
332        Ok(blocks)
333    }
334
335    /// Retrieve [`BlockInfo`]s by given heights range.
336    pub fn get_by_range(&self, start: u32, end: u32) -> Result<Vec<BlockInfo>> {
337        let blockhashes = self.blocks.get_order_by_range(start, end)?;
338        let hashes: Vec<HeaderHash> = blockhashes.into_iter().map(|(_, hash)| hash).collect();
339        self.get_blocks_by_hash(&hashes)
340    }
341
342    /// Retrieve last 'N' [`BlockInfo`]s from the blockchain.
343    pub fn get_last_n(&self, n: usize) -> Result<Vec<BlockInfo>> {
344        let records = self.blocks.get_last_n_orders(n)?;
345
346        let mut last_n = vec![];
347        for record in records {
348            let header_hash = record.1;
349            let blocks = self.get_blocks_by_hash(&[header_hash])?;
350            for block in blocks {
351                last_n.push(block.clone());
352            }
353        }
354
355        Ok(last_n)
356    }
357
358    /// Auxiliary function to reset the blockchain and consensus state
359    /// to the provided block height.
360    pub fn reset_to_height(&self, height: u32) -> Result<()> {
361        // First we grab the last block height
362        let (last, _) = self.last()?;
363
364        // Check if request height is after our last height
365        if height >= last {
366            return Ok(())
367        }
368
369        // Grab all state inverse diffs until requested height,
370        // going backwards.
371        let heights: Vec<u32> = (height + 1..=last).rev().collect();
372        let inverse_diffs = self.blocks.get_state_inverse_diff(&heights, true)?;
373
374        // Create an overlay to apply the reverse diffs
375        let overlay = BlockchainOverlay::new(self)?;
376
377        // Apply the inverse diffs sequence
378        let overlay_lock = overlay.lock().unwrap();
379        let mut lock = overlay_lock.overlay.lock().unwrap();
380        for inverse_diff in inverse_diffs {
381            // Since we used strict retrieval it's safe to unwrap here
382            let inverse_diff = inverse_diff.unwrap();
383            lock.add_diff(&inverse_diff)?;
384            lock.apply_diff(&inverse_diff)?;
385            self.sled_db.flush()?;
386        }
387        drop(lock);
388        drop(overlay_lock);
389
390        Ok(())
391    }
392}
393
394/// Atomic pointer to sled db overlay.
395pub type SledDbOverlayPtr = Arc<Mutex<sled_overlay::SledDbOverlay>>;
396
397/// Atomic pointer to blockchain overlay.
398pub type BlockchainOverlayPtr = Arc<Mutex<BlockchainOverlay>>;
399
400/// Overlay structure over a [`Blockchain`] instance.
401pub struct BlockchainOverlay {
402    /// Main [`sled_overlay::SledDbOverlay`] to the sled db connection
403    pub overlay: SledDbOverlayPtr,
404    /// Headers overlay
405    pub headers: HeaderStoreOverlay,
406    /// Blocks overlay
407    pub blocks: BlockStoreOverlay,
408    /// Transactions overlay
409    pub transactions: TxStoreOverlay,
410    /// Contract overlay
411    pub contracts: ContractStoreOverlay,
412}
413
414impl BlockchainOverlay {
415    /// Instantiate a new `BlockchainOverlay` over the given [`Blockchain`] instance.
416    pub fn new(blockchain: &Blockchain) -> Result<BlockchainOverlayPtr> {
417        // Here we configure all our blockchain sled trees to be protected in the overlay
418        let protected_trees = vec![
419            SLED_BLOCK_TREE,
420            SLED_BLOCK_ORDER_TREE,
421            SLED_BLOCK_DIFFICULTY_TREE,
422            SLED_BLOCK_STATE_INVERSE_DIFF_TREE,
423            SLED_HEADER_TREE,
424            SLED_SYNC_HEADER_TREE,
425            SLED_TX_TREE,
426            SLED_TX_LOCATION_TREE,
427            SLED_PENDING_TX_TREE,
428            SLED_PENDING_TX_ORDER_TREE,
429            SLED_CONTRACTS_TREE,
430            SLED_BINCODE_TREE,
431        ];
432        let overlay = Arc::new(Mutex::new(sled_overlay::SledDbOverlay::new(
433            &blockchain.sled_db,
434            protected_trees,
435        )));
436        let headers = HeaderStoreOverlay::new(&overlay)?;
437        let blocks = BlockStoreOverlay::new(&overlay)?;
438        let transactions = TxStoreOverlay::new(&overlay)?;
439        let contracts = ContractStoreOverlay::new(&overlay)?;
440
441        Ok(Arc::new(Mutex::new(Self { overlay, headers, blocks, transactions, contracts })))
442    }
443
444    /// Check if blockchain contains any blocks
445    pub fn is_empty(&self) -> Result<bool> {
446        self.blocks.is_empty()
447    }
448
449    /// Retrieve the last block height and hash.
450    pub fn last(&self) -> Result<(u32, HeaderHash)> {
451        self.blocks.get_last()
452    }
453
454    /// Retrieve the last block info.
455    pub fn last_block(&self) -> Result<BlockInfo> {
456        let (_, hash) = self.last()?;
457        Ok(self.get_blocks_by_hash(&[hash])?[0].clone())
458    }
459
460    /// Retrieve the last block height.
461    pub fn last_block_height(&self) -> Result<u32> {
462        Ok(self.last()?.0)
463    }
464
465    /// Retrieve the last block timestamp.
466    pub fn last_block_timestamp(&self) -> Result<Timestamp> {
467        let (_, hash) = self.last()?;
468        Ok(self.get_blocks_by_hash(&[hash])?[0].header.timestamp)
469    }
470
471    /// Insert a given [`BlockInfo`] into the overlay.
472    /// This functions wraps all the logic of separating the block into specific
473    /// data that can be fed into the different trees of the overlay.
474    /// Upon success, the functions returns the block hash that
475    /// were given and appended to the overlay.
476    /// Since we are adding to the overlay, we don't need to exeucte
477    /// the writes atomically.
478    pub fn add_block(&self, block: &BlockInfo) -> Result<HeaderHash> {
479        // Store header
480        self.headers.insert(&[block.header.clone()])?;
481
482        // Store block
483        let blk: Block = Block::from_block_info(block);
484        let txs_hashes = blk.txs.clone();
485        let block_hash = self.blocks.insert(&[blk])?[0];
486        let block_hash_vec = [block_hash];
487
488        // Store block order
489        self.blocks.insert_order(&[block.header.height], &block_hash_vec)?;
490
491        // Store transactions
492        self.transactions.insert(&block.txs)?;
493
494        // Store transactions locations
495        self.transactions.insert_location(&txs_hashes, block.header.height)?;
496
497        Ok(block_hash)
498    }
499
500    /// Check if the given [`BlockInfo`] is in the database and all trees.
501    pub fn has_block(&self, block: &BlockInfo) -> Result<bool> {
502        let blockhash = match self.blocks.get_order(&[block.header.height], true) {
503            Ok(v) => v[0].unwrap(),
504            Err(_) => return Ok(false),
505        };
506
507        // Check if we have all transactions
508        let txs: Vec<TransactionHash> = block.txs.iter().map(|tx| tx.hash()).collect();
509        if self.transactions.get(&txs, true).is_err() {
510            return Ok(false)
511        }
512
513        // Check provided info produces the same hash
514        Ok(blockhash == block.hash())
515    }
516
517    /// Retrieve [`Header`]s by given hashes. Fails if any of them is not found.
518    pub fn get_headers_by_hash(&self, hashes: &[HeaderHash]) -> Result<Vec<Header>> {
519        let headers = self.headers.get(hashes, true)?;
520        let ret: Vec<Header> = headers.iter().map(|x| x.clone().unwrap()).collect();
521
522        Ok(ret)
523    }
524
525    /// Retrieve [`BlockInfo`]s by given hashes. Fails if any of them is not found.
526    pub fn get_blocks_by_hash(&self, hashes: &[HeaderHash]) -> Result<Vec<BlockInfo>> {
527        let blocks = self.blocks.get(hashes, true)?;
528        let blocks: Vec<Block> = blocks.iter().map(|x| x.clone().unwrap()).collect();
529        let ret = self.get_blocks_infos(&blocks)?;
530
531        Ok(ret)
532    }
533
534    /// Retrieve all [`BlockInfo`] for given slice of [`Block`].
535    /// Fails if any of them is not found
536    fn get_blocks_infos(&self, blocks: &[Block]) -> Result<Vec<BlockInfo>> {
537        let mut ret = Vec::with_capacity(blocks.len());
538        for block in blocks {
539            let headers = self.headers.get(&[block.header], true)?;
540            // Since we used strict get, its safe to unwrap here
541            let header = headers[0].clone().unwrap();
542
543            let txs = self.transactions.get(&block.txs, true)?;
544            let txs = txs.iter().map(|x| x.clone().unwrap()).collect();
545
546            let info = BlockInfo::new(header, txs, block.signature);
547            ret.push(info);
548        }
549
550        Ok(ret)
551    }
552
553    /// Retrieve [`Block`]s by given hashes and return their transactions hashes.
554    pub fn get_blocks_txs_hashes(&self, hashes: &[HeaderHash]) -> Result<Vec<TransactionHash>> {
555        let blocks = self.blocks.get(hashes, true)?;
556        let mut ret = vec![];
557        for block in blocks {
558            ret.extend_from_slice(&block.unwrap().txs);
559        }
560
561        Ok(ret)
562    }
563
564    /// Checkpoint overlay so we can revert to it, if needed.
565    pub fn checkpoint(&self) {
566        self.overlay.lock().unwrap().checkpoint();
567    }
568
569    /// Revert to current overlay checkpoint.
570    pub fn revert_to_checkpoint(&self) -> Result<()> {
571        self.overlay.lock().unwrap().revert_to_checkpoint()?;
572
573        Ok(())
574    }
575
576    /// Auxiliary function to create a full clone using SledDbOverlay::clone,
577    /// generating new pointers for the underlying overlays.
578    pub fn full_clone(&self) -> Result<BlockchainOverlayPtr> {
579        let overlay = Arc::new(Mutex::new(self.overlay.lock().unwrap().clone()));
580        let headers = HeaderStoreOverlay::new(&overlay)?;
581        let blocks = BlockStoreOverlay::new(&overlay)?;
582        let transactions = TxStoreOverlay::new(&overlay)?;
583        let contracts = ContractStoreOverlay::new(&overlay)?;
584
585        Ok(Arc::new(Mutex::new(Self { overlay, headers, blocks, transactions, contracts })))
586    }
587}
darkfi/blockchain/mod.rs

darkfi/blockchain/
mod.rs
