準備交易聲明

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 物件

The 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` 處理支付流程的完整實際範例。