Pipelines · November 18, 2026 · 6 min read

Event schemas that last: modelling decoded Solana activity

The decoded events you publish today will be read by code written next year, after the programs behind them have changed. Separate what you saw from what you concluded, and version the conclusions.

Design a Solana event schema in two layers. The first holds raw facts that never change, such as the signature, slot, instruction index, program and account keys. The second holds interpretations, such as a swap with its amounts, each stamped with the layout and rule version that produced it, so upgrades add versions instead of rewriting history.

Two layers: raw facts and interpretations#

A decoded event mixes two kinds of information that age differently.

Raw facts are what the transaction literally contained: who signed it, which slot it appeared in, which program each instruction called, which accounts it passed and the bytes of its data. These never change. If you stored them correctly once, they are correct forever.

Interpretations are what your code concluded: that instruction 3 was a swap of token A for token B, that the input amount was a given number, that the transaction as a whole was arbitrage. These change whenever a program updates its layout, whenever you fix a bug in your decoder, and whenever you improve your rules.

Put them in the same record and every change to your interpretation forces you to rewrite the facts too. Keep them apart, link them by key, and you can reprocess interpretations as often as you like while the facts stay untouched.

Fields every event needs#

FieldLayerNotes
signaturerawThe first signature; the transaction's identity
slotrawThe slot the transaction was seen in; a transaction can appear in more than one fork
instruction indexrawPosition within the transaction; the identity of an instruction
program idrawThe program the instruction called
account keysrawIn instruction order, after resolving lookup tables
datarawThe instruction bytes, kept even after decoding
message formatrawLegacy, v0 or v1
statuslifecycleProvisional, then confirmed, failed or dropped
event typeinterpretationFor example swap, transfer, create, upgrade
event schema versioninterpretationThe version of this event type's fields
layout sourceinterpretationThe IDL or layout used, with its hash
rule versioninterpretationThe version of your classification rules
decoded fieldsinterpretationThe event type's own fields

Status sits between the layers. It is not an interpretation, because it comes from the chain, but it does change over time, so it gets its own update path.

Versioning interpretations#

Version two things separately: the shape of each event type, and the logic that fills it.

  • Event schema version changes when you add, remove or retype a field. Adding an optional field is the common case and should not break readers.
  • Rule version and layout source change when the same fields are filled differently, for example after a program upgrade or a decoder fix. The shape is identical; the values may not be.

Keep old interpretations when you produce new ones, at least for a while. A consumer can then compare the two, and you can roll back a bad rule change without reprocessing from the raw layer.

Registries and compatibility#

If you publish events on a message bus, a schema registry makes the shape explicit and checks changes before they ship. Registries used with Kafka enforce compatibility modes: a backward compatible change lets new readers read old data, and a forward compatible change lets old readers read new data. For event streams that live a long time, adding optional fields with defaults is the change that keeps both directions working.

The registry checks the shape, not the meaning. It cannot tell you that a field called amount_in now holds a different unit. That is what the rule version is for.

Worked example: a swap event#

A swap event, showing the fields and the layer each belongs to. Values are left out on purpose: the shape is the point.

FieldLayerExample content
signature, slot, instruction indexrawThe transaction and the swap's position in it
program idrawThe DEX or aggregator program
account keysrawPool, user token accounts, mints, in the program's order
datarawThe instruction bytes as received
statuslifecycleProvisional until reconciled
event type, event schema versioninterpretationswap, version 2
input mint, output mintinterpretationRead from the accounts the layout names
amount in, minimum amount outinterpretationRead from the instruction data
amount outinterpretationEmpty until confirmed data supplies it
layout source, rule versioninterpretationThe IDL hash and your rule version

Note the empty amount out. The actual output of a swap is produced by execution, so a schema built for shred data must allow it to be filled in later rather than pretending the field is known.

What a schema cannot record#

A schema can only hold what the decoder can see. Raw transactions carry no logs and no inner instructions, so events that programs emit during execution, through log lines or through a call to themselves, never appear in shred data. If your consumers expect those program events, the schema needs a slot for them that is filled from confirmed data, and the documentation should say so plainly.

Kafka topic design shows how to key and publish these events, and the message bus comparison covers where they travel. Program events explains which event styles exist and why none of them sit in raw transactions. For keeping the raw layer free of duplicates, see idempotent writes; for keeping the interpretation layer current, see IDL drift. To fill the schema with live data, start with the quickstart.

A schema version should move when a program does, which is why watching for program upgrades belongs next to the registry.

Interpretations such as who routed a swap are exactly the layer that should carry its own version.

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 nextBackfill and live: joining history to a stream without gaps