Skip to content

engineapi: switch Engine API SSZ to execution-apis#793 #21729

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
yperbasis wants to merge 13 commits into
base: main
Choose a base branch
from
Draft

engineapi: switch Engine API SSZ to execution-apis#793 #21729

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
1f9c45f
engineapi: switch Engine API SSZ to execution-apis#793
yperbasis Jun 10, 2026
d414050
engineapi: align Engine API SSZ with execution-apis#793 update
yperbasis Jun 15, 2026
82f088d
engineapi: enforce hash-list limit on decode, reset PayloadStatus opt…
yperbasis Jun 15, 2026
d255e08
engineapi: move should_override_builder to Cancun in BuiltPayload SSZ
yperbasis Jun 18, 2026
085bad2
Merge origin/main into yperbasis/engine-ssz-793
yperbasis Jun 18, 2026
7f5d008
engineapi: add geth byte-compatibility golden vectors for REST-SSZ
yperbasis Jun 18, 2026
945e5f9
engineapi, cl/cltypes/solid: bound execution_requests at MAX_EXECUTIO…
yperbasis Jun 18, 2026
d19d2af
engineapi: rename byte-compat vectors to golden, credit go-ethereum i…
yperbasis Jun 18, 2026
bbd83d8
engineapi, cl/cltypes/solid: simplify execution_requests bound to dec…
yperbasis Jun 18, 2026
f13fff6
engineapi: distinguish oversize from other read errors in readSSZBody
yperbasis Jun 18, 2026
8bedc58
engineapi: name the blob-bundle bound MAX_BLOB_COMMITMENTS_PER_BLOCK
Jun 18, 2026
85c721d
engineapi: compute SSZ entry sizes directly and reuse zero blob buffers
Jun 18, 2026
4497b4c
Merge branch 'main' into yperbasis/engine-ssz-793
yperbasis Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 0 additions & 20 deletions execution/engineapi/engine_api_methods.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,26 +64,6 @@ var ourCapabilities = []string{
"engine_getBlobsV1",
"engine_getBlobsV2",
"engine_getBlobsV3",
"POST /engine/v1/payloads",
"POST /engine/v2/payloads",
"POST /engine/v3/payloads",
"POST /engine/v4/payloads",
"POST /engine/v5/payloads",
"GET /engine/v1/payloads/{payload_id}",
"GET /engine/v2/payloads/{payload_id}",
"GET /engine/v3/payloads/{payload_id}",
"GET /engine/v4/payloads/{payload_id}",
"GET /engine/v5/payloads/{payload_id}",
"GET /engine/v6/payloads/{payload_id}",
"POST /engine/v1/forkchoice",
"POST /engine/v2/forkchoice",
"POST /engine/v3/forkchoice",
"POST /engine/v4/forkchoice",
"POST /engine/v1/blobs",
"POST /engine/v2/blobs",
"POST /engine/v3/blobs",
"POST /engine/v1/client/version",
"POST /engine/v1/capabilities",
}

// Returns the most recent version of the payload(for the payloadID) at the time of receiving the call
Expand Down
187 changes: 76 additions & 111 deletions execution/engineapi/engine_types/ssz.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,8 @@
package engine_types

import (
"encoding/hex"
"encoding/binary"
"fmt"
"strings"

"github.com/holiman/uint256"

Expand All @@ -17,18 +16,18 @@ import (
"github.com/erigontech/erigon/common"
"github.com/erigontech/erigon/common/clonable"
"github.com/erigontech/erigon/common/hexutil"
"github.com/erigontech/erigon/common/ssz"
"github.com/erigontech/erigon/execution/types"
)

const (
sszMaxBlobHashes = 4096
sszMaxGetBlobHashes = 128
sszMaxBytesPerTransaction = 0x40000000
sszMaxValidationError = 1024
sszBlobBytes = 0x20000
sszKZGBytes = 48
sszCellsPerExtBlob = 128
sszMaxCellProofs = 33554432
sszMaxBlobCommitmentsPerBlock = 4096
sszMaxBytesPerTransaction = 0x40000000
sszMaxValidationError = 1024
sszBlobBytes = 0x20000
sszKZGBytes = 48
sszCellsPerExtBlob = 128
sszMaxCellProofs = sszMaxBlobCommitmentsPerBlock * sszCellsPerExtBlob
)

var mainnetBeaconCfg = &clparams.MainnetBeaconConfig
Expand Down Expand Up @@ -196,50 +195,92 @@ func withdrawalsFromList(l *solid.ListSSZ[*cltypes.Withdrawal]) []*types.Withdra
return out
}

// optionalSSZString is Optional[String] = List[List[byte, MAX_ERROR_BYTES], 1].
type optionalSSZString struct {
value *string
}

func (o *optionalSSZString) Static() bool { return false }

func (o *optionalSSZString) EncodeSSZ(dst []byte) ([]byte, error) {
if o.value == nil {
return dst, nil
}
msg := []byte(*o.value)
if len(msg) > sszMaxValidationError {
msg = msg[:sszMaxValidationError]
}
dst = append(dst, 4, 0, 0, 0)
return append(dst, msg...), nil
}

func (o *optionalSSZString) DecodeSSZ(buf []byte, _ int) error {
o.value = nil
if len(buf) == 0 {
return nil
}
if len(buf) < 4 {
return ssz.ErrLowBufferSize
}
if binary.LittleEndian.Uint32(buf) != 4 {
return ssz.ErrBadOffset
}
if len(buf)-4 > sszMaxValidationError {
return ssz.ErrTooBigList
}
msg := string(buf[4:])
o.value = &msg
return nil
}

func (o *optionalSSZString) EncodingSizeSSZ() int {
if o.value == nil {
return 0
}
return 4 + min(len(*o.value), sszMaxValidationError)
}

func (*optionalSSZString) Clone() clonable.Clonable { return &optionalSSZString{} }

func (s *PayloadStatus) Static() bool { return false }

func (s *PayloadStatus) EncodeSSZ(dst []byte) ([]byte, error) {
status, err := payloadStatusByte(s.Status)
if err != nil {
return nil, err
}
var latest []common.Hash
if s.LatestValidHash != nil {
latest = []common.Hash{*s.LatestValidHash}
}
latestHashes := solid.NewHashList(1)
for _, hash := range latest {
latestHashes.Append(hash)
if s.LatestValidHash != nil {
latestHashes.Append(*s.LatestValidHash)
}
errBytes := solid.NewByteListSSZ(sszMaxValidationError)
validationErr := &optionalSSZString{}
if s.ValidationError != nil && s.ValidationError.Error() != nil {
msg := []byte(s.ValidationError.Error().Error())
if len(msg) > sszMaxValidationError {
msg = msg[:sszMaxValidationError]
}
_ = errBytes.SetBytes(msg)
msg := s.ValidationError.Error().Error()
validationErr.value = &msg
}
return ssz2.MarshalSSZ(dst, []byte{status}, latestHashes, errBytes)
return ssz2.MarshalSSZ(dst, []byte{status}, latestHashes, validationErr)
}

func (s *PayloadStatus) DecodeSSZ(buf []byte, version int) error {
latest := solid.NewHashList(1)
errBytes := solid.NewByteListSSZ(sszMaxValidationError)
validationErr := &optionalSSZString{}
status := []byte{0}
if err := ssz2.UnmarshalSSZ(buf, version, status, latest, errBytes); err != nil {
if err := ssz2.UnmarshalSSZ(buf, version, status, latest, validationErr); err != nil {
return err
}
Comment thread
yperbasis marked this conversation as resolved.
engineStatus, err := payloadStatusFromByte(status[0])
if err != nil {
return err
}
s.Status = engineStatus
s.LatestValidHash = nil
if latest.Length() > 0 {
hash := latest.Get(0)
s.LatestValidHash = &hash
}
if msg := string(errBytes.Bytes()); msg != "" {
s.ValidationError = NewStringifiedErrorFromString(msg)
s.ValidationError = nil
if validationErr.value != nil {
s.ValidationError = NewStringifiedErrorFromString(*validationErr.value)
}
return nil
}
Expand Down Expand Up @@ -315,7 +356,7 @@ func (a *PayloadAttributes) EncodeSSZ(dst []byte) ([]byte, error) {
return ssz2.MarshalSSZ(dst, uint64(a.Timestamp), a.PrevRandao[:], a.SuggestedFeeRecipient[:])
case clparams.CapellaVersion:
return ssz2.MarshalSSZ(dst, uint64(a.Timestamp), a.PrevRandao[:], a.SuggestedFeeRecipient[:], withdrawals)
case clparams.DenebVersion:
case clparams.DenebVersion, clparams.ElectraVersion, clparams.FuluVersion:
return ssz2.MarshalSSZ(dst, uint64(a.Timestamp), a.PrevRandao[:], a.SuggestedFeeRecipient[:], withdrawals, root[:])
default: // GloasVersion+
return ssz2.MarshalSSZ(dst, uint64(a.Timestamp), a.PrevRandao[:], a.SuggestedFeeRecipient[:], withdrawals, root[:], slot, targetGasLimit)
Expand All @@ -338,7 +379,7 @@ func (a *PayloadAttributes) DecodeSSZ(buf []byte, version int) error {
return err
}
a.Withdrawals = withdrawalsFromList(withdrawals)
case clparams.DenebVersion:
case clparams.DenebVersion, clparams.ElectraVersion, clparams.FuluVersion:
if err := ssz2.UnmarshalSSZ(buf, version, &timestamp, a.PrevRandao[:], a.SuggestedFeeRecipient[:], withdrawals, root[:]); err != nil {
return err
}
Expand Down Expand Up @@ -373,44 +414,6 @@ func (a *PayloadAttributes) payloadAttributesSSZVersion() clparams.StateVersion
return clparams.BellatrixVersion
}

func (v *ClientVersionV1) Static() bool { return false }

func (v *ClientVersionV1) EncodeSSZ(dst []byte) ([]byte, error) {
code := solid.NewByteListSSZ(2)
name := solid.NewByteListSSZ(64)
version := solid.NewByteListSSZ(64)
_ = code.SetBytes([]byte(v.Code))
_ = name.SetBytes([]byte(v.Name))
_ = version.SetBytes([]byte(v.Version))
var commit [4]byte
ch := strings.TrimPrefix(v.Commit, "0x")
if b, err := hex.DecodeString(ch); err == nil && len(b) >= 4 {
copy(commit[:], b[:4])
}
return ssz2.MarshalSSZ(dst, code, name, version, commit[:])
}

func (v *ClientVersionV1) DecodeSSZ(buf []byte, version int) error {
code := solid.NewByteListSSZ(2)
name := solid.NewByteListSSZ(64)
ver := solid.NewByteListSSZ(64)
var commit [4]byte
if err := ssz2.UnmarshalSSZ(buf, version, code, name, ver, commit[:]); err != nil {
return err
}
v.Code = string(code.Bytes())
v.Name = string(name.Bytes())
v.Version = string(ver.Bytes())
v.Commit = "0x" + hex.EncodeToString(commit[:])
return nil
}

func (v *ClientVersionV1) EncodingSizeSSZ() int { out, _ := v.EncodeSSZ(nil); return len(out) }
func (v *ClientVersionV1) HashSSZ() ([32]byte, error) {
return [32]byte{}, nil
}
func (*ClientVersionV1) Clone() clonable.Clonable { return &ClientVersionV1{} }

func newKZGCommitment(in []byte) *cltypes.KZGCommitment {
var out cltypes.KZGCommitment
copy(out[:], in)
Expand All @@ -436,13 +439,13 @@ func NewBlobsBundleSSZ(version clparams.StateVersion) *BlobsBundle {
func (b *BlobsBundle) Static() bool { return false }

func (b *BlobsBundle) EncodeSSZ(dst []byte) ([]byte, error) {
proofsLimit := sszMaxBlobHashes
proofsLimit := sszMaxBlobCommitmentsPerBlock
if b.blobsBundleSSZVersion() >= clparams.FuluVersion {
proofsLimit = sszMaxCellProofs
}
commitments := solid.NewStaticListSSZ[*cltypes.KZGCommitment](sszMaxBlobHashes, sszKZGBytes)
commitments := solid.NewStaticListSSZ[*cltypes.KZGCommitment](sszMaxBlobCommitmentsPerBlock, sszKZGBytes)
proofs := solid.NewStaticListSSZ[*cltypes.KZGProof](proofsLimit, sszKZGBytes)
blobs := solid.NewStaticListSSZ[*cltypes.Blob](sszMaxBlobHashes, sszBlobBytes)
blobs := solid.NewStaticListSSZ[*cltypes.Blob](sszMaxBlobCommitmentsPerBlock, sszBlobBytes)
for _, commitment := range b.Commitments {
commitments.Append(newKZGCommitment(commitment))
}
Expand All @@ -457,13 +460,13 @@ func (b *BlobsBundle) EncodeSSZ(dst []byte) ([]byte, error) {

func (b *BlobsBundle) DecodeSSZ(buf []byte, version int) error {
b.SSZVersion = clparams.StateVersion(version)
proofsLimit := sszMaxBlobHashes
proofsLimit := sszMaxBlobCommitmentsPerBlock
if b.SSZVersion >= clparams.FuluVersion {
proofsLimit = sszMaxCellProofs
}
commitments := solid.NewStaticListSSZ[*cltypes.KZGCommitment](sszMaxBlobHashes, sszKZGBytes)
commitments := solid.NewStaticListSSZ[*cltypes.KZGCommitment](sszMaxBlobCommitmentsPerBlock, sszKZGBytes)
proofs := solid.NewStaticListSSZ[*cltypes.KZGProof](proofsLimit, sszKZGBytes)
blobs := solid.NewStaticListSSZ[*cltypes.Blob](sszMaxBlobHashes, sszBlobBytes)
blobs := solid.NewStaticListSSZ[*cltypes.Blob](sszMaxBlobCommitmentsPerBlock, sszBlobBytes)
if err := ssz2.UnmarshalSSZ(buf, version, commitments, proofs, blobs); err != nil {
return err
}
Expand Down Expand Up @@ -554,41 +557,3 @@ func (b *BlobAndProofV2) DecodeSSZ(buf []byte, version int) error {
func (b *BlobAndProofV2) EncodingSizeSSZ() int { out, _ := b.EncodeSSZ(nil); return len(out) }
func (b *BlobAndProofV2) HashSSZ() ([32]byte, error) { return [32]byte{}, nil }
func (*BlobAndProofV2) Clone() clonable.Clonable { return &BlobAndProofV2{} }

type NullableBlobAndProofV2 struct {
BlobAndProof *BlobAndProofV2
}

func NewNullableBlobAndProofV2(blob *BlobAndProofV2) *NullableBlobAndProofV2 {
return &NullableBlobAndProofV2{BlobAndProof: blob}
}

func (n *NullableBlobAndProofV2) Static() bool { return false }

func (n *NullableBlobAndProofV2) EncodeSSZ(dst []byte) ([]byte, error) {
blobAndProof := solid.NewDynamicListSSZ[*BlobAndProofV2](1)
if n != nil && n.BlobAndProof != nil {
blobAndProof.Append(n.BlobAndProof)
}
return ssz2.MarshalSSZ(dst, blobAndProof)
}

func (n *NullableBlobAndProofV2) DecodeSSZ(buf []byte, version int) error {
blobAndProof := solid.NewDynamicListSSZ[*BlobAndProofV2](1)
if err := ssz2.UnmarshalSSZ(buf, version, blobAndProof); err != nil {
return err
}
n.BlobAndProof = nil
if blobAndProof.Len() != 0 {
n.BlobAndProof = blobAndProof.Get(0)
}
return nil
}

func (n *NullableBlobAndProofV2) EncodingSizeSSZ() int { out, _ := n.EncodeSSZ(nil); return len(out) }
func (n *NullableBlobAndProofV2) HashSSZ() ([32]byte, error) {
return [32]byte{}, nil
}
func (*NullableBlobAndProofV2) Clone() clonable.Clonable {
return &NullableBlobAndProofV2{}
}
Loading
Loading