Migrating from V0 to V1 Transactions

Migrate Umi applications from V0 to V1 transactions to use larger transactions and configure the compute budget directly on the transaction message.

Summary

Umi 1.6.0 adds opt-in support for V1 transactions through useV1(), defaultTransactionVersion: 1, and version: 1 on direct transaction inputs.

• V1 raises the serialized transaction limit from 1,232 to 4,096 bytes.
• V1 stores compute limits and the total priority fee in TransactionV1Config.
• V1 does not support Address Lookup Tables or Compute Budget instructions.
• Umi still defaults to V0, and connected wallets must support V1.

Quick Start

Select V1 on the transaction builder and replace Compute Budget instructions with setTransactionConfig.

1. Upgrade to Umi 1.6.0 or later and @solana/web3.js 1.99.0 or later.
2. Add .useV1() to the transaction builder.
3. Remove setComputeUnitLimit and setComputeUnitPrice instructions.
4. Add .setTransactionConfig({ computeUnitLimit, priorityFee }).
5. Test V1 signing with every wallet supported by the application.

Jump to: Prerequisites · V0 and V1 Differences · Builder Migration · Application Default · Direct Creation · Address Lookup Tables · Common Errors · FAQ

Prerequisites

V1 migration requires compatible Umi, Web3.js, RPC, and wallet versions.

Differences Between V0 and V1 Transactions

V1 increases the transaction size limit but does not support V0 Address Lookup Tables or Compute Budget instructions.

V1 is most useful when a transaction exceeds the V0 size limit without relying on an Address Lookup Table.

Migrating a Transaction Builder to V1

A V0 transaction builder migrates to V1 by replacing Compute Budget instructions with useV1() and setTransactionConfig().

V0 Transaction Builder Before Migration

The V0 transaction builder expresses the compute unit limit and price as instructions.

import { transactionBuilder } from '@metaplex-foundation/umi'
import {
  setComputeUnitLimit,
  setComputeUnitPrice,
  transferSol,
} from '@metaplex-foundation/mpl-toolbox'

await transactionBuilder()
  .add(setComputeUnitLimit(umi, { units: 600_000 }))
  .add(setComputeUnitPrice(umi, { microLamports: 1_000 }))
  .add(transferSol(umi, transferArgs))
  .sendAndConfirm(umi)

V1 Transaction Builder After Migration

The V1 transaction builder expresses the compute unit limit and total priority fee in the transaction message.

import { lamports, transactionBuilder } from '@metaplex-foundation/umi'
import { transferSol } from '@metaplex-foundation/mpl-toolbox'

await transactionBuilder()
  .add(transferSol(umi, transferArgs))
  .useV1()
  .setTransactionConfig({
    computeUnitLimit: 600_000,
    priorityFee: lamports(600),
  })
  .sendAndConfirm(umi)

The 600 lamport total fee equals 600,000 × 1,000 ÷ 1,000,000. Round up when the conversion does not produce a whole lamport.

Setting V1 as the Application Default

Setting defaultTransactionVersion: 1 makes all transaction builders use V1 unless a builder explicitly selects another version.

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

const umi = createUmi('https://api.mainnet-beta.solana.com', {
  defaultTransactionVersion: 1,
})

This option also affects builders returned by Metaplex program libraries. A builder that calls useV0() still overrides the application default.

Applications that install the transaction factory directly can configure the plugin instead:

import { web3JsTransactionFactory } from '@metaplex-foundation/umi-transaction-factory-web3js'

umi.use(web3JsTransactionFactory({ defaultTransactionVersion: 1 }))

Migrating Direct Transaction Creation to V1

Direct umi.transactions.create() calls must set version: 1 and provide explicit nonzero runtime limits.

const transaction = umi.transactions.create({
  version: 1,
  blockhash: (await umi.rpc.getLatestBlockhash()).blockhash,
  instructions: [myInstruction],
  payer: umi.payer.publicKey,
  transactionConfig: {
    computeUnitLimit: 200_000,
    loadedAccountsDataSizeLimit: 64 * 1024 * 1024,
  },
})

TransactionBuilder supplies legacy-equivalent defaults for omitted compute and loaded-account limits. The low-level create() method does not; an omitted limit is treated as zero by the runtime.

Configuring V1 Transaction Limits

TransactionV1Config controls compute, account data, heap size, and the total priority fee.

The builder defaults computeUnitLimit to min(200,000 × instruction count, 1,400,000) and loadedAccountsDataSizeLimit to 64 MiB when those fields are omitted.

Keeping Address Lookup Table Transactions on V0

Transactions that require Address Lookup Tables must remain on V0.

const builder = transactionBuilder()
  .add(myInstruction)
  .useV0()
  .setAddressLookupTables([myLookupTable])

Do not remove an Address Lookup Table merely to force a transaction onto V1. Compare the compiled account list and serialized size, then use the format that satisfies the transaction's requirements.

Updating Custom Umi Integrations

Custom transaction factories and exhaustive version handling must add V1 support when upgrading to Umi 1.6.0.

• Implement getDefaultVersion() on custom TransactionFactoryInterface implementations.
• Add a 1 case to code that exhaustively switches over TransactionVersion.
• Add version: 0 to direct V0 TransactionInput objects because the V0 version field is now required.
• Inspect transaction.message.version when reading transactions; V1 messages include transactionConfig.

Umi's RPC integration requests maxSupportedTransactionVersion: 1, so umi.rpc.getTransaction() can fetch V1 transactions.

Common V1 Migration Errors

Umi rejects incompatible builder combinations before sending the transaction.

Notes

• V1 is opt-in in Umi 1.6.0; the default remains V0 for backward compatibility.
• V1 became active on Solana mainnet-beta in epoch 1035 on September 15, 2026.
• Sending and simulation use base64 encoding, which supports V1 transactions larger than 1,232 bytes.
• Umi validates the compute unit limit and heap size before serialization.
• The implementation and compatibility details are documented in metaplex-foundation/umi#216.

FAQ

Does Umi Use V1 Transactions by Default?

Umi 1.6.0 keeps V0 as the default for backward compatibility. Call useV1() on a transaction builder or set defaultTransactionVersion: 1 when creating Umi.

Can a Umi V1 Transaction Use an Address Lookup Table?

V1 transactions do not support Address Lookup Tables. Keep any transaction that requires an Address Lookup Table on V0.

Can a V1 Transaction Contain Compute Budget Program Instructions?

Umi rejects V1 transaction builders that contain Compute Budget instructions. Use setTransactionConfig() to set the compute unit limit, total priority fee, loaded accounts data size limit, or heap size.

Is the V1 Transaction Priority Fee a Price per Compute Unit?

TransactionV1Config.priorityFee is the total priority fee as a SolAmount, not a price per compute unit. Convert a micro-lamport price by multiplying it by the compute unit limit, dividing by 1,000,000, and rounding up to lamports.

Do All Solana Wallets Support V1 Transactions?

Wallet support for transaction version 1 is not universal. Umi can serialize V1 transactions for wallet adapters, but the connected wallet must accept and sign the transaction.