Overview

Vercre comprises a collection of libraries for issuing, holding, and verifying Verifiable Credentials. It is designed to be modular and flexible, allowing implementers to use only the modules needed.

Libraries

The three top-level Vercre libraries can be used independently or work together for an end-to-end Verifiable Data solution:

  • vercre-wallet — greatly simplifies building cross-platform wallets.
  • vercre-vci — for building credential issuance APIs.
  • vercre-vp — for building verifiable presentation APIs.

Shell

Each library requires a shell to wrap and expose functionality. The shell is responsible for handling the application's specific requirements, such as user interface, storage, and network communication.

Example shell implementations can be found in each libraries examples directory.

Implementation

The libraries are written in Rust and are designed to be used in a variety of environments, including WebAssembly, mobile, and server-side applications.

Motivation

When initially exposed to the concepts underpinning decentralized identity, we were excited about its potential to create 'trust-less' digital ecosystems. Privacy-respecting, cryptographically-provable digital credentials would revolutionize the way we interact online.

Immediately after that, we were struck by the range of protocols and the dearth of easy-to-use open-source libraries available to integrate into our applications. Decentralized identity needed to be more accessible for average developers like us.

With the introduction of the OpenID for Verifiable Credential Issuance and Verifiable Presentations standards we believe there is an opportunity to redress this lack and bring Verifiable Credentials further into the mainstream.

Our Contribution

So we thought: why not? Let's see if we can create something for ourselves and others to use to integrate Verifiable Credentials into applications.

We are hoping to contribute to the emergence of decentralized digital trust ecosystems by providing a set of easy-to-use, open-source libraries.

By settling on the OpenID standards, we are making a (safe-ish) bet on the not-inconsiderable base of OpenID-based systems and libraries developed over the years. We want to leverage this existing infrastructure to make it easier for developers to integrate Verifiable Credentials into their applications.

Why Rust?

One of the benefits of a systems programming language like Rust is the ability to control low-level details.

Rust's small binary footprint and efficient memory usage make it well-suited for deployment on small, low-spec devices for a truly distributed infrastructure. And while we have yet to optimize for either, we are confident Rust will be up to the task.

Also, without the need for garbage collection, Rust libraries are eminently well-suited for use by other programming languages via foreign-function interfaces. Non-Rust applications can integrate Vercre without the memory safety risks inherent with other systems programming languages.

Getting Started

Install the tools

This is an example of a rust-toolchain.toml file, which you can add at the root of your repo. It should ensure that the correct rust channel and compile targets are installed automatically for you when you use any rust tooling within the repo.

[toolchain]
channel = "stable"
components = ["rustfmt", "rustc-dev"]
targets = [
  "aarch64-apple-darwin",
  "wasm32-unknown-unknown",
]
profile = "minimal"

Create a new project

cargo new my_project
cd my_project

[TODO]

Releasing Updates

Overview

Overall, the Vercre's release process favours bringing new features to market frequently, while minimizing the risk of releasing a broken version. It draws heavily on the Rust release process, which is well-documented and understood.

Release Process

Core tenets

The release process starts as soon as a change is identified. That is, the decision to release is not a separate step at the end of development, but rather a natural consequence of bringing a change to market.

TLDR:

  • main is the source of truth.
  • Development is undertaken on feature branches and is considered complete when requirements have been met and CI checks pass.
  • Completed features are merged back into main, gated behind a "feature flag".
  • A short-lived release branch is created for testing and release preparation with any changes merged back into main.
  • Once ready, a release is tagged, published, and the branch deleted.

main branch

The main branch is the source of truth. It should always be in a releasable state, and is the basis for all development. While new development is undertaken on feature branches, changes should be merged as soon as practicable, protected behind a temporary feature flag for the change.

Feature branches

Development is undertaken on feature branches. Branches should be as short-lived as possible, and are deleted once the change is merged back into main.

If possible, larger changes should be broken down into smaller, more manageable changes, and developed on separate branches.

Every feature change should be added to the manually curated CHANGELOG.md for the relevant crate.

Publishing a release

The publishing process is initiated by creating a new, short-lived, release branch from main. The branch should be named for the release version, e.g. release-v0.2.0.

Create a new branch from main and check out:

git checkout -b release-v0.2.0

The new version number can be determined by running a a semver check on the codebase to establish the whether this is a major, minor, or patch release.

cargo make semver

Comprehensive integration testing is undertaken on this branch, with any changes merged back into main. Once the release is ready, the code is tagged, published, and the branch deleted.

Create release tag and push the branch and tag to the remote repository:

git tag v0.2.0 -m "v0.2.0 release"

# push new branch
git push --set-upstream origin release-v0.2.0
git push --tags

TODO: Add a section on how to create a release on Github.

cargo make release minor

Changelog

All notable changes should be documented in the project's CHANGELOG.md file. Per Keep a Changelog recommendations, changes are a manually documented, high-level summary of changes in a release.

Dry run

Set the release level using one of release, major, minor, patch, alpha, beta, rc

For example, to release a minor version:

cargo make release minor

Publish

Release to crates.io:

cargo make publish minor

Issuance