@mingchain/ming-did-core

铭识 (MingDID) 核心库 - 基于 BSV 区块链的去中心化身份标识系统

概述

铭识 (MingDID) 是铭链科技开发的去中心化身份标识 (DID) 系统，基于 BSV 区块链实现符合 W3C DID Core 规范的 DID 方法。

核心特性

• 🚀 完整的 DID 生命周期管理 - 创建、解析、更新、撤销
• 🔐 secp256k1 密钥管理 - 安全密钥生成、签名、验证
• ⛓️ BSV 原生集成 - OP_RETURN 存储、UTXO 链追踪
• 🤖 AI Agent 扩展 - 原生支持 AI Agent 身份和委托
• 📦 W3C 兼容 - 符合 DID Core 和 VC Data Model 规范

安装

npm install @mingchain/ming-did-core
# 或
yarn add @mingchain/ming-did-core
# 或
pnpm add @mingchain/ming-did-core

快速开始

初始化

import { MingDID, createMingDID } from '@mingchain/ming-did-core';

// 创建实例
const did = createMingDID({
  network: 'mainnet', // 或 'testnet'
  wocApiKey: 'your-api-key', // 可选
});

// 或使用构造函数
const did2 = new MingDID({
  network: 'testnet',
});

创建 DID

// 创建新 DID（自动生成密钥）
const createResult = await did.create({
  services: [
    {
      type: 'MessagingService',
      serviceEndpoint: 'https://api.example.com/messages',
    },
  ],
  agentProfile: {
    agentType: 'ai-agent',
    capabilities: ['email.send', 'file.read'],
    metadata: {
      name: 'MyAgent',
    },
  },
});

console.log('DID:', createResult.did);
// did:mingchain:e803b04af611b67074af7864e5ee520060265547f8b929f2494b3e05af190636

console.log('DID Document:', createResult.document);
console.log('Private Key:', createResult.privateKey); // 安全存储！
console.log('Transaction IDs:', createResult.transactionIds);

解析 DID

// 解析 DID 获取文档
const resolution = await did.resolve('did:mingchain:e803b04a...');

if (resolution.didDocument) {
  console.log('Document:', resolution.didDocument);
  console.log('Deactivated:', resolution.didDocumentMetadata.deactivated);
} else {
  console.log('Resolution Error:', resolution.resolutionMetadata.error);
}

更新 DID

// 更新 DID 文档
const updateResult = await did.update(
  'did:mingchain:e803b04a...',
  {
    addAgentProfile: {
      agentType: 'ai-agent',
      capabilities: ['task.execute', 'new.capability'],
    },
    updateServices: [
      // ... 新的服务列表
    ],
  },
  privateKey // 必须提供私钥签名
);

console.log('New Transaction:', updateResult.transactionId);

撤销 DID

// 撤销 DID
const revokeResult = await did.deactivate(
  'did:mingchain:e803b04a...',
  {
    privateKey,
    reason: 'User requested', // 可选
  }
);

console.log('Revoked at:', revokeResult.deactivatedAt);

验证所有权

// 验证 DID 所有权
const isOwner = await did.verifyOwnership(
  'did:mingchain:e803b04a...',
  privateKey
);

if (isOwner) {
  console.log('You own this DID!');
}

密钥管理

import { KeyManager, MingDID } from '@mingchain/ming-did-core';

const keyManager = new KeyManager();

// 生成密钥对
const keyPair = keyManager.generateKeyPair();
console.log('Address:', keyPair.address);
console.log('Public Key:', keyPair.publicKey);
console.log('WIF:', keyPair.privateKey);

// 从 WIF 创建密钥对
const fromWif = keyManager.createKeyPairFromWIF('5KiMhXRP4Gm3P9qhpw1p41ea227CQDYSAcLhXDgwyrcC7YQqCz8');

// 签名和验证
const message = 'Hello, MingDID!';
const { signature } = keyManager.sign(message, keyPair.privateKey);
const isValid = keyManager.verify(message, signature, keyPair.publicKey);

API 参考

MingDID 类

构造函数

new MingDID(config: MingDIDConfig)

配置选项:

• network: 'mainnet' | 'testnet' - 网络类型
• wocApiKey: string - WhatsOnChain API 密钥
• resolverUrl: string - 自定义解析器 URL
• cacheAdapter: CacheAdapter - 缓存适配器
• walletAdapter: WalletAdapter - 钱包适配器
• defaultFee: number - 默认手续费率 (sat/vB)

方法

| 方法 | 描述 | |------|------| | create(options?) | 创建新 DID | | resolve(did) | 解析 DID 到文档 | | update(did, options, privateKey) | 更新 DID 文档 | | deactivate(did, options) | 撤销 DID | | verifyOwnership(did, privateKey) | 验证所有权 | | getChainInfo(did) | 获取 UTXO 链信息 |

静态方法

MingDID.generateKeyPair()  // 生成密钥对
MingDID.create(config?)     // 创建实例

DIDDocument 类

// 创建空文档
DIDDocument.createEmpty(id: string): MingDIDDocument

// 添加验证方法
DIDDocument.addVerificationMethod(doc, method): MingDIDDocument

// 添加服务
DIDDocument.addService(doc, service): MingDIDDocument

// 设置代理配置
DIDDocument.setAgentProfile(doc, profile): MingDIDDocument

// 更新文档
DIDDocument.update(doc, options): MingDIDDocument

// 转为规范形式
DIDDocument.toCanonical(doc): string

OpReturnCodec 类

// 编码文档
codec.encodeDocument(version, identityCode, document): Uint8Array[]

// 解码文档
codec.decodeDocument(payload: string): Record<string, unknown>

// 编码创建操作
codec.encodeCreate(identityCode): Uint8Array[]

// 编码撤销操作
codec.encodeRevoke(identityCode, reason?): Uint8Array[]

WoCClient 类

WhatsOnChain API 客户端:

const client = new WoCClient('mainnet', apiKey);

// 获取 UTXO
client.getUtxos(address): Promise<UTXO[]>

// 获取交易
client.getTransaction(txid): Promise<ChainTransaction>

// 广播交易
client.broadcastTransaction(txHex): Promise<{ success: boolean; txid?: string }>

// 获取余额
client.getBalance(address): Promise<{ confirmed; unconfirmed; total }>

DID 文档结构

interface MingDIDDocument {
  '@context': string[];
  id: string;                          // "did:mingchain:<txid>"
  verificationMethod: VerificationMethod[];
  authentication: string[];           // 身份验证方法
  assertionMethod?: string[];         // 断言方法
  capabilityInvocation?: string[];    // 能力调用
  capabilityDelegation?: string[];    // 能力委托
  service?: ServiceEndpoint[];        // 服务端点
  controller?: string[];              // 控制器
  agentProfile?: AgentProfile;         // AI Agent 配置
  delegationChain?: DelegationRecord[]; // 委托链
}

OP_RETURN 格式

MINGDID:<version>:<identityCode>:<payload>

版本:
1 - CREATE (创建)
2 - DOCUMENT (文档)
3 - REVOKE (撤销)
4 - DELEGATE (委托)

测试

# 运行所有测试
npm test

# 监听模式
npm run test:watch

# 覆盖率报告
npm run test:coverage

许可

MIT License