Canonical: https://solanashreds.xyz/blog/event-schemas-that-last

# 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

| Field | Layer | Notes |
|---|---|---|
| signature | raw | The first signature; the transaction's identity |
| slot | raw | The slot the transaction was seen in; a transaction can appear in more than one fork |
| instruction index | raw | Position within the transaction; the identity of an instruction |
| program id | raw | The program the instruction called |
| account keys | raw | In instruction order, after resolving lookup tables |
| data | raw | The instruction bytes, kept even after decoding |
| message format | raw | Legacy, v0 or v1 |
| status | lifecycle | Provisional, then confirmed, failed or dropped |
| event type | interpretation | For example swap, transfer, create, upgrade |
| event schema version | interpretation | The version of this event type's fields |
| layout source | interpretation | The IDL or layout used, with its hash |
| rule version | interpretation | The version of your classification rules |
| decoded fields | interpretation | The 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.

| Field | Layer | Example content |
|---|---|---|
| signature, slot, instruction index | raw | The transaction and the swap's position in it |
| program id | raw | The DEX or aggregator program |
| account keys | raw | Pool, user token accounts, mints, in the program's order |
| data | raw | The instruction bytes as received |
| status | lifecycle | Provisional until reconciled |
| event type, event schema version | interpretation | swap, version 2 |
| input mint, output mint | interpretation | Read from the accounts the layout names |
| amount in, minimum amount out | interpretation | Read from the instruction data |
| amount out | interpretation | Empty until confirmed data supplies it |
| layout source, rule version | interpretation | The 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.

## Related pages

[Kafka topic design](https://solanashreds.xyz/docs/pipeline/kafka) shows how to key and publish these events, and the [message bus comparison](https://solanashreds.xyz/compare/kafka-vs-nats-vs-redis-streams) covers where they travel. [Program events](https://solanashreds.xyz/learn/solana-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](https://solanashreds.xyz/blog/idempotent-writes-for-chain-data); for keeping the interpretation layer current, see [IDL drift](https://solanashreds.xyz/blog/idl-drift). To fill the schema with live data, start with the [quickstart](https://solanashreds.xyz/docs/quickstart).

A schema version should move when a program does, which is why [watching for program upgrades](https://solanashreds.xyz/blog/watching-program-upgrades) belongs next to the registry.

Interpretations such as [who routed a swap](https://solanashreds.xyz/blog/who-made-this-swap) are exactly the layer that should carry its own version.
