From dd678ee6ce77f4344cc59b11ebde2e65d7c57b3f Mon Sep 17 00:00:00 2001 From: Nicholas Dudfield Date: Tue, 7 Jul 2026 11:52:36 +0700 Subject: [PATCH] docs(consensus): document the CE proposal wire-format rollout dependency After featureConsensusEntropy activates, proposals may carry a serialized ExtendedPosition in the legacy currenttxhash protobuf field, so pre-CE binaries that require an exact 32-byte currenttxhash cannot participate as proposal peers; disabling sidecar fetch/reconciliation does NOT restore compatibility (the wire-format change is independent of the sidecar gate). Verified against the implementation (RCLConsensus, ConsensusExtensions, PeerImp). --- src/xrpld/app/consensus/ConsensusEntropyIntent.md | 8 ++++++++ src/xrpld/app/consensus/ConsensusExtensionsDesign.md | 10 ++++++++++ 2 files changed, 18 insertions(+) diff --git a/src/xrpld/app/consensus/ConsensusEntropyIntent.md b/src/xrpld/app/consensus/ConsensusEntropyIntent.md index c31549e48..3f4703abe 100644 --- a/src/xrpld/app/consensus/ConsensusEntropyIntent.md +++ b/src/xrpld/app/consensus/ConsensusEntropyIntent.md @@ -136,6 +136,14 @@ proposal bytes remain byte-identical to base XRPL. `ExtendedPosition` serializes to exactly the legacy 32-byte tx-set hash when no sidecar fields are set. +**Rollout note:** after `featureConsensusEntropy` is enabled, live proposals may +carry a serialized `ExtendedPosition` in the legacy `currenttxhash` protobuf +field. That is a proposal wire-format dependency, not a sidecar-fetch +dependency. Older binaries that only accept a 32-byte `currenttxhash` are not +compatible proposal participants after activation; operators must upgrade the +proposal-processing network first, or add explicit version/capability +negotiation before attempting a heterogeneous rollout. + **INV-8 — No unbounded liveness dependency.** Every sub-state has a bounded timeout with a deterministic downgrade. CE must never be the reason a round stalls once base consensus is itself making progress. diff --git a/src/xrpld/app/consensus/ConsensusExtensionsDesign.md b/src/xrpld/app/consensus/ConsensusExtensionsDesign.md index 753467c10..c33bc46f9 100644 --- a/src/xrpld/app/consensus/ConsensusExtensionsDesign.md +++ b/src/xrpld/app/consensus/ConsensusExtensionsDesign.md @@ -434,6 +434,16 @@ The extended proposal machinery is enabled when either feature needs signed sidecar fields. Do not make Export depend on RNG availability just because RNG was the first consumer of `ExtendedPosition`. +Rollout invariant: once a network enables `featureConsensusEntropy`, proposal +messages may use the legacy `currenttxhash` protobuf field to carry a serialized +`ExtendedPosition`, not just a raw 32-byte transaction-set hash. This is a +proposal wire-format change, not a sidecar-reconciliation detail. Disabling +sidecar fetch/reconciliation does not restore compatibility with older binaries +that require `currenttxhash` to be exactly 32 bytes. A network that activates CE +therefore needs every binary expected to process live proposals to understand +the extended position format, or it needs explicit version/capability +negotiation before activation. + When `featureExport` is disabled, the export sidecar gate is disabled too. Stale collector entries must not keep a stopped amendment active.