从 V0 迁移到 V1 交易

将 Umi 应用从 V0 迁移到 V1 交易，以使用更大的交易，并直接在交易消息中配置计算预算。

总结

Umi 1.6.0 通过 useV1()、defaultTransactionVersion: 1 和直接交易输入中的 version: 1 提供可选的 V1 交易支持。

• V1 将序列化交易大小上限从 1,232 字节提高到 4,096 字节。
• V1 在 TransactionV1Config 中存储计算上限和优先费总额。
• V1 不支持 Address Lookup Tables 或 Compute Budget 指令。
• Umi 仍默认使用 V0，且连接的钱包必须支持 V1。

快速开始

在交易构建器上选择 V1，并使用 setTransactionConfig 取代 Compute Budget 指令。

1. 升级到 Umi 1.6.0 或更高版本，并升级到 @solana/web3.js 1.99.0 或更高版本。
2. 向交易构建器添加 .useV1()。
3. 移除 setComputeUnitLimit 和 setComputeUnitPrice 指令。
4. 添加 .setTransactionConfig({ computeUnitLimit, priorityFee })。
5. 使用应用支持的每一种钱包测试 V1 签名。

跳转到： 先决条件 · V0 与 V1 的差异 · 构建器迁移 · 应用默认版本 · 直接创建 · Address Lookup Tables · 常见错误 · 常见问题

先决条件

迁移到 V1 需要兼容的 Umi、Web3.js、RPC 和钱包版本。

V0 与 V1 交易的差异

V1 提高了交易大小上限，但不支持 V0 的 Address Lookup Tables 或 Compute Budget 指令。

当交易超过 V0 大小上限但不依赖 Address Lookup Table 时，V1 最为实用。

将交易构建器迁移到 V1

要将 V0 交易构建器迁移到 V1，需要用 useV1() 和 setTransactionConfig() 取代 Compute Budget 指令。

迁移前的 V0 交易构建器

V0 交易构建器通过指令表达计算单元上限和价格。

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 交易构建器

V1 交易构建器在交易消息中表达计算单元上限和优先费总额。

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)

优先费总额 600 lamport 等于 600,000 × 1,000 ÷ 1,000,000。如果转换结果不是整数 lamport，请向上取整。

将 V1 设为应用默认版本

设置 defaultTransactionVersion: 1 后，除非构建器明确选择其他版本，否则所有交易构建器都将使用 V1。

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

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

此选项也会影响 Metaplex 程序库返回的构建器。调用 useV0() 的构建器仍会覆盖应用默认版本。

直接安装交易工厂的应用可以改为配置插件：

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

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

将直接创建交易迁移到 V1

直接调用 umi.transactions.create() 时，必须设置 version: 1，并提供明确的非零运行时上限。

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 会提供与旧版等效的默认值。低级 create() 方法不会提供默认值；运行时会将省略的上限视为零。

配置 V1 交易上限

TransactionV1Config 控制计算量、账户数据、堆大小和优先费总额。

省略这些字段时，构建器默认将 computeUnitLimit 设为 min(200,000 × 指令数量, 1,400,000)，并将 loadedAccountsDataSizeLimit 设为 64 MiB。

将使用 Address Lookup Table 的交易保留在 V0

需要 Address Lookup Tables 的交易必须保留在 V0。

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

请勿仅为强制交易使用 V1 而移除 Address Lookup Table。应比较编译后的账户列表和序列化大小，然后使用满足交易要求的格式。

更新自定义 Umi 集成

升级到 Umi 1.6.0 时，自定义交易工厂和穷举式版本处理必须添加 V1 支持。

• 在自定义 TransactionFactoryInterface 实现上实现 getDefaultVersion()。
• 对穷举切换 TransactionVersion 的代码添加 1 分支。
• 对直接创建的 V0 TransactionInput 对象添加 version: 0，因为现在必须提供 V0 版本字段。
• 读取交易时检查 transaction.message.version；V1 消息包含 transactionConfig。

Umi 的 RPC 集成会请求 maxSupportedTransactionVersion: 1，因此 umi.rpc.getTransaction() 可以获取 V1 交易。

常见的 V1 迁移错误

Umi 会在发送交易前拒绝不兼容的构建器组合。

注意事项

• 在 Umi 1.6.0 中，V1 为可选版本；为了向后兼容，默认版本仍为 V0。
• V1 于 2026 年 9 月 15 日在 Solana mainnet-beta 的 epoch 1035 中启用。
• 发送和模拟使用 base64 编码，支持大于 1,232 字节的 V1 交易。
• Umi 会在序列化前验证计算单元上限和堆大小。
• 实现与兼容性详情记录在 metaplex-foundation/umi#216 中。

常见问题

Umi 默认使用 V1 交易吗？

为了向后兼容，Umi 1.6.0 仍以 V0 为默认版本。请在交易构建器上调用 useV1()，或在创建 Umi 时设置 defaultTransactionVersion: 1。

Umi V1 交易可以使用 Address Lookup Table 吗？

V1 交易不支持 Address Lookup Tables。任何需要 Address Lookup Table 的交易都应继续使用 V0。

V1 交易可以包含 Compute Budget 程序指令吗？

Umi 会拒绝包含 Compute Budget 指令的 V1 交易构建器。请使用 setTransactionConfig() 设置计算单元上限、优先费总额、已加载账户数据大小上限或堆大小。

V1 交易优先费是按每个计算单元计价吗？

TransactionV1Config.priorityFee 是以 SolAmount 表示的优先费总额，而不是每个计算单元的价格。将 micro-lamport 单价乘以计算单元上限，再除以 1,000,000，并向上取整为 lamport。

所有 Solana 钱包都支持 V1 交易吗？

交易版本 1 尚未得到所有钱包的支持。Umi 可以为钱包适配器序列化 V1 交易，但连接的钱包必须接受并签署该交易。