Crate akd_client

source ·
Expand description

Overview

This crate contains a “lean” client to verify AKD proofs which doesn’t depend on any crates other than the native hashing implementations and optionally VRF usage. This makes it suitable for embedded applications, e.g. inside limited clients (Android, iPhone, WebAssembly, etc) which may not have a large dependency library they can pull upon.

Present proof validation

At the time of this documentation authoring, we presently support LookupProof verification without depending on the full AKD library.

Planned future support

Going forward this crate will re-implement the client verifications of the base crate, but with this “lean” mentality in mind. Should you not be running in a constrained environment then feel free to simply use the base AKD library crate.

Features

The features of this library are

  1. default blake3: Blake3 256-bit hashing
  2. sha256: SHA2 256-bit hashing
  3. sha512: SHA3 512-bit hashing
  4. sha3_256: SHA3 256-bit hashing
  5. sha3_512: SHA3 512-bit hashing

which dictate which hashing function is used by the verification components. Blake3 256-bit hashing is the default implementation and utilizes the blake3 crate. Features sha256 and sha512 both utilize SHA2 cryptographic functions from the sha2 crate. Lastly sha3_256 and sha3_512 features utilize the sha3 crate for their hashing implementations. To utilize a hash implementation other than blake3, you should compile with

//          [disable blake3]      [enable other hash]
cargo build --no-default-features --features sha3_256

Additional features

Additionally there are some features not related to the underlying hash function utilization

  1. wasm: Compile with web-assembly support for WASM compilation
  2. wee_alloc: Utilize the WEE allocator, which is roughly 1KB instead of 10KB as a allocator but slower. This is helpful in cases of constrained binary footprint size to help minimize
  3. nostd: Disable use of the std library
  4. vrf: Enable verification of VRFs client-side. Requires addition of the crates [curve25519-dalek] and [ed25519-dalek] as dependencies

You can compile and pack the WASM output with

cd akd_client # optional
wasm-pack build --features wasm

which currently has a resultant WASM file size of ~191KB with VRF verification enabled

WASM Compilation and Deployment

For WASM deployment of the AKD client, you’ll want to read the wasm_bindgen documentation which has reference material dependent on your environment.

Client Types

A small note about the types in this library. They are specifically independent of the main AKD crate because it’s assumed that to perform a verification at the edge, the client will have had to receive some over-the-air message which contains the data inside the proof. Therefore they’d need to be deserialized and handled independently of the AKD crate which wouldn’t be a dependency anyways. This is why the types are independent and specified separately from the core AKD types.

Modules

This module contains the client verification calls to verify different membership types

Structs

This proof is just an array of UpdateProofs.
Represents a specific level of the tree with the parental sibling and the direction of the parent for use in tree hash calculations
Proof that a given label was at a particular state at the given epoch. This means we need to show that the state and version we are claiming for this node must have been:
Merkle proof of membership of a NodeLabel with a particular hash value in the tree at a given epoch
Represents a node (label + hash) in the AKD
Represents the label of a AKD node
Merkle Patricia proof of non-membership for a NodeLabel in the tree at a given epoch.
A vector of UpdateProofs are sent as the proof to a history query for a particular key. For each version of the value associated with the key, the verifier must check that:
AKD client verification error
The payload that is outputted as a result of successful verification of a LookupProof or HistoryProof. This includes the fields containing the epoch that the leaf was published in, the version corresponding to the value, and the value itself.

Enums

Client verification error codes

Constants

The label used for an empty node
The value to be hashed every time an empty node’s hash is to be considered
A “tombstone” is a false value in an AKD ValueState denoting that a real value has been removed (e.g. data rentention policies). Should a tombstone be encountered, we have to assume that the hash of the value is correct, and we move forward without being able to verify the raw value. We utilize an empty array to save space in the storage layer

Type Definitions

The label of a particular entry in the AKD
The value of a particular entry in the AKD
A hash digest (size will depend on hashing algorithm specified at compilation time)
This type is used to indicate a direction for a particular node relative to its parent.