跳到主要内容

API 参考

本节为 @arcblock/did 库中的所有公共函数和类型提供了全面的 API 参考。它包括用于创建、验证和检查去中心化身份（DID）等常见任务的实用、可直接复制粘贴的代码片段。

DID 创建

这些函数用于从各种加密输入（如私钥、公钥或哈希）生成 DID。

fromSecretKey

根据私钥和指定的 DID 类型配置生成 DID。

参数

  • sk BytesType (required) — 十六进制编码的私钥字符串。
  • type DIDTypeArg — DID 类型配置。可以是一个快捷字符串（例如，'arcblock'、'eth'）或一个类型对象。默认为标准的 ArcBlock DID 类型。

返回值

  • did string — 生成的 DID 字符串。

示例

创建一个应用 DID

javascript
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

根据公钥和指定的 DID 类型配置生成 DID。

参数

  • pk BytesType (required) — 十六进制编码的公钥字符串。
  • type DIDTypeArg — DID 类型配置。默认为标准的 ArcBlock DID 类型。

返回值

  • did string — 生成的 DID 字符串。

示例

创建一个以太坊风格的 DID

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

const pk = '0x4bc2a31265153f07e70e0bab08724e6b85e217f8cd628ceb62974247bb493382ce28cab79ad7119ee1ad3ebcdb98a16805211530ecc6cfefa1b88e6dff99232a';

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

fromPublicKeyHash

根据公钥哈希和指定的 DID 类型生成 DID。输出格式（Base58 或 Base16）取决于 DID 类型中指定的编码类型。

参数

  • buffer string (required) — 十六进制编码的公钥哈希。
  • type DIDTypeArg (required) — DID 类型配置。

返回值

  • did string — 生成的 DID 字符串。

示例

javascript
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

根据一个通用的十六进制编码哈希和角色类型生成 DID。

参数

  • hash string (required) — 十六进制编码的哈希。
  • role number (default: ROLE_ACCOUNT) — 来自 mcrypto.types.RoleType 的角色类型。默认为 ROLE_ACCOUNT。

返回值

  • did string — 生成的 DID 字符串。

示例

javascript
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 验证

这些函数有助于验证 DID 的完整性及其与公钥的关系。

isValid

通过验证其格式和校验和来检查 DID 字符串是否有效。

参数

  • did string (required) — 要验证的 DID 字符串。

返回值

  • isValid boolean — 如果 DID 有效，则返回 true，否则返回 false。

示例

javascript
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

检查给定的 DID 是否由特定的公钥生成。

参数

  • did string (required) — DID 字符串。
  • pk BytesType (required) — 用于检查的十六进制编码的公钥。

返回值

  • isMatch boolean — 如果 DID 与公钥对应，则返回 true，否则返回 false。

示例

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

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

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

类型工具

用于创建、解析和转换 DID 类型信息的函数。

DidType

从快捷字符串或部分类型定义创建一个标准化的 DID Type 对象。它会自动使用 ArcBlock DID 的默认值填充任何缺失的属性。

参数

  • type DIDTypeArg — 一个快捷字符串（'arcblock'、'eth'、'passkey'）或一个部分的 DIDType 对象。

返回值

  • didType DIDType — 一个完整的 DIDType 对象。

示例

javascript
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

从 DID 字符串中提取 DID 类型信息（角色、密钥类型、哈希算法等）。

参数

  • did string (required) — DID 字符串。

返回值

  • didType DIDType — 一个包含数字类型代码的 DIDType 对象。

示例

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

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

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

toTypeInfoStr

从 DID 字符串中提取 DID 类型信息，并以人类可读的字符串格式返回。

参数

  • did string (required) — DID 字符串。

返回值

  • didTypeStr DIDTypeStr — 一个包含类型字符串表示的 DIDTypeStr 对象。

示例

javascript
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

将 DID Type 对象转换为其紧凑的 2 字节十六进制字符串表示形式。

参数

  • type DIDTypeArg (required) — 一个 DID Type 对象或快捷方式。

返回值

  • hex string — 代表该类型的 4 字符十六进制字符串。

示例

javascript
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

检查字符串是否为有效的以太坊地址，包括校验和验证。

参数

  • did string (required) — 要检查的字符串。

返回值

  • isEth boolean — 如果它是有效的以太坊 DID，则返回 true。

toChecksumAddress

将以太坊地址转换为其带校验和的格式。

参数

  • address string (required) — 以太坊地址。

返回值

  • checksummedAddress string — 带校验和的地址。

格式化工具

用于添加或删除标准 DID 前缀的辅助函数。

toDid

确保 DID 字符串以 did:abt: 为前缀。

参数

  • address string (required) — 原始 DID 地址。

返回值

  • did string — 完全限定的 DID 字符串。

示例

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

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

toAddress

从 DID 字符串中移除 did:abt: 前缀，返回原始地址。

参数

  • did string (required) — 一个完全限定的 DID 字符串。

返回值

  • address string — 原始 DID 地址。

示例

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

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

常量

用于 DID 类型和前缀的预定义常量。

ConstantDescription
DID_PREFIXArcBlock DID 的标准字符串前缀："did:abt:"。
DID_TYPE_ARCBLOCK代表默认 ArcBlock DID 配置的 DIDType 对象。
DID_TYPE_ETHEREUM用于以太坊兼容 DID 的 DIDType 对象。
DID_TYPE_PASSKEY用于从 passkey 派生的 DID 的 DIDType 对象。

类型

整个库中使用的关键 TypeScript 类型定义。

  • DIDType object — 一个定义 DID 加密属性的对象。它包括 role、pk（密钥类型）、hash（哈希算法）和 address（编码类型）。
  • DIDTypeStr object — 与 DIDType 类似，但属性值是人类可读的字符串，而不是数字代码。
  • DIDTypeArg DIDTypeShortcut | DIDType — 一个联合类型，可以是一个快捷字符串或一个 DIDType 对象，在许多函数中用作参数。
  • DIDTypeShortcut string — 用于预定义 DID 配置的字面量字符串类型：'default'、'arcblock'、'eth'、'ethereum' 或 'passkey'。
  • BytesType string | Buffer — 一个可以是十六进制编码字符串或 Buffer 的类型，代表二进制数据。