Skip to content

Commit

Permalink
add readme (#351)
Browse files Browse the repository at this point in the history
  • Loading branch information
@nitro-neal
nitro-neal authored Sep 10, 2024
1 parent bb75678 commit 01194b3
Show file tree
Hide file tree
Showing 2 changed files with 183 additions and 78 deletions.
172 changes: 94 additions & 78 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,59 @@
# Work in progress
# 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](#features)
- [Getting Started](#getting-started)
- [Cloning](#cloning)
- [Development Prerequisites](#development-prerequisites)
- [Hermit](#hermit)
- [Building and Testing](#building-and-testing)
- [Binding Process](#binding-process)
- [API Documentation](#api-documentation)
- [Basic Usage](#basic-usage)
- [DidJwk Creation](#didjwk-creation)
- [Verifiable Credential Creation & Signing](#verifiable-credential-creation--signing)
- [Verifiable Presentation Creation & Signing](#verifiable-presentation-creation--signing)
- [Presentation Exchange](#presentation-exchange)
- [Rust Examples](#rust-examples)
- [Instantiate a new did:jwk](#instantiate-a-new-didjwk)
- [Simple Verifiable Credential Creation & Signing](#simple-verifiable-credential-creation--signing)
- [Kotlin Examples](#kotlin-examples)
- [Instantiate a new did:jwk](#instantiate-a-new-didjwk-1)
- [Simple Verifiable Credential Creation & Signing](#simple-verifiable-credential-creation--signing-1)


## 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](docs/API_DESIGN.md). Additionally, comprehensive
guides can be found at the [TBD Developer site](https://developer.tbd.website/docs/) 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:
```sh
git clone --recurse-submodules [email protected]:TBD54566975/web5-rs.git
```

This repo is not ready for consumption, and is under heavy development. Right now the Rust core bindings work only for Apple Silicon systems.
Or to add submodules after cloning:
```sh
git submodule update --init
```

## Development Prerequisites

Expand Down Expand Up @@ -43,104 +96,67 @@ $> just [buildTarget]
For instance:

```shell
$> just test-kotlin
...
[INFO] Tests run: 10, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 10.035 s
[INFO] Finished at: 2024-07-15T00:38:03-04:00
[INFO] ------------------------------------------------------------------------
$> just build
```

## Tooling Details

While we execute most commands with `just`, some developers may like finer-grained control over the underlying build systems. This is a guide to those tools.
## Binding Process

### Rust
The binding process follows these key steps:

This project is written in [Rust](https://www.rust-lang.org/), a modern, performant, statically-linked programming language. It's installed and configured on you `$PATH` via Hermit, above.
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.

You may verify your `rust` installation via the terminal:
2. **Building the Kotlin Bindings**
The Kotlin bindings are generated from the core Rust code and live in the `bound/kt` directory. These bindings allow Kotlin applications to access the functionality of the core Rust libraries through idiomatic Kotlin APIs.

```shell
$> which rustup
~/web5-rs/bin/rustup // For instance

$> rustc --version
rustc 1.79.0 (129f3b996 2024-06-10)
```
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.

You may need to initialize your `rustc` environment if you see:
## API Documentation
For the full detailed API design and usage examples, refer to the [API Design Document](docs/API_DESIGN.md)

```shell
error: rustup could not choose a version of rustc to run, because one wasn't specified explicitly, and no default is configured.
help: run 'rustup default stable' to download the latest stable release of Rust and set it as your default toolchain.
```
## Basic Usage

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

```shell
$> rustup default stable
info: ... // Downloading things
info: default toolchain set to 'stable-aarch64-apple-darwin'
1. **DidJwk Creation**
You can create DIDs using the `Did::create` method.

stable-aarch64-apple-darwin installed - rustc 1.79.0 (129f3b996 2024-06-10)
```
2. **Verifiable Credential Creation & Signing**
Create a verifiable credential using `VerifiableCredential::create` and sign it with a DID.

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

The Java bindings are built with the
[Maven Project Management](https://maven.apache.org/) tool.
It is installed via Hermit above.
4. **Presentation Exchange**
Select the appropriate credentials and generate presentations based on the presentation definitions using `PresentationDefinition::select_credentials` and `create_presentation_from_credentials`.

If you want to build an artifact on your local filesystem, you can do so by running the
following command, specifying the `-f` flag to point to the `pom.xml` for the Kotlin project.
## Rust Examples
### Instantiate a new `did:jwk`

```shell
mvn -f bound/kt/pom.xml clean verify
```rust
let did_jwk = DidJwk::create(None);
println!("Created DID JWK: {}", did_jwk.did.uri);
```

This will first clean all previous builds and compiled code, then:
compile, test, and build the artifacts in each of the submodules
of this project in the `$moduleName/target` directory, for example:
### Simple Verifiable Credential Creation & Signing

```shell
ls -l bound/kt/target/
```rust
let vc = VerifiableCredential::create(issuer, credential_subject, None)?;
let vc_jwt = vc.sign(bearer_did, None)?;
```

You should see similar to:
## Kotlin Examples
### Instantiate a new `did:jwk`

```shell
total 57416
drwxr-xr-x@ 8 alr staff 256 Jul 15 00:38 classes
drwxr-xr-x@ 3 alr staff 96 Jul 15 00:37 generated-sources
drwxr-xr-x@ 3 alr staff 96 Jul 15 00:38 generated-test-sources
drwxr-xr-x@ 3 alr staff 96 Jul 15 00:42 maven-archiver
drwxr-xr-x@ 3 alr staff 96 Jul 15 00:37 maven-status
drwxr-xr-x@ 14 alr staff 448 Jul 15 00:42 surefire-reports
drwxr-xr-x@ 4 alr staff 128 Jul 15 00:38 test-classes
-rw-r--r--@ 1 alr staff 29123862 Jul 15 00:42 web5-core-kt-1.0-SNAPSHOT.jar
```
If you'd like to skip packaging and test only, run:

```shell
mvn -f bound/kt/pom.xml test
```kotlin
val didJwk = DidJwk.create()
println("Created DID JWK: ${didJwk.did.uri}")
```

You may also run a single test; use the `-Dtest=` parameter to denote which test to run, for example:
### Simple Verifiable Credential Creation & Signing

```shell
mvn -f bound/kt/pom.xml test -Dtest=TestClassName
```kotlin
val vc = VerifiableCredential.create(issuer, credentialSubject)
val vcJwt = vc.sign(bearerDid)
```

To install builds into your local Maven repository, run from the root:

```shell
mvn -f bound/kt/pom.xml install
```

For more, see the documentation on [Maven Lifecycle](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html).
89 changes: 89 additions & 0 deletions docs/TOOLING_DETAILS.MD
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
## Tooling Details

While we execute most commands with `just`, some developers may like finer-grained control over the underlying build systems. This is a guide to those tools.

### Rust

This project is written in [Rust](https://www.rust-lang.org/), a modern, performant, statically-linked programming language. It's installed and configured on you `$PATH` via Hermit, above.

You may verify your `rust` installation via the terminal:

```shell
$> which rustup
~/web5-rs/bin/rustup // For instance

$> rustc --version
rustc 1.79.0 (129f3b996 2024-06-10)
```

You may need to initialize your `rustc` environment if you see:

```shell
error: rustup could not choose a version of rustc to run, because one wasn't specified explicitly, and no default is configured.
help: run 'rustup default stable' to download the latest stable release of Rust and set it as your default toolchain.
```
Fix by executing:
```shell
$> rustup default stable
info: ... // Downloading things
info: default toolchain set to 'stable-aarch64-apple-darwin'
stable-aarch64-apple-darwin installed - rustc 1.79.0 (129f3b996 2024-06-10)
```
### Maven
The Java bindings are built with the
[Maven Project Management](https://maven.apache.org/) tool.
It is installed via Hermit above.
If you want to build an artifact on your local filesystem, you can do so by running the
following command, specifying the `-f` flag to point to the `pom.xml` for the Kotlin project.
```shell
mvn -f bound/kt/pom.xml clean verify
```
This will first clean all previous builds and compiled code, then:
compile, test, and build the artifacts in each of the submodules
of this project in the `$moduleName/target` directory, for example:
```shell
ls -l bound/kt/target/
```
You should see similar to:
```shell
total 57416
drwxr-xr-x@ 8 alr staff 256 Jul 15 00:38 classes
drwxr-xr-x@ 3 alr staff 96 Jul 15 00:37 generated-sources
drwxr-xr-x@ 3 alr staff 96 Jul 15 00:38 generated-test-sources
drwxr-xr-x@ 3 alr staff 96 Jul 15 00:42 maven-archiver
drwxr-xr-x@ 3 alr staff 96 Jul 15 00:37 maven-status
drwxr-xr-x@ 14 alr staff 448 Jul 15 00:42 surefire-reports
drwxr-xr-x@ 4 alr staff 128 Jul 15 00:38 test-classes
-rw-r--r--@ 1 alr staff 29123862 Jul 15 00:42 web5-core-kt-1.0-SNAPSHOT.jar
```
If you'd like to skip packaging and test only, run:

```shell
mvn -f bound/kt/pom.xml test
```

You may also run a single test; use the `-Dtest=` parameter to denote which test to run, for example:

```shell
mvn -f bound/kt/pom.xml test -Dtest=TestClassName
```

To install builds into your local Maven repository, run from the root:

```shell
mvn -f bound/kt/pom.xml install
```

For more, see the documentation on [Maven Lifecycle](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html).

0 comments on commit 01194b3

Please sign in to comment.