API 參考 | ArcBlock

本節提供 Wallet 物件及其工廠函數的詳細文件。您將找到每個函數的說明、其參數、返回值，以及用於建立錢包、簽署訊息和驗證簽章等常見操作的實用程式碼範例。

工廠函數

這些函數是建立 Wallet 執行個體的主要方式。每個函數都有特定的用途，無論您是從頭開始、從現有金鑰還是從 DID 位址建立新錢包。

fromSecretKey()

從私鑰建立一個完整的錢包執行個體。以此方式建立的錢包可用於簽署和驗證。

參數

sk string | Buffer | Uint8Array (required) — 私鑰，通常為十六進位格式。
_type DIDTypeArg (default: 'default') — DID 類型組態。可以是一個預定義的字串，如 'default' 或 'eth'，或一個自訂類型物件。更多詳情請參閱 @arcblock/did 文件。

返回值

wallet WalletObject — 一個能夠簽署和驗證的新錢包物件。

範例

Signing and Verifying a Message

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

// 十六進位格式的私鑰
const sk = '0xD67C071B6F51D2B61180B9B1AA9BE0DD0704619F0E30453AB4A592B036EDE644E4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7';

// 使用預設 DID 類型建立錢包
const wallet = fromSecretKey(sk);

const message = 'data to sign';
const signature = wallet.sign(message);

console.log('Generated Signature:', signature);

const isValid = wallet.verify(message, signature);
assert.ok(isValid, "Signature should be verified successfully.");
console.log('Verification successful!');

fromPublicKey()

從公鑰建立一個錢包執行個體。這種類型的錢包只能用於驗證簽章，不能用於簽署訊息，因為它缺少私鑰。

參數

pk string | Buffer | Uint8Array (required) — 公鑰，通常為十六進位格式。
_type DIDTypeArg (default: 'default') — DID 類型組態。決定與金鑰相關的雜湊和簽署演算法。

返回值

wallet WalletObject — 一個能夠驗證簽章的新錢包物件。

範例

Verifying a known signature

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

const pk = '0xE4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7';
const message = 'data to sign';
const knownSignature = '0x8122c608f61b04f6b574f005dc8e0463d393a7fb50e0426bca587b20778a8a9f6376bab87bc3983b0a5f1c9581f6d94162317c715a3c1c0f086be1e514399109';

const wallet = fromPublicKey(pk);

// 這個錢包可以驗證簽章
const isValid = wallet.verify(message, knownSignature);
assert.ok(isValid, "Signature should be verified.");

// 這將會拋出一個錯誤，因為沒有私鑰
try {
  wallet.sign(message);
} catch (e) {
  console.error(e.message); // 沒有私鑰無法簽署資料
}

fromAddress()

從 DID 位址建立一個最小的錢包執行個體。由於公鑰和私鑰是未知的，此錢包不能用於簽署或驗證。其主要用途是檢查編碼在位址中的 DID 類型資訊。

參數

address string (required) — 一個有效的 DID 位址（例如：'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr'）。

返回值

wallet WalletObject — 一個包含位址和派生類型資訊的新錢包物件。

範例

Inspecting a DID Address

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

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

console.log('Wallet Address:', wallet.address);
console.log('Role Type:', wallet.type.role); // 2 (ROLE_APPLICATION)
console.log('PK Type:', wallet.type.pk);     // 1 (ED25519)
console.log('Hash Type:', wallet.type.hash);   // 2 (SHA3)

fromRandom()

產生一個帶有隨機建立金鑰對的新錢包。這是建立新身份的標準方式。

參數

_type DIDTypeArg (default: 'default') — 新錢包的 DID 類型。使用 'eth' 來產生一個與以太坊相容的錢包。

返回值

wallet WalletObject — 一個帶有隨機產生的金鑰對的新錢包物件。

範例

Creating a new standard and an Ethereum wallet

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

// 建立一個標準錢包（base58 位址）
const standardWallet = fromRandom();
console.log('Standard DID Address:', standardWallet.address);
console.log('Secret Key:', standardWallet.secretKey);

// 建立一個與以太坊相容的錢包（base16 位址）
const ethWallet = fromRandom('eth');
console.log('Ethereum Address:', ethWallet.address);
console.log('Secret Key:', ethWallet.secretKey);

fromJSON()

從一個序列化的 JSON 物件重建一個錢包執行個體，通常是由 wallet.toJSON() 方法建立的物件。

參數

json SerializedWallet (required) — 一個序列化的錢包物件。
- type string (required) — DID 類型字串。
- pk string (required) — 十六進位格式的公鑰。
- sk string (required) — 十六進位格式的私鑰。
- address string (required) — DID 位址。

返回值

wallet WalletObject — 從 JSON 資料還原的錢包物件。

範例

Serializing and Deserializing a Wallet

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

const originalWallet = fromRandom();

// 將錢包序列化為 JSON 物件
const walletJSON = originalWallet.toJSON();
console.log('Serialized Wallet:', walletJSON);

// 從 JSON 物件還原錢包
const restoredWallet = fromJSON(walletJSON);

assert.equal(originalWallet.address, restoredWallet.address, 'Addresses should match');
assert.equal(originalWallet.secretKey, restoredWallet.secretKey, 'Secret keys should match');

console.log('Wallet restored successfully!');

isValid()

檢查給定物件是否為有效的 WalletObject。這對於類型保護和確保錢包具有必要的屬性和方法很有用。

參數

wallet any (required) — 要檢查的物件。
canSign boolean (default: true) — 若為 true，該函數還會檢查是否存在私鑰和 sign 方法。

返回值

isValid boolean — 如果物件是有效的錢包，則返回 true，否則返回 false。

範例

Validating Wallet Objects

const { fromRandom, fromPublicKey, isValid } = require('@ocap/wallet');

const signingWallet = fromRandom();
const verifyingWallet = fromPublicKey(signingWallet.publicKey);

// 一個完整的錢包可用於簽署
console.log('Is signing wallet valid for signing?', isValid(signingWallet)); // true

// 從公鑰建立的錢包不可用於簽署
console.log('Is verifying wallet valid for signing?', isValid(verifyingWallet)); // false

// 但如果我們不要求簽署功能，它就是有效的
console.log('Is verifying wallet valid for verification?', isValid(verifyingWallet, false)); // true

// 空物件不是有效的錢包
console.log('Is empty object a valid wallet?', isValid({})); // false

錢包物件

WalletObject 是由工廠函數返回的核心實體。它包含加密金鑰、DID 位址以及執行加密操作的方法。

屬性

address string — 從公鑰和類型資訊派生的 DID 位址。
publicKey BytesType — 公鑰。格式（例如，十六進位字串、Buffer）取決於錢包的建立方式。
secretKey BytesType — 私鑰。對於從公鑰或位址建立的錢包，此項為 undefined。
type DIDType — 一個包含 DID 類型資訊（角色、公鑰、雜湊、位址編碼）的物件。

方法

.sign()

使用錢包的私鑰簽署一段資料。

參數

data BytesType (required) — 要簽署的資料。
hashBeforeSign boolean (default: true) — 若為 true，資料在簽署前會使用錢包的雜湊演算法進行雜湊處理。
encoding string (default: 'hex') — 簽章的輸出編碼（'hex'、'base64'、'base58'、'buffer' 等）。

返回值

signature BytesType — 以指定編碼產生的簽章。

.verify()

使用錢包的公鑰驗證一段資料的簽章。

參數

data BytesType (required) — 被簽署的原始資料。
signature BytesType (required) — 要驗證的簽章。
hashBeforeVerify boolean (default: true) — 若為 true，資料在驗證前會進行雜湊處理，以匹配簽署過程。

返回值

isValid Promise<boolean> — 一個 promise，如果簽章有效，則解析為 true，否則解析為 false。

.hash()

使用錢包設定的雜湊演算法對資料進行雜湊處理。

參數

data BytesType (required) — 要進行雜湊處理的資料。
round number (default: 1) — 雜湊處理的輪數。
encoding string (default: 'hex') — 雜湊值的輸出編碼。

返回值

hash BytesType — 以指定編碼產生的雜湊結果。

.ethSign()

使用以太坊特定的簽署演算法（eth_sign 行為）簽署訊息。僅適用於類型為 'eth' 的錢包。

參數

data string (required) — 要簽署的資料。
hashBeforeSign boolean (default: true) — 若為 true，資料會先使用以太坊特定的 ethHash 方法進行雜湊處理。

返回值

signature string — 產生的以太坊簽章。

.ethVerify()

從以太坊簽章中恢復簽署者的位址，並與錢包的位址進行比較。僅適用於類型為 'eth' 的錢包。

參數

data string (required) — 被簽署的原始資料。
signature string (required) — 以太坊簽章。
hashBeforeVerify boolean (default: true) — 若為 true，資料在驗證前會使用 ethHash 進行雜湊處理。

返回值

isValid boolean — 如果恢復的位址與錢包的位址匹配，則返回 true，否則返回 false。

.toJSON()

將錢包的狀態序列化為一個純 JSON 物件。這對於儲存或傳輸錢包資料很有用。

返回值

serialized SerializedWallet — 一個包含錢包類型、金鑰和位址的 JSON 物件。