API Reference | ArcBlock

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.