cuprate_blockchain/ops/
mod.rs

1//! Abstracted Monero database operations.
2//!
3//! This module contains many free functions that use the
4//! traits in this crate to generically call Monero-related
5//! database operations.
6//!
7//! # `impl Table`
8//! Functions in this module take [`Tables`](crate::tables::Tables) and
9//! [`TablesMut`](crate::tables::TablesMut) directly - these are
10//! _already opened_ database tables.
11//!
12//! As such, the responsibility of
13//! transactions, tables, etc, are on the caller.
14//!
15//! Notably, this means that these functions are as lean
16//! as possible, so calling them in a loop should be okay.
17//!
18//! # Atomicity
19//! As transactions are handled by the _caller_ of these functions,
20//! it is up to the caller to decide what happens if one them return
21//! an error.
22//!
23//! To maintain atomicity, transactions should be [`abort`](cuprate_database::TxRw::abort)ed
24//! if one of the functions failed.
25//!
26//! For example, if [`add_block()`](block::add_block) is called and returns an [`Err`],
27//! `abort`ing the transaction that opened the input `TableMut` would reverse all tables
28//! mutated by `add_block()` up until the error, leaving it in the state it was in before
29//! `add_block()` was called.
30//!
31//! # Sub-functions
32//! The main functions within this module are mostly within the [`block`] module.
33//!
34//! Practically speaking, you should only be using 2 functions for mutation:
35//! - [`add_block`](block::add_block)
36//! - [`pop_block`](block::pop_block)
37//!
38//! The `block` functions are "parent" functions, calling other
39//! sub-functions such as [`add_output()`](output::add_output).
40//!
41//! `add_output()` itself only modifies output-related tables, while the `block` "parent"
42//! functions (like `add_block` and `pop_block`) modify all tables required.
43//!
44//! `add_block()` makes sure all data related to the input is mutated, while
45//! this sub-function _do not_, it specifically mutates _particular_ tables.
46//!
47//! When calling this sub-functions, ensure that either:
48//! 1. This effect (incomplete database mutation) is what is desired, or that...
49//! 2. ...the other tables will also be mutated to a correct state
50//!
51//! # Example
52//! Simple usage of `ops`.
53//!
54//! ```rust
55//! use hex_literal::hex;
56//!
57//! use cuprate_test_utils::data::BLOCK_V16_TX0;
58//! use cuprate_blockchain::{
59//!     cuprate_database::{
60//!         ConcreteEnv,
61//!         Env, EnvInner,
62//!         DatabaseRo, DatabaseRw, TxRo, TxRw,
63//!     },
64//!     config::ConfigBuilder,
65//!     tables::{Tables, TablesMut, OpenTables},
66//!     ops::block::{add_block, pop_block},
67//! };
68//!
69//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
70//! // Create a configuration for the database environment.
71//! let tmp_dir = tempfile::tempdir()?;
72//! let db_dir = tmp_dir.path().to_owned();
73//! let config = ConfigBuilder::new()
74//!     .data_directory(db_dir.into())
75//!     .build();
76//!
77//! // Initialize the database environment.
78//! let env = cuprate_blockchain::open(config)?;
79//!
80//! // Open up a transaction + tables for writing.
81//! let env_inner = env.env_inner();
82//! let tx_rw = env_inner.tx_rw()?;
83//! let mut tables = env_inner.open_tables_mut(&tx_rw)?;
84//!
85//! // Write a block to the database.
86//! let mut block = BLOCK_V16_TX0.clone();
87//! # block.height = 0;
88//! add_block(&block, &mut tables)?;
89//!
90//! // Commit the data written.
91//! drop(tables);
92//! TxRw::commit(tx_rw)?;
93//!
94//! // Read the data, assert it is correct.
95//! let tx_rw = env_inner.tx_rw()?;
96//! let mut tables = env_inner.open_tables_mut(&tx_rw)?;
97//! let (height, hash, serai_block) = pop_block(None, &mut tables)?;
98//!
99//! assert_eq!(height, 0);
100//! assert_eq!(serai_block, block.block);
101//! assert_eq!(hash, hex!("43bd1f2b6556dcafa413d8372974af59e4e8f37dbf74dc6b2a9b7212d0577428"));
102//! # Ok(()) }
103//! ```
104
105pub mod alt_block;
106pub mod block;
107pub mod blockchain;
108pub mod key_image;
109pub mod output;
110pub mod property;
111pub mod tx;
112
113mod macros;
cuprate_blockchain/ops/mod.rs

cuprate_blockchain/ops/
mod.rs
