Boog900
a82c08cc80
Some checks are pending
Audit / audit (push) Waiting to run
CI / fmt (push) Waiting to run
CI / typo (push) Waiting to run
CI / ci (macos-latest, stable, bash) (push) Waiting to run
CI / ci (ubuntu-latest, stable, bash) (push) Waiting to run
CI / ci (windows-latest, stable-x86_64-pc-windows-gnu, msys2 {0}) (push) Waiting to run
Deny / audit (push) Waiting to run
Doc / build (push) Waiting to run
Doc / deploy (push) Blocked by required conditions
* fix db lifetimes * fix redb * fix blockchain with redb * add docs |
||
---|---|---|
.. | ||
src | ||
Cargo.toml | ||
DESIGN.md | ||
README.md |
Cuprate's blockchain database.
This documentation is mostly for practical usage of cuprate_blockchain
.
For a high-level overview, see the database section in Cuprate's architecture book.
Purpose
This crate does 3 things:
- Uses [
cuprate_database
] as a base database layer - Implements various
Monero
related operations, [tables], and [types] - Exposes a [
tower::Service
] backed by a thread-pool
Each layer builds on-top of the previous.
As a user of cuprate_blockchain
, consider using the higher-level [service
] module,
or at the very least the [ops
] module instead of interacting with the cuprate_database
traits directly.
cuprate_database
Consider reading cuprate_database
's crate documentation before this crate, as it is the first layer.
If/when this crate needs is used, be sure to use the version that this crate re-exports, e.g.:
use cuprate_blockchain::{
cuprate_database::RuntimeError,
};
This ensures the types/traits used from cuprate_database
are the same ones used by cuprate_blockchain
internally.
Feature flags
The service
module requires the service
feature to be enabled.
See the module for more documentation.
Different database backends are enabled by the feature flags:
heed
(LMDB)redb
The default is heed
.
tracing
is always enabled and cannot be disabled via feature-flag.
Invariants when not using service
cuprate_blockchain
can be used without the service
feature enabled but
there are some things that must be kept in mind when doing so.
Failing to uphold these invariants may cause panics.
LMDB
requires the user to resize the memory map resizing (see [cuprate_database::RuntimeError::ResizeNeeded
]LMDB
has a maximum reader transaction count, currently it is set to128
LMDB
has maximum key/value byte size which must not be exceeded
Examples
The below is an example of using cuprate_blockchain
lowest API, i.e. using a mix of this crate and cuprate_database
's traits directly -
this is NOT recommended.
For examples of the higher-level APIs, see:
- [
ops
] - [
service
]
use cuprate_blockchain::{
cuprate_database::{
ConcreteEnv,
Env, EnvInner,
DatabaseRo, DatabaseRw, TxRo, TxRw,
},
config::ConfigBuilder,
tables::{Tables, TablesMut},
OpenTables,
};
# fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create a configuration for the database environment.
let tmp_dir = tempfile::tempdir()?;
let db_dir = tmp_dir.path().to_owned();
let config = ConfigBuilder::new()
.db_directory(db_dir.into())
.build();
// Initialize the database environment.
let env = cuprate_blockchain::open(config)?;
// Open up a transaction + tables for writing.
let env_inner = env.env_inner();
let tx_rw = env_inner.tx_rw()?;
let mut tables = env_inner.open_tables_mut(&tx_rw)?;
// ⚠️ Write data to the tables directly.
// (not recommended, use `ops` or `service`).
const KEY_IMAGE: [u8; 32] = [88; 32];
tables.key_images_mut().put(&KEY_IMAGE, &())?;
// Commit the data written.
drop(tables);
TxRw::commit(tx_rw)?;
// Read the data, assert it is correct.
let tx_ro = env_inner.tx_ro()?;
let tables = env_inner.open_tables(&tx_ro)?;
let (key_image, _) = tables.key_images().first()?;
assert_eq!(key_image, KEY_IMAGE);
# Ok(()) }