> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Compatibilidad con transacciones v1
> Prepara tu integración con Solana para las transacciones v1: establece maxSupportedTransactionVersion en 1, actualiza a un SDK compatible con v1 y lee las comisiones de prioridad desde transactionConfig.
Agave 4.2 introduce las transacciones v1 ([SIMD-0385](https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0385-transaction-v1.md)). Una vez que la compuerta de funcionalidad se active en la red principal, las billeteras y los programas comenzarán a enviar transacciones v1, y cualquier solicitud que obtenga los datos completos de una transacción deberá habilitarlas explícitamente.
Esta página explica qué cambia, qué endpoints de Helius se ven afectados y cómo actualizar tu código. Para consultar la lista de verificación completa de Agave 4.2, incluidos los tipos de recompensas, la semántica de actualización de cuentas y los tiempos de los slots, consulta la [lista de verificación para migrar a Agave 4.2](https://www.helius.dev/blog/agave-4-2-migration-checklist).
## Qué cambia en las transacciones v1
Las transacciones heredadas y v0 no cambian. Para la mayoría de las integraciones, hay dos aspectos importantes de las transacciones v1:
* **Debes habilitarlas explícitamente para recibirlas.** Las solicitudes de datos completos de transacciones necesitan `maxSupportedTransactionVersion: 1`, y tu biblioteca cliente necesita una versión que pueda deserializar v1.
* **El presupuesto de cómputo se traslada al encabezado del mensaje.** Un mensaje v1 contiene un objeto `transactionConfig` con `computeUnitLimit`, `heapSize`, `loadedAccountsDataSizeLimit` e `priorityFee`. Una transacción v1 no contiene instrucciones del programa ComputeBudget.
El formato de transmisión también cambia (un nuevo byte de versión y las firmas al final de la transacción), pero esto solo afecta al código que decodifica bytes sin procesar de transacciones. Consulta [Decodificar bytes sin procesar de transacciones](#decodifica-bytes-sin-procesar-de-transacciones-con-un-analizador-compatible-con-v1) más adelante.
En las respuestas JSON, una transacción v1 informa `"version": 1` y su `message` incluye `transactionConfig`:
```json theme={"system"}
{
"version": 1,
"transaction": {
"signatures": ["..."],
"message": {
"accountKeys": ["..."],
"instructions": [
{ "programIdIndex": 3, "accounts": [0, 1], "data": "3Bxs4..." }
],
"recentBlockhash": "...",
"transactionConfig": {
"computeUnitLimit": 200000,
"heapSize": null,
"loadedAccountsDataSizeLimit": 200000,
"priorityFee": 50000
}
}
}
}
```
`"priorityFee": 50000` significa que esta transacción paga 50,000 lamports en total. Un campo `null` significa que el remitente no lo estableció. Los mensajes heredados y v0 omiten `transactionConfig` por completo.
## Establece maxSupportedTransactionVersion en 1
Cada solicitud que devuelve los datos completos de una transacción debe declarar la versión de transacción más alta que puede procesar. Establece `maxSupportedTransactionVersion: 1` en:
* [`getTransaction`](/docs/es/rpc/guides/gettransaction)
* [`getBlock`](/docs/es/rpc/guides/getblock)
* [`getTransactionsForAddress`](/docs/es/rpc/gettransactionsforaddress) con `transactionDetails: "full"`
* [`transactionSubscribe`](/docs/es/rpc/websocket/transaction-subscribe) con `transactionDetails: "accounts"` o `"full"`
* [`blockSubscribe`](/docs/es/api-reference/rpc/websocket/blocksubscribe)
Una solicitud que omite el parámetro o lo establece en `0` falla con el error JSON-RPC `-32015` en cuanto encuentra una transacción v1:
```json theme={"system"}
{
"jsonrpc": "2.0",
"error": {
"code": -32015,
"message": "Transaction version (1) is not supported by the requesting client. Please use \"maxSupportedTransactionVersion\" in your request."
},
"id": 1
}
```
Para `getBlock`, una sola transacción v1 en cualquier parte del bloque hace que falle toda la solicitud. Si ves `-32015` en tus registros, el proyecto ya está fallando con transacciones versionadas.
```json getTransaction theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "getTransaction",
"params": [
"2id3YC2jK9G5Wo2phDx4gJVAew8DcY5NAojnVuao8rkxwPYPe8cSwE5GzhEgJA2y8fVjDEo6iR6ykBvDxrTQrtpb",
{
"encoding": "jsonParsed",
"commitment": "confirmed",
"maxSupportedTransactionVersion": 1
}
]
}
```
```json getBlock theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "getBlock",
"params": [
341197053,
{
"encoding": "jsonParsed",
"transactionDetails": "full",
"maxSupportedTransactionVersion": 1
}
]
}
```
```json getTransactionsForAddress theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "getTransactionsForAddress",
"params": [
"86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
{
"transactionDetails": "full",
"encoding": "jsonParsed",
"limit": 100,
"maxSupportedTransactionVersion": 1
}
]
}
```
```json transactionSubscribe theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "transactionSubscribe",
"params": [
{ "accountInclude": ["86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"] },
{
"commitment": "confirmed",
"encoding": "jsonParsed",
"transactionDetails": "full",
"maxSupportedTransactionVersion": 1
}
]
}
```
## Actualiza tu SDK antes de aumentar el valor
Establecer `maxSupportedTransactionVersion: 1` indica al nodo que devuelva transacciones v1. Tu biblioteca cliente aún debe poder deserializarlas. Actualízala primero y luego cambia el parámetro:
| Cliente | Versión mínima compatible con transacciones v1 |
| -------------------------------------------------- | ------------------------------------------------- |
| `@solana/kit` | 8.0 |
| `@solana/web3.js` | v3 |
| `solana-sdk` / `solana-transaction-status` de Rust | Una versión compilada con los crates de Agave 4.2 |
| `yellowstone-grpc-client` | 13.3.0 |
| `yellowstone-grpc-proto` | 12.6.0 |
| `helius-laserstream` (JavaScript) | 0.8.4 |
| `helius-laserstream` (Rust) | 0.6.3 |
| `helius-laserstream` (Go) | 0.2.0 |
Las implementaciones anteriores de `VersionedTransaction.deserialize` en JavaScript solo procesan transacciones heredadas y v0, y generan un error ante un byte inicial `0x81`. Los protos anteriores de Yellowstone son previos a los campos de mensajes v1, por lo que los consumidores de gRPC que usan esas versiones nunca ven `transactionConfig`. Para los clientes gRPC de Go, vuelve a generarlos a partir de los protos más recientes de Yellowstone y `solana-storage-proto`.
## Lee las comisiones de prioridad desde transactionConfig
El código que calcula la comisión de prioridad de una transacción buscando instrucciones del programa ComputeBudget (`ComputeBudget111111111111111111111111111111`, `setComputeUnitPrice`, `setComputeUnitLimit`) interpreta que todas las transacciones v1 pagan cero. En v1, los valores se encuentran en `message.transactionConfig` y las unidades son diferentes:
| Formato | Dónde se encuentra la comisión | Unidad |
| ------------ | --------------------------------- | ----------------------------------- |
| Heredado, v0 | Instrucción `setComputeUnitPrice` | Microlamports por unidad de cómputo |
| v1 | `transactionConfig.priorityFee` | Lamports totales de la transacción |
No adaptes el cálculo heredado de `price × computeUnitLimit ÷ 1e6` a `priorityFee`. Este último ya representa el total.
```typescript priority-fee.ts theme={"system"}
import bs58 from "bs58";
const COMPUTE_BUDGET = "ComputeBudget111111111111111111111111111111";
/** Total priority fee in lamports for a `json`-encoded transaction. */
function priorityFeeLamports(tx: any): number {
const message = tx.transaction.message;
// v1: the header carries the total directly.
if (message.transactionConfig) {
return message.transactionConfig.priorityFee ?? 0;
}
// Legacy and v0: derive it from ComputeBudget instructions.
let microLamportsPerCu = 0n;
let computeUnitLimit: bigint | null = null;
let otherInstructions = 0;
for (const ix of message.instructions) {
if (message.accountKeys[ix.programIdIndex] !== COMPUTE_BUDGET) {
otherInstructions++;
continue;
}
const data = bs58.decode(ix.data);
const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
if (data[0] === 2) computeUnitLimit = BigInt(view.getUint32(1, true));
if (data[0] === 3) microLamportsPerCu = view.getBigUint64(1, true);
}
// Without an explicit limit, the runtime grants 200,000 CU per non-ComputeBudget instruction, capped at 1,400,000.
const limit = computeUnitLimit ?? BigInt(Math.min(otherInstructions * 200_000, 1_400_000));
return Number((microLamportsPerCu * limit) / 1_000_000n);
}
```
Bifurca la lógica según `transactionConfig` (o `version === 1`), no según la presencia de instrucciones de ComputeBudget, ya que una transacción heredada sin comisión de prioridad tampoco las contiene.
## Decodifica bytes sin procesar de transacciones con un analizador compatible con v1
Esta sección solo se aplica si consumes bytes sin procesar de transacciones, por ejemplo, desde [preconfSubscribe](/docs/es/pre-confirmations/preconf-subscribe), [preprocessedSubscribe](/docs/es/preprocessed-transactions/preprocessed-subscribe) o una respuesta RPC codificada con `base64`. Si trabajas con respuestas `json` o `jsonParsed`, omite esta sección.
Las transacciones v1 cambian el formato de transmisión de dos maneras:
* **Byte de versión.** Una transacción v1 comienza con `0x81` (129 en decimal). Una transacción v0 comienza con `0x80`.
* **Las firmas se trasladan al final.** Las transacciones heredadas y v0 colocan primero las firmas y luego el mensaje. Las transacciones v1 colocan primero el mensaje y las firmas al final, por lo que los decodificadores de estilo `bincode` que esperan un arreglo inicial de firmas fallan con los bytes de v1.
Para ver una explicación campo por campo del formato de transmisión v1, consulta [Transacciones v1 en el artículo sobre versiones de transacciones de Solana](https://www.helius.dev/blog/solana-transaction-versions#transaction-v1).
Usa un decodificador que comprenda el formato v1:
* **Rust:** [`agave-transaction-view`](https://docs.rs/agave-transaction-view) analiza transacciones heredadas, v0 y v1 directamente. [`wincode`](https://docs.rs/wincode), el serializador compatible con bincode que usan los SDK actuales de Solana, también decodifica v1 en `VersionedTransaction`.
* **JavaScript / TypeScript:** `@solana/kit` 8.0+ o `@solana/web3.js` v3.
Los decodificadores personalizados deben comprobar el primer byte: `0x81` indica v1, y las firmas aparecen después del mensaje en lugar de antes.
## Lista de verificación
1. Busca con grep `getBlock`, `getTransaction`, `getTransactionsForAddress`, `transactionSubscribe` e `blockSubscribe`, incluidos los cuerpos JSON-RPC sin procesar y los wrappers de SDK como `connection.getParsedTransaction`.
2. Actualiza a un SDK compatible con v1.
3. Establece `maxSupportedTransactionVersion: 1` en cada llamada encontrada en el paso 1.
4. Reemplaza la búsqueda de instrucciones de ComputeBudget por una comprobación de `transactionConfig` y trata `priorityFee` como el total de lamports.
5. Reemplaza los decodificadores sin procesar de estilo `bincode` por `agave-transaction-view` o un SDK actualizado.
6. Actualiza las dependencias de streaming a las versiones de la tabla anterior.
7. Busca con grep `-32015` en los registros después del cambio para confirmar que nada siga fallando.
Para profundizar en las especificaciones de las versiones de transacciones de Solana, los formatos de transmisión y los ejemplos, lee nuestro artículo [Versiones de transacciones de Solana: heredadas, v0 y v1](https://www.helius.dev/blog/solana-transaction-versions).
## Recursos relacionados
Parámetros, estructura de la respuesta y ejemplos para obtener una sola transacción.
Obtén un bloque completo, incluidas todas las transacciones que contiene.
Historial de transacciones filtrado y paginado para cualquier dirección en una sola llamada.
Todos los cambios incompatibles de Agave 4.2, con los pasos para solucionarlos.