add readme

[nitro-neal]

Web5 SDK Mono Repo

This monorepo houses the core components of the Web5 platform containing the core Rust code with Kotlin bindings. It features libraries for building applications with decentralized identifiers (DIDs), verifiable credentials (VCs), presentation exchange (PEX), and much more.

Table of Contents

• Features
• Getting Started
  • Cloning
• Development Prerequisites
  • Hermit
• Building and Testing
• Binding Process
• API Documentation
• Basic Usage
  • DidJwk Creation
  • Verifiable Credential Creation & Signing
  • Verifiable Presentation Creation & Signing
  • Presentation Exchange
• Rust Examples
  • Instantiate a new did:jwk
  • Simple Verifiable Credential Creation & Signing
• Kotlin Examples
  • Instantiate a new did:jwk
  • Simple Verifiable Credential Creation & Signing

Features

• DID creation and management (support for multiple DID methods).
• Verifiable Credential creation, signing, and verification.
• Status List Credentials for revocation and suspension.
• Verifiable Presentation creation and signing.
• Presentation Exchange support to handle credential selection based on definitions and generating submissions.
• Cross-platform support with multi-language bindings

Getting Started

To start developing applications and services with the Web5 RS SDK, the following steps will guide
you through setting up your local development environment.

For detailed documentation on usage refer to the
API reference documentation. Additionally, comprehensive
guides can be found at the TBD Developer site to enhance
your understanding of the underlying concepts and how to implement them effectively.

Cloning

This repository uses git submodules. To clone this repo with submodules:

git clone --recurse-submodules [email protected]:TBD54566975/web5-rs.git

Or to add submodules after cloning:

git submodule update --init

Development Prerequisites

Hermit

This project uses hermit to manage tooling like the Rust compiler, Java Development Kit and Maven project management system.
See this page to set up Hermit on your machine - make sure to
download the open source build and activate it for the project.

Once you've installed Hermit and before running builds on this repo,
run from the root:

source ./bin/activate-hermit

This will set your environment up correctly in the
terminal emulator you're on. Executing just commands should "just work", no
matter the underlying tooling used (ie. rustc, cargo, mvn, java, etc).

Building and Testing

To run, find a build target from the table below and use just:

$> just [buildTarget]

Command	Description
setup	Initalizes the environment, including git submodules, rustup, etc.
build	Builds the Rust core
test	Tests the Rust core
lint	Performs code formatting on the Rust core
bind	Builds all language bindings
bind-kotlin	Builds the Kotlin language bindings
test-bound	Tests all language bindings
test-kotlin	Tests the Kotlin language bindings

For instance:

$> just build

Binding Process

The binding process follows these key steps:

1. Core Rust Development
   All the core logic for working with DIDs, verifiable credentials, and cryptographic signing and verification is implemented in Rust. Rust is chosen as the core layer for its memory safety, performance, and cross-platform capabilities.

2. Building the Kotlin Bindings
   The Kotlin bindings are generated from the core Rust code and live in the bound/kotlin directory. These bindings allow Kotlin applications to access the functionality of the core Rust libraries through idiomatic Kotlin APIs.

3. Packaging & Distribution
   The Kotlin bindings are packaged and distributed as a Kotlin library, which can be imported and used in Kotlin applications just like any other dependency.

API Documentation

For the full detailed API design and usage examples, refer to the API Design Document

Basic Usage

The SDK allows developers to work with decentralized identifiers (DIDs), verifiable credentials, and presentation exchanges. Below are the key use cases:

1. DidJwk Creation
   You can create DIDs using the Did::create method.

2. Verifiable Credential Creation & Signing
   Create a verifiable credential using VerifiableCredential::create and sign it with a DID.

3. Verifiable Presentation Creation & Signing
   Use the SDK to create and sign verifiable presentations with VerifiablePresentation::create and sign.

4. Presentation Exchange
   Select the appropriate credentials and generate presentations based on the presentation definitions using PresentationDefinition::select_credentials and create_presentation_from_credentials.

Rust Examples

Instantiate a new did:jwk

let did_jwk = DidJwk::create(None);
println!("Created DID JWK: {}", did_jwk.did.uri);

Simple Verifiable Credential Creation & Signing

let vc = VerifiableCredential::create(issuer, credential_subject, None)?;
let vc_jwt = vc.sign(bearer_did, None)?;

Kotlin Examples

Instantiate a new did:jwk

val didJwk = DidJwk.create(null)
println("Created DID JWK: ${didJwk.did.uri}")

Simple Verifiable Credential Creation & Signing

val vc = VerifiableCredential.create(issuer, credentialSubject)
val vcJwt = vc.sign(bearerDid)