Solana shred format reference

Wire unit

Each UDP payload represents exactly one raw Solana shred. Datagram length may not exceed 1,228 bytes under shredstream.sh. Actual length varies by role and variant, so parsing uses the returned length plus the selected format.

All multibyte integer fields in the headers below are little-endian. Byte ranges use a start-inclusive, end-exclusive convention.

Common header

The current common header is 83 bytes.

The minimal safe read for the common header is 83 bytes. Reject a shorter datagram before accessing any common field.

Data header

For current data variants, bytes 83 through 87 form the role-specific header, making byte 88 its exclusive end.

Data flags

The value 0x40 marks data complete. The value 0xC0 marks last in slot and therefore also data complete. A parser should use the bit definitions from its pinned client release rather than accept unknown combinations.

Do not interpret the size field as total datagram length. Padding, chained-root material, Merkle proof nodes, or a retransmitter signature may follow the declared ledger data.

Coding header

Current coding variants place their role header at bytes 83 through 88, with 89 as the exclusive end.

For a coding shred, add k to position to obtain its erasure-shard location. That local array location differs from the global coding index. Subtract position from coding index to derive the first coding index.

The common current target pairs 32 data shreds with 32 coding members per FEC set. Final sets may contain fewer members. Allocate from sanitized k and m instead of treating the illustrated 32-plus-32 layout as permanent.

Variant families

The variant byte dispatches format and must not be decoded through a guessed mask. In current Merkle forms, its lowest four bits carry proof-entry count while other bits select role and flags. The matching Agave release defines valid discriminants and combinations.

Merkle-dependent regions

There is no one valid proof offset for all packets. Data or coding role, proof depth, chain presence, retransmitter signature presence, and payload capacity all affect the boundary. Use typed accessors from the pinned implementation.

Identity and ordering keys

Each role owns an independent index space. A deduplication key containing only slot and numeric index can wrongly discard the valid member from the other role.

FEC consistency checks

Admission to one recovery set requires agreement on slot, cluster shred version, FEC-set index, data count, coding count, protected shard size, compatible variant, and authenticated Merkle context when present. Coding members must imply one first coding index. Reconstructed data then undergoes every structural and authentication check applied to direct arrivals.

Do not append coding payload to ledger bytes. Coding shreds exist to reconstruct missing data members.

Signed material

Resolve the expected verification key through the trusted schedule entry for that slot's leader. Matching source IP, plausible slot, or correct cluster shred version cannot establish authenticity.

Deshredding boundary

Concatenate only sanitized data slices, following data-index order across the applicable completed range. A parser's accessor excludes headers, padding, proof nodes, chain roots, and every retransmitter signature.

Completion flags mark boundaries but cannot fill an earlier incomplete range. Even a slot-final flag leaves a gap when required data is absent and FEC recovery has not succeeded.

Fail-closed parser order

1. Reject any received datagram longer than the 1,228-byte ceiling.
2. Check enough bytes exist for the common header.
3. Read and dispatch the variant.
4. Read common fields with checked slices.
5. Compare the cluster shred version.
6. Parse the data or coding header.
7. Validate sizes, indices, counts, flags, and proof layout.
8. Resolve the scheduled leader.
9. Verify legacy signed data or the Merkle root.
10. Admit the packet to duplicate, ordering, and FEC state.

Unknown variants and impossible lengths are explicit rejections. Falling back to a legacy layout can turn proof bytes into plausible application data.