Struct exonum_merkledb::indexes::proof_map::MapProof

pub struct MapProof<K, V, KeyMode = Hashed> { /* fields omitted */ }

View of a ProofMapIndex, i.e., a subset of its elements coupled with a proof, which jointly allow restoring the object_hash() of the index. Apart from the existing elements, MapProof can assert absence of certain keys from the underlying index.

Workflow

You can create MapProofs with get_proof() and get_multiproof() methods of ProofMapIndex. 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 map = fork.get_proof_map("index");
let (h1, h2, h3) = (hash(&[1]), hash(&[2]), hash(&[3]));
map.put(&h1, 100u32);
map.put(&h2, 200u32);

// Get the proof from the index.
let proof = map.get_multiproof(vec![h1, h3]);

// Check the proof consistency.
let checked_proof = proof.check()?;
assert!(checked_proof.entries().eq(vec![(&h1, &100u32)]));
assert!(checked_proof.missing_keys().eq(vec![&h3]));
assert_eq!(checked_proof.index_hash(), map.object_hash());

// 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(map.object_hash())?;

JSON serialization

MapProof is serialized to JSON as an object with 2 array fields:

• proof is an array of { path: ProofPath, hash: Hash } objects.
• entries is an array with 2 kinds of objects: { missing: K } for keys missing from the underlying index, and { key: K, value: V } for key-value pairs, existence of which is asserted by the proof.

let fork = { let db = TemporaryDB::new(); db.fork() };
let mut map = fork.get_proof_map("index");
let (h1, h2) = (HashTag::hash_leaf(&[1]), HashTag::hash_leaf(&[2]));
map.put(&h1, 100_u32);
map.put(&h2, 200_u32);

let proof = map.get_proof(h2);
assert_eq!(
    serde_json::to_value(&proof).unwrap(),
    json!({
        "proof": [{
            "path": Hashed::transform_key(&h1),
            "hash": HashTag::hash_leaf(&100_u32.to_bytes()),
        }],
        "entries": [{ "key": h2, "value": 200 }],
    })
);

Note on external implementations

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

Methods

impl<K, V, KeyMode> MapProof<K, V, KeyMode>

pub fn proof_unchecked(&self) -> Vec<(ProofPath, Hash)>

Provides access to the proof part of the view. Useful mainly for debug purposes.

pub fn missing_keys_unchecked(&self) -> impl Iterator<Item = &K>

Retrieves references to keys that the proof shows as missing from the map. This method does not perform any integrity checks of the proof.

pub fn all_entries_unchecked(&self) -> impl Iterator<Item = (&K, Option<&V>)>

Retrieves references to existing and non-existing entries in the proof.

Existing entries have Some value, non-existing have None. This method does not perform any integrity checks of the proof.

impl<K, V, KeyMode> MapProof<K, V, KeyMode> where
    V: BinaryValue,
    KeyMode: ToProofPath<K>, 

pub fn check(&self) -> Result<CheckedMapProof<K, V>, MapProofError>

Checks this proof.

Errors

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

• proof elements are ordered by increasing path field.
• No path in proof is a prefix of another path in proof or a path inferred from an entry.
• Paths in proof and ones computed from entries are all distinct.

Examples

let fork = { let db = TemporaryDB::new(); db.fork() };
let mut map = fork.get_proof_map("index");
let (h1, h2) = (hash(&[1]), hash(&[2]));
map.put(&h1, 100u32);
map.put(&h2, 200u32);

let proof = map.get_proof(h2);
let checked_proof = proof.check().unwrap();
assert_eq!(checked_proof.entries().collect::<Vec<_>>(), vec![(&h2, &200u32)]);
assert_eq!(checked_proof.index_hash(), map.object_hash());

pub fn check_against_hash(
    &self,
    expected_map_hash: Hash
) -> Result<CheckedMapProof<K, V>, ValidationError<MapProofError>>

Checks this proof against a trusted map hash. Fails if the proof is malformed or the hash does not match the one computed from the proof.

pub fn map_values<U, F>(self, map_fn: F) -> MapProof<K, U, KeyMode> where
    U: BinaryValue,
    F: FnMut(V) -> U, 

Maps values in this proof. Note that this transform may render the proof invalid.

Trait Implementations

impl<K: Clone, V: Clone, KeyMode: Clone> Clone for MapProof<K, V, KeyMode>

fn clone(&self) -> MapProof<K, V, KeyMode>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K: Debug, V: Debug, KeyMode: Debug> Debug for MapProof<K, V, KeyMode>

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

Formats the value using the given formatter.

impl<'de, K, V, KeyMode> Deserialize<'de> for MapProof<K, V, KeyMode> where
    K: Deserialize<'de>,
    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<K: PartialEq, V: PartialEq, KeyMode: PartialEq> PartialEq<MapProof<K, V, KeyMode>> for MapProof<K, V, KeyMode>

fn eq(&self, other: &MapProof<K, V, KeyMode>) -> bool

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

fn ne(&self, other: &MapProof<K, V, KeyMode>) -> bool

This method tests for !=.

impl<K, V, S> ProtobufConvert for MapProof<K, V, S> where
    K: BinaryValue,
    V: BinaryValue, 

type ProtoStruct = MapProof

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<K, V, KeyMode> Serialize for MapProof<K, V, KeyMode> where
    K: Serialize,
    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<K, V, KeyMode> StructuralPartialEq for MapProof<K, V, KeyMode>