Problem
Problem is that currently when working on the net_interface if we make a breaking change to the interface we should probably upgrade the version in certain situations to ensure compatibility
Implement graceful network upgrade mechanism
Operators upgrade on their own schedule, so the network needs to handle mixed-version nodes without coordination. This issue tracks adding multi-version protocol support with an automatic deprecation horizon.
We currently have three protocol strings hardcoded with no upgrade path:
/enclave/kad/1.0.0 (Kademlia)
/enclave/sync/0.0.1 (request-response)
/enclave/0.0.1 (identify)
When we ship breaking changes, nodes that haven't upgraded yet will silently fail or behave unpredictably. We need a system where old and new nodes coexist during a transition window, and stale nodes get cleanly disconnected with clear log output when support is dropped.
Tasks
Centralize protocol versions
Wire identify for version enforcement
Enable multi-version request-response
Log version info clearly
Document the upgrade cycle
Upgrade cycle summary
Release A ──► Both versions supported, nodes upgrade at their own pace
(bump NETWORK_ERA, keep MIN_COMPATIBLE_ERA)
...wait...
Release B ──► Drop old version, bump MIN_COMPATIBLE_ERA
Nodes still on Release A get disconnected with a clear log message
Problem
Problem is that currently when working on the net_interface if we make a breaking change to the interface we should probably upgrade the version in certain situations to ensure compatibility
Implement graceful network upgrade mechanism
Operators upgrade on their own schedule, so the network needs to handle mixed-version nodes without coordination. This issue tracks adding multi-version protocol support with an automatic deprecation horizon.
We currently have three protocol strings hardcoded with no upgrade path:
/enclave/kad/1.0.0(Kademlia)/enclave/sync/0.0.1(request-response)/enclave/0.0.1(identify)When we ship breaking changes, nodes that haven't upgraded yet will silently fail or behave unpredictably. We need a system where old and new nodes coexist during a transition window, and stale nodes get cleanly disconnected with clear log output when support is dropped.
Tasks
Centralize protocol versions
./crates/net/protocols.rswith constants forNETWORK_ERA,MIN_COMPATIBLE_ERA, and all protocol version stringscreate_behaviour()andPROTOCOL_NAMEwith references to the new constants// remove after YYYY-MM-DD)Wire identify for version enforcement
NETWORK_ERAinto the identify protocol string (e.g./enclave/{NETWORK_ERA})NodeBehaviourEvent::Identify(identify::Event::Received { .. })inprocess_swarm_event(currently falls through to theunknowncatch-all)MIN_COMPATIBLE_ERAlisten_addrsfrom identify into Kademlia on successful version checkEnable multi-version request-response
create_behaviour()to register request-response with the protocol list fromprotocols.rs(supports multiple entries so libp2p negotiates the highest common version)Log version info clearly
NETWORK_ERA,MIN_COMPATIBLE_ERA, and active protocol versionsDocument the upgrade cycle
UPGRADING.md) describing the release process:NETWORK_ERA, keepMIN_COMPATIBLE_ERAunchangedMIN_COMPATIBLE_ERA, stale nodes get disconnectedUpgrade cycle summary