engine

package
v1.17.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 22, 2026 License: GPL-3.0, LGPL-3.0 Imports: 13 Imported by: 233

Documentation

Index

Constants

View Source 
const (
	ClientCode = "GE"
	ClientName = "go-ethereum"
)

Client identifiers to support ClientVersionV1.

Variables

View Source 
var (
	// VALID is returned by the engine API in the following calls:
	//   - newPayloadV1:       if the payload was already known or was just validated and executed
	//   - forkchoiceUpdateV1: if the chain accepted the reorg (might ignore if it's stale)
	VALID = "VALID"

	// INVALID is returned by the engine API in the following calls:
	//   - newPayloadV1:       if the payload failed to execute on top of the local chain
	//   - forkchoiceUpdateV1: if the new head is unknown, pre-merge, or reorg to it fails
	INVALID = "INVALID"

	// SYNCING is returned by the engine API in the following calls:
	//   - newPayloadV1:       if the payload was accepted on top of an active sync
	//   - forkchoiceUpdateV1: if the new head was seen before, but not part of the chain
	SYNCING = "SYNCING"

	// ACCEPTED is returned by the engine API in the following calls:
	//   - newPayloadV1: if the payload was accepted, but not processed (side chain)
	ACCEPTED = "ACCEPTED"

	GenericServerError       = &EngineAPIError{code: -32000, msg: "Server error"}
	UnknownPayload           = &EngineAPIError{code: -38001, msg: "Unknown payload"}
	InvalidForkChoiceState   = &EngineAPIError{code: -38002, msg: "Invalid forkchoice state"}
	InvalidPayloadAttributes = &EngineAPIError{code: -38003, msg: "Invalid payload attributes"}
	TooLargeRequest          = &EngineAPIError{code: -38004, msg: "Too large request"}
	InvalidParams            = &EngineAPIError{code: -32602, msg: "Invalid parameters"}
	UnsupportedFork          = &EngineAPIError{code: -38005, msg: "Unsupported fork"}
	TooDeepReorg             = &EngineAPIError{code: -38006, msg: "Too deep reorg"}

	STATUS_INVALID         = ForkChoiceResponse{PayloadStatus: PayloadStatusV1{Status: INVALID}, PayloadID: nil}
	STATUS_SYNCING         = ForkChoiceResponse{PayloadStatus: PayloadStatusV1{Status: SYNCING}, PayloadID: nil}
	INVALID_TERMINAL_BLOCK = PayloadStatusV1{Status: INVALID, LatestValidHash: &common.Hash{}}
)

Functions

func DecodeTransactions added in v1.17.1 

func DecodeTransactions(enc [][]byte) ([]*types.Transaction, error)

func ExecutableDataToBlock 

func ExecutableDataToBlock(data ExecutableData, versionedHashes []common.Hash, beaconRoot *common.Hash, requests [][]byte) (*types.Block, error)

ExecutableDataToBlock constructs a block from executable data. It verifies that the following fields: 

	len(extraData) <= 32
	uncleHash = emptyUncleHash
	difficulty = 0
 	if versionedHashes != nil, versionedHashes match to blob transactions

and that the blockhash of the constructed block matches the parameters. Nil Withdrawals value will propagate through the returned block. Empty Withdrawals value must be passed via non-nil, length 0 value in data.

func ExecutableDataToBlockNoHash added in v1.14.10 

func ExecutableDataToBlockNoHash(data ExecutableData, versionedHashes []common.Hash, beaconRoot *common.Hash, requests [][]byte) (*types.Block, error)

ExecutableDataToBlockNoHash is analogous to ExecutableDataToBlock, but is used for stateless execution, so it skips checking if the executable data hashes to the requested hash (stateless has to *compute* the root hash, it's not given).

Types

type BlobAndProofListV1 added in v1.17.4 

type BlobAndProofListV1 []*BlobAndProofV1

BlobAndProofListV1 is a list of BlobAndProofV1 with a hand-rolled JSON marshaler that avoids the overhead of encoding/json for large blob payloads.

func (BlobAndProofListV1) MarshalJSON added in v1.17.4 

func (list BlobAndProofListV1) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

type BlobAndProofListV2 added in v1.17.4 

type BlobAndProofListV2 []*BlobAndProofV2

BlobAndProofListV2 is a list of BlobAndProofV2 with a hand-rolled JSON marshaler that avoids the overhead of encoding/json for large blob payloads.

func (BlobAndProofListV2) MarshalJSON added in v1.17.4 

func (list BlobAndProofListV2) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

type BlobAndProofV1 added in v1.14.12 

type BlobAndProofV1 struct {
	Blob  hexutil.Bytes `json:"blob"`
	Proof hexutil.Bytes `json:"proof"`
}

type BlobAndProofV2 added in v1.16.0 

type BlobAndProofV2 struct {
	Blob       hexutil.Bytes   `json:"blob"`
	CellProofs []hexutil.Bytes `json:"proofs"` // proofs MUST contain exactly CELLS_PER_EXT_BLOB cell proofs.
}

type BlobsBundle added in v1.16.4 

type BlobsBundle struct {
	Commitments []hexutil.Bytes `json:"commitments"`
	Proofs      []hexutil.Bytes `json:"proofs"`
	Blobs       []hexutil.Bytes `json:"blobs"`
}

BlobsBundle includes the marshalled sidecar data. Note this structure is shared by BlobsBundleV1 and BlobsBundleV2 for the sake of simplicity.

- BlobsBundleV1: proofs contain exactly len(blobs) kzg proofs. - BlobsBundleV2: proofs contain exactly CELLS_PER_EXT_BLOB * len(blobs) cell proofs.

type ClientVersionV1 added in v1.13.13 

type ClientVersionV1 struct {
	Code    string `json:"code"`
	Name    string `json:"name"`
	Version string `json:"version"`
	Commit  string `json:"commit"`
}

ClientVersionV1 contains information which identifies a client implementation.

func (*ClientVersionV1) String added in v1.13.13 

func (v *ClientVersionV1) String() string

type EngineAPIError 

type EngineAPIError struct {
	// contains filtered or unexported fields
}

EngineAPIError is a standardized error message between consensus and execution clients, also containing any custom error message Geth might include.

func (*EngineAPIError) Error 

func (e *EngineAPIError) Error() string

func (*EngineAPIError) ErrorCode 

func (e *EngineAPIError) ErrorCode() int

func (*EngineAPIError) ErrorData 

func (e *EngineAPIError) ErrorData() interface{}

func (*EngineAPIError) With 

func (e *EngineAPIError) With(err error) *EngineAPIError

With returns a copy of the error with a new embedded custom data field.

type ExecutableData 

type ExecutableData struct {
	ParentHash      common.Hash          `json:"parentHash"    gencodec:"required"`
	FeeRecipient    common.Address       `json:"feeRecipient"  gencodec:"required"`
	StateRoot       common.Hash          `json:"stateRoot"     gencodec:"required"`
	ReceiptsRoot    common.Hash          `json:"receiptsRoot"  gencodec:"required"`
	LogsBloom       []byte               `json:"logsBloom"     gencodec:"required"`
	Random          common.Hash          `json:"prevRandao"    gencodec:"required"`
	Number          uint64               `json:"blockNumber"   gencodec:"required"`
	GasLimit        uint64               `json:"gasLimit"      gencodec:"required"`
	GasUsed         uint64               `json:"gasUsed"       gencodec:"required"`
	Timestamp       uint64               `json:"timestamp"     gencodec:"required"`
	ExtraData       []byte               `json:"extraData"     gencodec:"required"`
	BaseFeePerGas   *big.Int             `json:"baseFeePerGas" gencodec:"required"`
	BlockHash       common.Hash          `json:"blockHash"     gencodec:"required"`
	Transactions    [][]byte             `json:"transactions"  gencodec:"required"`
	Withdrawals     []*types.Withdrawal  `json:"withdrawals"`
	BlobGasUsed     *uint64              `json:"blobGasUsed"`
	ExcessBlobGas   *uint64              `json:"excessBlobGas"`
	SlotNumber      *uint64              `json:"slotNumber,omitempty"`
	BlockAccessList *bal.BlockAccessList `json:"blockAccessList,omitempty"`
}

ExecutableData is the data necessary to execute an EL payload.

func (ExecutableData) MarshalJSON 

func (e ExecutableData) MarshalJSON() ([]byte, error)

MarshalJSON marshals as JSON.

func (*ExecutableData) UnmarshalJSON 

func (e *ExecutableData) UnmarshalJSON(input []byte) error

UnmarshalJSON unmarshals from JSON.

type ExecutionPayloadBody added in v1.14.9 

type ExecutionPayloadBody struct {
	TransactionData []hexutil.Bytes     `json:"transactions"`
	Withdrawals     []*types.Withdrawal `json:"withdrawals"`
}

ExecutionPayloadBody is used in the response to GetPayloadBodiesByHash and GetPayloadBodiesByRange

type ExecutionPayloadEnvelope 

type ExecutionPayloadEnvelope struct {
	ExecutionPayload *ExecutableData `json:"executionPayload"  gencodec:"required"`
	BlockValue       *big.Int        `json:"blockValue"  gencodec:"required"`
	BlobsBundle      *BlobsBundle    `json:"blobsBundle"`
	Requests         [][]byte        `json:"executionRequests"`
	Override         bool            `json:"shouldOverrideBuilder"`
	Witness          *hexutil.Bytes  `json:"witness,omitempty"`
}

func BlockToExecutableData 

func BlockToExecutableData(block *types.Block, fees *big.Int, sidecars []*types.BlobTxSidecar, requests [][]byte) *ExecutionPayloadEnvelope

BlockToExecutableData constructs the ExecutableData structure by filling the fields from the given block. It assumes the given block is post-merge block.

func (ExecutionPayloadEnvelope) MarshalJSON 

func (e ExecutionPayloadEnvelope) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*ExecutionPayloadEnvelope) UnmarshalJSON 

func (e *ExecutionPayloadEnvelope) UnmarshalJSON(input []byte) error

UnmarshalJSON unmarshals from JSON.

type ForkChoiceResponse 

type ForkChoiceResponse struct {
	PayloadStatus PayloadStatusV1 `json:"payloadStatus"`
	PayloadID     *PayloadID      `json:"payloadId"`
}

type ForkchoiceStateV1 

type ForkchoiceStateV1 struct {
	HeadBlockHash      common.Hash `json:"headBlockHash"`
	SafeBlockHash      common.Hash `json:"safeBlockHash"`
	FinalizedBlockHash common.Hash `json:"finalizedBlockHash"`
}

type PayloadAttributes 

type PayloadAttributes struct {
	Timestamp             uint64              `json:"timestamp"             gencodec:"required"`
	Random                common.Hash         `json:"prevRandao"            gencodec:"required"`
	SuggestedFeeRecipient common.Address      `json:"suggestedFeeRecipient" gencodec:"required"`
	Withdrawals           []*types.Withdrawal `json:"withdrawals"`
	BeaconRoot            *common.Hash        `json:"parentBeaconBlockRoot"`
	SlotNumber            *uint64             `json:"slotNumber"`
}

PayloadAttributes describes the environment context in which a block should be built.

func (PayloadAttributes) MarshalJSON 

func (p PayloadAttributes) MarshalJSON() ([]byte, error)

MarshalJSON marshals as JSON.

func (*PayloadAttributes) UnmarshalJSON 

func (p *PayloadAttributes) UnmarshalJSON(input []byte) error

UnmarshalJSON unmarshals from JSON.

type PayloadID 

type PayloadID [8]byte

PayloadID is an identifier of the payload build process

func (PayloadID) Is added in v1.13.11 

func (b PayloadID) Is(versions ...PayloadVersion) bool

Is returns whether the identifier matches any of provided payload versions.

func (PayloadID) MarshalText 

func (b PayloadID) MarshalText() ([]byte, error)

func (PayloadID) String 

func (b PayloadID) String() string

func (*PayloadID) UnmarshalText 

func (b *PayloadID) UnmarshalText(input []byte) error

func (PayloadID) Version added in v1.13.11 

func (b PayloadID) Version() PayloadVersion

Version returns the payload version associated with the identifier.

type PayloadStatusV1 

type PayloadStatusV1 struct {
	Status          string         `json:"status"`
	Witness         *hexutil.Bytes `json:"witness,omitempty"`
	LatestValidHash *common.Hash   `json:"latestValidHash"`
	ValidationError *string        `json:"validationError"`
}

type PayloadVersion added in v1.13.11 

type PayloadVersion byte

PayloadVersion denotes the version of PayloadAttributes used to request the building of the payload to commence. 

var (
	// PayloadV1 is the identifier of ExecutionPayloadV1 introduced in paris fork.
	// https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#executionpayloadv1
	PayloadV1 PayloadVersion = 0x1

	// PayloadV2 is the identifier of ExecutionPayloadV2 introduced in shanghai fork.
	//
	// https://github.com/ethereum/execution-apis/blob/main/src/engine/shanghai.md#executionpayloadv2
	// ExecutionPayloadV2 has the syntax of ExecutionPayloadV1 and appends a
	// single field: withdrawals.
	PayloadV2 PayloadVersion = 0x2

	// PayloadV3 is the identifier of ExecutionPayloadV3 introduced in cancun fork.
	//
	// https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#executionpayloadv3
	// ExecutionPayloadV3 has the syntax of ExecutionPayloadV2 and appends the new
	// fields: blobGasUsed and excessBlobGas.
	PayloadV3 PayloadVersion = 0x3

	// PayloadV4 is the identifier of ExecutionPayloadV4 introduced in amsterdam fork.
	//
	// https://github.com/ethereum/execution-apis/blob/main/src/engine/amsterdam.md#executionpayloadv4
	// ExecutionPayloadV4 has the syntax of ExecutionPayloadV3 and appends the new
	// field slotNumber.
	PayloadV4 PayloadVersion = 0x4
)

type StatelessPayloadStatusV1 added in v1.14.10 

type StatelessPayloadStatusV1 struct {
	Status          string      `json:"status"`
	StateRoot       common.Hash `json:"stateRoot"`
	ReceiptsRoot    common.Hash `json:"receiptsRoot"`
	ValidationError *string     `json:"validationError"`
}

StatelessPayloadStatusV1 is the result of a stateless payload execution.

type TransitionConfigurationV1 

type TransitionConfigurationV1 struct {
	TerminalTotalDifficulty *hexutil.Big   `json:"terminalTotalDifficulty"`
	TerminalBlockHash       common.Hash    `json:"terminalBlockHash"`
	TerminalBlockNumber     hexutil.Uint64 `json:"terminalBlockNumber"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.