eth/catalyst: implement engine_newPayloadWithWitnessV5 and use witness field spec ordering (#35009)

This PR:
- Adds `engine_newPayloadWithWitnessV5`. The codebase already supports
the previous `VX`, so only `V5` was missing.
- Make the consensus witness format use the field [ordering defined in
the
spec](8d7e68f4b7/src/ethereum/forks/amsterdam/stateless_host_exec_witness.py (L175-L176))
to make it canonical.

cc @gballet

---------

Co-authored-by: Guillaume Ballet <3272758+gballet@users.noreply.github.com>

core/stateless/encoding.go

@@ -17,8 +17,10 @@
 package stateless
 
 import (
+	"bytes"
 	"errors"
 	"io"
+	"slices"
 
 	"github.com/ethereum/go-ethereum/common/hexutil"
 	"github.com/ethereum/go-ethereum/core/types"
@@ -28,16 +30,25 @@ import (
 // ToExtWitness converts our internal witness representation to the consensus one.
 func (w *Witness) ToExtWitness() *ExtWitness {
 	ext := &ExtWitness{
-		Headers: w.Headers,
+		Headers: slices.Clone(w.Headers),
 	}
+	slices.Reverse(ext.Headers)
+
 	ext.Codes = make([]hexutil.Bytes, 0, len(w.Codes))
 	for code := range w.Codes {
 		ext.Codes = append(ext.Codes, []byte(code))
 	}
+	slices.SortFunc(ext.Codes, func(a, b hexutil.Bytes) int {
+		return bytes.Compare(a, b)
+	})
+
 	ext.State = make([]hexutil.Bytes, 0, len(w.State))
 	for node := range w.State {
 		ext.State = append(ext.State, []byte(node))
 	}
+	slices.SortFunc(ext.State, func(a, b hexutil.Bytes) int {
+		return bytes.Compare(a, b)
+	})
 	return ext
 }
 
@@ -46,7 +57,12 @@ func (w *Witness) FromExtWitness(ext *ExtWitness) error {
 	if len(ext.Headers) == 0 {
 		return errors.New("witness must contain at least one header")
 	}
-	w.Headers = ext.Headers
+	w.Headers = slices.Clone(ext.Headers)
+	// don't trust the input and sort headers in reverse order
+	// this is only useful for calling `Root`
+	slices.SortFunc(w.Headers, func(a, b *types.Header) int {
+		return b.Number.Cmp(a.Number)
+	})
 
 	w.Codes = make(map[string]struct{}, len(ext.Codes))
 	for _, code := range ext.Codes {

core/stateless/encoding_test.go

@@ -0,0 +1,130 @@
+// Copyright 2026 The go-ethereum Authors
+// This file is part of the go-ethereum library.
+//
+// The go-ethereum library is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// The go-ethereum library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
+
+package stateless
+
+import (
+	"bytes"
+	"math/big"
+	"testing"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/core/types"
+)
+
+func TestWitnessToExtWitnessOrdersFields(t *testing.T) {
+	witness := &Witness{
+		Headers: []*types.Header{testHeader(3), testHeader(2), testHeader(1)},
+		Codes: map[string]struct{}{
+			string([]byte{0x02}):       {},
+			string([]byte{0x01, 0xff}): {},
+			string([]byte{0x01}):       {},
+		},
+		State: map[string]struct{}{
+			string([]byte{0xff}): {},
+			string([]byte{0x00}): {},
+			string([]byte{0x7f}): {},
+		},
+	}
+	ext := witness.ToExtWitness()
+
+	checkHeaderNumbers(t, ext.Headers, []uint64{1, 2, 3})
+	checkBytes(t, "codes", ext.Codes, [][]byte{
+		{0x01},
+		{0x01, 0xff},
+		{0x02},
+	})
+	checkBytes(t, "state", ext.State, [][]byte{
+		{0x00},
+		{0x7f},
+		{0xff},
+	})
+}
+
+func TestWitnessFromExtWitnessNormalizesHeaderOrder(t *testing.T) {
+	tests := []struct {
+		name    string
+		headers []*types.Header
+	}{
+		{
+			name:    "spec ordered",
+			headers: []*types.Header{testHeader(1), testHeader(2), testHeader(3)},
+		},
+		{
+			name:    "not ordered",
+			headers: []*types.Header{testHeader(2), testHeader(3), testHeader(1)},
+		},
+		{
+			name:    "internal ordered",
+			headers: []*types.Header{testHeader(3), testHeader(2), testHeader(1)},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var witness Witness
+			if err := witness.FromExtWitness(&ExtWitness{Headers: tt.headers}); err != nil {
+				t.Fatalf("FromExtWitness returned error: %v", err)
+			}
+			checkHeaderNumbers(t, witness.Headers, []uint64{3, 2, 1})
+			if root := witness.Root(); root != testHeaderRoot(3) {
+				t.Fatalf("root mismatch: have %s, want %s", root, testHeaderRoot(3))
+			}
+		})
+	}
+}
+
+func TestWitnessFromExtWitnessRejectsEmptyHeaders(t *testing.T) {
+	var witness Witness
+	if err := witness.FromExtWitness(&ExtWitness{}); err == nil {
+		t.Fatal("expected empty witness error")
+	}
+}
+
+func testHeader(number uint64) *types.Header {
+	return &types.Header{
+		Number: new(big.Int).SetUint64(number),
+		Root:   testHeaderRoot(number),
+	}
+}
+
+func testHeaderRoot(number uint64) common.Hash {
+	return common.Hash{byte(number)}
+}
+
+func checkHeaderNumbers(t *testing.T, headers []*types.Header, want []uint64) {
+	t.Helper()
+	if len(headers) != len(want) {
+		t.Fatalf("header count mismatch: have %d, want %d", len(headers), len(want))
+	}
+	for i, header := range headers {
+		if header.Number.Uint64() != want[i] {
+			t.Fatalf("header %d number mismatch: have %d, want %d", i, header.Number.Uint64(), want[i])
+		}
+	}
+}
+
+func checkBytes(t *testing.T, name string, got []hexutil.Bytes, want [][]byte) {
+	t.Helper()
+	if len(got) != len(want) {
+		t.Fatalf("%s count mismatch: have %d, want %d", name, len(got), len(want))
+	}
+	for i := range got {
+		if !bytes.Equal(got[i], want[i]) {
+			t.Fatalf("%s %d mismatch: have %x, want %x", name, i, got[i], want[i])
+		}
+	}
+}

eth/catalyst/witness.go

@@ -162,6 +162,36 @@ func (api *ConsensusAPI) NewPayloadWithWitnessV4(ctx context.Context, params eng
 	return api.newPayload(ctx, params, versionedHashes, beaconRoot, requests, true)
 }
 
+// NewPayloadWithWitnessV5 is analogous to NewPayloadV5, only it also generates
+// and returns a stateless witness after running the payload.
+func (api *ConsensusAPI) NewPayloadWithWitnessV5(ctx context.Context, params engine.ExecutableData, versionedHashes []common.Hash, beaconRoot *common.Hash, executionRequests []hexutil.Bytes) (engine.PayloadStatusV1, error) {
+	switch {
+	case params.Withdrawals == nil:
+		return invalidStatus, paramsErr("nil withdrawals post-shanghai")
+	case params.ExcessBlobGas == nil:
+		return invalidStatus, paramsErr("nil excessBlobGas post-cancun")
+	case params.BlobGasUsed == nil:
+		return invalidStatus, paramsErr("nil blobGasUsed post-cancun")
+	case versionedHashes == nil:
+		return invalidStatus, paramsErr("nil versionedHashes post-cancun")
+	case beaconRoot == nil:
+		return invalidStatus, paramsErr("nil beaconRoot post-cancun")
+	case executionRequests == nil:
+		return invalidStatus, paramsErr("nil executionRequests post-prague")
+	case params.BlockAccessList == nil:
+		return invalidStatus, paramsErr("nil block access list post-amsterdam")
+	case params.SlotNumber == nil:
+		return invalidStatus, paramsErr("nil slotnumber post-amsterdam")
+	case !api.checkFork(params.Timestamp, forks.Amsterdam):
+		return invalidStatus, unsupportedForkErr("newPayloadV5 must only be called for amsterdam payloads")
+	}
+	requests := convertRequests(executionRequests)
+	if err := validateRequests(requests); err != nil {
+		return engine.PayloadStatusV1{Status: engine.INVALID}, engine.InvalidParams.With(err)
+	}
+	return api.newPayload(ctx, params, versionedHashes, beaconRoot, requests, true)
+}
+
 // ExecuteStatelessPayloadV1 is analogous to NewPayloadV1, only it operates in
 // a stateless mode on top of a provided witness instead of the local database.
 func (api *ConsensusAPI) ExecuteStatelessPayloadV1(params engine.ExecutableData, opaqueWitness hexutil.Bytes) (engine.StatelessPayloadStatusV1, error) {