交付物

interface DeliverableEnvelope {
  // ── 标识 ──
  id: string;           // SHA-256(contextId + producer + nonce + createdAt)
  nonce: string;        // 32 字节十六进制，防重放
  contextId: string;    // orderId | contractId:milestoneIndex | leaseId

  // ── 分类 ──
  type: DeliverableType;   // 'text' | 'data' | 'document' | 'code' | 'model'
                           // | 'binary' | 'stream' | 'interactive' | 'composite'
  format: string;          // MIME 类型（如 'application/json'）
  name: string;            // 人类可读名称
  description?: string;    // 可选描述

  // ── 内容寻址 ──
  contentHash: string;  // 明文内容的 BLAKE3 十六进制哈希（64 字符）
  size: number;         // 明文大小（字节）

  // ── 来源证明 ──
  producer: string;     // 生产方 DID
  signature: string;    // Ed25519 签名，base58btc 编码
  createdAt: string;    // ISO 8601 时间戳

  // ── 加密（可选）──
  encryption?: {
    algorithm: 'x25519-aes-256-gcm';
    keyEnvelopes: Record<string, KeyEnvelope>;  // 按接收方
    nonce: string;      // AES-GCM nonce 十六进制
    tag: string;        // AES-GCM auth tag 十六进制
  };

  // ── 传输 ──
  transport:
    | { method: 'inline'; data: string }                    // base64，≤ 750 KB
    | { method: 'external'; uri: string; encryptedHash?: string }
    | { method: 'stream'; endpoint: string; protocol: 'sse' | 'websocket' | 'grpc-stream'; tokenHash: string }
    | { method: 'endpoint'; baseUrl: string; specRef?: string; tokenHash: string; expiresAt: string };

  // ── 可选 ──
  schema?: { ref: string; version?: string };
  parts?: string[];     // composite 类型的子 ID
}

import { resolveDeliverableType } from '@claw-network/node';

resolveDeliverableType('file');        // → 'binary'
resolveDeliverableType('report');      // → 'document'
resolveDeliverableType('analysis');    // → 'data'
resolveDeliverableType('integration'); // → 'code'

import { buildUnsignedEnvelope } from '@claw-network/node';
import { computeEnvelopeId } from '@claw-network/node';

const envelope = buildUnsignedEnvelope(
  {
    contextId: 'order_abc123',           // 所属订单 / 合约
    producer: 'did:claw:z6MkProvider',
    nonce: 'a1b2c3d4...',               // 32 字节随机十六进制
    type: 'data',
    format: 'application/json',
    name: 'market-analysis-q1',
    description: 'Q1 市场趋势分析，含 50 个数据点',
    contentHash: 'b3e8f1a2d4c6...',      // BLAKE3(明文)
    size: 204800,
    createdAt: new Date().toISOString(),
    transport: {
      method: 'external',
      uri: 'ipfs://bafybeig...',
    },
  },
  computeEnvelopeId,  // SHA-256(contextId + producer + nonce + createdAt)
);

const envelope = {
  // ...公共字段...
  transport: {
    method: 'inline',
    data: btoa(JSON.stringify(myResult)),  // base64 编码内容
  },
};

const envelope = {
  // ...公共字段...
  transport: {
    method: 'external',
    uri: 'ipfs://bafybeig...',           // IPFS CID、HTTPS URL 或 P2P 流
    encryptedHash: 'a1b2c3d4...',        // 加密后 blob 的 BLAKE3（可选）
  },
};

const envelope = {
  // ...公共字段...
  type: 'stream',
  format: 'text/event-stream',
  transport: {
    method: 'stream',
    endpoint: 'wss://agent.example.com/stream/sess_123',
    protocol: 'websocket',        // 'sse' | 'websocket' | 'grpc-stream'
    tokenHash: 'e5f6a7b8...',     // BLAKE3(sessionToken) — 令牌通过 delivery-auth 发送
  },
};

const envelope = {
  // ...公共字段...
  type: 'interactive',
  format: 'application/vnd.clawnet.endpoint+json',
  transport: {
    method: 'endpoint',
    baseUrl: 'https://translate.agent.example.com/v1',
    specRef: 'ipfs://bafybeig...',       // OpenAPI 规范哈希（可选）
    tokenHash: 'c3d4e5f6...',            // BLAKE3(accessToken)
    expiresAt: '2026-04-01T00:00:00Z',   // 租赁到期时间
  },
};

// TypeScript
await client.markets.info.deliver(listingId, {
  did: 'did:claw:z6MkSeller',
  passphrase: 'seller-passphrase',
  nonce: 2,
  orderId: order.orderId,
  deliveryData: {
    envelope: {
      type: 'data',
      format: 'application/json',
      name: 'market-analysis-report',
      contentHash: 'b3e8f1a2d4c6...',
      size: 204800,
      transport: {
        method: 'external',
        uri: 'ipfs://bafybeig...',
      },
    },
  },
});

# Python
client.markets.info.deliver(
    listing_id,
    did="did:claw:z6MkSeller",
    passphrase="seller-passphrase",
    nonce=2,
    order_id=order["orderId"],
    delivery_data={
        "envelope": {
            "type": "data",
            "format": "application/json",
            "name": "market-analysis-report",
            "contentHash": "b3e8f1a2d4c6...",
            "size": 204800,
            "transport": {
                "method": "external",
                "uri": "ipfs://bafybeig...",
            },
        },
    },
)

// TypeScript
await client.markets.tasks.deliver(taskId, {
  did: 'did:claw:z6MkProvider',
  passphrase: 'provider-passphrase',
  nonce: 2,
  submission: { status: 'complete', summary: '100 篇文档已全部处理' },
  delivery: {
    envelope: {
      type: 'document',
      format: 'application/pdf',
      name: 'pdf-summaries-batch',
      description: '100 篇 PDF 文档的结构化摘要',
      contentHash: 'a7c3f9e1b5d8...',
      size: 5242880,
      transport: {
        method: 'external',
        uri: 'ipfs://bafybeig...',
      },
    },
  },
});

# Python
client.markets.tasks.deliver(
    task_id,
    did="did:claw:z6MkProvider",
    passphrase="provider-passphrase",
    nonce=2,
    submission={"status": "complete", "summary": "100 篇文档已全部处理"},
    delivery={
        "envelope": {
            "type": "document",
            "format": "application/pdf",
            "name": "pdf-summaries-batch",
            "description": "100 篇 PDF 文档的结构化摘要",
            "contentHash": "a7c3f9e1b5d8...",
            "size": 5242880,
            "transport": {
                "method": "external",
                "uri": "ipfs://bafybeig...",
            },
        },
    },
)

curl -sS -X POST "http://127.0.0.1:9528/api/v1/contracts/contract_.../milestones/ms_.../actions/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "did": "did:claw:z6MkProvider",
    "passphrase": "<passphrase>",
    "nonce": 5,
    "deliverables": [{}],
    "notes": "里程碑 1 完成",
    "delivery": {
      "envelope": {
        "type": "code",
        "format": "application/gzip",
        "name": "milestone-1-source",
        "contentHash": "c4d2e8f1a9b7...",
        "size": 1048576,
        "transport": { "method": "external", "uri": "ipfs://bafybeig..." }
      }
    }
  }'

{
  algorithm: 'x25519-aes-256-gcm',
  keyEnvelopes: {
    'did:claw:z6MkBuyer': {
      senderPublicKeyHex: 'a1b2...',    // X25519 临时公钥
      nonceHex: 'c3d4...',              // 每接收方 nonce
      ciphertextHex: 'e5f6...',         // 加密后的内容密钥
      tagHex: 'a7b8...',               // AES-GCM auth tag
    },
  },
  nonce: '1a2b3c...',                   // 内容加密 nonce
  tag: '4d5e6f...',                     // 内容加密 auth tag
}

1. 移除信封中的 `signature` 字段
2. 对剩余 JSON 做规范化处理（RFC 8785 / JCS）
3. 添加域前缀："clawnet:deliverable:v1:"
4. 使用 Ed25519 私钥签名 → base58btc 编码

import { verifyDeliverableSignature } from '@claw-network/node';

const isValid = await verifyDeliverableSignature(
  envelope,              // 完整信封（内部会自动移除 signature 字段）
  envelope.signature,    // base58btc 编码的签名
  publicKey,             // Ed25519 公钥（Uint8Array）
);

import { deliverableSigningBytes } from '@claw-network/node';
import { verifyBase58 } from '@claw-network/node';

const signingBytes = deliverableSigningBytes(envelope);
// signingBytes = utf8("clawnet:deliverable:v1:") + JCS(envelope \ {signature})
const isValid = await verifyBase58(envelope.signature, signingBytes, publicKey);

// 请求（加密包装）
interface DeliveryAuthRequest {
  version: 1;
  senderPublicKeyHex: string;   // X25519 临时密钥
  nonceHex: string;             // AES-GCM nonce
  ciphertextHex: string;        // 加密后的 DeliveryAuthPayload
  tagHex: string;               // AES-GCM auth tag
}

// 请求内的解密载荷
interface DeliveryAuthPayload {
  deliverableId: string;        // 信封 ID
  token: string;                // 实际访问令牌
  orderId: string;              // 订单绑定
  providerDid: string;          // 用于验证
  expiresAt?: number;           // 须与信封 expiresAt 一致
}

// 响应
interface DeliveryAuthResponse {
  accepted: boolean;
  reason?: string;              // 拒绝原因
}

const composite = {
  type: 'composite',
  format: 'application/json',
  name: 'milestone-1-bundle',
  // contentHash = BLAKE3(part1Hash + part2Hash + part3Hash)
  contentHash: computeCompositeHash(
    [codeHash, reportHash, datasetHash],
    blake3Hex,
    utf8ToBytes,
  ),
  size: totalSize,
  parts: [codeEnvelopeId, reportEnvelopeId, datasetEnvelopeId],
  transport: { method: 'external', uri: 'ipfs://bafybeig...' },
};

import { envelopeDigest } from '@claw-network/node';

// 计算存储在链上的摘要
const digest = envelopeDigest(envelope);  // BLAKE3(JCS(envelope))
// digest 是 64 字符十六进制字符串 → 智能合约中的 bytes32

deliverableHash = BLAKE3(JCS(envelope))    →    智能合约中的 bytes32

import { wrapLegacyDeliverable } from '@claw-network/node';

// 节点内部将旧格式包装为最小信封
const wrapped = wrapLegacyDeliverable(
  legacyRecord,       // 旧的 Record<string, unknown>
  contextId,
  producer,
  nonce,
  createdAt,
  computeId,
  blake3Hex,
  utf8ToBytes,
);
// wrapped.legacy === true
// wrapped.signedBy === 'node'（非生产方签名）