Skip to main content

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 install @web5/api

Import​

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

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.

No snippet found for javascript

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​
No snippet found for javascript
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​
No snippet found for javascript
Connect with an existing agent and existing DID​

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

No snippet found for javascript
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'.

No snippet found for javascript