跳转到内容

交易与最终确认

构建一笔由 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 的模块与错误索引后向用户展示清晰提示。

更多故障原因请参阅问题排查。