vid/
lib.rs

1// Copyright (c) 2024 Espresso Systems (espressosys.com)
2// This file is part of the HotShot-VID library.
3
4// You should have received a copy of the MIT License
5// along with the HotShot-VID library. If not, see <https://mit-license.org/>.
6
7//! Verifiable Information Retrieval (VID).
8#![deny(missing_docs)]
9
10use displaydoc::Display;
11use jf_merkle_tree::MerkleTreeError;
12use jf_poseidon2::Poseidon2Error;
13use serde::{Deserialize, Serialize};
14
15pub mod avidm;
16pub mod avidm_gf2;
17/// Internal helpers (Merkle hashing primitives, byte-to-field conversion).
18/// Re-exported as `pub` so benches and external tooling can reuse the
19/// `Blake3DigestAlgorithm` plumbing.
20pub mod utils;
21
22/// A glorified [`bool`] that leverages compile lints to encourage the caller to
23/// use the result.
24///
25/// Intended as the return type for verification of proofs, signatures, etc.
26/// Recommended for use in the nested [`Result`] pattern: see <https://sled.rs/errors>.
27type VerificationResult = Result<(), ()>;
28
29/// The error type for `VidScheme` methods.
30#[derive(Display, Debug)]
31pub enum VidError {
32    /// invalid args: {0}
33    Argument(String),
34    /// internal error: {0}
35    Internal(anyhow::Error),
36    /// Insufficient shares
37    InsufficientShares,
38    /// Share index out of bound
39    IndexOutOfBound,
40    /// Invalid parameter
41    InvalidParam,
42    /// Invalid VID share
43    InvalidShare,
44}
45
46impl From<Poseidon2Error> for VidError {
47    fn from(err: Poseidon2Error) -> Self {
48        VidError::Internal(err.into())
49    }
50}
51
52impl From<MerkleTreeError> for VidError {
53    fn from(err: MerkleTreeError) -> Self {
54        VidError::Internal(err.into())
55    }
56}
57
58impl From<reed_solomon_simd::Error> for VidError {
59    fn from(err: reed_solomon_simd::Error) -> Self {
60        VidError::Internal(err.into())
61    }
62}
63
64/// Alias
65type VidResult<T> = Result<T, VidError>;
66
67/// Trait definition for a Verifiable Information Dispersal (VID) scheme.
68pub trait VidScheme {
69    /// VID Parameters
70    type Param: Send + Sync + Serialize + for<'a> Deserialize<'a>;
71
72    /// VID Share type
73    type Share: Send + Sync + Serialize + for<'a> Deserialize<'a>;
74
75    /// VID commitment type
76    type Commit: Eq + PartialEq + Send + Sync + Serialize + for<'a> Deserialize<'a>;
77
78    /// Commit to a `payload` without generating shares.
79    fn commit(param: &Self::Param, payload: &[u8]) -> VidResult<Self::Commit>;
80
81    /// Disperse the given `payload` according to the weights in `distribution`.
82    fn disperse(
83        param: &Self::Param,
84        distribution: &[u32],
85        payload: &[u8],
86    ) -> VidResult<(Self::Commit, Vec<Self::Share>)>;
87
88    /// Verify the given VID `share` against the VID `commit`.
89    #[allow(clippy::result_unit_err)]
90    fn verify_share(
91        param: &Self::Param,
92        commit: &Self::Commit,
93        share: &Self::Share,
94    ) -> VidResult<VerificationResult>;
95
96    /// Recover the payload from the given `shares`.
97    fn recover(
98        param: &Self::Param,
99        commit: &Self::Commit,
100        shares: &[Self::Share],
101    ) -> VidResult<Vec<u8>>;
102}
vid/lib.rs

vid/
lib.rs
