交易與最終確認
建立一筆由 D9 錢包簽署的轉帳交易,送出至鏈上並等待區塊最終確認。錢包僅負責簽署;交易建構、廣播與狀態追蹤皆由你的 DApp 透過自有 RPC 連線完成。
前置條件:
1. 透過內建錢包發送轉帳
Section titled “1. 透過內建錢包發送轉帳”在 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 會等待區塊完成最終確認後再回傳。
2. 透過 WalletConnect 請求簽署
Section titled “2. 透過 WalletConnect 請求簽署”在外部瀏覽器中,需要自行完成負載建構與廣播:
- 從
connector.getAccounts選取已授權帳戶。 - 從自有 RPC 讀取創世雜湊、Runtime 版本與帳戶 Nonce。
- 使用 PAPI 3 描述檔建立呼叫並估算手續費。
- 透過
d9_signTransaction將簽署負載傳送至錢包(見下方程式碼)。 - 將回傳的已簽署 Extrinsic 廣播至 RPC 節點。
- 等待區塊最終確認(
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的模組與錯誤索引後向使用者顯示明確提示。
更多故障原因請參閱問題排查。
