[][src]Crate vade

This library is intended to be used as a core library for developing own self sovereign identity based applications.

So why the name? "Vade" is an acronym for "VC and DID engine". It focuses on working with VCs and DIDs but does not hold much logic concerning their structure. Confused? Guessed as much, so what does does this library actually does is:

  • offering traits that define how actual implementations (aka "plugins") for working with VCs and DIDs should behave
  • storing those plugins in a Vade instance
  • querying against all registered plugins for certain actions (e.g. for getting VCs/DIDs)

It has been designed with the idea of offering a consistent interface to work with while supporting to move the actual work into plugins, which also helps to reduce the dependencies.

This library is currently under development and behavior as well as provided traits will most probably change over time.

Usage

First add vade as a dependency to your Cargo.toml. Then you can create new instances in your code (taken from our tests):

extern crate vade;

use vade::Vade;

#[test]
fn library_can_be_created() {
    let _vade = Vade::new();
}

Okay, that did not do much yet. The core library also offers a simple in-memory cache, called RustStorageCache, which can be used when working with VC and DID documents, that are available offline and should just be stored and/or retrieved locally. So to use RustStorageCache as a VcResolver, we just need to add it as a VcResolver plugin:

extern crate vade;

use vade::Vade;
use vade::traits::VcResolver;
use vade::plugin::rust_storage_cache::RustStorageCache;


#[tokio::test]
async fn library_vc_can_set_vcs_with_two_resolvers_via_library_set() {
    let mut vade = Vade::new();
    let storage = RustStorageCache::new();
    library.register_vc_resolver(Box::from(storage));

    match library.set_vc_document("example_key", "example_value").await {
        Ok(()) => (),
        Err(e) => panic!(format!("{}", e)),
    }
    let fetched = library.get_vc_document("example_key").await.unwrap();
    assert!(fetched == "example_value");
}

Keep in mind, that the RustStorageCache resolver can be considered a reference implementation about how resolvers may behave and that it does not validate integrity and validity of given documents. For features like these, you can implement your own resolvers by following the respective traits.

Plugins

Plugins are the modules, that perform the actual work in the Vade module. This project already has one plugin included RustStorageCache, which can be used as a refrence for creating own plugins.

Create new Plugins

Developing plugins for vade is can be done by implementing one or more traits from vade::library::traits, e.g.

An example for a simple plugin can is the provided RustStorageCache. This implements DidResolver as well as VcResolver functionalities. For your implementation you can of course decide to implement only a single trait in a plugin.

Basic Behavior

This plugin implements the following traits:

This allows us to register it as these resolvers with

respectively.

As soon as they are registered as a plugin for a certain type of operation, they are called for related operations (e.g. get_vc_document) by the Vade instance they are registered in.

Library Functions, that utilize Plugins

This sections shows a short overview over the plugin related functions. For more details, have a look at the Vade documentation.

Plugin registration

These functions can be used to register new resolver plugins:

Setters

These functions will call all registered plugins respectively and with given arguments (e.g. setting a DID will only call DID resolver functions, etc.):

If multiple plugins are registered, awaits completion of all actions. First plugin, that fails lets this request fail.

Getters

These functions will call all registered plugins respectively and with given arguments (e.g. getting a DID will only call DID resolver functions, etc.):

If multiple plugins are registered, first successful response will be used. Request will fail if all plugins failed.

Validation

These functions will call all registered plugins respectively and with given arguments (e.g. getting a DID will only call DID resolver functions, etc.):

A document is considered as valid if at least one resolver confirms its validity. Resolvers may throw to indicate:

  • that they are not responsible for this document
  • that they consider this document as invalid

The current validation flow offers only a limited way of feedback for invalidity and may undergo further changes in future.

More Plugins

A plugin working with VCs and DIDs on evan.network called vade-evan has been implemented. Its usage is equivalent to the description above, more details can be found on its project page.

You can also start writing your own plugin, by following the behavior outlined with the traits in this library.

Modules

plugin

Plugins provided by the vade library. Currently includes the RustStorageCache plugin.

traits

Traits for interoperability with Vade instances.

Structs

Vade

Vade library, that holds plugins and delegates calls to them.