API Reference

DID & Wallet Utilities

This section provides an overview of functions designed to manage Decentralized Identifiers (DIDs) and cryptographic wallets within the Blocklet ecosystem. These utilities are essential for creating blocklet-specific identities, generating application wallets for transaction signing, and extracting DID-related information from user sessions.
toBlockletDid#Converts a string or Buffer into a valid Blocklet-specific DID. If the input is already a valid DID, it is returned as-is. Otherwise, it generates a DID of type ROLE_ANY from the public key derived from the input.
Syntax
const toBlockletDid = (name: string | Buffer): string => { ... }Parameters
Name
Type
Description
name
string | Buffer
A string or buffer to be converted into a Blocklet DID. Whitespace is trimmed if a string is provided.
Returns
string: A valid DID string.
Example
import toBlockletDid from '@blocklet/meta/lib/did';

// Create a DID from a simple name
const did1 = toBlockletDid('my-blocklet-name');
console.log(did1);

// Inputting a valid DID returns it directly
const existingDid = 'z8iZpkybU8DZt5bJ8sy6n3s2v1h2xY3Z4a5b6'; // Example DID
const did2 = toBlockletDid(existingDid);
console.log(did2 === existingDid); // truegetApplicationWallet#Generates a deterministic wallet object for a Blocklet. This wallet is used for signing application-level requests and transactions. The function can operate in two primary modes: deriving the wallet from the Blocklet's DID and the parent node's secret key, or generating it directly from a provided application-specific secret key.
This function supports different blockchain types, including standard ArcBlock wallets and Ethereum-compatible wallets.

Syntax
const getApplicationWallet = (didOrSk: string, nodeSk?: string, type?: DIDType | 'default' | 'eth' | 'ethereum', index?: number): WalletObject => { ... }Parameters
Name
Type
Description
didOrSk
string
The Blocklet's DID or a custom secret key.
nodeSk
string
Optional. The secret key of the parent ABT Node. Required if didOrSk is a DID.
type
DIDType | 'default' | 'eth' | 'ethereum'
Optional. The type of wallet to generate. Defaults to a standard ArcBlock wallet. Use 'eth' or 'ethereum' for an Ethereum-compatible wallet.
index
number
Optional. The derivation index, used when deriving from a DID and nodeSk. Defaults to 0.
Returns
WalletObject: A wallet object from @ocap/wallet containing keys, address, and signing methods.
Throws
Error: If didOrSk is an invalid DID and cannot be parsed as a secret key.
Error: If didOrSk is a valid DID but nodeSk is not provided.
Examples
Generate wallet from Blocklet DID and Node SKimport getApplicationWallet from '@blocklet/meta/lib/wallet';

const blockletDid = 'z...'; // A valid Blocklet DID
const nodeSk = '...'; // The node's secret key

const wallet = getApplicationWallet(blockletDid, nodeSk);
console.log('Wallet Address:', wallet.address);

Generate Ethereum wallet from a custom SKimport getApplicationWallet from '@blocklet/meta/lib/wallet';

const customAppSk = '0x...'; // A 66-char hex string for Ethereum

const ethWallet = getApplicationWallet(customAppSk, undefined, 'ethereum');
console.log('Ethereum Wallet Address:', ethWallet.address);

User Information Helpers#These are a collection of utility functions for parsing a UserInfo object, typically obtained after a user logs in, to extract specific DIDs and account details.
getPermanentDid(user: UserInfo)#Retrieves the user's primary, permanent DID.
Returns: string - The user's main DID.
getConnectedAccounts(user: UserInfo)#Retrieves the full list of accounts connected to the user's profile.
Returns: object[] - An array of connected account objects.
getConnectedDids(user: UserInfo)#Extracts a list of all DIDs from the user's connected accounts.
Returns: string[] - An array of DID strings.
getWallet(user: UserInfo)#Finds the DID Wallet account among the connected accounts.
Returns: object | undefined - The wallet account object or undefined if not found.
getWalletDid(user: UserInfo)#Retrieves the DID specifically associated with the user's DID Wallet.
Returns: string | undefined - The wallet's DID or undefined.
getSourceProvider(user: UserInfo)#Gets the provider the user originally used to log in for the current session.
Returns: string - The name of the source provider (e.g., LOGIN_PROVIDER.WALLET).
getSourceProviders(user: UserInfo)#Gets a list of all providers from the user's connected accounts.
Returns: string[] - An array of provider names.
Example Usage
import { getPermanentDid, getWalletDid } from '@blocklet/meta/lib/did-utils';

const userInfo = {
  did: 'z1...user_main_did',
  connectedAccounts: [
    { provider: 'wallet', did: 'z2...user_wallet_did' },
    { provider: 'github', did: 'z3...user_github_did' },
  ],
  // ... other user properties
};

const mainDid = getPermanentDid(userInfo);
const walletDid = getWalletDid(userInfo);

console.log('Main DID:', mainDid); // 'z1...user_main_did'
console.log('Wallet DID:', walletDid); // 'z2...user_wallet_did'getBlockletInfo#A comprehensive utility that parses the full BlockletState to extract metadata and generate wallets. While it returns extensive information, its wallet-generation capabilities are particularly relevant here. It uses getApplicationWallet internally and can create both a standard wallet and a permanent wallet based on environment variables.
Key Wallet-Related Return Properties
Property
Type
Description
wallet
WalletObject
The primary wallet for the Blocklet session.
permanentWallet
WalletObject
The permanent wallet, which can be different from the session wallet if BLOCKLET_APP_PSK is set. Defaults to the primary wallet.
secret
string
A session secret derived from the wallet's secret key, address, and a session salt. Useful for signing cookies or tokens.
Example
import getBlockletInfo from '@blocklet/meta/lib/info';

const blockletState = {
  meta: {
    did: 'z...blocklet_did'
  },
  environments: [
    // { key: 'BLOCKLET_APP_SK', value: '...' } // Optional custom SK
  ],
  settings: {
    session: {
      salt: 'some-random-salt'
    }
  }
  // ... other state properties
};

const nodeSk = '...'; // The node's secret key

try {
  const info = getBlockletInfo(blockletState, nodeSk);
  console.log('Blocklet DID:', info.did);
  console.log('Wallet Address:', info.wallet.address);
  console.log('Session Secret:', info.secret);
} catch (error) {
  console.error('Failed to get blocklet info:', error.message);
}This function centralizes the logic for deriving critical operational data, including cryptographic identities, from the blocklet's stateful context.

With an understanding of how to manage DIDs and wallets, you can proceed to the Security Utilities to learn how to use these wallets for signing and verifying data.

Name	Type	Description
`didOrSk`	`string`	The Blocklet's DID or a custom secret key.
`nodeSk`	`string`	Optional. The secret key of the parent ABT Node. Required if `didOrSk` is a DID.
`type`	`DIDType \| 'default' \| 'eth' \| 'ethereum'`	Optional. The type of wallet to generate. Defaults to a standard ArcBlock wallet. Use 'eth' or 'ethereum' for an Ethereum-compatible wallet.
`index`	`number`	Optional. The derivation index, used when deriving from a DID and nodeSk. Defaults to `0`.

Property	Type	Description
`wallet`	`WalletObject`	The primary wallet for the Blocklet session.
`permanentWallet`	`WalletObject`	The permanent wallet, which can be different from the session wallet if `BLOCKLET_APP_PSK` is set. Defaults to the primary wallet.
`secret`	`string`	A session secret derived from the wallet's secret key, address, and a session salt. Useful for signing cookies or tokens.

Overview

Getting Started

Blocklet Specification (blocklet.yml)

API Reference

DID & Wallet Utilities

toBlockletDid#

getApplicationWallet#

User Information Helpers#

`getPermanentDid(user: UserInfo)`#

`getConnectedAccounts(user: UserInfo)`#

`getConnectedDids(user: UserInfo)`#

`getWallet(user: UserInfo)`#

`getWalletDid(user: UserInfo)`#

`getSourceProvider(user: UserInfo)`#

`getSourceProviders(user: UserInfo)`#

getBlockletInfo#

Component & State Utilities

Security Utilities