API Reference

This section provides a comprehensive API reference for all public functions and types within the @arcblock/did library. It includes practical, copy-paste-ready code snippets for common tasks like creating, validating, and inspecting Decentralized Identities (DIDs).

DID Creation#

These functions are used to generate DIDs from various cryptographic inputs like secret keys, public keys, or hashes.

fromSecretKey#

Generates a DID from a secret key and a specified DID type configuration.

Parameters

sk
BytesType
required
The hex-encoded secret key string.
type
DIDTypeArg

The DID type configuration. Can be a shortcut string (e.g., 'arcblock', 'eth') or a type object. Defaults to the standard ArcBlock DID type.

Returns

did
string
The generated DID string.

Example

Create an Application DID

import { fromSecretKey, types } from '@arcblock/did';

const sk = '0xD67C071B6F51D2B61180B9B1AA9BE0DD0704619F0E30453AB4A592B036EDE644E4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7';

const appType = {
  role: types.RoleType.ROLE_APPLICATION,
  pk: types.KeyType.ED25519,
  hash: types.HashType.SHA3,
};

const did = fromSecretKey(sk, appType);
console.log(did); // zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr

fromPublicKey#

Generates a DID from a public key and a specified DID type configuration.

Parameters

pk
BytesType
required
The hex-encoded public key string.
type
DIDTypeArg
The DID type configuration. Defaults to the standard ArcBlock DID type.

Returns

did
string
The generated DID string.

Example

Create an Ethereum-style DID

import { fromPublicKey } from '@arcblock/did';

const pk = '0x4bc2a31265153f07e70e0bab08724e6b85e217f8cd628ceb62974247bb493382ce28cab79ad7119ee1ad3ebcdb98a16805211530ecc6cfefa1b88e6dff99232a';

const ethDid = fromPublicKey(pk, 'eth');
console.log(ethDid); // 0x9d8A62f656a8d1615C1294fd71e9CFb3E4855A4F

fromPublicKeyHash#

Generates a DID from a public key hash and a specified DID type. The output format (Base58 or Base16) depends on the encoding type specified in the DID type.

Parameters

buffer
string
required
The hex-encoded public key hash.
type
DIDTypeArg
required
The DID type configuration.

Returns

did
string
The generated DID string.

Example

import { fromPublicKeyHash, types, DidType } from '@arcblock/did';
import { Hasher } from '@ocap/mcrypto';

const pk = '0xFF47B3022FA503EAA1E9FA4B20FA8B16694EA56096F3A2E9109714062B3486D9';
const pkHash = Hasher.SHA3.hash256(pk);
const nodeType = DidType({ role: types.RoleType.ROLE_NODE });

const did = fromPublicKeyHash(pkHash, nodeType);
console.log(did); // z89nF4GRYvgw5mqk8NqVVC7NeZLWKbcbQY7V

fromHash#

Generates a DID from a generic hex-encoded hash and a role type.

Parameters

hash
string
required
The hex-encoded hash.
role
number
default:ROLE_ACCOUNT

The role type from mcrypto.types.RoleType. Defaults to ROLE_ACCOUNT.

Returns

did
string
The generated DID string.

Example

import { fromHash, types } from '@arcblock/did';
import { Hasher } from '@ocap/mcrypto';

const pk = '0xE4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7';
const pkHash = Hasher.SHA3.hash256(pk);

const did = fromHash(pkHash, types.RoleType.ROLE_APPLICATION);
console.log(did); // zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr

DID Validation#

These functions help verify the integrity of a DID and its relationship to a public key.

isValid#

Checks if a DID string is valid by verifying its format and checksum.

Parameters

did
string
required
The DID string to validate.

Returns

isValid
boolean
Returns `true` if the DID is valid, `false` otherwise.

Example

import { isValid } from '@arcblock/did';

// ArcBlock DIDs (Base58)
console.log(isValid('zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr')); // true
console.log(isValid('did:abt:z1nfCgfPqvSQCaZ2EVZPXbwPjKCkMrqfTUu')); // true

// ArcBlock DIDs (Base16)
console.log(isValid('0x0021e4b8f62674897ed75df0f7356e82c6f9a64a5c13f3cc0cd3')); // true

// Ethereum DIDs
console.log(isValid('0x9d8A62f656a8d1615C1294fd71e9CFb3E4855A4F')); // true

// Invalid DIDs
console.log(isValid('abc')); // false
console.log(isValid('z1muQ3xqHQK2uiACHyChikobsiY5kLqtSha')); // false (bad checksum)

isFromPublicKey#

Checks if a given DID was generated from a specific public key.

Parameters

did
string
required
The DID string.
pk
BytesType
required
The hex-encoded public key to check against.

Returns

isMatch
boolean
Returns `true` if the DID corresponds to the public key, `false` otherwise.

Example

import { isFromPublicKey } from '@arcblock/did';

const pk = '0xE4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7';
const did = 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr';

console.log(isFromPublicKey(did, pk)); // true
console.log(isFromPublicKey('abc', pk)); // false

Type Utilities#

Functions for creating, parsing, and converting DID type information.

DidType#

Creates a standardized DID Type object from a shortcut string or a partial type definition. It automatically fills in any missing properties with defaults for an ArcBlock DID.

Parameters

type
DIDTypeArg
A shortcut string ('arcblock', 'eth', 'passkey') or a partial DIDType object.

Returns

didType
DIDType
A complete DIDType object.

Example

import { DidType, types } from '@arcblock/did';

// Using a shortcut
const ethType = DidType('eth');
console.log(ethType);
// { role: 1, pk: 2, hash: 2, address: 1 }

// Using a partial type object
const nodeType = DidType({ role: types.RoleType.ROLE_NODE });
console.log(nodeType);
// { role: 3, pk: 1, hash: 4, address: 0 }

toTypeInfo#

Extracts the DID type information (role, key type, hash algorithm, etc.) from a DID string.

Parameters

did
string
required
The DID string.

Returns

didType
DIDType
A DIDType object containing the numeric type codes.

Example

import { toTypeInfo } from '@arcblock/did';

const did = 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr';
const typeInfo = toTypeInfo(did);

console.log(typeInfo);
// { role: 12, pk: 1, hash: 1, address: 0 }

toTypeInfoStr#

Extracts the DID type information from a DID string and returns it in a human-readable string format.

Parameters

did
string
required
The DID string.

Returns

didTypeStr
DIDTypeStr
A `DIDTypeStr` object with string representations of the types.

Example

import { toTypeInfoStr } from '@arcblock/did';

const did = 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr';
const typeInfo = toTypeInfoStr(did);

console.log(typeInfo);
// { role: 'ROLE_APPLICATION', pk: 'ED25519', hash: 'SHA3', address: 'BASE58' }

fromTypeInfo#

Converts a DID Type object into its compact 2-byte hex string representation.

Parameters

type
DIDTypeArg
required
A DID Type object or shortcut.

Returns

hex
string
The 4-character hex string representing the type.

Example

import { fromTypeInfo, types } from '@arcblock/did';

const appType = {
  role: types.RoleType.ROLE_APPLICATION,
  pk: types.KeyType.ED25519,
  hash: types.HashType.SHA3,
  address: types.EncodingType.BASE58,
};

const typeHex = fromTypeInfo(appType);
console.log(typeHex); // 0c01

isEthereumDid#

Checks if a string is a valid Ethereum address, including checksum validation.

Parameters

did
string
required
The string to check.

Returns

isEth
boolean
Returns `true` if it's a valid Ethereum DID.

toChecksumAddress#

Converts an Ethereum address to its checksummed format.

Parameters

address
string
required
The Ethereum address.

Returns

checksummedAddress
string
The checksummed address.

Formatting Utilities#

Helper functions to add or remove the standard DID prefix.

toDid#

Ensures a DID string is prefixed with did:abt:.

Parameters

address
string
required
A raw DID address.

Returns

did
string
The fully qualified DID string.

Example

import { toDid } from '@arcblock/did';

const address = 'z1muQ3xqHQK2uiACHyChikobsiY5kLqtShA';
console.log(toDid(address)); // did:abt:z1muQ3xqHQK2uiACHyChikobsiY5kLqtShA

toAddress#

Removes the did:abt: prefix from a DID string, returning the raw address.

Parameters

did
string
required
A fully qualified DID string.

Returns

address
string
The raw DID address.

Example

import { toAddress } from '@arcblock/did';

const did = 'did:abt:z1muQ3xqHQK2uiACHyChikobsiY5kLqtShA';
console.log(toAddress(did)); // z1muQ3xqHQK2uiACHyChikobsiY5kLqtShA

Constants#

Predefined constants for DID types and prefixes.

Constant

Description

DID_PREFIX

The standard string prefix for ArcBlock DIDs: "did:abt:".

DID_TYPE_ARCBLOCK

A DIDType object representing the default ArcBlock DID configuration.

DID_TYPE_ETHEREUM

A DIDType object for Ethereum-compatible DIDs.

DID_TYPE_PASSKEY

A DIDType object for DIDs derived from passkeys.

Types#

Key TypeScript type definitions used throughout the library.

DIDType
object

An object that defines the cryptographic properties of a DID. It includes role, pk (key type), hash (hash algorithm), and address (encoding type).

DIDTypeStr
object

Similar to DIDType, but the property values are human-readable strings instead of numeric codes.

DIDTypeArg
DIDTypeShortcut | DIDType

A union type that can be either a shortcut string or a DIDType object, used as an argument in many functions.

DIDTypeShortcut
string

A literal string type for predefined DID configurations: 'default', 'arcblock', 'eth', 'ethereum', or 'passkey'.

BytesType
string | Buffer

A type that can be either a hex-encoded string or a Buffer, representing binary data.

Core Concepts
@ocap/wallet