- Purpose
- Requirements
- Test Vectors
- Web5 SDK Features
This repo sets forth the development process, requirements, and the desired feature for the following SDKs:
Feature tracking will take place entirely on GitHub through Github Issues and the SDK development Github project.
Proposing new features that impact all SDKs will occur by creating a Github Issue in this repo. The Issue should include motivation or rationale in addition to any relevant reading material. New features will be discussed and decided upon during weekly syncs
Important
Language agnostic test vectors must be produced prior to commencing implementation beyond the first SDK
Test vectors are in the test-vector directory. More info on test vectors can be found there.
Prioritization of features or specific work items will be reflected during weekly sync meetings.
An individual SDK will consider a feature implemented once the following requirements have been met:
- Produce/update API reference documentation for any/all methods added to the public API surface. documenting private API methods is optional
- Produce/update relevant example usage
- Test coverage must be provided for all public API methods.
- Tests that consume shared test vectors must all be passing
-
Propose API surface design prior to implementation. This can be done by opening a feature request Issue and fostering a discussion around the proposed design. This can be followed by a corresponding draft PR and providing prototypal code.
-
Approval Required from a minimum of 2 people.
Note
Requiring two reviewers will likely slow things down at the benefit of ensuring there's a sufficient amount of visibility on the changes being made. It also prevents bottlenecks from forming. Many people on our team should be able to speak to the features landing in our SDKs.
-
Each Release will have an accompanying Github Release
-
Each Github Release will have an accompanying git tag that matches the version being published
-
For the forseeable future, each SDK is free to publish releases at a frequency that the SDK's respective DRI sees fit
Each SDK will use GitHub Actions for CI/CD and other automations.
Find the latest Projects Health Dashboard here.
Each SDK will be published to the most widely adopted registry/repository for the respective language
| SDK | Repository |
|---|---|
| Typescript | npm |
| Kotlin | maven central |
| Rust | crates.io |
| Swift | swift package index |
| Go | tbd |
Each SDK will auto generate API reference documentation using the respective language's commenting convention and doc gen tooling
Important
At a minimum, API reference documentation will be published to the respective sdk repository's Github Pages. e.g. https://tbd54566975.github.io/tbdex-kt/.
| Language | Comment Convention | Docs Generator |
|---|---|---|
| Typescript | TSDoc | API Extractor |
| Kotlin | KDoc | Dokka |
| Rust | Documentation comments | rustdoc |
| Swift | Swift Markup | DocC |
| Go | tbd | tbd |
Important
Producing API reference documentation is the responsibility of an implementer.
Each SDK will publish example usage for each implemented feature. This can either be included as a part of API reference documentation or published separately.
Test vectors ensure interoporability of features across SDKs and language implementations by providing common test cases with an input and expected output pair. They include both success and failure cases that can be vectorized.
This repo serves as the home for all web5 feature related vectors. They are available in the test-vectors directory.
The tbdex repo houses tbdex feature related vectors. They are available in the test-vectors directory.
The sdk-report-runner repo consumes the output tests for these test vectors in each repo and generates a report - report-runner.
New test vectors should follow the standard vector structure. Vectors are automatically validated against their JSON Schema via CI.
Create a PR in this repo for adding / updating Web5 test vectors.
Test vectors are used to determine feature completeness via our test harness. Results of test harness runs can be found here.
| Key Type | Algorithm | Type |
|---|---|---|
| secp256k1 | ES256K |
Signing and Verification |
| Ed25519 | EdDSA |
Signing and Verification |
Important
In-memory signing using secp256k1 MUST produce k-deterministic low-s signatures with ECDSA as per RFC6979. Verification must not require low-s signatures.
Each SDK will implement a consistent and extensible public interface for key management minimally providing concrete implementations of:
| Feature |
|---|
| Key Manager Interface |
| In-Memory Key Manager |
| AWS KMS |
| Device Enclave (Mobile) |
| Keychain (Mobile) |
Further, the key manager interface must be passed as an argument to all public API methods that require key material. e.g.
- DID Creation
- Data Signing
Important
AWS KMS does not support Ed25519. At some point in the future, we can consider introducing support for key wrapping
Important
Consumers of our SDKs should be able to provide their own KeyManager implementations if desired
Independent of DID Methods, we support DID Documents according to DID Core v1.0 with the adjustments specified in this corresponding document.
| Method | Creation | Resolution | Note |
|---|---|---|---|
did:web |
❌ | ✅ | - |
did:jwk |
✅ | ✅ | - |
did:dht |
✅ | ✅ | This is our default method. |
did:key |
Has been implemented in both Kotlin and Typescript, no plans for support in other languages. | ||
did:ion |
Support for did:ion has been deprecated. |
We support Verifiable Credentials according to the Verifiable Credentials Data Model 1.1 with the adjustments specified in this corresponding document.
Important
Credential validation will soon be specified more clearly.
| Feature |
|---|
| Data model |
| Validation (data model, JSON Schema, status, more to come.) |
Signing and verification of Verifiable Credentials as vc-jwt |
Signing and verification of Verifiable Presentations as vp-jwt |
| Feature |
|---|
| Data model |
| Validation (data model, JSON Schema, status) |
Signing and verification of Verifiable Credentials with vc-jose-cose. |
Signing and verification of Verifiable Presentations with vp-jose-cose |
| Feature |
|---|
| Data model |
| Signing and verification |
For usage with the W3C Verifiable Credential Data Model 1.1.
| Feature |
|---|
| Data model |
Status checking (supporting at least Revocation and Suspension statuses) |
| Status setting |
Signing and verification with vc-jwt |
For usage with the W3C Verifiable Credential Data Model 2.0.
| Feature |
|---|
| Data model |
Status checking (supporting at least Revocation and Suspension statuses) |
| Status setting |
Signing and verification with vc-jose-cose |
For usage with both the W3C Verifiable Credential Data Model 1.1 and the W3C Verifiable Credential Data Model 2.0.
| Feature |
|---|
Creation and validation of JsonSchema |
Creation and validation of JsonSchemaCredential using vc-jwt with the VCDM v1.1 |
Creation and validation of JsonSchemaCredential using vc-jose-cose with the VCDM v2.0 |
| Feature |
|---|
| Data model |
| Validation |
Credential Evaluation using the VCDM v1.1 (both vc-jwt and vp-jwt), the VCDM v2.0 using vc-jose-cose, and SD-JWT |
| Predicates |
| Relational Constraints |
| Credential Status |