准备交易声明

prepareTx 声明是 dApp 的一个强大工具，尤其是在需要用户完成并签署交易的支付和资产转移场景中。与标准的 signature 声明（其中整个交易是预先定义的）不同，prepareTx 会向钱包发送一个部分构造的交易。然后，钱包负责添加必要的输入（如代币或资产）以满足指定的 requirement，签署完成的交易，并将其返回给 dApp。

当 dApp 知道需要支付什么但不知道用户将使用哪些特定资产支付时，这特别有用。用户可以直接从他们的钱包中选择所需的输入，提供了灵活且安全的用户体验。

对于 dApp 已完全构建好交易的更简单的签名请求，请参阅签名声明。

它是如何工作的

prepareTx 声明的工作流程涉及应用程序定义交易的核心逻辑，而将资金部分留给用户的钱包处理。

Prepare Transaction Claim

发起
用户在 dApp 中执行需要交易的操作，例如进行购买。
声明生成
dApp 构建一个部分交易（例如，向其自己的地址转账）和一个 requirement 对象，详细说明用户需要贡献什么（例如，100 个原生代币）。
钱包交互
钱包接收到声明，向用户展示交易详情，并提供一个界面让他们选择满足 requirement 所需的代币或资产。
完成与签署
一旦用户批准并选择了他们的资产，钱包将使用所选的输入完成交易，并使用用户的私钥进行签名。
返回 dApp
钱包将已完全签署、可随时广播的交易返回给 dApp。
广播
dApp 接收到已签署的交易，然后可以将其提交到区块链进行处理。

参数

prepareTx 声明对象使用以下属性进行配置：

Parameter	Type	Description
`description`	string	一个用户友好的消息，解释交易的目的。默认为 '准备并签署此交易以继续。'。
`partialTx`	string or object	必需。部分构造的交易。这可以是一个原始交易对象或一个预编码的、Base58 编码的字符串。
`requirement`	object	必需。一个指定钱包必须添加到交易中的资源的对象。
`display`	string	可选。一个包含 `{ type, content }` 的 JSON 字符串，用于在钱包中提供更丰富的 UI 显示。
`chainInfo`	object	将执行交易的区块链信息。可以在此处提供，也可以在 `WalletAuthenticator` 配置中全局提供。
`meta`	any	可选。您想与声明关联的任何额外元数据。默认为 `{}`。
`mfa`	boolean	可选。如果设置为 `true`，钱包将被提示执行多因素身份验证。
`nonce`	string	可选。如果协议要求，要在交易中包含的 nonce。

Requirement 对象

requirement 对象对于定义用户需要贡献什么是至关重要的。

Field	Type	Description
`tokens`	`Array<object>`	必需。一个代币需求数组。每个对象必须包含 `address`（代币的 DID）和 `value`（所需的金额，为字符串或 BN.js 实例）。
`assets`	`object`	可选。一个指定 NFT 需求的对象。您可以按 `address`、`parent`、`issuer` 筛选资产，或指定要包含的资产 `amount`。

示例

这是一个如何请求 prepareTx 声明的示例。dApp 希望收到 100 个单位的特定代币。它创建一个部分交易并为钱包定义需求。

DID Connect Handler

const claims = {
  // 使用 SDK 将编码的原始交易对象
  prepareTx_raw: [
    'prepareTx',
    ({ userDid, userPk }) => ({
      type: 'TransferV2Tx', // SDK 要编码的交易类型
      description: '完成此付款以购买该商品。',
      display: JSON.stringify({ type: 'text', content: '购买确认，商品 #123' }),
      partialTx: {
        itx: {
          to: 'z2qa5b3g7492c3697a4e69b9a6b986b59e4d5',
        },
      },
      requirement: {
        tokens: [
          {
            address: 'z35nB2SA6xxBuoaiuUXUw6Gah2SNU3UzqdgEt', // 代币地址
            value: '100',
          },
        ],
      },
    }),
  ],

  // 使用预先编码的部分交易
  prepareTx_encoded: async ({ userDid, userPk }) => {
    // 此编码步骤通常会在您的后端进行
    const client = new Client('https://beta.abtnetwork.io/api');
    const encoded = await client.encodeTransferV2Tx({
      tx: {
        itx: {
          to: 'z2qa5b3g7492c3697a4e69b9a6b986b59e4d5',
        },
      },
      wallet: fromRandom(), // 用于编码的占位钱包
    });

    return {
      type: 'prepareTx',
      description: '完成此付款以购买该商品。',
      partialTx: toBase58(encoded.buffer), // 作为 Base58 字符串的预编码缓冲区
      requirement: {
        tokens: [
          {
            address: 'z35nB2SA6xxBuoaiuUXUw6Gah2SNU3UzqdgEt',
            value: '100',
          },
        ],
      },
    };
  },
};

在这两种情况下，钱包都会收到部分交易和需求。然后它会提示用户从其持有的资产中选择 100 个单位地址为 z35nB2SA6xxBuoaiuUXUw6Gah2SNU3UzqdgEt 的代币，将它们作为输入添加到交易中，进行签名，并返回结果。

后续步骤

掌握 prepareTx 声明后，您可能对其他相关功能感兴趣。

签名声明

适用于需要用户签署一个完全形成的交易或简单消息的场景。

交易支付示例

查看一个使用 `prepareTx` 处理支付流程的、实用的端到端示例。