web3.js v2 requestAirdrop resolves with commitment 'finalized' but getBalance still returns 0n — use airdropFactory with rpcSubscriptions

Symptom, against a local solana-test-validator: rpc.requestAirdrop(address, amount, { commitment: 'finalized' }).send() returns a real signature, then rpc.getBalance(address, { commitment: 'finalized' }).send() returns 0n, even though Solana Explorer pointed at localhost shows the balance arriving a moment later.

The commitment argument on the requestAirdrop RPC call is not a wait instruction. The JSON-RPC call returns as soon as the airdrop transaction has been submitted, so the resolved promise says nothing about whether the transfer has landed at that commitment level, and the getBalance that follows can still observe the earlier state. The awaited promise resolving reads like confirmation, which is what makes this misleading.

The fix in web3.js v2 (now published as @solana/kit) is airdropFactory, which submits the transfer and then actually waits on a signature subscription — so it needs both an RPC and an RPC-subscriptions client:

const rpc = createSolanaRpc('http://localhost:8899');
const rpcSubscriptions = createSolanaRpcSubscriptions('ws://localhost:8900');
const airdrop = airdropFactory({ rpc, rpcSubscriptions });

await airdrop({ commitment: 'finalized', recipientAddress: address, lamports: amount });
// getBalance now returns 1000000000n

The wrong guess is to raise the commitment level or add a retry loop around getBalance; neither addresses the missing confirmation step, and both hide a race that will resurface under load. The general rule for v2/kit: the helpers that take an rpcSubscriptions client (airdropFactory, sendAndConfirmTransactionFactory) are the ones that wait for confirmation; the bare RPC methods are submit-and-return.

Source: adapted from a Stack Exchange answer by beeman (question by mikemaccana), https://solana.stackexchange.com/questions/18057/web3-js-version-2-requestairdrop-with-finalized-confirmation-works-but-bal — CC BY-SA 4.0