What is a Solana shred version?

2 bytes separate cluster lineages

Every current Solana shred carries a two-byte version in its common header. The value helps a validator or raw receiver distinguish packets intended for one cluster lineage from traffic belonging to another.

The version is derived from cluster genesis-related state by the protocol implementation. Operators normally obtain the expected value from trusted cluster configuration or the same software path used by validators. A receiver does not negotiate it with each UDP sender.

Two bytes provide a compact filter, not a globally unique network identifier. The field is useful because accidental cross-cluster traffic is common and cheap to reject. It is not a substitute for slot-leader authentication, variant parsing, or fork tracking.

Version is not software release

A shred version is not the Agave package version, semantic release number, feature-set identifier, or RPC API version. Values such as 2.1.7 or 3.0.0 describe software releases and do not belong in the two-byte wire field.

Software can upgrade while the cluster's expected shred version remains stable. A feature activation can introduce a new shred variant without turning the version field into a decoder capability bitmap. Conversely, two clusters running similar software can have different shred versions because their genesis lineage differs.

Name configuration fields expected_shred_version, not protocol_version or agave_version. Clear naming prevents deployment automation from filling the wire value with a package number.

The receiver needs one expected value

A production consumer should know which cluster it serves. Its configuration includes one expected shred version for that cluster context. Every admitted packet must match before expensive cryptography or FEC work.

An analytics service intentionally monitoring several clusters can maintain separate pipelines keyed by trusted ingress and configured version. It should not accept any observed version into one shared assembly table. Slot numbers overlap across clusters, and leader schedules differ.

Configuration provenance matters. Read the value from a trusted node configuration, a controlled startup source, or a verified implementation derivation. Learning the expected version from the first public UDP packet lets an attacker select the receiver's cluster view.

Early rejection saves real work

The version field sits in the fixed common header and costs one bounded read plus one comparison. Ed25519 verification, Merkle hashing, buffer allocation, and Reed-Solomon work cost substantially more.

Rejecting a mismatch early is therefore both correctness and load control. At 5,585 packets per second, even a small stream of unrelated cluster traffic can consume measurable CPU if it reaches signature verification.

The fast path still performs minimum datagram-length and variant-offset safety checks first. A short packet cannot be trusted to contain the two-byte field. Once safely parsed, wrong_version should end admission without allocating slot or FEC state.

Matching version is only one gate

An attacker can copy the expected two-byte value into arbitrary bytes. Version equality proves no possession of a leader key and no membership in a valid Merkle set.

After the version check, the receiver still validates slot horizon, index, parent offset or coding metadata, proof layout, leader schedule, signature, and FEC consistency. Recovered data still undergoes sanitation.

Think of version as an address label on an envelope. It routes the packet toward the correct processing context. Cryptographic verification determines whether the expected leader authenticated the content. Consensus later determines whether that content remains in the ledger.

Variant compatibility is separate

The one-byte shred variant and the two-byte shred version answer different questions. Version asks whether the packet belongs to the intended cluster lineage. Variant asks which wire layout and authentication procedure it uses.

A receiver can see the expected version alongside an unsupported variant after a network feature activates. Treating version equality as decoder compatibility would cause the parser to apply an older layout to newer bytes.

Track unsupported_variant separately from wrong_version. The first calls for software support or feature awareness. The second points to cluster configuration, cross-traffic, replay, or malformed input. Combining them hides upgrade risk.

Genesis context supplies stability

Deriving the version from genesis-related state gives a cluster a stable lineage marker without adding a long identifier to every packet. The receiver should use the protocol's derivation rather than reproduce it from memory.

Do not invent a version from cluster name text such as mainnet-beta. Names can be aliases. Private clusters may reuse labels. Trusted genesis data and validator-compatible code establish the expected numeric value.

The compact result can theoretically collide across unrelated lineages because the field has only 65,536 possible values. Authentication and schedule context are still required. The design aims to reject common accidental overlap cheaply, not provide collision-resistant identity.

Cross-cluster traffic looks plausible

Slots, indexes, signatures, and packet lengths from another Solana cluster can all be structurally valid. Without a version filter, a receiver might allocate state for those packets before leader verification eventually fails against the target schedule.

The danger is greater in test environments where several feeds share hosts or multicast-like distribution. A firewall rule based only on one relay address cannot distinguish clusters if the relay carries more than one configured source.

Put cluster identity into process configuration, metrics labels, packet capture metadata, and storage namespaces. Version checking then supports an already explicit boundary rather than trying to infer one after data is mixed.

Changes require an operational gate

An expected version change should be treated as a controlled cluster event, not an automatically accepted value observed on the wire. Update configuration from an authoritative source, deploy decoder compatibility if needed, and monitor mismatch rates during transition.

Dual acceptance can be appropriate only when protocol operations explicitly require it and assembly state remains separated. Blindly accepting old and new values into one slot map permits cross-lineage mixtures.

Alert on a sustained shift from occasional mismatches to a dominant new value. Do not log every packet at line rate. Aggregate counts by observed value, source path, and time window, with bounded samples for investigation.

Storage keys need cluster context

Within one configured pipeline, slot, type, and index identify a shred candidate. Across multiple clusters, that tuple collides. Persisted captures, caches, and metrics need an explicit cluster or lineage namespace.

The two-byte version can contribute to that namespace, but it should not be the only long-term identity because collisions are possible. Use a trusted cluster identifier or genesis hash in metadata, with the wire version retained as an observed field.

This is especially important for offline replay. A packet file containing version 31 and slot 300,000,000 cannot be interpreted correctly without knowing which leader schedule, feature set, and variant rules were active for its cluster.

Version mismatch is not corruption

A packet with the wrong expected version may be perfectly valid for another cluster. Report it as wrong cluster or version mismatch, not necessarily bad signature or malformed bytes.

This distinction helps operations. A sudden version mismatch from one internal source can reveal a routing error. Malformed lengths from arbitrary addresses point to a different problem. Valid signatures under another cluster's scheduled leaders can confirm accidental feed mixing.

Security responses also differ. Cross-cluster packets can be dropped immediately with minimal logging. Malformed packets need rate and parser-safety scrutiny. Authenticated same-version conflicts require duplicate evidence handling.

Raw relays preserve the field

shredstream.sh forwards raw UDP shreds. It does not rewrite slot, version, signature, or FEC metadata. The received two-byte value is the producer's protocol field.

The product's stable source IP helps customers admit delivery traffic through a firewall. It does not select or transform the cluster version inside each packet. Consumers remain responsible for configuring the expected value and validating it.

This separation is beneficial. End-to-end bytes let a receiver run the same parsing and authentication rules it would use on packets observed closer to Turbine. A relay-side decoded label would be easier to consume but would add another trust and compatibility boundary.

Testing version behavior

Unit tests should cover expected value, one-bit mismatch, truncated common header, both data and coding variants, and values at zero and 65,535. The parser must reject mismatch before creating FEC state.

Integration tests should replay valid packets from another configured cluster and verify that signature code is not reached. Upgrade tests should pair the expected version with an unsupported variant to ensure the failure remains unsupported_variant rather than false acceptance.

Operational tests should inject a low-rate mismatch and confirm counters, alerts, and sample logs work without flooding. The objective is a cheap, observable gate whose behavior remains stable under hostile traffic.

Version cannot replace context

The field has 16 bits. It cannot encode a full genesis hash, active feature set, software release, fork, leader key, or commitment level. Designing it as though it can produces hidden assumptions.

A correct receiver carries broader context beside the parsed version: target cluster, accepted variants, leader schedule, slot horizon, and later consensus observations. The version eliminates packets that plainly do not fit that context.

The modest claim is the useful one. Two bytes prevent much accidental mixing before it reaches costly protocol machinery. Every stronger property comes from another check.

Captures need version plus decoder provenance

A packet capture can outlive the software that recorded it. Saving raw datagrams without cluster identity, expected shred version, receive lengths, and decoder feature context makes later analysis ambiguous.

Write a small capture manifest beside the packet stream. Include configured cluster or genesis identity, expected version, Agave or protocol source revision used for layouts, enabled variant support, source path, capture clock basis, and whether bytes include any outer Solana networking nonce or only raw shred payload.

On replay, compare observed header versions with the manifest before feeding packets to current code. A newer decoder may accept a variant that the original process rejected. That is useful for analysis, but results should say replay_decoder rather than rewrite historical admission status.

Migration tests can use the same captures. Run old and new decoders against expected-version packets and compare parsed identity, authenticated root or signed message, FEC grouping, data boundaries, and rejection reasons. A changed result may be a deliberate compatibility fix or a regression.

Version mismatches in archived data also reveal routing history. Count them, but keep their cluster interpretation separate unless matching trusted genesis and leader-schedule context is available. The two-byte field alone cannot label an unknown capture as mainnet, testnet, or a private cluster.

This provenance costs little compared with storing high-rate payloads. It turns a binary file from unexplained traffic into reproducible protocol evidence and prevents a later package version from being mistaken for the original wire lineage.

Capture manifests should be immutable beside the raw segment. If an operator corrects a mistaken cluster label, append a correction record with author and time instead of overwriting the conditions under which packets were originally admitted. Reproducibility depends on knowing both the observed bytes and the receiver assumptions in force.

That record also supports independent audits months after collection.