Making developing with Web5 components at least 5 times easier to work with.
Web5 consists of the following components:
- Decentralized Identifiers
- Verifiable Credentials
- DWeb Node personal datastores
The SDK sets out to gather the most oft used functionality from all three of these pillar technologies to provide a simple library that is as close to effortless as possible.
Creates an isolated API object for doing Web5 things, split into three main top-level objects: did, dwn, and vc.
When creating a Web5 instance the following options can be provided:
This object contains options related to web5.dwn.
node-Dwn: A customizableDwninstance to use instead of a default one created byweb5.dwn. This can be used to customize the storage location/structure/etc. of theDwn, how DIDs are resolved, etc..
The create method under the did scope enables generation of DIDs for a supported set of DID Methods. The output is method-specific, and handles things like key generation and assembly of DID Documents that can be published to decentralized DID networks.
const myDid = await web5.did.create('ion');The package provides a DID manager mechanism that handles interactions with a DID that is being 'managed' by the local code (be it in a web page, agent app, or elsewhere). By adding a DID to the manager, the library ensures that all interactions with that DID, including things like signing and encryption, are handled automatically.
Assuming the myDid instance is present from the example above, you would pass the following values to add it to the DID manager:
await web5.did.manager.set(myDid.id, {
connected: true,
endpoint: 'app://dwn', //this points to the user's local DWN
keys: {
'#dwn': {
keyPair: myDid.keys.find(key => key.id === 'dwn').keyPair,
}
}
});Method for querying the DWeb Node of a provided target DID.
The query request must contain the following:
author-string: The decentralized identifier of the DID signing the query. This may be the same as thetargetparameter if the target and the signer of the query are the same entity, which is common for an app querying the DWeb Node of its own user.message-object: The properties of the DWeb Node Message Descriptor that will be used to construct a valid DWeb Node message.
const web5 = new Web5();
const response = await web5.dwn.records.query('did:example:bob', {
author: 'did:example:alice',
message: {
filter: {
schema: 'https://schema.org/Playlist',
dataFormat: 'application/json'
}
}
});
console.log(response.entries) // logs array of Record class instancesMethod for writing a record to the DWeb Node of a provided target DID.
The write request must contain the following:
author-string: The decentralized identifier of the DID signing the query. This may be the same as thetargetparameter if the target and the signer of the query are the same entity, which is common for an app querying the DWeb Node of its own user.message-object: The properties of the DWeb Node Message Descriptor that will be used to construct a valid DWeb Node message.data-blob | stream | file: The data object of the bytes to be sent.
const web5 = new Web5();
const { record } = await web5.dwn.records.create('did:example:alice', {
author: 'did:example:alice',
data: 'Hello World!',
message: {
dataFormat: 'text/plain'
}
});
console.log(record.data.text()) // logs "Hello World!" in consoleEvery modifying method (create, write, etc.) and query entries return an instance of Record class, which is a representation of the Record(s) involved. Record class instances have the following properties:
recordId-string: The unique identifier based on the record entry's composition. Note: all entries across all records are deterministically unique.descriptor-object: The descriptor object for the constructed DWeb Node message.data-object: a object with the following convenience methods that read out the data of the record entry in the following formats:text-function: produces a textual representation of the data.json-function: if the value is JSON data, this method will return a parsed JSON object.stream-function: returns the raw stream of bytes for the data.
Method for writing a record to the DWeb Node of a provided target DID.
The write request must contain the following:
author-string: The decentralized identifier of the DID signing the query. This may be the same as thetargetparameter if the target and the signer of the query are the same entity, which is common for an app querying the DWeb Node of its own user.message-object: The properties of the DWeb Node Message Descriptor that will be used to construct a valid DWeb Node message.data-blob | stream | file: The data object of the bytes to be sent.
For this example we assume we have created the record and are using the output Record instance from above to overwrite the data of the record with a subsequent write:
const web5 = new Web5();
const { record } = await web5.dwn.records.write('did:example:alice', {
author: 'did:example:alice',
data: 'Hello again!',
message: {
recordId: record.recordId,
dataFormat: 'text/plain'
}
});
console.log(record.data.text()) // prints "Hello again!" in consoleMethod for writing a record to the DWeb Node of a provided target DID.
The write request must contain the following:
author-string: The decentralized identifier of the DID signing the query. This may be the same as thetargetparameter if the target and the signer of the query are the same entity, which is common for an app querying the DWeb Node of its own user.message-object: The properties of the DWeb Node Message Descriptor that will be used to construct a valid DWeb Node message.recordId-string: the required record ID string that identifies the record data you are fetching.
const web5 = new Web5();
const response = await web5.dwn.records.read('did:example:alice', {
author: 'did:example:alice',
message: {
recordId: 'bfw35evr6e54c4cqa4c589h4cq3v7w4nc534c9w7h5'
}
});Method for deleting a record in the DWeb Node of a provided target DID.
The delete request must contain the following:
author-string: The decentralized identifier of the DID signing the query. This may be the same as thetargetparameter if the target and the signer of the query are the same entity, which is common for an app querying the DWeb Node of its own user.message-object: The properties of the DWeb Node Message Descriptor that will be used to construct a valid DWeb Node message.recordId-string: the required record ID string that identifies the record being deleted.
const web5 = new Web5();
const response = await web5.dwn.records.delete('did:example:alice', {
author: 'did:example:alice',
message: {
recordId: 'bfw35evr6e54c4cqa4c589h4cq3v7w4nc534c9w7h5'
}
});Method for querying the protocols that a target DID has added configurations for in their DWeb Node.
The query request must contain the following:
author-string: The decentralized identifier of the DID signing the query. This may be the same as thetargetparameter if the target and the signer of the query are the same entity, which is common for an app querying the DWeb Node of its own user.message-object: The properties of the DWeb Node Message Descriptor that will be used to construct a valid DWeb Node message.filter-object: an object that defines a set of properties to filter results.protocol-URI string: a URI that represents the protocol being queried for.
const web5 = new Web5();
const response = await web5.dwn.protocols.query('did:example:alice', {
author: 'did:example:alice',
message: {
filter: {
protocol: "https://decentralized-music.org/protocol",
}
}
});Method for deleting a record in the DWeb Node of a provided target DID.
The configuration request must contain the following:
author-string: The decentralized identifier of the DID signing the query. This may be the same as thetargetparameter if the target and the signer of the query are the same entity, which is common for an app querying the DWeb Node of its own user.message-object: The properties of the DWeb Node Message Descriptor that will be used to construct a valid DWeb Node message.protocol-URI string: a URI that represents the protocol being configured via thedefinitionobject.definition-object: an object that defines the ruleset that will be applied to the records and activities under the protocol.labels-object: an object that defines the composition of records that will be used in therecordstree below.records-object: a recursive object that defines the structure of an app, including data relationships and constraints on which entities can perform various activities.
const web5 = new Web5();
const response = await web5.dwn.protocols.configure('did:example:alice', {
author: 'did:example:alice',
message: {
protocol: "https://decentralized-music.org/protocol",
definition: {
"labels": {
"playlist": {
"schema": "https://decentralized-music.org/protocol/playlist",
"dataFormat": [ "application/json" ]
},
"track": {
"schema": "https://decentralized-music.org/protocol/track",
"dataFormat": [ "application/json" ]
},
"audio": {
"schema": "https://decentralized-music.org/protocol/audio",
"dataFormat": [ "audio/aac", "audio/mp4" ]
}
},
"records": {
"playlist": {},
"track": {
"records": {
"audio": {}
}
}
}
}
}
});Enables an app to request connection to a user's local identity app, or generate an in-app DID to represent the user (e.g. if the user does not have an identity app).
NOTE: This method MUST be invoked within the scope of a 'trusted user action', which is something the browser/OS decides. For browsers this is generally some direct user intent, like clicking a link or button.
The connect method optionally accepts an object with the following properties:
Used by connect to store connection data/keys/etc. for reuse when calling connect again (e.g. during another session).
If provided, storage must be an object that has the same methods as Storage.
If not provided, an instance of LocalStorage is used instead.
Controls where in storage the connection data is stored.
Defaults to 'web5-connection'.
Controls where in storage the connection keys are stored.
Defaults to 'web5-keys'.
Controls whether to prompt the user to start a new connection if a connection has not already been established.
Defaults to false.
After calling connect, at least one of the following events will be dispatched on the Web5 instance:
A 'open' event is dispatched if a local identity app is found, containing a verification pin and port number used for the connection.
event.detail.pin-number: 1-4 digit numerical code that must be displayed to the user to ensure they are connecting to the desired local identity app.event.detail.port-number: The port number used by the the local identity app to listen for connections.
A 'connection' event is dispatched if the user accepts the connection, containing the DID the user selected in the local identity app.
event.details.did-string: The DID selected by the user in the local identity app.
A 'close' event is dispatched if the user refuses to accept or respond to the connection attempt for any reason.
An 'error' event is dispached if anything goes wrong (e.g. Web5 was unable to find any local identity apps).
document.querySelector('#connect_button').addEventListener('click', async event => {
event.preventDefault();
const web5 = new Web5();
web5.addEventListener('open', (event) => {
const { pin } = event.detail
document.querySelector('#pin_code_text').textContent = pin;
});
web5.addEventListener('connection', (event) => {
const { did } = event.detail
alert('Connection succeeded! Connected to DID: ' + did);
});
web5.addEventListener('close', (event) => {
alert('Connection was denied');
});
web5.addEventListener('error', (event) => {
console.error(event);
});
web5.connect();
});| 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 |