A TypeScript decoder for raw Solana shreds
A Node.js receiver that reads shreds from a UDP port, rebuilds each block component from its data shreds, and decodes every legacy, v0 and v1 transaction with @solana/kit. The framing between shreds and transactions is the part you write yourself; this page gives you that code, tested.
Yes, you can decode Solana shreds in TypeScript. Read the 88-byte data shred header yourself, join data shreds into block components, walk the entry framing to cut out each transaction, then pass those exact bytes to @solana/kit. The decoder below does that for legacy, v0 and v1 transactions, and keeps your UDP socket drained.
What JavaScript can and cannot do here#
There is no official shred parser for JavaScript. The shred header and the entry batches inside a block are simple binary layouts, so this page reads them by hand with a DataView. Transactions are a different story: three wire formats are live on mainnet, and @solana/kit already decodes all of them into signatures, account keys and instructions.
One detail shapes the code. Kit 8.6.0 decodes any transaction correctly when it gets exactly that transaction's bytes, but it treats whatever it is given as one transaction: inside an entry batch, its streaming reader runs on to the end of the buffer. In our test it reported 833 bytes for a 793-byte v1 transaction, 1,020 for a 980-byte v0 and 861 for an 821-byte legacy one, every time swallowing the 40 bytes that followed. So transactionLength measures each transaction first, and kit only ever sees an exact slice.
Recovery from coding shreds is the other thing this page leaves out, to keep the decoder short: it uses data shreds only. What that costs is spelled out below.
Steps#
- Bind a
dgramsocket and keep its handler short: read, assemble, hand off. - Check the variant byte at offset 64.
0x9_and0xB_are data shreds; coding shreds and anything else, including the verification packet, are skipped. - Read the slot (offset 65), the index (73), the flags (85) and the
sizefield (86), which says how much of the datagram is payload. - Collect data shreds per slot. A run of shreds that ends with the
DATA_COMPLETEflag (0x40) is one block component. - Read the component: a u64 entry count of zero means a header or footer marker; otherwise each entry has
num_hashes, a 32-byte hash and a u64 transaction count. - Measure each transaction with
transactionLength, decode that slice with kit, and print one JSON line per transaction from a worker thread.
package.json#
{"private": true,"type": "module","dependencies": {"@solana/kit": "8.6.0"},"devDependencies": {"@types/node": "24.10.1","typescript": "5.9.2"},"scripts": {"test": "node test.ts ../../examples/fixtures/shreds/470901815.shreds ../../examples/fixtures/shreds/470901816.shreds && node test-recipes.ts && node test-quickstart.ts","typecheck": "tsc -p ."}}
decoder.ts#
// Raw Solana shreds in, transactions out, in TypeScript.// The shred header and the entry framing are read by hand; each transaction is decoded by @solana/kit 8.6.0.// No erasure recovery: coding shreds are skipped, so a lost data shred costs the block component it belongs to.import {getTransactionDecoder,getCompiledTransactionMessageDecoder,getBase58Decoder,} from "@solana/kit";const txDecoder = getTransactionDecoder();const messageDecoder = getCompiledTransactionMessageDecoder();const base58 = getBase58Decoder();const DATA_COMPLETE = 0x40;export type DataShred = { slot: bigint; index: number; flags: number; payload: Uint8Array };export type TxLine = { slot: number; signature: string; version: string; feePayer: string; programs: string[] };/** Read one UDP datagram. Returns a data shred, or null for coding shreds and anything that is not a shred. */export function readDataShred(buf: Uint8Array): DataShred | null {if (buf.length < 88) return null;const kind = buf[64] & 0xf0; // variant byte, after the 64-byte signatureif (kind !== 0x90 && kind !== 0xb0) return null; // 0x9_ and 0xB_ are Merkle data shredsconst v = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);const size = v.getUint16(86, true); // headers plus payloadif (size < 88 || size > buf.length) return null;return { slot: v.getBigUint64(65, true), index: v.getUint32(73, true), flags: buf[85], payload: buf.subarray(88, size) };}/** Groups data shreds by slot and returns each block component as soon as all of its shreds are in. */export class Assembler {private slots = new Map<bigint, { shreds: Map<number, DataShred>; starts: Set<number>; done: Set<number> }>();push(s: DataShred): Uint8Array[] {let st = this.slots.get(s.slot);if (!st) this.slots.set(s.slot, (st = { shreds: new Map(), starts: new Set([0]), done: new Set() }));if (st.shreds.has(s.index)) return []; // duplicate datagramst.shreds.set(s.index, s);if (s.flags & DATA_COMPLETE) st.starts.add(s.index + 1);const ready: Uint8Array[] = [];for (const start of [...st.starts].sort((a, b) => a - b)) {if (st.done.has(start)) continue;let end = start;while (st.shreds.has(end) && !(st.shreds.get(end)!.flags & DATA_COMPLETE)) end++;if (!st.shreds.has(end)) continue; // still missing a shred of this componentconst parts = [];for (let i = start; i <= end; i++) parts.push(st.shreds.get(i)!.payload);ready.push(Buffer.concat(parts));st.done.add(start);}return ready;}/** Drop slots far behind the newest one, so memory stays bounded. */forgetBefore(slot: bigint) { for (const k of this.slots.keys()) if (k < slot) this.slots.delete(k); }}/** Walk one block component. An entry batch starts with a non-zero u64 count; a zero count marks a header or footer.* Yields the exact bytes of each transaction, in block order. */export function* transactionSlices(component: Uint8Array): Generator<Uint8Array> {const v = new DataView(component.buffer, component.byteOffset, component.byteLength);const entries = v.getBigUint64(0, true);let o = 8;for (let e = 0n; e < entries; e++) {o += 8 + 32; // num_hashes (u64) and the entry hashconst count = Number(v.getBigUint64(o, true)); o += 8;for (let t = 0; t < count; t++) {const len = transactionLength(component, o); // kit 8.6.0 reads to the end of the buffer, so slice firstyield component.subarray(o, o + len);o += len;}}}/** Every transaction in a block component, decoded by kit. */export function* transactionsIn(component: Uint8Array): Generator<ReturnType<typeof txDecoder.decode>> {for (const bytes of transactionSlices(component)) yield txDecoder.decode(bytes);}/** Compact-u16 ("shortvec"): 7 bits per byte, high bit set while more bytes follow. */function shortvec(b: Uint8Array, o: number): [value: number, next: number] {let value = 0, shift = 0;for (;;) { const byte = b[o++]; value |= (byte & 0x7f) << shift; if (!(byte & 0x80)) return [value, o]; shift += 7; }}/** Byte length of the serialized transaction that starts at `start` (legacy, v0 or v1). */export function transactionLength(b: Uint8Array, start: number): number {const v = new DataView(b.buffer, b.byteOffset, b.byteLength);if (b[start] === 129) {// v1 (SIMD-0385): fixed header, then addresses, config words, instruction headers and payloads; signatures LAST.const sigs = b[start + 1], mask = v.getUint32(start + 4, true);const instructions = b[start + 40], addresses = b[start + 41];let configWords = 0; for (let m = mask; m; m &= m - 1) configWords++;const headers = start + 42 + 32 * addresses + 4 * configWords;let o = headers + 4 * instructions;for (let i = 0; i < instructions; i++) o += b[headers + 4 * i + 1] + v.getUint16(headers + 4 * i + 2, true);return o + 64 * sigs - start;}let o = start, n: number;[n, o] = shortvec(b, o); o += 64 * n; // signatures first in legacy and v0const v0 = (b[o] & 0x80) !== 0; if (v0) o++; // v0 messages start with a version byteo += 3; // message header[n, o] = shortvec(b, o); o += 32 * n + 32; // account keys, recent blockhashlet ixs: number; [ixs, o] = shortvec(b, o);for (let i = 0; i < ixs; i++) { o++; [n, o] = shortvec(b, o); o += n; [n, o] = shortvec(b, o); o += n; }if (v0) {let tables: number; [tables, o] = shortvec(b, o);for (let i = 0; i < tables; i++) { o += 32; [n, o] = shortvec(b, o); o += n; [n, o] = shortvec(b, o); o += n; }}return o - start;}/** One JSON-ready line per transaction. */export function describe(slot: bigint, tx: ReturnType<typeof txDecoder.decode>): TxLine {const message = messageDecoder.decode(tx.messageBytes);const keys = message.staticAccounts;const first = Object.values(tx.signatures)[0];return {slot: Number(slot),signature: first ? base58.decode(first) : "",version: String(message.version),feePayer: keys[0],// legacy and v0 list `instructions`; v1 splits them into `instructionHeaders` and payloadsprograms: [...new Set(("instructionHeaders" in message? message.instructionHeaders.map((h) => h.programAccountIndex): message.instructions.map((ix) => ix.programAddressIndex)).map((i) => keys[i]))],};}
decode-worker.ts#
// Worker thread: turns completed block components into JSON lines, so the UDP thread only reads and assembles.import { parentPort } from "node:worker_threads";import { transactionsIn, describe } from "./decoder.ts";parentPort!.on("message", ({ slot, component }: { slot: bigint; component: Uint8Array }) => {try {for (const tx of transactionsIn(component)) process.stdout.write(JSON.stringify(describe(slot, tx)) + "\n");} catch (err) {process.stderr.write(`slot ${slot}: skipped a component: ${(err as Error).message}\n`);}});
receiver.ts#
// Listen on a UDP port and print every decoded transaction as one JSON line.// Node 24 runs TypeScript directly: node receiver.ts 8001// The socket thread only reads shreds and assembles block components; a worker decodes them.// Decoding inline would stall the socket while the kernel buffer overflows, and UDP drops what does not fit.import dgram from "node:dgram";import { Worker } from "node:worker_threads";import { Assembler, readDataShred } from "./decoder.ts";const port = Number(process.argv[2] ?? 8001);// WORKER=./filter-worker.ts swaps in the program filter from the filtering page (D10)const decoder = new Worker(new URL(process.env.WORKER ?? "./decode-worker.ts", import.meta.url));const sock = dgram.createSocket({ type: "udp4", recvBufferSize: 64 * 1024 * 1024 });const assembler = new Assembler();let newest = 0n;sock.on("message", (buf) => {const shred = readDataShred(buf);if (!shred) return; // coding shreds, verification packets, noiseif (shred.slot > newest) { newest = shred.slot; assembler.forgetBefore(newest - 64n); }for (const component of assembler.push(shred)) decoder.postMessage({ slot: shred.slot, component });});sock.bind(port, () => console.error(`listening on udp/${port}`));
Running it#
Use Node 24, which runs TypeScript files directly. Install with npm ci, and open your port to inbound UDP without a rule on where it comes from, since our sending port changes. Then start node receiver.ts 8001 with the port your stream arrives on. Each transaction becomes one line:
{"slot":470901815,"signature":"36rFNmu3EShgKrPSipWyK6A8Yn58jWuHYrByCDDJCFVKzLCMiAGu4mFD4hw5zVKABJnenQSYmhbTWUhJfPsUKiuy","version":"1","feePayer":"4M1ViRmsMu2vHBSsWK4b2PMKjQihwzXv78Luy3si5Moi","programs":["Archer8kgiavM61GyusMzaaS2ft5sALtNsD1HxkUPMhy"]}
version is legacy, 0 or 1. programs lists the programs a transaction's top-level instructions call; for v0 they are always static keys, so no lookup table needs resolving for it. The receiver ignores datagrams that are not shreds, which includes the verification packet sent during activation; read that one with a plain listener such as nc -ul 8001, as checking delivery explains, and start the decoder afterwards.
Why a worker thread: on our test machine, decoding inline handled about 9,000 datagrams a second, most of it spent turning account keys into base58 strings. In a local replay over loopback at 20,000 datagrams a second, a test rate rather than the feed's, an inline decoder lost more than half the packets, because UDP drops whatever the socket buffer cannot hold. With decoding moved to the worker, the same run lost nothing.
Fixture run#
The fixtures are two consecutive mainnet blocks, fetched with getBlock and shredded locally by Agave 4.4.1's own Shredder, so the transactions and their order are real. Tests: node test.ts on Node 24.14 with @solana/kit 8.6.0, TypeScript 5.9.2 in strict mode.
| Test | Result |
|---|---|
| Every data shred, read from the capture file | 269 of 269 and 512 of 512 transactions, in block order |
| Versions decoded | 178 legacy, 331 v0 and 272 v1 |
| Local replay over UDP at 20,000 datagrams a second (a test rate, not the feed's rate), shuffled, every 5th datagram sent twice | 269 of 269 and 512 of 512, no repeats, nothing foreign |
| One data shred lost mid-slot | 256 of 269 and 448 of 512: only the 13 and 64 transactions of the affected component are missing |
Limits of skipping FEC recovery#
A block component is often dozens of data shreds long. Lose one of them and this decoder drops the whole component, even though the coding shreds that arrived alongside could have rebuilt it. In the test above, a single lost shred cost 64 transactions. That is fine for alerts and dashboards that can miss the odd batch; it is not fine for a ledger of every transaction.
If you need completeness, put recovery in front of the decoder: the Rust decoder rebuilds lost data shreds from coding shreds, and the pipeline map shows where recovery sits. This decoder also reports what a transaction asked for, not what happened: shreds carry no success flag, logs or balance changes.
Questions#
Can I decode Solana shreds in JavaScript?#
Yes. Parse the shred header and the entry framing yourself, as above, and let @solana/kit decode the transactions. Nothing beyond kit is needed at runtime.
Does @solana/web3.js work instead of kit?#
This page uses kit 8.6.0 because we tested it against legacy, v0 and v1 fixtures. We have not tested the older web3.js 1.x against v1 transactions, so it is not used here.
Why measure transaction lengths by hand?#
Because kit assumes the bytes it gets are one whole transaction. Inside an entry batch more transactions follow, and its streaming reader runs into them, for legacy, v0 and v1 alike. Decoding an exact slice works for every version, so the decoder finds each slice first.
Next#
Versioned transactions explained covers the three formats, and decode token transfers builds on these lines. If you are still choosing a language, Rust, Go, Python or TypeScript for a decoder weighs them side by side. To run it on a live stream, see pricing.
Sources#
- @solana/kit 8.6.0 (anza-xyz/kit): getTransactionDecoder and getCompiledTransactionMessageDecoder (checked 2026-11-18)
- Agave v4.4.1 ledger/src/shred.rs: common header offsets, variant byte, data shred flags and size (checked 2026-11-18)
- Agave v4.4.1 entry/src/block_component.rs: entry batches and markers inside a block (checked 2026-11-18)
- SIMD-0385, the v1 wire format: a leading 129 byte, and signatures placed after the message (checked 2026-11-18)
- Fixtures: mainnet blocks 470,901,815 and 470,901,816 (getBlock), shredded locally with the Agave 4.4.1 Shredder (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.