A golden fixture pairs a captured input with decoded output you have checked by hand or against RPC. Keep real transactions in each format, store their expected decoded rows next to them, and diff the decoder's output in CI on every change, updating the expected files only when a program's layout changes on purpose.
Capturing inputs you can replay#
A decoder has two kinds of input, and it is worth keeping fixtures of both.
Transaction bytes. The simplest fixture is one raw transaction. getBlock and getTransaction can return transactions as base64 encoded bytes; ask for maxSupportedTransactionVersion 1 so that v0 and v1 transactions come back as well as legacy ones. Save the bytes with the slot and signature they came from. These fixtures test everything from message parsing upward and are small enough to keep in the repository.
Packet captures. To test the stages below the transaction (grouping, recovery, deshredding), you need the datagrams themselves. Record them on your receiver with a packet capture tool, for example tcpdump -w filtered to your UDP port, for a few slots. Packet captures are large and contain real traffic, so keep them out of the repository and in your own storage, and record a checksum in the repository instead.
Pick inputs on purpose rather than at random. You want each message format, each program you decode, transactions that failed on chain, transactions using lookup tables, and at least one slot that needed erasure recovery.
A fixture directory that stays readable#
| Path | Holds |
|---|---|
fixtures/tx/<signature>.bin | Raw transaction bytes, exactly as decoded from the stream or returned by RPC |
fixtures/tx/<signature>.meta.json | Slot, format, source, the date captured, and why this fixture exists |
fixtures/tx/<signature>.expected.json | The decoded output your decoder must produce, sorted and stable |
fixtures/slots/<slot>.sha256 | Checksum of a packet capture kept in external storage |
fixtures/slots/<slot>.expected.json | Signatures in entry order for that slot, as your pipeline should emit them |
Write a reason in every meta file. A year later, "covers a v0 swap whose pool sits in a lookup table" tells a reviewer why this fixture must never be deleted.
Writing expected output you can trust#
An expected file is only as good as the check behind it. Generate it from your decoder once, then verify it against an independent source before you commit it.
- Account keys. For v0 transactions,
getTransactionreturns the addresses loaded from lookup tables in its metadata. Compare them with your decoder's resolved key list; this is the most common place for silent errors. - Instruction arguments. Compare amounts and named accounts with the program's own IDL or source, or with an explorer's decoded view for the same signature.
- Order. For slot fixtures, compare the transaction order with the block returned by
getBlockfor that slot.
Make the output deterministic: sort keys, fix the number format, and leave out anything that changes between runs, such as timestamps of when you decoded.
Running fixtures in CI#
- For every transaction fixture, run the decoder on the
.binfile and write its output in the same canonical form as the expected file. - Diff the two. Any difference fails the build and prints the field that changed.
- For slot fixtures, fetch the capture by checksum from storage, replay it through the receiver stages and compare the emitted signature list.
- Allow an explicit update mode, set by an environment variable, that rewrites expected files. Never run it automatically.
- Require that a pull request which changes expected files says why, in the meta file or the description.
Refreshing after program upgrades#
Programs change their layouts. When one does, transactions before the upgrade still follow the old layout, and transactions after it follow the new one. Do not overwrite the old fixtures: they protect your decoder's handling of history. Add new fixtures from after the upgrade, record the slot ranges each layout covers, and make sure the decoder chooses the layout by slot. IDL drift covers how to version those layouts, and fuzzing the parser adds crash inputs to the same fixture set.
What golden fixtures cannot catch#
Fixtures only test the inputs you chose. A program you never captured, or a layout change that happens after your last capture, will not show up until you add a fixture for it. They also freeze your understanding at the moment you wrote the expected file; if that understanding was wrong and RPC agreed for the wrong reason, the fixture protects the bug. Recheck a sample of expected files against confirmed data from RPC whenever you change how you interpret a program.
Related pages#
Decoder test fixtures gives the how-to with the shared fixture set. If you need to keep packet captures for longer, archive formats compares the options. The transaction structure page explains the fields your expected files should cover. Fixtures are easiest to collect from your own receiver, so a Standard Shreds destination is a good place to record them.
Refresh the fixtures for a program as soon as an upgrade instruction for it shows up in the stream.
Test the filter stage as well: where to place the program filter changes which fixtures matter.
Sources#
- Solana RPC getTransaction (raw encodings, loadedAddresses in meta) (checked 2026-11-18)
- Solana RPC getBlock (maxSupportedTransactionVersion) (checked 2026-11-18)
- tcpdump manual (capturing UDP to pcap files) (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.