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:
- The Quickstart setup.
polkadot-api@3.3.0and locald9descriptors from RPC Verification.src/amount.tsfrom Read the Chain.
1. Send a transfer via the in-app wallet
Section titled “1. Send a transfer via the in-app wallet”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.
2. Sign through WalletConnect
Section titled “2. Sign through WalletConnect”In external browsers outside D9 Wallet, handle signing and broadcast explicitly:
- Select an approved account from
connector.getAccounts. - Query the genesis hash, runtime version, and account nonce from your RPC endpoint.
- Build the call with your PAPI 3 descriptors and estimate the fee.
- Send the signer payload to D9 Wallet via
d9_signTransaction: - Broadcast the signed extrinsic over your RPC connection.
- Wait for finalization (
chain_getFinalizedHead) and inspectSystem::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, }), );}Verify
Section titled “Verify”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.okistrueandresult.block.hashis the finalized block hash. - Manual tracking:
System::ExtrinsicSuccessconfirms execution;System::ExtrinsicFailedindicates dispatch failure—decode theDispatchErrormodule and error index before presenting feedback to the user.
For common broadcast or execution errors, see Troubleshooting.
