Resolving address lookup tables when you decode from shreds
A v0 transaction names some of its accounts only by table and index. This recipe resolves them with a small cache in TypeScript: parse the table account, apply the same-slot rule, warm up per batch, refetch when a table has grown, and return nothing rather than a guess when a table is gone.
To resolve an address lookup table for a v0 transaction, fetch the table account, skip its 56-byte header, and read 32-byte addresses at the indexes the transaction lists: all writable lookups first, then all readonly ones, appended after the static keys. A cache makes it fast; refetch a table when an index points past its cached length.
The cache, decision by decision#
| Situation | What the cache does | Why |
|---|---|---|
| A table it has never seen | fetch it, batched with every other unknown table | one getMultipleAccounts call takes up to 100 accounts |
| A new entry batch arrives | warm up: fetch all its unknown tables at once | one call per batch instead of one per table |
| An index past the cached length | refetch that table once | the table was extended after you cached it; existing positions never change |
| Addresses added in the same slot | not usable by that transaction | the table records its last extended slot and the length before it |
| The table account no longer exists | return null and remember it | a closed table cannot be resolved from current state; do not guess or refetch forever |
| A deactivated table | keep using it | it stays usable while its deactivation slot is still in the 512 most recent SlotHashes entries |
Steps#
- Parse the v0 transaction and collect its lookups: a table address plus writable and readonly index lists.
- Before resolving an entry batch, warm the cache with every table the batch uses.
- For each transaction, refetch any table whose cached length is too short for the indexes it needs.
- Apply the same-slot rule: if the table was extended in the transaction's own slot, only the addresses before that extension count.
- Build the full list: static keys, then each table's writable picks in lookup order, then each table's readonly picks.
- If a table is gone, mark the transaction unresolved and settle it later from RPC.
alt.ts: parse a table and resolve one transaction#
// Resolve v0 address lookup tables. Layout: solana-address-lookup-table-interface 4.0.0 src/state.rs// (LOOKUP_TABLE_META_SIZE = 56, then 32-byte addresses). Rules: get_active_addresses_len.import { b58, fromB58 } from "./base58.ts";import type { Tx } from "./tx.ts";export type LookupTable = { deactivationSlot: bigint; lastExtendedSlot: bigint; lastExtendedStartIndex: number; addresses: string[] };export function parseLookupTable(data: Uint8Array): LookupTable {const v = new DataView(data.buffer, data.byteOffset, data.byteLength);if (v.getUint32(0, true) !== 1) throw new Error("not an initialized lookup table");const addresses: string[] = [];for (let o = 56; o + 32 <= data.length; o += 32) addresses.push(b58(data.subarray(o, o + 32)));return { deactivationSlot: v.getBigUint64(4, true), lastExtendedSlot: v.getBigUint64(12, true),lastExtendedStartIndex: data[20], addresses };}/** Addresses a transaction in `slot` may use: ones appended in that same slot are not usable yet. */export function activeAddresses(t: LookupTable, slot: bigint): string[] {return slot > t.lastExtendedSlot ? t.addresses : t.addresses.slice(0, t.lastExtendedStartIndex);}export type Resolved = { accountKeys: string[]; writableLoaded: string[]; readonlyLoaded: string[] };/** Full account list for a v0 transaction: static keys, then all writable lookups, then all readonly lookups.* Throws when a table is missing or an index is past its active length: refetch the table and retry. */export function resolve(tx: Tx, slot: bigint, getTable: (key: string) => LookupTable | undefined): Resolved {const writableLoaded: string[] = [], readonlyLoaded: string[] = [];for (const l of tx.lookups) {const t = getTable(l.table);if (!t) throw new Error(`lookup table ${l.table} not cached`);// A deactivated table can still be used until it is closed; a closed one simply is not found.const active = activeAddresses(t, slot);const pick = (i: number) => { if (i >= active.length) throw new Error(`index ${i} past active length of ${l.table}`); return active[i]; };writableLoaded.push(...l.writable.map(pick));readonlyLoaded.push(...l.readonly.map(pick));}return { accountKeys: [...tx.staticKeys, ...writableLoaded, ...readonlyLoaded], writableLoaded, readonlyLoaded };}export { fromB58 };
alt-cache.ts: fetch, warm up, refresh#
// A lookup table cache for a shred decoder: fetch unknown tables in one batched RPC call, refresh a table when a// transaction points past its cached length (it was extended), and remember tables that no longer exist.// Layout and rules: alt.ts (solana-address-lookup-table-interface 4.0.0).import { parseLookupTable, resolve, type LookupTable, type Resolved } from "./alt.ts";import type { Tx } from "./tx.ts";type Rpc = (method: string, params: unknown[]) => Promise<any>;export function jsonRpc(url: string): Rpc {return async (method, params) => {for (let attempt = 0; ; attempt++) {const r = await fetch(url, { method: "POST", headers: { "content-type": "application/json" },body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }) });if (r.status === 429 && attempt < 5) { await new Promise((ok) => setTimeout(ok, 500 * 2 ** attempt)); continue; }const j = await r.json();if (j.error) throw new Error(`${method}: ${j.error.message}`);return j.result;}};}export class LookupTableCache {private tables = new Map<string, LookupTable>();private missing = new Set<string>(); // closed or never existed: do not refetch on every transactionprivate rpc: Rpc;fetches = 0;constructor(rpc: Rpc) { this.rpc = rpc; }/** Fetch tables we do not hold (or must refresh), up to 100 per getMultipleAccounts call. */async load(keys: string[]): Promise<void> {const want = [...new Set(keys)];for (let i = 0; i < want.length; i += 100) {const batch = want.slice(i, i + 100);const res = await this.rpc("getMultipleAccounts", [batch, { encoding: "base64", commitment: "confirmed" }]);this.fetches++;res.value.forEach((acc: any, j: number) => {if (!acc) { this.missing.add(batch[j]); this.tables.delete(batch[j]); return; }this.tables.set(batch[j], parseLookupTable(Buffer.from(acc.data[0], "base64")));});}}/** Warm up: fetch every unknown table used by a batch of transactions (say, one entry batch) in one go. */async warm(txs: Tx[]): Promise<void> {const keys = txs.flatMap((t) => t.lookups.map((l) => l.table)).filter((k) => !this.tables.has(k) && !this.missing.has(k));if (keys.length) await this.load(keys);}/** Resolve a v0 transaction seen in `slot`. Returns null when a table is gone (closed before we saw it). */async resolve(tx: Tx, slot: bigint): Promise<Resolved | null> {const unknown = tx.lookups.map((l) => l.table).filter((k) => !this.tables.has(k) && !this.missing.has(k));if (unknown.length) await this.load(unknown);// A cached table shorter than an index we need was extended since we fetched it: refetch it once.const stale = tx.lookups.filter((l) => {const t = this.tables.get(l.table);return t && Math.max(-1, ...l.writable, ...l.readonly) >= t.addresses.length;}).map((l) => l.table);if (stale.length) await this.load(stale);if (tx.lookups.some((l) => this.missing.has(l.table))) return null;return resolve(tx, slot, (k) => this.tables.get(k));}/** For tests: pretend we fetched a table before its last extension. */truncate(key: string, length: number) { const t = this.tables.get(key); if (t) t.addresses = t.addresses.slice(0, length); }}
Using it inside the decoder loop#
// The UDP receiver with lookup table resolution: every v0 transaction's full account list, or "unresolved".// RPC_URL=https://your-rpc node src/receiver-with-alts.ts 8001import dgram from "node:dgram";import { parseShred, SlotAssembler, parseComponent } from "./shreds.ts";import { decodeTx } from "./tx.ts";import { LookupTableCache, jsonRpc } from "./alt-cache.ts";const tables = new LookupTableCache(jsonRpc(process.env.RPC_URL ?? "https://api.mainnet-beta.solana.com"));const asm = new SlotAssembler();let queue = Promise.resolve(); // resolve batches one after another, never on the socket's thread of controlasync function onEntryBatch(slot: bigint, rawTransactions: Uint8Array[]) {const txs = rawTransactions.map(decodeTx);await tables.warm(txs.filter((t) => t.version === 0)); // one RPC call for every new table in the batchfor (const tx of txs) {const resolved = tx.version === 0 ? await tables.resolve(tx, slot) : { accountKeys: tx.staticKeys };if (!resolved) { console.error(`slot ${slot}: unresolved ${tx.signatures[0]}`); continue; }console.log(JSON.stringify({ slot: Number(slot), signature: tx.signatures[0], version: tx.version, accounts: resolved.accountKeys }));}}const sock = dgram.createSocket({ type: "udp4", recvBufferSize: 64 * 1024 * 1024 });sock.on("message", (buf) => {const shred = parseShred(buf);if (!shred) return;for (const run of asm.push(shred)) {let c; try { c = parseComponent(run); } catch { continue; }if (c.kind !== "entries") continue;const raws = c.entries.flatMap((e) => e.transactions);queue = queue.then(() => onEntryBatch(shred.slot, raws)).catch((e) => console.error(`slot ${shred.slot}: ${e.message}`));}});sock.bind(Number(process.argv[2] ?? 8001), () => console.error(`listening on udp/${process.argv[2] ?? 8001}`));
shreds.ts and tx.ts are the parsers from the TypeScript decoder. Legacy and v1 transactions carry every account inline and need no table. Resolution runs on a promise queue after the socket handler returns, so a slow RPC answer delays output but does not stop the receive loop.
How this code was tested#
The test serves the fixture table accounts from a local fake RPC and compares the result with what mainnet RPC itself reports as loadedAddresses for each transaction.
| Test | Result |
|---|---|
| Cold cache, every v0 transaction in two mainnet blocks | 331 of 331 match loadedAddresses, 31 RPC calls |
| Warmed once per block | 331 of 331 match, 2 RPC calls |
| A cached table truncated to zero addresses | refetched exactly once, resolved correctly |
| The RPC reports a table closed | null, and the table is not fetched again |
| The full receiver above, fixtures replayed over UDP | 781 of 781 lines carry exactly the account list RPC reports |
Node 24, no dependencies. The table accounts were read at slot 470,901,882, a little after the blocks, which is safe because tables only grow at the end.
Production notes#
- Use a commitment that matches your risk.
confirmedsees a fresh extension sooner thanfinalized; the same-slot rule protects you from using addresses the transaction could not have used. - Bound the cache. Busy tables are reused constantly; keep a size limit and evict the least recently used, but keep the "missing" set too, or a closed table costs you a call per transaction.
- Do not block the socket. Resolution waits on RPC. Run it after the receive loop hands transactions off, as the decoding pipeline suggests.
- Rate limits. A public RPC endpoint answers HTTP 429 under load; the client above backs off and retries, but plan on your own endpoint.
- Program IDs need none of this. They are always static keys, so you can filter by program before resolving anything.
When resolution is not possible#
Once a table has been closed, nothing in current state says what its indexes used to point at; only data saved at the time can. If your RPC lags behind the leader, a brand-new table may not exist yet when you ask. In both cases mark the transaction unresolved, keep its static keys and programs, and fill the rest when you reconcile with RPC. The concept behind all of this is covered in address lookup tables, and the lookup table problem discusses the trade-offs.
Next#
Feed the resolved accounts to the Anchor instruction decoder. To run all of it on your own feed, see pricing.
Sources#
- anza-xyz/solana-sdk address-lookup-table-interface src/state.rs: 56-byte meta, active length, deactivation status (checked 2026-11-18)
- anza-xyz/solana-sdk message v0: account order static, writable lookups, readonly lookups (checked 2026-11-18)
- Solana RPC: getMultipleAccounts (up to 100 accounts per call) (checked 2026-11-18)
- Fixtures: mainnet blocks 470,901,815 and 470,901,816 with meta.loadedAddresses; lookup table accounts read at slot 470,901,882 (checked 2026-11-18)
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.