跳到主要內容

核心概念

本節介紹 @ocap/wallet 套件背後的基本概念。您將學習什麼是 Wallet 物件、其結構、建立它的不同方式，以及它與去中心化身分（DID）的關鍵關係。

Wallet 物件不僅僅是金鑰對的容器；它是一個功能強大、自成一體的實用工具，用於執行與 DID 相關的所有必要密碼學操作。它封裝了金鑰、DID 類型資訊，以及根據其類型定義的規則對資料進行簽署、驗證和雜湊處理的方法。

Wallet 物件

The WalletObject 是此函式庫的核心部分。它包含管理數位身分所需的所有資訊和功能。每個錢包都由以下關鍵屬性組成：

  • type DIDType (required) — 定義錢包的密碼學演算法和編碼格式的物件。
  • secretKey string | Buffer — 私鑰。這是簽署操作所必需的。請妥善保管，確保安全。
  • publicKey string | Buffer (required) — 公鑰，由私鑰衍生而來。用於驗證簽署。
  • address string (required) — 與錢包關聯的去中心化身分（DID）字串，由公鑰衍生而來。

了解錢包類型

錢包的行為完全由其 type 決定，這是一個來自 @arcblock/did 套件的 DIDType 物件。此類型物件指定了要使用的密碼學演算法和格式。

一個 DIDType 由四個主要部分組成：

屬性說明
role定義 DID 的用途（例如，帳戶、應用程式、節點）。
pk要使用的公鑰演算法（例如，ED25519、ETHEREUM）。
hash要使用的雜湊演算法（例如，SHA3、KECCAK）。
address最終 DID 字串的編碼格式（例如，BASE58、BASE16）。

此函式庫為常見的設定提供了方便的快捷方式，例如 'default'（用於 ArcBlock DID）和 'ethereum'。

您還可以為特定使用案例定義自訂錢包類型，例如建立應用程式 DID：

Wallet Type Configuration

javascript
const { WalletType } = require('@ocap/wallet');
const { types } = require('@ocap/mcrypto');

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

// 現在您可以使用此類型來建立新錢包
// const wallet = fromRandom(appWalletType);

建立錢包

您可以根據您擁有的資訊，透過多種方式實例化錢包。下圖說明了一般流程：

Core Concepts

以下是主要的工廠函式：

fromRandom

這是建立一個全新錢包最簡單的方法。它會產生一個新的隨機私鑰，並衍生出對應的公鑰和位址。

javascript
const { fromRandom } = require('@ocap/wallet');

// 使用預設的 ArcBlock 類型建立一個新錢包
const wallet = fromRandom();

console.log('New Wallet Address:', wallet.address);
console.log('Secret Key:', wallet.secretKey);

fromSecretKey

當您已經擁有私鑰時，請使用此函式來還原錢包。這是載入現有身分最常見的方式。

javascript
const { fromSecretKey } = require('@ocap/wallet');

const sk = '0xD67C071...'; // 您現有的私鑰
const wallet = fromSecretKey(sk);

console.log('Restored Wallet Address:', wallet.address);

fromPublicKey

如果您只有公鑰，可以建立一個「唯讀」錢包。此錢包可用於驗證簽署和衍生位址，但由於缺少私鑰，無法用於簽署訊息。

javascript
const { fromPublicKey } = require('@ocap/wallet');

const pk = '0xE4852B7...'; // 一個現有的公鑰
const wallet = fromPublicKey(pk);

console.log('Address from PK:', wallet.address);
// wallet.sign('message'); // 這將會拋出錯誤

fromAddress

僅從 DID 位址建立錢包對於解析嵌入在位址字串中的類型資訊很有用。這種類型的錢包功能非常有限，無法簽署或驗證資料。

javascript
const { fromAddress } = require('@ocap/wallet');

const did = 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr';
const wallet = fromAddress(did);

// 您可以檢查從位址衍生的類型資訊
console.log('Wallet Type:', wallet.type);

fromJSON

此函式允許您從先前使用 wallet.toJSON() 方法建立的序列化 JSON 物件中重建錢包。這對於儲存和擷取錢包非常理想。

javascript
const { fromRandom, fromJSON } = require('@ocap/wallet');

// 1. 建立一個錢包並將其序列化
const originalWallet = fromRandom();
const serialized = originalWallet.toJSON();

// 2. 之後，從 JSON 物件中還原它
const restoredWallet = fromJSON(serialized);

console.log('Restored successfully:', originalWallet.address === restoredWallet.address);

與 DID 的關係

Wallet 物件與去中心化身分（DID）有著內在的聯繫：

  • A Wallet 是 DID 的控制者。錢包內的私鑰是所有權的證明，授予持有者代表 DID 執行操作的能力。
  • wallet.address 就是 DID。它是可以與他人共享的公開識別碼。
  • wallet.type 定義了 DID 的屬性。它決定了 DID 的建構方式以及其在密碼學上的行為方式。

本質上，@ocap/wallet 函式庫提供了實用工具來建立、管理和利用由 @arcblock/did 規範所定義的身分。

了解了這些核心概念後，您現在可以探索 API 參考 以獲取所有可用方法及其參數的詳細資訊。