跳到內容

交易與最終確認

建立一筆由 D9 錢包簽署的轉帳交易,送出至鏈上並等待區塊最終確認。錢包僅負責簽署;交易建構、廣播與狀態追蹤皆由你的 DApp 透過自有 RPC 連線完成。

前置條件:

在 D9 錢包內建瀏覽器中,每個已授權帳戶都附帶 txCreator,直接傳入 tx.create(txCreator) 即可喚起簽署。

getCurrentAccount 每次呼叫都必須讀取目前啟用帳戶而非快取副本,確保錢包彈窗前後皆完成授權驗證:

import { createClient } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { d9, getMetadata } from "@polkadot-api/descriptors";
import type { D9ConnectorAccount } from "@d9-network/dapp-connector";
import { toChainAddress } from "@d9-network/dapp-connector/protocol";
import { parseAmount } from "./amount";
import { d9Config } from "./config";
export async function executeInjectedTransfer(
account: D9ConnectorAccount,
recipientAddress: string,
d9AmountString: string,
getCurrentAccount: () => Promise<D9ConnectorAccount | undefined>,
) {
if (account.transport !== "papi" || !account.txCreator) {
throw new Error("此操作需要包含有效 txCreator 的注入式錢包帳戶");
}
const txCreator = account.txCreator;
const recipient = toChainAddress(recipientAddress);
const rawValue = parseAmount(d9AmountString, 12);
if (rawValue <= 0n) throw new Error("轉帳金額必須大於零");
const assertAuthority = async () => {
const current = await getCurrentAccount();
if (current?.transport !== "papi" || current.address !== account.address ||
current.txCreator !== txCreator) {
throw new Error("廣播前帳戶授權狀態已變更");
}
};
const client = createClient(getWsProvider(d9Config.rpcUrl), { getMetadata });
try {
const identity = await client.getChainSpecData();
if (identity.genesisHash !== d9Config.expectedGenesisHash) {
throw new Error("RPC 創世雜湊與設定不相符");
}
const api = client.getTypedApi(d9);
const tx = api.tx.Balances.transfer_keep_alive({
dest: { type: "Id", value: recipient },
value: rawValue,
});
await assertAuthority();
const signedTx = await tx.create(txCreator);
// 錢包簽署後再次驗證帳戶授權狀態
await assertAuthority();
const result = await client.submit(signedTx);
if (!result.ok) {
throw new Error(`鏈上交易執行失敗: ${JSON.stringify(result.dispatchError)}`);
}
return result;
} finally {
client.destroy();
}
}

client.submit 會等待區塊完成最終確認後再回傳。

在外部瀏覽器中,需要自行完成負載建構與廣播:

  1. 從 connector.getAccounts 選取已授權帳戶。
  2. 從自有 RPC 讀取創世雜湊、Runtime 版本與帳戶 Nonce。
  3. 使用 PAPI 3 描述檔建立呼叫並估算手續費。
  4. 透過 d9_signTransaction 將簽署負載傳送至錢包(見下方程式碼)。
  5. 將回傳的已簽署 Extrinsic 廣播至 RPC 節點。
  6. 等待區塊最終確認(chain_getFinalizedHead)並檢查 System::Events。
import type { D9WalletConnectTransportHandle } from "@d9-network/dapp-connector";
import type {
D9AccountId,
D9PjsSignerPayload,
} from "@d9-network/dapp-connector/protocol";
import { walletRuntime } from "./wallet";
export async function requestWalletConnectSign(
handle: D9WalletConnectTransportHandle,
accountId: D9AccountId,
signerPayload: D9PjsSignerPayload,
) {
return walletRuntime.runPromise(
handle.requestTransaction({
version: 1, // D9 封套版本號
account: accountId,
transaction: signerPayload,
}),
);
}

僅收到廣播回應並不代表交易成功,必須等待交易進入 已最終確認 階段:

階段 意義
交易池中 待打包,仍可能被丟棄或取代
已入塊 已打包進區塊,但區塊仍可能重組
已最終確認 不可逆;依 Extrinsic 索引核對 System::Events
  • 使用 client.submit: result.ok 為 true,result.block.hash 即為最終確認的區塊雜湊。
  • 手動追蹤: System::ExtrinsicSuccess 代表執行成功;System::ExtrinsicFailed 代表執行失敗,請解碼 DispatchError 的模組與錯誤索引後向使用者顯示明確提示。

更多故障原因請參閱問題排查。