core/stateless: fix witness RLP backward compat with WIT/0 peers (#2068)

cffls · web-flow · commit 6b0405c0a5ca · 2026-02-18T23:04:10.000-08:00
* core/stateless: fix witness RLP backward compat with WIT/0 peers

Nodes upgraded from WIT/0 to WIT/1 were incorrectly jailing WIT/0 peers
with "rlp: too few elements for stateless.ExtWitness". A 5-field
ExtWitness encoding (Context, Headers, Codes, State, Keys) was
accidentally introduced during an upstream geth merge, replacing the
original 3-field wire format (Context, Headers, State) that WIT/0 peers
still use.

Introduce BorWitness as the canonical 3-field wire format. EncodeRLP now
encodes using BorWitness (State only, codes excluded). DecodeRLP tries
BorWitness first and falls back to ExtWitness for backward compatibility
with peers that temporarily ran the extended encoding.

ExtWitness is retained as the representation for the JSON debug API
(ExecutionWitness, ExecutionWitnessByHash) and as the fallback decode
target for the transitional period.

* Add test
diff --git a/core/stateless/encoding.go b/core/stateless/encoding.go
@@ -24,7 +24,28 @@ import (
 	"github.com/ethereum/go-ethereum/rlp"
 )
 
-// ToExtWitness converts our internal witness representation to the consensus one.
+// BorWitness is the canonical 3-field RLP encoding used for network
+// transmission in Bor. The State field carries all proof data — both
+// contract bytecodes and MPT state trie nodes — as a flat list of byte slices.
+type BorWitness struct {
+	Context *types.Header
+	Headers []*types.Header
+	State   [][]byte
+}
+
+// ExtWitness is a witness representation used by the JSON debug API and for
+// backward-compatible RLP decoding of peers that temporarily used the
+// extended 5-field format. It is not the canonical wire format.
+type ExtWitness struct {
+	Context *types.Header
+	Headers []*types.Header `json:"headers"`
+	Codes   []hexutil.Bytes `json:"codes"`
+	State   []hexutil.Bytes `json:"state"`
+	Keys    []hexutil.Bytes `json:"keys"`
+}
+
+// ToExtWitness converts our internal witness representation to the ExtWitness
+// form used by the JSON debug API.
 func (w *Witness) ToExtWitness() *ExtWitness {
 	w.lock.RLock()
 	defer w.lock.RUnlock()
@@ -44,7 +65,7 @@ func (w *Witness) ToExtWitness() *ExtWitness {
 	return ext
 }
 
-// fromExtWitness converts the consensus witness format into our internal one.
+// fromExtWitness converts the ExtWitness format into our internal representation.
 func (w *Witness) fromExtWitness(ext *ExtWitness) error {
 	w.context = ext.Context
 	w.Headers = ext.Headers
@@ -60,25 +81,55 @@ func (w *Witness) fromExtWitness(ext *ExtWitness) error {
 	return nil
 }
 
-// EncodeRLP serializes a witness as RLP.
+// EncodeRLP serializes a witness as RLP using the canonical BorWitness 3-field
+// format. Only state trie nodes are encoded; contract bytecodes are not
+// included in the wire format.
 func (w *Witness) EncodeRLP(wr io.Writer) error {
-	return rlp.Encode(wr, w.ToExtWitness())
+	w.lock.RLock()
+	defer w.lock.RUnlock()
+
+	bw := &BorWitness{
+		Context: w.context,
+		Headers: w.Headers,
+		State:   make([][]byte, 0, len(w.State)),
+	}
+	for node := range w.State {
+		bw.State = append(bw.State, []byte(node))
+	}
+	return rlp.Encode(wr, bw)
 }
 
-// DecodeRLP decodes a witness from RLP.
+// DecodeRLP decodes a witness from RLP. It first attempts the canonical
+// BorWitness 3-field format. If that fails (e.g. the peer sent the legacy
+// 5-field ExtWitness encoding), it falls back to ExtWitness for backward
+// compatibility.
+//
+// When decoding BorWitness, State items are placed into w.State and w.Codes
+// is left empty, since codes are not part of the BorWitness wire format.
 func (w *Witness) DecodeRLP(s *rlp.Stream) error {
+	raw, err := s.Raw()
+	if err != nil {
+		return err
+	}
+
+	// Try BorWitness first. A 5-field list will fail here with "too many
+	// elements", routing cleanly to the ExtWitness fallback.
+	var bw BorWitness
+	if err := rlp.DecodeBytes(raw, &bw); err == nil {
+		w.context = bw.Context
+		w.Headers = bw.Headers
+		w.Codes = make(map[string]struct{})
+		w.State = make(map[string]struct{}, len(bw.State))
+		for _, node := range bw.State {
+			w.State[string(node)] = struct{}{}
+		}
+		return nil
+	}
+
+	// Fall back to the legacy 5-field ExtWitness format.
 	var ext ExtWitness
-	if err := s.Decode(&ext); err != nil {
+	if err := rlp.DecodeBytes(raw, &ext); err != nil {
 		return err
 	}
 	return w.fromExtWitness(&ext)
 }
-
-// ExtWitness is a witness RLP encoding for transferring across clients.
-type ExtWitness struct {
-	Context *types.Header
-	Headers []*types.Header `json:"headers"`
-	Codes   []hexutil.Bytes `json:"codes"`
-	State   []hexutil.Bytes `json:"state"`
-	Keys    []hexutil.Bytes `json:"keys"`
-}
diff --git a/core/stateless/encoding_test.go b/core/stateless/encoding_test.go
@@ -0,0 +1,182 @@
+package stateless
+
+import (
+	"math/big"
+	"testing"
+
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/rlp"
+)
+
+// TestDecodeRLP_BorWitnessFormat verifies that a witness RLP-encoded in the
+// canonical 3-field BorWitness format is correctly decoded.
+func TestDecodeRLP_BorWitnessFormat(t *testing.T) {
+	contextHeader := &types.Header{Number: big.NewInt(100)}
+	parentHeader := &types.Header{Number: big.NewInt(99)}
+	node1 := []byte("statenode1")
+	node2 := []byte("statenode2")
+
+	bw := &BorWitness{
+		Context: contextHeader,
+		Headers: []*types.Header{parentHeader},
+		State:   [][]byte{node1, node2},
+	}
+
+	encoded, err := rlp.EncodeToBytes(bw)
+	if err != nil {
+		t.Fatalf("failed to encode BorWitness: %v", err)
+	}
+
+	var w Witness
+	if err := rlp.DecodeBytes(encoded, &w); err != nil {
+		t.Fatalf("DecodeRLP failed for BorWitness input: %v", err)
+	}
+
+	if w.context.Number.Cmp(contextHeader.Number) != 0 {
+		t.Errorf("context number: got %v, want %v", w.context.Number, contextHeader.Number)
+	}
+	if len(w.Headers) != 1 || w.Headers[0].Number.Cmp(parentHeader.Number) != 0 {
+		t.Errorf("headers mismatch after decode")
+	}
+
+	// All State items from BorWitness should land in w.State.
+	if len(w.State) != 2 {
+		t.Errorf("state len: got %d, want 2", len(w.State))
+	}
+	for _, node := range [][]byte{node1, node2} {
+		if _, ok := w.State[string(node)]; !ok {
+			t.Errorf("state node %q missing after decode", node)
+		}
+	}
+
+	// Codes are not part of the BorWitness wire format.
+	if len(w.Codes) != 0 {
+		t.Errorf("Codes should be empty after BorWitness decode, got %d entries", len(w.Codes))
+	}
+}
+
+// TestDecodeRLP_ExtWitnessFormat verifies backward compatibility: a witness
+// encoded in the legacy 5-field ExtWitness format is correctly decoded via the
+// fallback path, with Codes and State placed in their respective internal maps.
+func TestDecodeRLP_ExtWitnessFormat(t *testing.T) {
+	contextHeader := &types.Header{Number: big.NewInt(100)}
+	parentHeader := &types.Header{Number: big.NewInt(99)}
+	code1 := hexutil.Bytes("contractbytecode")
+	node1 := hexutil.Bytes("statetrienode")
+
+	ext := &ExtWitness{
+		Context: contextHeader,
+		Headers: []*types.Header{parentHeader},
+		Codes:   []hexutil.Bytes{code1},
+		State:   []hexutil.Bytes{node1},
+		Keys:    nil,
+	}
+
+	encoded, err := rlp.EncodeToBytes(ext)
+	if err != nil {
+		t.Fatalf("failed to encode ExtWitness: %v", err)
+	}
+
+	var w Witness
+	if err := rlp.DecodeBytes(encoded, &w); err != nil {
+		t.Fatalf("DecodeRLP failed for ExtWitness input: %v", err)
+	}
+
+	if w.context.Number.Cmp(contextHeader.Number) != 0 {
+		t.Errorf("context number: got %v, want %v", w.context.Number, contextHeader.Number)
+	}
+	if len(w.Headers) != 1 || w.Headers[0].Number.Cmp(parentHeader.Number) != 0 {
+		t.Errorf("headers mismatch after decode")
+	}
+
+	if len(w.Codes) != 1 {
+		t.Errorf("Codes len: got %d, want 1", len(w.Codes))
+	}
+	if _, ok := w.Codes[string(code1)]; !ok {
+		t.Errorf("code %q missing from Codes after ExtWitness decode", code1)
+	}
+
+	if len(w.State) != 1 {
+		t.Errorf("State len: got %d, want 1", len(w.State))
+	}
+	if _, ok := w.State[string(node1)]; !ok {
+		t.Errorf("node %q missing from State after ExtWitness decode", node1)
+	}
+}
+
+// TestEncodeRLP_UsesBorWitnessFormat verifies that EncodeRLP produces the
+// canonical 3-field BorWitness format and that codes are excluded from it.
+func TestEncodeRLP_UsesBorWitnessFormat(t *testing.T) {
+	w := &Witness{
+		context: &types.Header{Number: big.NewInt(100)},
+		Headers: []*types.Header{{Number: big.NewInt(99)}},
+		Codes:   map[string]struct{}{"contractcode": {}},
+		State:   map[string]struct{}{"statenode": {}},
+	}
+
+	encoded, err := rlp.EncodeToBytes(w)
+	if err != nil {
+		t.Fatalf("EncodeRLP failed: %v", err)
+	}
+
+	// The output must be decodable as BorWitness (3 fields).
+	var bw BorWitness
+	if err := rlp.DecodeBytes(encoded, &bw); err != nil {
+		t.Fatalf("encoded output is not a valid BorWitness: %v", err)
+	}
+
+	// Only State nodes should be present — codes are not encoded.
+	if len(bw.State) != 1 || string(bw.State[0]) != "statenode" {
+		t.Errorf("BorWitness.State = %v, want [statenode]", bw.State)
+	}
+
+	// The output must NOT be decodable as ExtWitness (5 fields).
+	var ext ExtWitness
+	if err := rlp.DecodeBytes(encoded, &ext); err == nil {
+		t.Error("expected ExtWitness decode to fail for BorWitness output, but it succeeded")
+	}
+}
+
+// TestRoundtrip_BorWitnessFormat verifies the full encode→decode cycle using
+// EncodeRLP and DecodeRLP (BorWitness path).
+func TestRoundtrip_BorWitnessFormat(t *testing.T) {
+	original := &Witness{
+		context: &types.Header{Number: big.NewInt(200)},
+		Headers: []*types.Header{{Number: big.NewInt(199)}, {Number: big.NewInt(198)}},
+		Codes:   map[string]struct{}{"code": {}},
+		State:   map[string]struct{}{"node1": {}, "node2": {}},
+	}
+
+	encoded, err := rlp.EncodeToBytes(original)
+	if err != nil {
+		t.Fatalf("EncodeRLP failed: %v", err)
+	}
+
+	var decoded Witness
+	if err := rlp.DecodeBytes(encoded, &decoded); err != nil {
+		t.Fatalf("DecodeRLP failed: %v", err)
+	}
+
+	if decoded.context.Number.Cmp(original.context.Number) != 0 {
+		t.Errorf("context number: got %v, want %v", decoded.context.Number, original.context.Number)
+	}
+	if len(decoded.Headers) != len(original.Headers) {
+		t.Errorf("headers count: got %d, want %d", len(decoded.Headers), len(original.Headers))
+	}
+
+	// State nodes are preserved across the roundtrip.
+	for node := range original.State {
+		if _, ok := decoded.State[node]; !ok {
+			t.Errorf("state node %q missing after roundtrip", node)
+		}
+	}
+	if len(decoded.State) != len(original.State) {
+		t.Errorf("state len: got %d, want %d", len(decoded.State), len(original.State))
+	}
+
+	// Codes are not in the BorWitness wire format and will be empty after decode.
+	if len(decoded.Codes) != 0 {
+		t.Errorf("Codes should be empty after BorWitness roundtrip, got %d", len(decoded.Codes))
+	}
+}
