Versioned transactions

Solana ondersteunt drie transactieformaten: legacy, v0 en v1. Elk formaat wordt hieronder beschreven aan de hand van dezelfde drie onderdelen: hoe de bytes op de wire worden ingedeeld, hoe accounts worden gerefereerd en waar de resourcelimieten vandaan komen.

Formaatoverzicht

Ga naar: Legacy · v0 · v1

Legacy-formaat

Het originele formaat, en nog steeds de standaard in de meeste tooling. Het heeft helemaal geen versieprefix: de eerste byte van de transactie is de compact-u16-teller van de handtekeningenarray, en de eerste byte van het bericht is num_required_signatures, waarvan het hoogste bit altijd niet is ingesteld.

Legacy wire-indeling

Elke array met variabele lengte wordt voorafgegaan door een compact-u16-lengte: 1 byte voor waarden 0–127, 2–3 bytes voor grotere waarden. Zie voor de indeling per instructie en een uitgewerkte grootteberekening binair transactieformaat.

Accounts in legacy

Elk account wordt als volledige 32-byte publieke sleutel in account_keys opgeschreven, en instructies verwijzen ernaar via een 1-byte-index in die array. Er is geen manier om te verwijzen naar een account dat niet expliciet in de transactie is opgenomen, wat bewerkstelligt dat een legacy-transactie beperkt blijft tot ongeveer 32 accounts voordat de 1.232 bytes zijn opgebruikt.

Resourcelimieten in legacy

De limiet voor rekeneenheden, de datalimiet voor geladen accounts, de heapgrootte en de prioriteitstoeslag worden allemaal aangevraagd door ComputeBudget-programma-instructies in de transactie op te nemen. Elk kost een instructie-slot en 150 rekeneenheden. Weglaten is veilig: de runtime valt terug op standaardwaarden van 200.000 CU per instructie (maximaal 1,4M), een datalimiet van 64 MiB, een heap van 32 KiB en een prioriteitstoeslag van nul.

V0-formaat

v0 is een legacy-bericht plus twee zaken: een versieprefix-byte 0x80 en een address_table_lookups-array die na de instructies wordt toegevoegd. Alles daarvoor is byte-identiek aan legacy.

V0-wire-indeling

Elke adrestabel-opzoekvermelding bevat:

Address lookup-tabellen

Een ALT is een onchain-account dat tot 256 publieke sleutels opslaat. Door naar een ALT te verwijzen, kan een transactie aanvullende accounts opnemen met behulp van 1-byte indices in plaats van 32-byte publieke sleutels, waardoor de overhead per account aanzienlijk wordt verminderd.

Tijdens runtime, voordat de uitvoering begint, lost de validator alle ALT-verwijzingen op naar volledige publieke sleutels. De opgeloste adressen worden toegevoegd aan de statische account sleutels om de volledige lijst met accountsleutels te vormen. ALT-opgeloste accounts volgen dezelfde volgorde als statische accounts: schrijfbare opzoekingen komen vóór alleen-lezen opzoekingen.

Resourcelimieten in v0

Ongewijzigd ten opzichte van legacy: ComputeBudget-instructies, met dezelfde standaardwaarden wanneer ze worden weggelaten.

V1-formaat

v1 verhoogt de groottelimiet naar 4.096 bytes en herstructureert het bericht rond een transactieconfiguratie: resourcelimieten verhuizen uit ComputeBudget-instructies naar velden op vaste posities in het bericht zelf. Hierdoor kan het netwerk een transactie rangschikken op prioriteitstoeslag met één read op een vast offset, in plaats van de instructielijst te scannen en te deserialiseren.

V1-wire-indeling

Twee structurele verschillen ten opzichte van legacy en v0 zijn het vermelden waard bij het schrijven van een decoder. De tellers zijn u8-velden met vaste breedte in plaats van compact-u16, en de instructies zijn opgesplitst in twee reeksen: eerst alle headers met vaste grootte, dan alle payloads met variabele lengte, in plaats van elke instructie aaneengesloten.

Accounts in v1: geen address lookup-tabellen

v1 verwijdert ALT-ondersteuning bewust. 64 ruwe adressen is 2.048 bytes, ruimschoots binnen de limiet van 4.096 bytes, dus elk adres is inline zoals in legacy. Als je applicatie afhankelijk is van lookup-tabellen, betekent overstappen naar v1 dat je die adressen inline moet opnemen.

Resourcelimieten in v1: de transactieconfiguratie

De configuratie is een u32-bitmasker gevolgd door waarden met vaste breedte voor elk veld waarvan het bit is ingesteld:

Onbekende bits worden afgewezen. Omdat het bericht ondertekend is, kunnen niet-herkende configuratievelden niet stilzwijgend worden weggelaten.

ComputeBudget-instructies zijn no-ops in v1

Een v1-transactie wijst ComputeBudget-instructies niet af — ze worden genegeerd voor configuratie. Ze worden nog steeds uitgevoerd als succesvolle no-ops, verbruiken 150 rekeneenheden en één van de 64 instructie-slots, zonder enig effect op het budget. Verwijder ze bij het bouwen van v1-transacties en stop met het scannen ernaar bij het lezen van v1-transacties: de waarden staan in de berichtconfiguratie.

Configuratievelden moeten expliciet worden ingesteld

De belangrijkste gedragswijziging voor verzenders: in tegenstelling tot legacy en v0 moeten v1-transacties de limiet voor rekeneenheden en de datalimiet voor geladen accounts expliciet instellen, anders mislukt je transactie.

De aanbevolen aanpak is om eenmalig te simuleren met beide limieten gemaximaliseerd, vervolgens de teruggegeven unitsConsumed en loadedAccountsDataSize terug te schrijven naar de configuratie, waarbij de datagrootte naar boven wordt afgerond naar de volgende 32 KiB-pagina voor marge (het blokkostenmodel rekent in 32 KiB-pagina's, dus marge onder de volgende paginagrens is gratis).

Voorbereiden op v1

v1 verandert het lezen van transacties, niet alleen het verzenden ervan. Wanneer v1 actief wordt, zal elke client die getTransaction of getBlock aanroept zonder in te schrijven falen op v1-transacties:

• Geef maxSupportedTransactionVersion: 1 door — het JSON-geheel getal 1, niet de string "1" — aan getTransaction en getBlock. 0 doorgeven mislukt op v1-transacties net als het weglaten van de parameter, dus een codebase die tijdens de v0- uitrol is bijgewerkt, moet de waarde alsnog wijzigen.
• getTransaction mislukt bij een v1-transactie met fout -32015, en één v1- transactie laat een volledige getBlock-respons mislukken met dezelfde fout — er is geen gedeeltelijk resultaat.
• blockSubscribe geeft block: null terug en stopt met vooruitgaan, zodat een consumer die dit als een leeg blok leest stilzwijgend achteropraakt vanaf de eerste v1-slot.
• getSignaturesForAddress inspecteert nooit transactie-inhoud, dus v1-handtekeningen worden normaal weergegeven.
• Ingeschreven responses bevatten een transactionConfig-object in het bericht voor v1- transacties (volledig afwezig voor legacy en v0). Pipelines die prioriteitstoeslagen of limieten voor rekeneenheden afleiden door te scannen op ComputeBudget-instructies rapporteren stilzwijgend nul voor elke v1-transactie.
• Gebruik encoding: 'base64' wanneer je transacties aan clientzijde decodeert, en voor sendTransaction/simulateTransaction met transacties groter dan 1.232 bytes — base58-codering blijft beperkt tot de oude grootte.
• Ondersteuning voor clientbibliotheken vereist recente versies: @solana/kit 8.0+, Agave 4.2.x-generatie Rust-crates, of web3.js v3. web3.js v1 leest v1 vanaf 1.99.0 en hoger, maar kan het niet bouwen of verzenden.

Voor de volledige migratiegids — inclusief ondersteuning voor clientbibliotheken, streaming (Geyser/gRPC) versiedetectie en simulatiegedrag — zie de upgradepagina voor transactieformaat v1.