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('生成的签名:', signature);

const isValid = wallet.verify(message, signature);
assert.ok(isValid, "签名应成功验证。");
console.log('验证成功！');

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, "签名应被验证。");

// 这将抛出一个错误，因为没有私钥
try {
  wallet.sign(message);
} catch (e) {
  console.error(e.message); // 没有 secretKey 无法签名数据
}

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);
console.log('角色类型:', wallet.type.role); // 2 (ROLE_APPLICATION)
console.log('公钥类型:', wallet.type.pk);     // 1 (ED25519)
console.log('哈希类型:', 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('标准 DID 地址:', standardWallet.address);
console.log('私钥:', standardWallet.secretKey);

// 创建一个与以太坊兼容的钱包（base16 地址）
const ethWallet = fromRandom('eth');
console.log('以太坊地址:', ethWallet.address);
console.log('私钥:', 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('序列化的钱包:', walletJSON);

// 从 JSON 对象恢复钱包
const restoredWallet = fromJSON(walletJSON);

assert.equal(originalWallet.address, restoredWallet.address, '地址应该匹配');
assert.equal(originalWallet.secretKey, restoredWallet.secretKey, '私钥应该匹配');

console.log('钱包已成功恢复！');

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('签名钱包是否可用于签名？', isValid(signingWallet)); // true

// 来自公钥的钱包不可用于签名
console.log('验证钱包是否可用于签名？', isValid(verifyingWallet)); // false

// 但如果我们不要求签名功能，它是有效的
console.log('验证钱包是否可用于验证？', isValid(verifyingWallet, false)); // true

// 空对象不是有效的钱包
console.log('空对象是有效钱包吗？', isValid({})); // false

Wallet 对象

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 对象。