Versioning

The DeRec protocol carries two distinct version concepts that should not be confused:

• Protocol version — identifies the schema and flow semantics implemented by the sender. Carried on every DeRecMessage envelope.

• Secret version — a monotonic counter on the protected Secret. Increments whenever the Secret's content changes.

This section describes both.

Protocol Version

Each DeRecMessage carries two fields that identify the protocol version used to construct the message:

• protocolVersionMajor

• protocolVersionMinor

These fields indicate the protocol version implemented by the sender. The protocol version describes the message schemas, protocol flows, and validation rules supported by the implementation.

Purpose

Protocol versioning allows implementations to detect compatibility differences between participants. When an Owner and Helper communicate, both sides may use these fields to determine whether they support the same protocol semantics.

Major and Minor Versions

The protocol separates version numbers into two components:

• Major version — used when protocol changes are not backward compatible.

• Minor version — used when changes extend the protocol while preserving compatibility with earlier versions.

The protocol specification does not mandate specific compatibility rules. Implementations may choose how strictly they enforce version matching when processing messages.

Version negotiation

Implementations may use this information to detect incompatible versions and fail gracefully if necessary. Version compatibility checks may occur during pairing or during message processing.

Secret Version

The protocol defines a version field associated with the protected Secret. The field appears on the Secret itself and on every share / Secret-sync message that carries a snapshot of it.

The version value identifies a specific snapshot of the Secret. The combination of (secret_id, version) identifies a logical state of the Owner identity, and Helpers index their stored shares by (secret_id, version, replica_id) — including replica_id is what allows concurrent writes from sibling Replicas to coexist side-by-side rather than overwriting each other.

version is a monotonic counter on the Secret. It MUST increment by one on every observable change to the Secret's content. There is no batching, no debounce — every observable change is a new version.

When does version change?

version increments whenever the Secret's content changes — in practice:

• User secrets are added, removed, or rotated

• The Helper roster changes (adding, removing, or replacing a Helper)

• The Replica roster changes (pairing or unpairing a Replica device under the same Owner identity)

• The threshold configuration changes

Each version also carries the replica_id of the device that produced it — stamped as owner_replica_id on the Secret and as replicaId on the outbound share / Secret-sync envelope. The two values should agree for any given (secret_id, version); disagreement is one of the surfaces the application uses to detect conflicts. See Conflict resolution.

Protocol Evolution

Independent implementations of the DeRec protocol may evolve over time. Implementations may add new message fields, introduce additional validation rules, or support new capabilities.

When interacting with other implementations, systems should ensure that both parties support compatible protocol behavior before executing protocol flows.

The protocol does not currently define a formal protocol version negotiation mechanism. Implementations may perform compatibility checks during pairing or session establishment.

Backward Compatibility

Protocol evolution should preserve interoperability with existing implementations whenever possible.

Backward compatibility may be maintained through practices such as:

• Maintaining existing message fields and semantics

• Adding new fields as optional rather than mandatory

• Ensuring that older implementations can safely ignore fields they do not recognize

• Preserving field numbers in serialized message schemas

These practices allow newer implementations to interact with older ones when the protocol behavior remains compatible.

Forward Compatibility

Forward compatibility allows older implementations to process messages generated by newer implementations without failing unexpectedly.

Structured message formats such as protobuf support forward compatibility by allowing unknown fields to be ignored during decoding.

However, if a protocol flow depends on behavior that an older implementation does not support, the interaction may fail due to validation errors or unsupported functionality.

Schema Evolution

Protocol message schemas may change over time as the protocol evolves. Safe schema evolution requires careful management of serialized message formats.

Recommended practices include:

• Adding new fields as optional

• Avoiding changes to the meaning of existing fields

• Reserving field numbers when removing fields

• Preserving field numbering to maintain serialization compatibility

These practices ensure that message serialization remains stable across protocol updates.

Compatibility Considerations

Implementations should assume that different versions of DeRec software may coexist within the ecosystem.

Systems should therefore detect incompatible behavior early and fail gracefully when interoperability cannot be guaranteed.

Compatibility checks should occur before executing protocol flows that depend on specific message structures or capabilities.

Design Implications

Versioning allows the DeRec protocol and its implementations to evolve without disrupting existing deployments.

The version field identifies the share referenced in protocol interactions, while protocol evolution governs how implementations extend or modify behavior over time.

Careful version management enables independent implementations to upgrade safely while preserving interoperability across the ecosystem.