Used to check for browser translation.
用于检测浏览器翻译。
ブラウザの翻訳を検出する
Core Concepts

WalletAuthenticator

The WalletAuthenticator class is a central component in the DID Connect SDK. It acts as the core logic on your application's backend, responsible for creating, formatting, and cryptographically signing all data sent to a user's DID Wallet. This signature allows the user's wallet to verify that it is interacting with your legitimate application, building a foundation of trust for the session.

While you can use WalletAuthenticator directly, it's most commonly used in tandem with its counterpart, the WalletHandlers, which manages the API endpoints for the DID Connect flow.

Role in the Authentication Flow#

The WalletAuthenticator is involved at two critical stages of the DID Connect lifecycle: initiating the request and verifying the response.

  1. Request Initiation: When a user wants to log in, your application uses the WalletAuthenticator to generate a signed message containing your app's information (appInfo), any requested data (claims), and the callback URL. This signed data is typically presented as a QR code.
  2. Response Verification: After the user scans the QR code and approves the request in their wallet, the wallet sends a signed response back to your application. The WalletAuthenticator then verifies the signature on this incoming response to confirm it genuinely came from the user.

The following diagram illustrates this interaction:

DID WalletApplication BackendApplication FrontendUserDID WalletApplication BackendApplication FrontendUserClicks "Connect Wallet"Request QR Code for loginInstantiate WalletAuthenticatorCall authenticator.sign() to create auth requestSend signed JWT payloadGenerate QR Code from payloadScan QR CodeVerify Application's SignatureDisplay App Info and requested claimsApprove RequestPOST signed response (user DID, claims)Call authenticator.verify() with responseVerification successfulSignal successful loginUser is logged in

Configuration#

To use WalletAuthenticator, you first need to create an instance with your application's configuration. This includes defining your application's identity (its wallet and descriptive info) and the blockchain context for any on-chain requests.

const { WalletAuthenticator } = require('@did-connect/sdk');
const { fromRandom } = require('@ocap/wallet');

// Your application needs its own wallet to sign requests.
// It's recommended to create one and store it securely.
const appWallet = fromRandom().toJSON();

const auth = new WalletAuthenticator({
wallet: appWallet,
appInfo: {
name: 'DID Connect Demo',
description: 'A demo application to show the potential of DID Wallet',
icon: 'https://arcblock.oss-cn-beijing.aliyuncs.com/images/wallet-round.png',
link: 'https://demo.didconnect.io' // A link for the user to return to your app from the wallet
},
chainInfo: {
host: 'https://beta.abtnetwork.io/api',
id: 'beta',
},
});

Constructor Parameters#

The constructor accepts a configuration object with the following key parameters:

Parameter

Type

Description

wallet

WalletObject or Function

Required. The application's wallet object or a function that returns one. This wallet is used to sign all requests sent to the user's wallet, proving the application's identity. It must contain a secret key.

appInfo

object or Function

Required. An object or function providing details about your application (name, description, icon) that will be displayed to the user in their wallet. See Configuration Objects for details.

chainInfo

object or Function

Optional. An object or function specifying the blockchain details (id, host) if you plan to request on-chain operations like transaction signing. See Configuration Objects for details.

delegator

WalletObject or Function

Optional. The wallet of the principal party when implementing delegated authentication. See the Delegated Connect Guide.

delegation

string or Function

Optional. The JWT proving the delegation relationship, used in conjunction with delegator.

timeout

Number

Optional. Timeout in milliseconds for asynchronous operations within the authenticator. Defaults to 8000.

Next Steps#

Now that you understand the role and configuration of WalletAuthenticator, you can proceed to:

  • Learn about its counterpart, WalletHandlers, which uses the authenticator to create the necessary API endpoints.
  • Dive into the detailed WalletAuthenticator API Reference for a full list of methods and advanced options.
  • Explore Claims to understand the different types of information and actions you can request from a user.
previous
Core Concepts
next
WalletHandlers