API Reference

WalletAuthenticator

The WalletAuthenticator class is the core engine for DID Connect. It handles the low-level cryptographic operations required to create, sign, and verify authentication messages between your application and a user's DID Wallet. It operates independently of any specific web framework, providing the fundamental building blocks for a secure DID-based interaction.
While you can use WalletAuthenticator directly, it is most often used in conjunction with the WalletHandlers class, which simplifies integration into Express.js applications by managing state, routing, and event handling.
Core Workflow with WalletAuthenticator#A typical authentication flow involves using WalletAuthenticator at several key stages:

Constructor#new WalletAuthenticator(config)#Creates a new instance of the authenticator. This instance holds your application's identity (wallet), information, and configuration for handling DID Connect sessions.
Parameter
Type
Description
config.wallet
WalletObject | Function
The application's wallet instance or a function that returns one. This wallet is used to sign all communications with the user's wallet.
config.appInfo
ApplicationInfo | Function
An object or function that returns information about your application (name, description, icon) to be displayed in the user's wallet.
config.chainInfo
ChainInfo | Function
An object or function specifying the blockchain that the application is connected to.
config.delegator
WalletObject | Function
(Optional) For delegated connect, this is the wallet of the party authorizing config.wallet to act on its behalf.
config.delegation
string | Function
(Optional) For delegated connect, the JWT that proves the delegation relationship.
config.timeout
Number
(Optional) Timeout in milliseconds for generating claims. Defaults to 8000.
config.baseUrl
string
(Optional) The base URL for assembling wallet request URIs. Can often be inferred from the request object.
config.tokenKey
string
(Optional) The query parameter key for the session token. Defaults to '_t_'.
Example
const { fromRandom } = require('@ocap/wallet');
const { WalletAuthenticator } = require('@did-connect/sdk');

// The application's own DID and wallet
const appWallet = fromRandom().toJSON();

const auth = new WalletAuthenticator({
  wallet: appWallet,
  baseUrl: 'https://myapplication.com',
  appInfo: {
    name: 'My Awesome App',
    description: 'This is a demo app for DID Connect.',
    icon: 'https://myapplication.com/logo.png',
    link: 'https://myapplication.com',
  },
  chainInfo: {
    host: 'https://beta.abtnetwork.io/api',
    id: 'beta',
  },
});Methods#uri(params)#Generates a deep link URL that can be displayed as a QR code for a DID Wallet to scan.
Parameter
Type
Description
params.baseUrl
string
The base URL, often inferred from the incoming request.
params.pathname
string
The callback path for the wallet.
params.token
string
The unique session token for this authentication action.
params.query
object
(Optional) Any additional query parameters to persist in the callback URL.
Returns: string - The deep link URL, e.g., https://abtwallet.io/i/?....
Example
const deepLink = auth.uri({
  baseUrl: 'https://myapplication.com',
  pathname: '/api/auth/callback',
  token: 'some_unique_session_token',
});
// deepLink can now be rendered as a QR code.sign(params)#Signs an authentication request to be sent to the wallet. This JWT contains the application's info and the specific claims being requested from the user.
Parameter
Type
Description
params.claims
object
The information required from the user, such as profile, signature, etc. See the Claims Reference for details.
params.pathname
string
The pathname to assemble the callback URL.
params.baseUrl
string
The base URL of the application.
params.challenge
string
A random challenge string to prevent replay attacks.
params.context
object
Contextual information about the request, such as the token, userDid, userPk, etc.
Returns: Promise<object> - An object { appPk, agentPk, sharedKey, authInfo } where authInfo is the signed JWT to be sent to the wallet.
verify(data, [locale], [enforceTimestamp])#Verifies a DID auth response sent from the DID Wallet. It checks the signature and decodes the JWT to extract the user's information and the requested claims.
Parameter
Type
Default
Description
data
object

The response object from the wallet, containing userPk and userInfo (the JWT).
locale
string
'en'
The locale for error messages.
enforceTimestamp
boolean
true
Whether to validate the timestamp in the JWT to prevent expired tokens.
Returns: Promise<object> - A promise that resolves to an object containing the verified data, including userDid, userPk, and the claims provided by the user.
Example
// In your POST handler where the wallet sends data
async function handleWalletResponse(req, res) {
  try {
    const walletResponse = req.body;
    const verifiedData = await auth.verify(walletResponse);

    console.log('User DID:', verifiedData.userDid);
    console.log('User provided profile:', verifiedData.claims[0]);

    // Proceed with user login or action
  } catch (error) {
    console.error('Verification failed:', error);
  }
}signResponse(params)#Signs a plain response to be sent back to the wallet after an action is completed, usually to indicate success or failure. This can also be used to chain workflows.
Parameter
Type
Description
params.response
object
(Optional) A JSON object to be returned to the wallet.
params.errorMessage
string
(Optional) An error message to display in the wallet.
params.successMessage
string
(Optional) A success message to display in the wallet.
params.nextWorkflow
string
(Optional) A URL to instruct the wallet to start the next step in a chained workflow. See Chaining Workflows.
params.nextUrl
string
(Optional) A URL for the wallet to open in its built-in webview.
params.cookies
object
(Optional) Key-value pairs to be set as cookies before opening nextUrl.
params.storages
object
(Optional) Key-value pairs to be set as localStorage before opening nextUrl.
Returns: Promise<object> - An object containing { appPk, agentPk, authInfo } where authInfo is the signed JWT for the wallet.
getPublicUrl(pathname, [params], [baseUrl])#A utility method to compute a public URL that can be returned to the wallet.
Parameter
Type
Description
pathname
string
The URL path.
params
object
(Optional) Query parameters to stringify.
baseUrl
string
(Optional) The base URL. Defaults to the one set in the constructor.
Returns: string - The fully formed public URL.
getAppInfo(params, [key])#Determine appInfo or memberAppInfo on the fly. This is useful when the application information needs to be decided dynamically based on the request context (e.g., user's locale).
Parameter
Type
Default
Description
params
object

Contains the context of this request.
key
string
'appInfo'
Either 'appInfo' or 'memberAppInfo'.
Returns: Promise<ApplicationInfo> - The dynamically resolved application info.
getChainInfo(params, [info])#Determine chainInfo on the fly. This method is valuable for multi-chain applications where the required blockchain might depend on the user or the specific action being performed.
Parameter
Type
Description
params
object
Contains the context of this request.
info
object | undefined
(Optional) A chain info object or function to use instead of the one from the constructor.
Returns: Promise<ChainInfo> - The dynamically resolved chain info.
getWalletInfo(params)#Resolves the application wallet dynamically. This is used when the wallet is provided as a function in the constructor, allowing for per-request wallet selection.
Parameter
Type
Description
params
object
Contains the context of the current request.
Returns: Promise<WalletObject> - The resolved wallet object.
getDelegator(params)#Resolves the delegator wallet dynamically. This is part of the Delegated Connect flow and is used when the delegator is provided as a function in the constructor.
Parameter
Type
Description
params
object
Contains the context of the current request.
Returns: Promise<WalletObject | null> - The resolved delegator wallet object, or null if not applicable.
getDelegation(params)#Resolves the delegation JWT dynamically. This is used in the Delegated Connect flow when the delegation proof is generated on a per-request basis.
Parameter
Type
Description
params
object
Contains the context of the current request.
Returns: Promise<string> - The resolved delegation JWT.
Type Definitions#ApplicationInfo#This object defines how your application is presented to the user inside their DID Wallet.
Property
Type
Description
name
string
Application name.
description
string
A brief description of your application.
icon
string
A URL to your application's logo/icon.
link
string
(Optional) The home page URL of your application.
path
string
(Optional) The deep link URL scheme. Defaults to https://abtwallet.io/i/.
publisher
string
(Optional) The did:abt: formatted DID of the application publisher.
ChainInfo#This object specifies the blockchain network your application intends to interact with for tasks like signing transactions.
Property
Type
Description
id
string
The chain ID. For ArcBlock chains, this is a string like 'beta' or 'main'. For EVM chains, it's the numeric chain ID.
type
string
The chain type, e.g., 'arcblock', 'ethereum'. Defaults to 'arcblock'.
host
string
The GraphQL endpoint of the chain's node, or an RPC endpoint for EVM chains.

Now that you understand the core functions of WalletAuthenticator, you can explore how to easily integrate it into a web server using the WalletHandlers class.

Parameter	Type	Description
`config.wallet`	`WalletObject` \| `Function`	The application's wallet instance or a function that returns one. This wallet is used to sign all communications with the user's wallet.
`config.appInfo`	`ApplicationInfo` \| `Function`	An object or function that returns information about your application (name, description, icon) to be displayed in the user's wallet.
`config.chainInfo`	`ChainInfo` \| `Function`	An object or function specifying the blockchain that the application is connected to.
`config.delegator`	`WalletObject` \| `Function`	(Optional) For delegated connect, this is the wallet of the party authorizing `config.wallet` to act on its behalf.
`config.delegation`	`string` \| `Function`	(Optional) For delegated connect, the JWT that proves the delegation relationship.
`config.timeout`	`Number`	(Optional) Timeout in milliseconds for generating claims. Defaults to `8000`.
`config.baseUrl`	`string`	(Optional) The base URL for assembling wallet request URIs. Can often be inferred from the request object.
`config.tokenKey`	`string`	(Optional) The query parameter key for the session token. Defaults to `'_t_'`.

Parameter	Type	Description
`params.baseUrl`	`string`	The base URL, often inferred from the incoming request.
`params.pathname`	`string`	The callback path for the wallet.
`params.token`	`string`	The unique session token for this authentication action.
`params.query`	`object`	(Optional) Any additional query parameters to persist in the callback URL.

Parameter	Type	Description
`params.claims`	`object`	The information required from the user, such as profile, signature, etc. See the Claims Reference for details.
`params.pathname`	`string`	The pathname to assemble the callback URL.
`params.baseUrl`	`string`	The base URL of the application.
`params.challenge`	`string`	A random challenge string to prevent replay attacks.
`params.context`	`object`	Contextual information about the request, such as the `token`, `userDid`, `userPk`, etc.

Parameter	Type	Default	Description
`data`	`object`		The response object from the wallet, containing `userPk` and `userInfo` (the JWT).
`locale`	`string`	`'en'`	The locale for error messages.
`enforceTimestamp`	`boolean`	`true`	Whether to validate the timestamp in the JWT to prevent expired tokens.

Parameter	Type	Description
`params.response`	`object`	(Optional) A JSON object to be returned to the wallet.
`params.errorMessage`	`string`	(Optional) An error message to display in the wallet.
`params.successMessage`	`string`	(Optional) A success message to display in the wallet.
`params.nextWorkflow`	`string`	(Optional) A URL to instruct the wallet to start the next step in a chained workflow. See Chaining Workflows.
`params.nextUrl`	`string`	(Optional) A URL for the wallet to open in its built-in webview.
`params.cookies`	`object`	(Optional) Key-value pairs to be set as cookies before opening `nextUrl`.
`params.storages`	`object`	(Optional) Key-value pairs to be set as `localStorage` before opening `nextUrl`.

Overview

Getting Started

Guides

Claims Reference

API Reference

Examples

WalletAuthenticator

Core Workflow with WalletAuthenticator#

Constructor#

new WalletAuthenticator(config)#

Methods#

uri(params)#

sign(params)#

verify(data, [locale], [enforceTimestamp])#

signResponse(params)#

getPublicUrl(pathname, [params], [baseUrl])#

getAppInfo(params, [key])#

getChainInfo(params, [info])#

getWalletInfo(params)#

getDelegator(params)#

getDelegation(params)#

Type Definitions#

ApplicationInfo#

ChainInfo#

API Reference

WalletHandlers

Parameter	Type	Description
`pathname`	`string`	The URL path.
`params`	`object`	(Optional) Query parameters to stringify.
`baseUrl`	`string`	(Optional) The base URL. Defaults to the one set in the constructor.

Parameter	Type	Default	Description
`params`	`object`		Contains the context of this request.
`key`	`string`	`'appInfo'`	Either `'appInfo'` or `'memberAppInfo'`.

Property	Type	Description
`name`	`string`	Application name.
`description`	`string`	A brief description of your application.
`icon`	`string`	A URL to your application's logo/icon.
`link`	`string`	(Optional) The home page URL of your application.
`path`	`string`	(Optional) The deep link URL scheme. Defaults to `https://abtwallet.io/i/`.
`publisher`	`string`	(Optional) The `did:abt:` formatted DID of the application publisher.

Property	Type	Description
`id`	`string`	The chain ID. For ArcBlock chains, this is a string like `'beta'` or `'main'`. For EVM chains, it's the numeric chain ID.
`type`	`string`	The chain type, e.g., `'arcblock'`, `'ethereum'`. Defaults to `'arcblock'`.
`host`	`string`	The GraphQL endpoint of the chain's node, or an RPC endpoint for EVM chains.