Struct exonum_merkledb::indexes::proof_list::ListProof

pub struct ListProof<V> { /* fields omitted */ }

View of a ProofListIndex, i.e., a subset of its elements coupled with a proof, which jointly allow restoring the object_hash() of the index. Apart from proving elements in the list, ListProof can assert that the list is shorter than the requested range of indexes.

Workflow

You can create ListProofs with get_proof() and get_range_proof() methods of ProofListIndex. Proofs can be verified on the server side with the help of check(). Prior to the check conversion, you may use *unchecked methods to obtain information about the proof.

let fork = { let db = TemporaryDB::new(); db.fork() };
let mut list = fork.get_proof_list("index");
list.extend(vec![100_u32, 200_u32, 300_u32]);

// Get the proof from the index
let proof = list.get_range_proof(1..);

// Check the proof consistency.
let checked_proof = proof.check()?;
assert_eq!(checked_proof.index_hash(), list.object_hash());
assert_eq!(*checked_proof.entries(), [(1, 200_u32), (2, 300_u32)]);

// If the trusted list hash is known, there is a convenient method
// to combine integrity check and hash equality check.
let checked_proof = proof.check_against_hash(list.object_hash())?;
assert!(checked_proof.indexes().eq(1..=2));

JSON serialization

ListProof is serialized to JSON as an object with the following fields:

• proof is an array of { height: number, index: number, hash: Hash } objects.
• entries is an array with list elements and their indexes, that is, tuples [number, V].
• length is the length of the underlying ProofListIndex.

let fork = { let db = TemporaryDB::new(); db.fork() };
let mut list = fork.get_proof_list("index");
list.extend(vec![1_u32, 2, 3]);
let h1 = HashTag::hash_leaf(&1_u32.to_bytes());
let h3 = HashTag::hash_leaf(&3_u32.to_bytes());
let h33 = HashTag::hash_single_node(&h3);

let proof = list.get_proof(1);
assert_eq!(
    serde_json::to_value(&proof).unwrap(),
    json!({
        "proof": [
            { "index": 0, "height": 1, "hash": h1 },
            { "index": 1, "height": 2, "hash": h33 },
        ],
        "entries": [[1, 2]],
        "length": 3,
    })
);

Note on external implementations

External implementations (e.g., in light clients) must treat serialized ListProofs as untrusted inputs. Implementations may rely on the invariants provided by Exonum nodes (e.g., ordering of proof / entries; see check()) only if these invariants are checked during proof verification.

Methods

impl<V: BinaryValue> ListProof<V>

pub fn list_len(&self) -> u64

Returns the length of the underlying ProofListIndex.

pub fn entries_unchecked(&self) -> &[(u64, V)]

Returns indexes and references to elements in the proof without verifying it.

pub fn indexes_unchecked<'s>(&'s self) -> impl Iterator<Item = u64> + 's

Returns iterator over indexes of the elements in the proof without verifying proof integrity.

pub fn hash_ops(&self) -> Result<usize, ListProofError>

Estimates the number of hash operations necessary to validate the proof.

An error will be returned if the proof fails basic integrity checks. Not returning an error does not guarantee that the proof is valid, however; the estimation skips most of the checks for speed.

pub fn check(&self) -> Result<CheckedListProof<V>, ListProofError>

Verifies the correctness of the proof.

If the proof is valid, a checked list proof is returned, which allows to access proven elements.

Errors

An error is returned if proof is malformed. The following checks are performed:

• proof field is ordered by increasing (height, index) tuple.
• entries are ordered by increasing index.
• Positions of elements in proof and entries are feasible.
• There is sufficient information in proof and entries to restore the Merkle tree root.
• There are no redundant entries in proof (i.e., ones that can be inferred from other proof elements / entries).

pub fn check_against_hash(
    &self,
    expected_list_hash: Hash
) -> Result<CheckedListProof<V>, ValidationError<ListProofError>>

Verifies the correctness of the proof according to the trusted list hash.

The method is essentially a convenience wrapper around check().

Return value

If the proof is valid, a checked list proof is returned, which allows to access proven elements. Otherwise, an error is returned.

Trait Implementations

impl<V: Debug> Debug for ListProof<V>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'de, V> Deserialize<'de> for ListProof<V> where
    V: Deserialize<'de>, 

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<V: PartialEq> PartialEq<ListProof<V>> for ListProof<V>

fn eq(&self, other: &ListProof<V>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &ListProof<V>) -> bool

This method tests for !=.

impl<V> ProtobufConvert for ListProof<V> where
    V: BinaryValue, 

type ProtoStruct = ListProof

Type generated from the Protobuf definition.

fn to_pb(&self) -> Self::ProtoStruct

Performs conversion to the type generated from Protobuf.

fn from_pb(pb: Self::ProtoStruct) -> Result<Self>

Performs conversion from the type generated from Protobuf.

impl<V> Serialize for ListProof<V> where
    V: Serialize, 

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl<V> StructuralPartialEq for ListProof<V>