penumbra_sdk_tct/
lib.rs

1//! The tiered commitment tree for Penumbra.
2//!
3//! ```ascii,no_run
4//! Eternity┃           ╱╲ ◀───────────── Anchor
5//!     Tree┃          ╱││╲               = Global Tree Root
6//!         ┃         * ** *           ╮
7//!         ┃      *   *  *   *        │ 8 levels
8//!         ┃   *     *    *     *     ╯
9//!         ┃  ╱╲    ╱╲    ╱╲    ╱╲
10//!         ┃ ╱││╲  ╱││╲  ╱││╲  ╱││╲ ◀─── Global Tree Leaf
11//!                         ▲             = Epoch Root
12//!                      ┌──┘
13//!                      │
14//!                      │
15//!    Epoch┃           ╱╲ ◀───────────── Epoch Root
16//!     Tree┃          ╱││╲
17//!         ┃         * ** *           ╮
18//!         ┃      *   *  *   *        │ 8 levels
19//!         ┃   *     *    *     *     ╯
20//!         ┃  ╱╲    ╱╲    ╱╲    ╱╲
21//!         ┃ ╱││╲  ╱││╲  ╱││╲  ╱││╲ ◀─── Epoch Leaf
22//!                  ▲                    = Block Root
23//!                  └───┐
24//!                      │
25//!                      │
26//!    Block┃           ╱╲ ◀───────────── Block Root
27//!     Tree┃          ╱││╲
28//!         ┃         * ** *           ╮
29//!         ┃      *   *  *   *        │ 8 levels
30//!         ┃   *     *    *     *     ╯
31//!         ┃  ╱╲    ╱╲    ╱╲    ╱╲
32//!         ┃ ╱││╲  ╱││╲  ╱││╲  ╱││╲ ◀─── Block Leaf
33//!                                       = Note Commitment
34//! ```
35
36#![deny(clippy::unwrap_used)]
37#![warn(missing_docs, rustdoc::broken_intra_doc_links)]
38#![cfg_attr(docsrs, feature(doc_auto_cfg))]
39
40#[macro_use]
41extern crate derivative;
42
43#[macro_use]
44extern crate serde;
45
46#[macro_use]
47extern crate tracing;
48
49#[macro_use]
50extern crate thiserror;
51
52#[macro_use]
53extern crate async_trait;
54
55mod commitment;
56mod index;
57mod proof;
58mod random;
59mod tree;
60mod witness;
61
62pub mod error;
63pub mod storage;
64pub mod structure;
65pub mod validate;
66
67#[doc(inline)]
68pub use {
69    commitment::StateCommitment,
70    internal::hash::Forgotten,
71    internal::hash::DOMAIN_SEPARATOR,
72    proof::Proof,
73    tree::{Position, Root, Tree},
74    witness::Witness,
75};
76
77#[cfg(any(doc, feature = "internal"))]
78pub mod internal;
79#[cfg(not(any(doc, feature = "internal")))]
80mod internal;
81
82#[cfg(feature = "r1cs")]
83pub mod r1cs;
84
85pub mod builder {
86    //! Builders for individual epochs and blocks: useful when constructing a [`Tree`](super::Tree)
87    //! in parallel, but unnecessary in a single thread.
88
89    pub mod epoch {
90        //! Build individual epochs to insert into [`Tree`](super::super::Tree)s.
91        pub use crate::tree::epoch::*;
92    }
93
94    pub mod block {
95        //! Build individual blocks to insert into [`epoch::Builder`](super::epoch::Builder)s or
96        //! [`Tree`](super::super::Tree)s.
97        pub use crate::tree::epoch::block::*;
98    }
99}
100
101// A crate-internal prelude to make things easier to import
102mod prelude {
103    pub(crate) use super::{
104        error::proof::VerifyError,
105        index,
106        internal::{
107            complete::{self, Complete, ForgetOwned, OutOfOrderOwned},
108            frontier::{
109                self, Focus, Forget, Frontier, Full, GetPosition, Insert, InsertMut, Item,
110                OutOfOrder,
111            },
112            hash::{CachedHash, Forgotten, GetHash, Hash, OptionHash},
113            height::{Height, IsHeight, Succ, Zero},
114            interface::Witness,
115            path::{self, AuthPath, Path, WhichWay},
116            three::{Elems, ElemsMut, IntoElems, Three},
117            UncheckedSetHash,
118        },
119        storage::{
120            self, AsyncRead, AsyncWrite, DeleteRange, Read, StoreCommitment, StoreHash,
121            StoredPosition, Update, Write,
122        },
123        structure::{self, HashOrNode, HashedNode, Kind, Node, Place},
124        Position, Proof, Root, StateCommitment, Tree,
125    };
126
127    // We use the hash map from `im`, but with the fast "hash prehashed data" hasher from `hash_hasher`
128    pub(crate) type HashedMap<K, V> = im::HashMap<K, V, hash_hasher::HashBuildHasher>;
129}
130
131#[cfg(feature = "arbitrary")]
132/// Generation of random [`Commitment`]s for testing.
133pub mod proptest {
134    #[doc(inline)]
135    pub use super::commitment::FqStrategy;
136}
137
138#[cfg(test)]
139mod test {
140    #[test]
141    fn check_eternity_size() {
142        // Disabled due to spurious test failure.
143        // static_assertions::assert_eq_size!(Tree, [u8; 32]);
144    }
145
146    #[test]
147    fn check_eternity_proof_size() {
148        // Disabled due to spurious test failure.
149        // static_assertions::assert_eq_size!(Proof, [u8; 2344]);
150    }
151}
penumbra_sdk_tct/lib.rs

penumbra_sdk_tct/
lib.rs
