Create API function matching paper functions (#150)

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## v0.3.0 (2024-01-20)
+
+- Adjust API to read better using DapolTree instead of Accumulator [36dd58f](https://github.com/silversixpence-crypto/dapol/commit/36dd58fcd9cd2100ac7a1c4a7010faab3397770f). Also included in this change:
+  - New Salt abstraction type [5c8a580](https://github.com/silversixpence-crypto/dapol/commit/5c8a580c5250a337592951234879852a8f1df285)
+  - New MaxLiability abstraction type [800b0a9](https://github.com/silversixpence-crypto/dapol/commit/800b0a95b67ad7b4badf4c089b2cfc10d400283b)
+  - Deserialize Salt & Secret using FromStr [169cfa5](https://github.com/silversixpence-crypto/dapol/commit/169cfa532e86e3f27d675764d8456fc3e3270564)
+  - Fix bug with Bulletproofs bit length [f2a2498](https://github.com/silversixpence-crypto/dapol/commit/f2a2498120fa35ecf589f43bc660d218ae2861ad)
+- Add benchmark graphs to readme [4a73d3c](https://github.com/silversixpence-crypto/dapol/commit/4a73d3cb8284f7f60659a376fa90c5714368e627)
+
 ## v0.2.0 (2023-12-27)
 
 - Add max_thread_count API parameter [62be10c](https://github.com/silversixpence-crypto/dapol/commit/62be10c9393b2b7e2a4feeedde53fd8a793cbf30)

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "dapol"
-version = "0.2.0"
+version = "0.3.0"
 authors = ["Stenton Mayne <[email protected]>"]
 edition = "2021"
 description = "DAPOL+ Proof of Liabilities protocol"
@@ -29,6 +29,8 @@ bench = false
 
 primitive-types = { version = "0.12.1", features = ["serde"] } # H256 & U256 (I think parity uses this so maybe we just use that crate instead)
 thiserror = "1.0"
+derive_builder = "0.12.0"
+chrono = "0.4.31"
 
 # crypto
 rand = "0.8.5"
@@ -59,17 +61,17 @@ patharg = "0.3.0"
 serde = { version = "1.0.188", features = ["derive"] }
 serde_with = "3.4.0"
 serde_bytes = "0.11.12"
+serde_json = "1.0.111"
+bincode = "1.3.3"
 toml = "0.8.2"
 csv = "1.3.0"
-bincode = "1.3.3"
-chrono = "0.4.31"
-derive_builder = "0.12.0"
 
 # fuzzing
 arbitrary = { version = "1", optional = true, features = ["derive"] }
 
 [features]
 fuzzing = ["rand/small_rng", "arbitrary"]
+testing = []
 
 [dev-dependencies]
 criterion = "0.5.0"

README.md

@@ -20,8 +20,10 @@ use as is. The code has _not_ been audited yet (as of Nov 2023) and so it is not
 Important tasks still to be done:
 - Write a spec: https://github.com/silversixpence-crypto/dapol/issues/17
 - Support the Deterministic mapping SMT accumulator type: https://github.com/silversixpence-crypto/dapol/issues/9
-- Fuzz some of the unit tests: https://github.com/silversixpence-crypto/dapol/issues/46
 - Sort out version issues with dependencies: https://github.com/silversixpence-crypto/dapol/issues/11
+- Allow the tree to be updatable: https://github.com/silversixpence-crypto/dapol/issues/109
+- Finish integration tests: https://github.com/silversixpence-crypto/dapol/issues/42
+- Use a database as the backend storage system (as opposed to memory): https://github.com/silversixpence-crypto/dapol/issues/44
 
 ## How this code can be used
 

benches/criterion_benches.rs

@@ -165,7 +165,7 @@ pub fn bench_build_tree<T: Measurement>(c: &mut Criterion<T>) {
                 let src_dir = env!("CARGO_MANIFEST_DIR");
                 let target_dir = Path::new(&src_dir).join("target");
                 let dir = target_dir.join("serialized_trees");
-                let path = DapolTree::parse_serialization_path(dir).unwrap();
+                let path = DapolTree::parse_tree_serialization_path(dir).unwrap();
                 let tree = dapol_tree.expect("Tree should have been built");
 
                 group.bench_function(
@@ -289,6 +289,7 @@ pub fn bench_generate_proof<T: Measurement>(c: &mut Criterion<T>) {
             let src_dir = env!("CARGO_MANIFEST_DIR");
             let target_dir = Path::new(&src_dir).join("target");
             let dir = target_dir.join("serialized_proofs");
+            std::fs::create_dir_all(dir.clone()).unwrap();
             let path = proof
                 .expect("Proof should be set")
                 .serialize(entity_id, dir)
@@ -386,7 +387,7 @@ pub fn bench_verify_proof<T: Measurement>(c: &mut Criterion<T>) {
                     format!("height_{}/num_entities_{}", h.as_u32(), n),
                 ),
                 |bench| {
-                    bench.iter(|| proof.verify(root_hash));
+                    bench.iter(|| proof.verify(*root_hash));
                 },
             );
         }

benches/manual_benches.rs

@@ -160,7 +160,7 @@ fn main() {
                 let src_dir = env!("CARGO_MANIFEST_DIR");
                 let target_dir = Path::new(&src_dir).join("target");
                 let dir = target_dir.join("serialized_trees");
-                let path = DapolTree::parse_serialization_path(dir).unwrap();
+                let path = DapolTree::parse_tree_serialization_path(dir).unwrap();
 
                 let time_start = Instant::now();
                 dapol_tree

examples/main.rs

@@ -1,8 +1,10 @@
 //! Example of a full PoL workflow.
 //!
 //! 1. Build a tree
-//! 2. Generate an inclusion proof
-//! 3. Verify an inclusion proof
+//! 2. Serialize tree & root node
+//! 3. Verify a root node
+//! 4. Generate an inclusion proof
+//! 5. Verify an inclusion proof
 //!
 //! At the time of writing (Nov 2023) only the NDM-SMT accumulator is supported
 //! so this is the only type of tree that is used in this example.
@@ -14,6 +16,7 @@ extern crate clap_verbosity_flag;
 extern crate csv;
 extern crate dapol;
 
+use dapol::DapolTree;
 use dapol::utils::LogOnErrUnwrap;
 
 fn main() {
@@ -44,6 +47,29 @@ fn main() {
     // Since the mappings are not the same the root hashes won't be either.
     assert_ne!(dapol_tree_1.root_hash(), dapol_tree_2.root_hash());
 
+    // =========================================================================
+    // (De)serialization.
+
+    let src_dir = env!("CARGO_MANIFEST_DIR");
+    let examples_dir = Path::new(&src_dir).join("examples");
+    let serialization_path = examples_dir.join("my_serialized_tree_for_testing.dapoltree");
+    let _ = dapol_tree_1.serialize(serialization_path.clone()).unwrap();
+
+    let dapol_tree_1 = DapolTree::deserialize(serialization_path).unwrap();
+
+    let public_root_path = examples_dir.join("public_root_data.json");
+    // let _ = dapol_tree_1.serialize_public_root_data(public_root_path.clone()).unwrap();
+    let public_root_data = DapolTree::deserialize_public_root_data(public_root_path).unwrap();
+
+    let secret_root_path = examples_dir.join("secret_root_data.json");
+    // let _ = dapol_tree_1.serialize_secret_root_data(secret_root_path.clone()).unwrap();
+    let secret_root_data = DapolTree::deserialize_secret_root_data(secret_root_path).unwrap();
+
+    // =========================================================================
+    // Root node verification.
+
+    DapolTree::verify_root_commitment(&public_root_data.commitment, &secret_root_data).unwrap();
+
     // =========================================================================
     // Inclusion proof generation & verification.
 
@@ -123,7 +149,7 @@ pub fn simple_inclusion_proof_generation_and_verification(
     entity_id: dapol::EntityId,
 ) {
     let inclusion_proof = dapol_tree.generate_inclusion_proof(&entity_id).unwrap();
-    inclusion_proof.verify(dapol_tree.root_hash()).unwrap();
+    inclusion_proof.verify(dapol_tree.root_hash().clone()).unwrap();
 }
 
 /// Example on how to generate and verify inclusion proofs.
@@ -146,5 +172,5 @@ pub fn advanced_inclusion_proof_generation_and_verification(
         .generate_inclusion_proof_with(&entity_id, aggregation_factor)
         .unwrap();
 
-    inclusion_proof.verify(dapol_tree.root_hash()).unwrap();
+    inclusion_proof.verify(dapol_tree.root_hash().clone()).unwrap();
 }

examples/public_root_data.json

@@ -0,0 +1,37 @@
+{
+  "hash": "0x68534c84b86c0698abf4126f3555dc38480a202a6ca4dfde025d751bdaccce8c",
+  "commitment": [
+    238,
+    140,
+    55,
+    234,
+    181,
+    121,
+    215,
+    189,
+    227,
+    164,
+    196,
+    150,
+    54,
+    239,
+    110,
+    15,
+    146,
+    251,
+    232,
+    6,
+    154,
+    103,
+    113,
+    210,
+    252,
+    38,
+    200,
+    64,
+    138,
+    4,
+    134,
+    53
+  ]
+}

examples/secret_root_data.json

@@ -0,0 +1,37 @@
+{
+  "liability": 1,
+  "blinding_factor": [
+    233,
+    183,
+    205,
+    125,
+    5,
+    61,
+    130,
+    1,
+    208,
+    177,
+    183,
+    150,
+    60,
+    234,
+    88,
+    127,
+    58,
+    15,
+    242,
+    33,
+    169,
+    179,
+    242,
+    27,
+    156,
+    29,
+    68,
+    220,
+    124,
+    229,
+    8,
+    5
+  ]
+}

src/accumulators.rs

@@ -4,8 +4,10 @@
 //! types of accumulators, which can all be found under this module.
 
 use clap::ValueEnum;
+use curve25519_dalek_ng::{ristretto::RistrettoPoint, scalar::Scalar};
 use primitive_types::H256;
 use serde::{Deserialize, Serialize};
+use std::fmt;
 
 mod ndm_smt;
 pub use ndm_smt::{NdmSmt, NdmSmtError, RandomXCoordGenerator};
@@ -34,12 +36,33 @@ impl Accumulator {
         }
     }
 
-    /// Return the hash digest/bytes of the root node for the binary tree.
-    pub fn root_hash(&self) -> H256 {
+    #[doc = include_str!("./shared_docs/root_hash.md")]
+    pub fn root_hash(&self) -> &H256 {
         match self {
             Self::NdmSmt(ndm_smt) => ndm_smt.root_hash(),
         }
     }
+
+    #[doc = include_str!("./shared_docs/root_commitment.md")]
+    pub fn root_commitment(&self) -> &RistrettoPoint {
+        match self {
+            Self::NdmSmt(ndm_smt) => ndm_smt.root_commitment(),
+        }
+    }
+
+    #[doc = include_str!("./shared_docs/root_liability.md")]
+    pub fn root_liability(&self) -> u64 {
+        match self {
+            Self::NdmSmt(ndm_smt) => ndm_smt.root_liability(),
+        }
+    }
+
+    #[doc = include_str!("./shared_docs/root_blinding_factor.md")]
+    pub fn root_blinding_factor(&self) -> &Scalar {
+        match self {
+            Self::NdmSmt(ndm_smt) => ndm_smt.root_blinding_factor(),
+        }
+    }
 }
 
 /// Various supported accumulator types.
@@ -49,3 +72,11 @@ pub enum AccumulatorType {
     NdmSmt,
     // TODO add other accumulators..
 }
+
+impl fmt::Display for AccumulatorType {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self {
+            AccumulatorType::NdmSmt => write!(f, "NDM-SMT"),
+        }
+    }
+}