Decentralized Web Node (DWN) SDK

Code Coverage

Introduction

This repository contains a reference implementation of Decentralized Web Node (DWN) as per the specification. This specification is in a draft state and very much so a WIP. For the foreseeable future, a lot of the work on DWN will be split across this repo and the repo that houses the specification, which you can find here. The current implementation does not include all interfaces described in the DWN spec, but is enough to begin building test applications.

This project is used as a dependency by several other projects.

Proposals and issues for the specification itself should be submitted as pull requests to the spec repo.

Installation

If you are interested in using DWNs and web5 in your web app, you probably want to look at web5-js, instead of this repository. Head on over here: https://github.com/TBD54566975/web5-js.

For advanced users wishing to use this repo directly:

npm install @tbd54566975/dwn-sdk-js

Additional Steps

This package has dependency on @noble/ed25519 and @noble/secp256k1 v2, additional steps are needed for some environments:

• Node.js <= 18

// node.js 18 and earlier,  needs globalThis.crypto polyfill
import { webcrypto } from "node:crypto";
// @ts-ignore
if (!globalThis.crypto) globalThis.crypto = webcrypto;

• React Native:

// If you're on react native. React Native needs crypto.getRandomValues polyfill and sha512
import "react-native-get-random-values";
import { hmac } from "@noble/hashes/hmac";
import { sha256 } from "@noble/hashes/sha256";
import { sha512 } from "@noble/hashes/sha512";
ed.etc.sha512Sync = (...m) => sha512(ed.etc.concatBytes(...m));
ed.etc.sha512Async = (...m) => Promise.resolve(ed.etc.sha512Sync(...m));

secp.etc.hmacSha256Sync = (k, ...m) =>
  hmac(sha256, k, secp.etc.concatBytes(...m));
secp.etc.hmacSha256Async = (k, ...m) =>
  Promise.resolve(secp.etc.hmacSha256Sync(k, ...m));

Usage

API docs

import { Dwn, DataStream, DidKeyResolver, Jws, RecordsWrite, RecordsQuery } from '@tbd54566975/dwn-sdk-js';

export const dwn = await Dwn.create();

...
const didKey = await DidKeyResolver.generate(); // generate a did:key DID
const signatureMaterial = Jws.createSignatureInput(didKey);
const data = randomBytes(32); // in node.js
// or in web
// const data = new Uint8Array(32);
// window.crypto.getRandomValues(data);

const recordsWrite = await RecordsWrite.create({
  data,
  dataFormat                  : 'application/json',
  published                   : true,
  schema                      : 'yeeter/post',
  authorizationSignatureInput : signatureMaterial
});

const dataStream = DataStream.fromBytes(data);
const result = await dwn.processMessage(didKey.did, recordsWrite.message, dataStream);

With a web wallet installed:

const result = await window.web5.dwn.processMessage({
  method: "RecordsQuery",
  message: {
    filter: {
      schema: "http://some-schema-registry.org/todo",
    },
    dateSort: "createdAscending",
  },
});

Release/Build Process

The DWN JS SDK releases builds to npmjs.com. There are two build types: stable build and unstable build.

Stable Build

This is triggered manually by:

1. Increment version in package.json in Semantic Versioning (semver) format.
2. Merge the change into main branch
3. Create a release from GitHub.

An official build with version matching the package.json will be published to npmjs.com.

Unstable Build

Every push to the main branch will automatically trigger an unstable build to npmjs.com for developers to experiment and test.

The version string contains the date as well as the commit hash of the last change.

An example version string:

0.0.26-unstable-2023-03-16-36ec2ce

• 0.0.26 came from version in package.json
• 2023-03-16 indicates the date of March 16th 2023
• 36ec2ce is the commit hash of the last change

Some projects that use this library:

• Web5 JS SDK
• Example CLI
• Example with a web wallet
• Server side aggregator

Architecture

NOTE: The diagram is a conceptual view of the architecture, the actual component abstraction and names in source file may differ.

Project Resources

| Resource | Description | | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | CODEOWNERS | Outlines the project lead(s) | | CODE_OF_CONDUCT.md | Expected behavior for project contributors, promoting a welcoming environment | | CONTRIBUTING.md | Developer guide to build, test, run, access CI, chat, discuss, file issues | | GOVERNANCE.md | Project governance | | LICENSE | Apache License, Version 2.0 | | Q_AND_A.md | Questions and answers on DWN |