feat: add support for stateful fixture format

.github/workflows/ci.action.yaml

@@ -20,10 +20,11 @@ jobs:
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           git-ref: ${{ github.event.pull_request.head.sha }}
+          git-repo: ${{ github.event.pull_request.head.repo.clone_url }}
           #run-args: '--log-level=debug'
           run-config-urls: >-
-            https://raw.githubusercontent.com/ethpandaops/benchmarkoor/${{ github.event.pull_request.head.sha }}/.github/workflows/config/benchmarkoor-global-cleanup.yaml,
-            https://raw.githubusercontent.com/ethpandaops/benchmarkoor/${{ github.event.pull_request.head.sha }}/.github/workflows/config/benchmarkoor-global-clientstdout.yaml
+            https://raw.githubusercontent.com/${{ github.event.pull_request.head.repo.full_name }}/${{ github.event.pull_request.head.sha }}/.github/workflows/config/benchmarkoor-global-cleanup.yaml,
+            https://raw.githubusercontent.com/${{ github.event.pull_request.head.repo.full_name }}/${{ github.event.pull_request.head.sha }}/.github/workflows/config/benchmarkoor-global-clientstdout.yaml
           run-config: |
             runner:
               benchmark:
@@ -62,10 +63,11 @@ jobs:
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           git-ref: ${{ github.event.pull_request.head.sha }}
+          git-repo: ${{ github.event.pull_request.head.repo.clone_url }}
           #run-args: '--log-level=debug'
           run-config-urls: >-
-            https://raw.githubusercontent.com/ethpandaops/benchmarkoor/${{ github.event.pull_request.head.sha }}/.github/workflows/config/benchmarkoor-global-cleanup.yaml,
-            https://raw.githubusercontent.com/ethpandaops/benchmarkoor/${{ github.event.pull_request.head.sha }}/.github/workflows/config/benchmarkoor-global-clientstdout.yaml
+            https://raw.githubusercontent.com/${{ github.event.pull_request.head.repo.full_name }}/${{ github.event.pull_request.head.sha }}/.github/workflows/config/benchmarkoor-global-cleanup.yaml,
+            https://raw.githubusercontent.com/${{ github.event.pull_request.head.repo.full_name }}/${{ github.event.pull_request.head.sha }}/.github/workflows/config/benchmarkoor-global-clientstdout.yaml
           run-config: |
             runner:
               container_runtime: podman
@@ -102,10 +104,11 @@ jobs:
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           git-ref: ${{ github.event.pull_request.head.sha }}
+          git-repo: ${{ github.event.pull_request.head.repo.clone_url }}
           #run-args: '--log-level=debug'
           run-config-urls: >-
-            https://raw.githubusercontent.com/ethpandaops/benchmarkoor/${{ github.event.pull_request.head.sha }}/.github/workflows/config/benchmarkoor-global-cleanup.yaml,
-            https://raw.githubusercontent.com/ethpandaops/benchmarkoor/${{ github.event.pull_request.head.sha }}/.github/workflows/config/benchmarkoor-global-clientstdout.yaml
+            https://raw.githubusercontent.com/${{ github.event.pull_request.head.repo.full_name }}/${{ github.event.pull_request.head.sha }}/.github/workflows/config/benchmarkoor-global-cleanup.yaml,
+            https://raw.githubusercontent.com/${{ github.event.pull_request.head.repo.full_name }}/${{ github.event.pull_request.head.sha }}/.github/workflows/config/benchmarkoor-global-clientstdout.yaml
           run-config: |
             runner:
               container_runtime: podman

action.yaml

@@ -20,6 +20,11 @@ inputs:
     required: false
     default: ''
 
+  git-repo:
+    description: 'Git repository URL to clone for building the image. Only used when image is not provided. Defaults to ethpandaops/benchmarkoor.'
+    required: false
+    default: 'https://github.com/ethpandaops/benchmarkoor.git'
+
   upload-artifacts:
     description: 'Whether to upload run results as GitHub artifacts'
     required: false
@@ -65,8 +70,10 @@ runs:
           GIT_REF="master"
         fi
 
-        echo "Cloning https://github.com/ethpandaops/benchmarkoor.git at ref $GIT_REF"
-        git clone https://github.com/ethpandaops/benchmarkoor.git benchmarkoor-build
+        GIT_REPO="${{ inputs.git-repo }}"
+
+        echo "Cloning ${GIT_REPO} at ref $GIT_REF"
+        git clone "${GIT_REPO}" benchmarkoor-build
         cd benchmarkoor-build
         git checkout "$GIT_REF"
 

pkg/eest/converter.go

@@ -63,6 +63,68 @@ func ConvertFixture(name string, fixture *Fixture) (*ConvertedTest, error) {
 	return result, nil
 }
 
+// ConvertStatefulFixture converts a stateful EEST fixture to JSON-RPC calls.
+// Unlike ConvertFixture, phases are explicit: setupEngineNewPayloads become
+// setup steps and engineNewPayloads become test steps.
+func ConvertStatefulFixture(name string, fixture *StatefulFixture) (*ConvertedTest, error) {
+	if fixture == nil {
+		return nil, fmt.Errorf("fixture is nil")
+	}
+
+	if len(fixture.EngineNewPayloads) == 0 {
+		return nil, fmt.Errorf("fixture has no test payloads")
+	}
+
+	result := &ConvertedTest{
+		Name:         name,
+		SetupLines:   make([]string, 0),
+		TestLines:    make([]string, 0),
+		GenesisHash:  fixture.SnapshotBlockHash,
+		FinalHash:    fixture.LastBlockHash,
+		PayloadCount: len(fixture.SetupEngineNewPayloads) + len(fixture.EngineNewPayloads),
+	}
+
+	// Convert setup payloads.
+	for i, payload := range fixture.SetupEngineNewPayloads {
+		lines, err := convertPayload(payload, i+1)
+		if err != nil {
+			return nil, fmt.Errorf("converting setup payload %d: %w", i, err)
+		}
+
+		result.SetupLines = append(result.SetupLines, lines...)
+	}
+
+	// Convert test payloads.
+	idOffset := len(fixture.SetupEngineNewPayloads)
+
+	for i, payload := range fixture.EngineNewPayloads {
+		lines, err := convertPayload(payload, idOffset+i+1)
+		if err != nil {
+			return nil, fmt.Errorf("converting test payload %d: %w", i, err)
+		}
+
+		result.TestLines = append(result.TestLines, lines...)
+	}
+
+	return result, nil
+}
+
+// ConvertPreRunFixture converts a pre-run fixture to JSON-RPC lines.
+func ConvertPreRunFixture(fixture *PreRunFixture) ([]string, error) {
+	var lines []string
+
+	for i, payload := range fixture.EngineNewPayloads {
+		converted, err := convertPayload(payload, i+1)
+		if err != nil {
+			return nil, fmt.Errorf("converting pre-run payload %d: %w", i, err)
+		}
+
+		lines = append(lines, converted...)
+	}
+
+	return lines, nil
+}
+
 // convertPayload generates JSON-RPC lines for a single payload.
 func convertPayload(payload *EngineNewPayload, id int) ([]string, error) {
 	if payload.ExecutionPayload == nil {

pkg/eest/fixture.go

@@ -6,9 +6,12 @@ import (
 	"strconv"
 )
 
-// SupportedFixtureFormat is the fixture format we support.
+// SupportedFixtureFormat is the fixture format for genesis-based tests.
 const SupportedFixtureFormat = "blockchain_test_engine_x"
 
+// SupportedStatefulFixtureFormat is the fixture format for snapshot-based stateful tests.
+const SupportedStatefulFixtureFormat = "blockchain_test_stateful_engine"
+
 // Fixture represents a single EEST test fixture.
 type Fixture struct {
 	Info               *FixtureInfo        `json:"_info"`
@@ -33,6 +36,43 @@ func (f *Fixture) IsSupportedFormat() bool {
 	return f.Info != nil && f.Info.FixtureFormat == SupportedFixtureFormat
 }
 
+// StatefulFixture represents a snapshot-based stateful EEST test fixture.
+// Unlike Fixture, it has no genesis or pre-alloc — state comes from an
+// external network snapshot referenced by SnapshotBlockNumber/Hash.
+type StatefulFixture struct {
+	Info                   *FixtureInfo        `json:"_info"`
+	Network                string              `json:"network"`
+	LastBlockHash          string              `json:"lastblockhash"`
+	Config                 *FixtureConfig      `json:"config"`
+	SnapshotBlockNumber    string              `json:"snapshotBlockNumber"`
+	SnapshotBlockHash      string              `json:"snapshotBlockHash"`
+	StartBlockNumber       string              `json:"startBlockNumber"`
+	StartBlockHash         string              `json:"startBlockHash"`
+	SetupEngineNewPayloads []*EngineNewPayload `json:"setupEngineNewPayloads"`
+	EngineNewPayloads      []*EngineNewPayload `json:"engineNewPayloads"`
+}
+
+// PreRunFixture represents a pre-run payload file for stateful benchmarks.
+// Contains global setup blocks (e.g. factory deploy) that bridge the gap
+// between the raw snapshot and the start block.
+type PreRunFixture struct {
+	Network             string              `json:"network"`
+	SnapshotBlockNumber string              `json:"snapshotBlockNumber"`
+	SnapshotBlockHash   string              `json:"snapshotBlockHash"`
+	EngineNewPayloads   []*EngineNewPayload `json:"engineNewPayloads"`
+}
+
+// FixtureConfig contains chain configuration for a fixture.
+type FixtureConfig struct {
+	Network string `json:"network"`
+	ChainID string `json:"chainid"`
+}
+
+// IsSupportedFormat returns true if the stateful fixture has a supported format.
+func (f *StatefulFixture) IsSupportedFormat() bool {
+	return f.Info != nil && f.Info.FixtureFormat == SupportedStatefulFixtureFormat
+}
+
 // BlockHeader represents an Ethereum block header.
 type BlockHeader struct {
 	ParentHash            string `json:"parentHash"`
@@ -206,7 +246,7 @@ type Consolidate struct {
 	TargetPubkey  string `json:"targetPubkey"`
 }
 
-// ParseFixtureFile parses a fixture JSON file.
+// ParseFixtureFile parses a fixture JSON file containing genesis-based fixtures.
 // The file contains a map of test names to Fixture objects.
 func ParseFixtureFile(data []byte) (map[string]*Fixture, error) {
 	var fixtures map[string]*Fixture
@@ -216,3 +256,37 @@ func ParseFixtureFile(data []byte) (map[string]*Fixture, error) {
 
 	return fixtures, nil
 }
+
+// ParseStatefulFixtureFile parses a fixture JSON file containing stateful fixtures.
+// The file contains a map of test names to StatefulFixture objects.
+func ParseStatefulFixtureFile(data []byte) (map[string]*StatefulFixture, error) {
+	var fixtures map[string]*StatefulFixture
+	if err := json.Unmarshal(data, &fixtures); err != nil {
+		return nil, err
+	}
+
+	return fixtures, nil
+}
+
+// DetectFixtureFormat inspects a fixture JSON file and returns the format
+// string from the first entry's _info.fixture-format field.
+// Returns empty string if the format cannot be determined.
+func DetectFixtureFormat(data []byte) string {
+	var raw map[string]json.RawMessage
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return ""
+	}
+
+	for _, entry := range raw {
+		var info struct {
+			Info *FixtureInfo `json:"_info"`
+		}
+		if err := json.Unmarshal(entry, &info); err == nil && info.Info != nil {
+			return info.Info.FixtureFormat
+		}
+
+		break // only check the first entry
+	}
+
+	return ""
+}