跳到主要內容

API 參考文件

本節為 @arcblock/did 函式庫中所有公開函式和型別提供了全面的 API 參考。它包含了可用於建立、驗證和檢視去中心化身分（DID）等常見任務的實用、可直接複製貼上的程式碼片段。

DID 建立

這些函式用於從各種加密輸入（如私鑰、公鑰或雜湊值）產生 DID。

fromSecretKey

從私鑰和指定的 DID 型別設定產生 DID。

參數

  • sk BytesType (required) — 十六進位編碼的私鑰字串。
  • type DIDTypeArg — DID 型別設定。可以是一個捷徑字串（例如，'arcblock'、'eth'）或一個型別物件。預設為標準的 ArcBlock DID 型別。

回傳值

  • did string — 產生的 DID 字串。

範例

Create an Application 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 字串。

範例

Create an Ethereum-style 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 DID (Base58)
console.log(isValid('zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr')); // true
console.log(isValid('did:abt:z1nfCgfPqvSQCaZ2EVZPXbwPjKCkMrqfTUu')); // true

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

// 以太坊 DID
console.log(isValid('0x9d8A62f656a8d1615C1294fd71e9CFb3E4855A4F')); // true

// 無效的 DID
console.log(isValid('abc')); // false
console.log(isValid('z1muQ3xqHQK2uiACHyChikobsiY5kLqtSha')); // false (校驗和錯誤)

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';

// 使用捷徑
const ethType = DidType('eth');
console.log(ethType);
// { role: 1, pk: 2, hash: 2, address: 1 }

// 使用部分型別物件
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 型別和前置詞的預定義常數。

常數說明
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 的型別，代表二進位資料。