Web5.connect()

The Web5 JS SDK provides a simple interface to get started building Web5 applications quickly. It provides APIs to use Decentralized Identifiers (DIDs) and Decentralized Web Nodes (DWNs) right away by initializing the SDK through Web5.connect().

Install

NPM

npm install @web5/api

CDN

<script src="https://unpkg.com/@web5/api@0.12.0/dist/browser.js"></script>

or

<script src="https://cdn.jsdelivr.net/npm/@web5/api@0.12.0/dist/browser.mjs"></script>

Import

NPM

Node 19+

import { Web5 } from '@web5/api';

Node <=18

/*
Needs globalThis.crypto polyfill.
This is *not* the crypto you're thinking of.
It's the original crypto...CRYPTOGRAPHY.
*/
import { webcrypto } from "node:crypto";
import { Web5 } from '@web5/api';

// @ts-ignore
if (!globalThis.crypto) globalThis.crypto = webcrypto;

React Native

/*
React Native needs crypto.getRandomValues polyfill and sha512.
This is *not* the crypto you're thinking of.
It's the original crypto...CRYPTOGRAPHY.
*/
import "react-native-get-random-values";
import { hmac } from "@noble/hashes/hmac";
import { sha256 } from "@noble/hashes/sha256";
import { sha512 } from "@noble/hashes/sha512";
import { Web5 } from '@web5/api';

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));

CDN

import { Web5 } from 'https://unpkg.com/@web5/api@0.12.0/dist/browser.js';

or

import { Web5 } from 'https://cdn.jsdelivr.net/npm/@web5/api@0.12.0/dist/browser.mjs'

Connect

Using Web5.connect(), an instance of Web5 is created that enables an app to connect to an existing decentralized identifier (DID) either by direct creation or connection to an identity agent app or create a new one. The method also creates a locally running Decentralized Web Node (DWN) and associates it with the DID.

This local DWN is synchronized with a remote DWN node (if specified) that enables connectivity and sync across the user's devices and other users. While the Web5 JS SDK is in technical preview, a remote DWN is automatically provisioned and connected to the local DWN - syncing every 2 minutes.

const { web5, did: userDid } = await Web5.connect();

Options

Enables an app to request connection to a user's local identity app (like a desktop or mobile agent - work is underway for reference apps of each), or generate an in-app DID to represent the user (e.g. if the user does not have an identity app)

note

The outputs of this method invocation will be used throughout the other API methods.

Parameters

options
Web5ConnectOptions
optional

Show parameters

agent
Web5Agent
optional

An instance of a Web5Agent implementation. Defaults to creating a local Web5UserAgent if not provided.

appData
AppDataStore
optional

An instance of an AppDataStore implementation. Defaults to a LevelDB-backed store with an insecure, static unlock passphrase if not provided. To allow the end user to enter a secure passphrase of their choosing, provide an initialized AppDataVault.

connectedDid
string
optional

An existing DID to connect to. If provided, the agent property must also be provided.

sync
string
optional

Enable or disable synchronization of DWN records between local and remote DWNs. Sync defaults to running every 2 minutes and can be set to any value accepted by ms (https://www.npmjs.com/package/ms). To disable sync set to 'off'

techPreview
TechPreviewOptions
optional

Show parameters

dwnEndpoints
string[]
optional

a list of DWN endpoints to define in the DID created and returned by this method. If this property is omitted during the Tech Preview, two nodes will be included by default (e.g. https://dwn.tbddev.org/dwn0, https://dwn.tbddev.org/dwn3)

Return Value

web5
Web5

A class instance of Web5 that enables access to a locally running DWN, DID interaction methods, and other capabilities related to the connected DID

did
DidApi

A class instance representing the decentralized identifier that was created or attained connection to

Examples

Below are examples of how to use Web5.connect() with or without additional option parameters.

Connect with no parameters

const { web5, did: userDid } = await Web5.connect();

Connect to DIF Community Node

Connect to the free DIF community node instance hosted by Google Cloud:

const {did, web5} = await Web5.connect({
  didCreateOptions: {
    // Use community DWN instance hosted on Google Cloud
    dwnEndpoints: ['https://dwn.gcda.xyz']
  },
  registration: {
    onSuccess: () => {
      /*
      Registration succeeded, set a local storage value to indicate the user 
      is registered and registration does not need to occur again
      */
    },
    onFailure: (error) => {
      /* 
      Registration failed, display an error message to the user, and pass in 
      the registration object again to retry next time the user connects
      */
    },
  },
})

Connect with an existing Decentralized Web Node endpoint

const { web5, did } = await Web5.connect({
    techPreview: {
      dwnEndpoints: ['https://dwn.your-domain.org/'],
    },
  });

Connect with an existing agent and existing DID

If connectedDid is provided, the agent property must also be provided.

const { web5, did } = await Web5.connect({
    agent: identityAgent,
    connectedDid: existingDid,
  });

Configure sync interval when connecting to Web5

Sync defaults to running every 2 minutes and can be set to any value accepted by ms. To disable sync set to 'off'.

const { web5, did } = await Web5.connect({
    sync: '5s',
  });