跳到主要内容

PutNftObjectCommand

PutNftObjectCommand 是一个专门的命令，旨在上传数字资产（如图像、视频或音频文件），并同时创建或更新其关联的 DID 文档。此过程有效地将去中心化标识符（DID）链接到特定的数据片段，这是在 DID 空间内管理非同质化代币（NFT）和其他可验证数字资产的关键步骤。

该命令自动化了几个复杂的步骤：它计算资产的哈希值，构建一个有效的 DID 文档，指定资产的位置和完整性哈希，并使用控制器钱包签署该文档以证明所有权。然后，它将资产和已签署的文档捆绑到对 DID空间的单个请求中。

工作流程概览

下图说明了使用 PutNftObjectCommand 时的典型工作流程：

PutNftObjectCommand

输入

PutNftObjectCommand 需要向其构造函数提供以下输入参数。

  • did string (required) — 资产的 DID。这是上传的对象和 DID 文档将与之关联的标识符。
  • controller WalletObject (required) — 对资产 DID 拥有控制权的钱包对象。该钱包将用于签署生成的 DID 文档，以证明所有权。
  • chainHost string (required) — 区块链浏览器 API 的基础 URL（例如：'https://beta.abtnetwork.io/api/'）。这用于在 DID 文档中构建浏览器服务端点。
  • display object (required) — 包含显示资产配置的对象。
    • key string (required) — 资产的文件名（例如：'my-nft-image.png'）。不应包含任何路径。
    • data Readable (required) — 代表资产文件内容的可读流。

输出

该命令返回一个标准的输出对象。

  • statusCode number — 响应的 HTTP 状态码。值为 200 表示 NFT 对象及其 DID 文档已成功上传。
  • data void — 请求成功时，data 字段为空。

示例

以下是如何使用 PutNftObjectCommand 上传 NFT 资产的完整示例。

首先，请确保您有一个要上传的文件，例如 my-nft.png。

Example

typescript
import { SpaceClient, PutNftObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
import * as fs from 'fs';
import * as path from 'path';

async function uploadNftAsset() {
  const wallet = getWallet(); // 假设环境中有一个可用的钱包

  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet: wallet,
  });

  // 1. 准备 NFT 资产的文件流
  const filePath = path.join(__dirname, 'my-nft.png');
  // 在创建流之前，确保文件存在
  if (!fs.existsSync(filePath)) {
    console.error(`File not found: ${filePath}`);
    // 作为占位符，创建一个虚拟文件以供示例运行
    fs.writeFileSync(filePath, 'This is a dummy NFT file.');
  }
  const fileStream = fs.createReadStream(filePath);

  // 2. 定义命令输入
  const commandInput = {
    // 您正在上传的资产的 DID
    did: 'z8iZnaYxnkMD5AKRjTKiCb8pQr1ut8UantAcf',
    // 控制此资产 DID 的钱包
    controller: wallet,
    // 区块链浏览器的主机
    chainHost: 'https://beta.abtnetwork.io/api/',
    display: {
      key: 'my-nft.png',
      data: fileStream,
    },
  };

  // 3. 创建并发送命令
  const command = new PutNftObjectCommand(commandInput);
  const output = await client.send(command);

  // 4. 检查结果
  if (output.statusCode === 200) {
    console.log('NFT asset uploaded successfully!');
  } else {
    console.error('Failed to upload NFT asset:', output);
  }
}

uploadNftAsset();

最佳实践

DID 文档自动化

PutNftObjectCommand 的主要优势在于其对 DID 文档创建和签名的自动化。当您发送该命令时，它会在内部执行以下操作：

  1. 哈希计算

    它读取 data 流并计算文件内容的 SHA3-256 哈希值。此哈希值嵌入到 DID 文档中，以保证资产的完整性。

  2. 文档构建

    它组装一个包含基本元数据的 DID 文档，其中包括用于访问显示资产和在区块浏览器上查看它的服务端点。

  3. 签名

    它使用提供的 controller 钱包的私钥对整个 DID 文档进行签名。此加密签名是可验证的，并证明控制器授权了此特定版本的文档。

控制器钱包

controller 钱包是安全和所有权模型的基础。请确保提供的钱包有权管理指定的资产 did。该钱包的公钥包含在 DID 文档的 verificationMethod 中，允许任何人验证签名。