Decoding · November 18, 2026 · 7 min read

The lookup table problem: decoding v0 transactions before anyone confirms them

A v0 transaction names many of its accounts by table position, not by key. That one design choice is why your decoded account lists come out short, and why the fix is a cache with rules rather than a single RPC call.

V0 transactions are hard to decode from shreds because many of their account keys are not in the transaction at all. The message lists lookup table addresses and positions inside those tables, so a decoder only learns which accounts an instruction touches after reading each table's current contents from chain state that the shred never carries.

What a v0 message carries instead of keys#

A version 0 message starts with a byte whose top bit is set (0x80), then lists static account keys like a legacy message. After the instructions comes a list of address_table_lookups. Each lookup holds one table account key plus two index arrays, one for writable entries and one for read-only entries.

The full account list a program sees is built in a fixed order:

  1. the static keys, in message order;
  2. every writable key pulled from the tables, lookup by lookup;
  3. every read-only key pulled from the tables, in the same lookup order.

Instructions refer to accounts by position in that combined list. So an instruction that says "account 23" means nothing until you have expanded the tables. The shred gives you the number 23 and the table's address. It does not give you the address stored at that position.

Version 1 transactions, live on mainnet since epoch 1035, do not support lookup tables at all, so this whole problem applies to v0 traffic only.

A real launch, counted index by index#

Take the Pump.fun launch in slot 470,908,254 with signature 3mNhCdgj…U718B (linked in the sources). It is a v0 transaction with 17 static keys and one lookup table that supplies 17 more: 6 writable and 11 read-only.

Position in the account listWhere it comes fromWhat a shred-only decoder knows
0 to 16static keys in the messagethe full address
17 to 22the table's writable indexesonly "table entries 16, 19, 22, 49, 30 and 73"
23 to 33the table's read-only indexesonly "table entries 158, 1, 10, 11, 18, 3, 124, 12, 4, 14 and 15"

The token creation instruction in that transaction lists 16 accounts. Eight of them sit at positions 17, 18 and 23 to 28, all table entries. Without the table, the decoder cannot name the program's mint authority, its global config account, its event authority or even the token program, although the instruction data itself decodes cleanly.

Three ways to get the table contents#

Every decoder ends up choosing one of these, or a mix:

StrategyHow it worksCorrectnessDependency
Fetch on demandcall getAccountInfo or getMultipleAccounts when an unknown table appearsgood for tables that rarely changeone RPC round trip per new table
Cache with invalidationkeep decoded tables in memory, refresh when an index points past the known lengthgood, if refresh rules are rightRPC for misses and refreshes
Track the tables yourselfdecode lookup table program instructions in the stream and apply extends and deactivationsbest freshness, hardest to get righta warm-up snapshot, then your own state

The table account's data is a 56-byte metadata header followed by 32-byte addresses, so parsing it is easy. Keeping it current is the hard part.

The same-slot edge case#

Tables grow. When an owner extends a table, the new addresses are recorded with the slot of the extension, and a transaction in that same slot cannot use them. A deactivated table keeps resolving while its deactivation slot is still among the 512 most recent entries of the SlotHashes sysvar, and resolves nothing once it drops out and the table can be closed (E4 tech facts T-12).

That means a cache keyed only by table address can be wrong in both directions: it can hold addresses a transaction was not allowed to use yet, and it can miss addresses added a moment ago. A safe cache stores the slot it last saw for each table and refuses to resolve an index it cannot account for, rather than guessing.

When a key cannot be resolved, mark it#

Sooner or later a transaction will reference a table you have never seen, or an index beyond what you hold. Three rules keep that from corrupting your data:

  • Never guess. Do not fill the gap with a nearby index or a stale copy.
  • Record the reference. Store the table address and index, so the row can be completed later.
  • Flag the row. Mark it as partially resolved, and let downstream code decide whether to act on it.

A row with an honest gap can be repaired after the fact. A row with a wrong key looks fine and spreads the error.

Which strategy fits alerts, trading and indexing#

The right choice depends on what a wrong key costs you:

  • Alerts on a short watch list. Fetch on demand. You care about a handful of programs and wallets, so misses are rare and a round trip is acceptable.
  • Trading decisions. Cache with invalidation, warmed at start-up with the tables your target programs use. A miss should skip the trade, never fill in a guess.
  • Indexing. Track tables yourself if you can, and still reconcile against RPC, where loadedAddresses shows what the runtime actually used.

Trade-offs no cache removes#

A lookup cache fixes missing keys, not missing outcomes. Even with perfect tables, a decoded v0 transaction still lacks its execution result, its logs and its inner instructions, which only arrive after replay. A cache also adds state that can drift, so it needs its own tests and its own metrics for misses and refreshes. If your product cannot tolerate partially resolved rows for even a moment, read finished transactions from RPC instead of decoding raw ones.

Build the cache next#

For the concept in full, read how address lookup tables extend a message, and compare legacy, v0 and v1 messages if your decoder still assumes one format. The procedure lives in a lookup table cache, step by step. Keep unresolved rows in a provisional state and close them by checking against confirmed data. A Standard Shreds feed is enough to build and test all of this before speed matters.

Sources#

Raw shreds on your own server

Ultra Low Latency Shreds is $200 and Standard Shreds is $100. You pay in crypto, tell us which IPv4 address and UDP port should receive the stream, and we wire it up by hand.

Read nextWhat your decoder cannot see: the blind spots of shred data