Versioned Transactions

Versioned transactions are the modern transaction format on Solana, introduced to lift a hard limit of the original layout. A legacy transaction lists every account it touches inline, and because a single transaction is capped at 1232 bytes, that inline list runs out of room quickly — a problem for DeFi routes and other composed instructions that reference dozens of accounts. A versioned (v0) transaction keeps the same instructions but adds support for Address Lookup Tables (ALTs): on-chain tables that store account addresses once, so the transaction can point at a table index instead of repeating a full 32-byte pubkey. That indirection lets one transaction reference far more accounts than a legacy message ever could, while staying under the byte limit.

Understanding Versioned Transactions

• Address Lookup Tables. An ALT is an on-chain account that stores a list of pubkeys. A v0 transaction references those accounts by their index in the table rather than embedding the full 32-byte address, compressing what would otherwise be a long inline account list.
• MessageV0 vs legacy Message. A legacy Message carries a flat staticAccountKeys array. A MessageV0 keeps that array but adds addressTableLookups, letting the runtime resolve extra accounts from one or more ALTs at execution time.
• Reads require the flag. getTransaction and getBlock will reject a v0 transaction unless you pass maxSupportedTransactionVersion: 0. Omit it and you get a version error instead of the transaction.
• Only version 0 exists. Today 0 is the single non-legacy transaction version Solana supports, so maxSupportedTransactionVersion: 0 is the value you will always use.
• Size vs account count. Because a transaction is capped at 1232 bytes, every inline account eats scarce space. Moving addresses into an ALT trades a fixed per-table cost for the ability to reference many more accounts within that same byte budget.

Building and Fetching a v0 Transaction

1import {
2  Connection,
3  PublicKey,
4  TransactionMessage,
5  VersionedTransaction,
6  SystemProgram,
7} from '@solana/web3.js';
8 
9const connection = new Connection('https://solana.therpc.io/YOUR_API_KEY', 'confirmed');
10 
11const { blockhash } = await connection.getLatestBlockhash();
12 
13const instructions = [
14  SystemProgram.transfer({
15    fromPubkey: payer.publicKey,
16    toPubkey: new PublicKey('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'),
17    lamports: 1_000_000,
18  }),
19];
20 
21const message = new TransactionMessage({
22  payerKey: payer.publicKey,
23  recentBlockhash: blockhash,
24  instructions,
25}).compileToV0Message(); // optionally pass lookup tables here
26 
27const tx = new VersionedTransaction(message);
28tx.sign([payer]);
29 
30const signature = await connection.sendTransaction(tx);
31 
32// Fetching it back REQUIRES maxSupportedTransactionVersion
33const fetched = await connection.getTransaction(signature, {
34  maxSupportedTransactionVersion: 0,
35});

Best Practices

• Always set the version flag on reads. Pass maxSupportedTransactionVersion: 0 to every getTransaction and getBlock call so v0 entries are returned instead of triggering a version error.
• Reach for ALTs only when needed. Creating and extending a lookup table is itself an on-chain action with its own cost and confirmation. Use ALTs for transactions that genuinely touch many accounts, not for simple transfers.
• Default new code to v0. Build new transactions as versioned (v0); legacy is still accepted but can never use Address Lookup Tables, so it caps how far your transaction composition can scale.
• Sign against a fresh blockhash. Fetch the blockhash with getLatestBlockhash immediately before signing so the transaction does not expire while you assemble it.
• Keep your SDK current. Older client versions of @solana/web3.js, solders, or the Rust/Go clients may not compile v0 messages at all — stay on a recent release before relying on versioned transactions.

See also

• getTransaction - Fetch a transaction (needs maxSupportedTransactionVersion)
• getBlock - Fetch a block of transactions
• sendTransaction - Submit a signed transaction
• getLatestBlockhash - Recent blockhash for building a transaction