Skip to content

Transactions & Finality

Build and submit a D9 transfer signed by D9 Wallet, then wait until the block is finalized. The wallet only signs—your DApp builds, broadcasts, and tracks transactions over its own RPC connection.

Prerequisites:

Inside D9 Wallet’s in-app browser, each approved account provides a txCreator. Pass it directly to tx.create(txCreator).

getCurrentAccount must query the live active account on every call rather than returning a cached snapshot so authorization is verified both before and after the wallet prompt:

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("This action requires an active injected account with txCreator");
}
const txCreator = account.txCreator;
const recipient = toChainAddress(recipientAddress);
const rawValue = parseAmount(d9AmountString, 12);
if (rawValue <= 0n) throw new Error("Transfer amount must be positive");
const assertAuthority = async () => {
const current = await getCurrentAccount();
if (current?.transport !== "papi" || current.address !== account.address ||
current.txCreator !== txCreator) {
throw new Error("Account authorization changed before broadcast");
}
};
const client = createClient(getWsProvider(d9Config.rpcUrl), { getMetadata });
try {
const identity = await client.getChainSpecData();
if (identity.genesisHash !== d9Config.expectedGenesisHash) {
throw new Error("RPC genesis hash does not match configuration");
}
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);
// Re-verify account authorization after the wallet prompt
await assertAuthority();
const result = await client.submit(signedTx);
if (!result.ok) {
throw new Error(`Transaction dispatch failed: ${JSON.stringify(result.dispatchError)}`);
}
return result;
} finally {
client.destroy();
}
}

client.submit resolves only once the transaction is included in a finalized block.

In external browsers outside D9 Wallet, handle signing and broadcast explicitly:

  1. Select an approved account from connector.getAccounts.
  2. Query the genesis hash, runtime version, and account nonce from your RPC endpoint.
  3. Build the call with your PAPI 3 descriptors and estimate the fee.
  4. Send the signer payload to D9 Wallet via d9_signTransaction:
  5. Broadcast the signed extrinsic over your RPC connection.
  6. Wait for finalization (chain_getFinalizedHead) and inspect 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 envelope version
account: accountId,
transaction: signerPayload,
}),
);
}

Broadcast acceptance alone does not guarantee success. Wait until the transaction is Finalized:

Stage Status
In pool Pending; can still be dropped or replaced
In block Included; block can still be reorganized
Finalized Irreversible; inspect System::Events for your extrinsic index
  • With client.submit: result.ok is true and result.block.hash is the finalized block hash.
  • Manual tracking: System::ExtrinsicSuccess confirms execution; System::ExtrinsicFailed indicates dispatch failure—decode the DispatchError module and error index before presenting feedback to the user.

For common broadcast or execution errors, see Troubleshooting.