跳到主要内容

核心概念

本节介绍 @ocap/wallet 包背后的基本概念。你将了解什么是钱包对象、其结构、创建它的不同方式，以及它与去中心化身份 (DID) 的关键关系。

钱包对象不仅仅是密钥对的容器；它是一个功能强大、自成一体的实用工具，用于执行与 DID 相关的所有必要加密操作。它封装了密钥、DID 类型信息以及根据其类型定义的规则对数据进行签名、验证和哈希的方法。

钱包对象

WalletObject 是该库的核心部分。它包含了管理数字身份所需的所有信息和功能。每个钱包都由以下关键属性组成：

  • type DIDType (required) — 一个定义钱包加密算法和编码格式的对象。
  • secretKey string | Buffer — 私钥。这是签名操作所必需的。请妥善保管，确保安全。
  • publicKey string | Buffer (required) — 公钥，从密钥派生。它用于验证签名。
  • address string (required) — 与钱包关联的去中心化身份标识符 (DID) 字符串，从公钥派生。

理解钱包类型

钱包的行为完全由其 type 决定，该 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('新钱包地址：', wallet.address);
console.log('密钥：', wallet.secretKey);

fromSecretKey

当你已有密钥时，使用此函数来恢复钱包。这是加载现有身份最常用的方法。

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

const sk = '0xD67C071...'; // 你已有的密钥
const wallet = fromSecretKey(sk);

console.log('恢复的钱包地址：', wallet.address);

fromPublicKey

如果你只有一个公钥，你可以创建一个“只读”钱包。这个钱包可以用来验证签名和派生地址，但因为它缺少密钥，所以不能用来签署消息。

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

const pk = '0xE4852B7...'; // 一个已有的公钥
const wallet = fromPublicKey(pk);

console.log('从 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);

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('成功恢复：', originalWallet.address === restoredWallet.address);

与 DID 的关系

钱包对象和去中心化身份 (DID) 有着内在的联系：

  • 钱包是 DID 的控制者。 钱包内的密钥是所有权的证明，授予持有者代表该 DID 执行操作的能力。
  • wallet.address 就是 DID。 它是可以与他人共享的公共标识符。
  • wallet.type 定义了 DID 的属性。 它决定了 DID 是如何构建的，以及它在密码学上应该如何表现。

从本质上讲，@ocap/wallet 库提供了创建、管理和使用由 @arcblock/did 规范定义的身份的实用工具。

了解了这些核心概念后，你现在可以浏览 API 参考 以获取有关所有可用方法及其参数的详细信息。