[Coordinator] Local setup for testing conflation backtesting

config/coordinator/coordinator-config-v2.toml

@@ -25,6 +25,7 @@ conflation-deadline = "PT6S" # =3*l2_block_time
 conflation-deadline-check-interval = "PT3S"
 conflation-deadline-last-block-confirmation-delay = "PT2S" # recommended: at least 2 * blockInterval
 l2-fetch-blocks-limit = 4000
+backtesting-directory = "/data/conflation-backtesting"
 force-stop-conflation-at-block-inclusive=100_000_000
 #force-stop-conflation-at-block-timestamp-inclusive=2000000000
 
@@ -310,3 +311,4 @@ failures-warning-threshold = 2
 
 [api]
 observability-port = 9545
+json-rpc-port = 9546

coordinator/app/src/main/kotlin/net/consensys/zkevm/coordinator/app/conflationbacktesting/ConflationBacktestingApp.kt

@@ -127,14 +127,8 @@ class ConflationBacktestingApp(
         endpoints = listOf(conflationBacktestingAppConfig.tracesApi.endpoint),
         requestLimitPerEndpoint = conflationBacktestingAppConfig.tracesApi.requestLimitPerEndpoint,
       ),
-      counters = mainCoordinatorConfig.traces.counters?.copy(
-        endpoints = listOf(conflationBacktestingAppConfig.tracesApi.endpoint),
-        requestLimitPerEndpoint = conflationBacktestingAppConfig.tracesApi.requestLimitPerEndpoint,
-      ),
-      conflation = mainCoordinatorConfig.traces.conflation?.copy(
-        endpoints = listOf(conflationBacktestingAppConfig.tracesApi.endpoint),
-        requestLimitPerEndpoint = conflationBacktestingAppConfig.tracesApi.requestLimitPerEndpoint,
-      ),
+      counters = null,
+      conflation = null,
     ),
     stateManager = mainCoordinatorConfig.stateManager.copy(
       endpoints = listOf(conflationBacktestingAppConfig.shomeiApi.endpoint),

docker/compose-spec-l2-services.yml

@@ -230,6 +230,43 @@ services:
       linea:
         ipv4_address: 11.11.11.115
 
+  conflation-backtesting-traces-node:
+    hostname: conflation-backtesting-traces-node
+    container_name: conflation-backtesting-traces-node
+    image: consensys/linea-besu-package:${BESU_PACKAGE_TAG:-beta-v5-rc6-20260316125820-f438666}
+    profiles: [ "l2", "l2-bc", "debug", "external-to-monorepo" ]
+    depends_on:
+      sequencer:
+        condition: service_healthy
+    ports:
+      - "7745:8545"
+      - "7746:8546"
+      - "7750:8550"
+      - "7751:8548"
+      - "30311:30303"
+    healthcheck:
+      test: [ "CMD-SHELL", "bash -c \"[ -f /tmp/pid ]\"" ]
+      interval: 1s
+      timeout: 1s
+      retries: 120
+    restart: "no"
+    environment:
+      JAVA_OPTS: -Xmx1g
+      LOG4J_CONFIGURATION_FILE: /var/lib/besu/log4j.xml
+    entrypoint: besu-untuned
+    command:
+      - --config-file=/var/lib/besu/conflation-backtesting-traces-node.config.toml
+      - --genesis-file=/initialization/genesis-besu.json
+      - --bootnodes=enode://14408801a444dafc44afbccce2eb755f902aed3b5743fed787b3c790e021fef28b8c827ed896aa4e8fb46e22bd67c39f994a73768b4b382f8597b0d44370e15d@11.11.11.101:30303
+    volumes:
+      - ./config/conflation-backtesting-traces-node/conflation-backtesting-traces-node-config.toml:/var/lib/besu/conflation-backtesting-traces-node.config.toml:ro
+      - ./config/conflation-backtesting-traces-node/log4j.xml:/var/lib/besu/log4j.xml:ro
+      - ./config/l2-genesis-initialization:/initialization/:ro
+      - ../tmp/local/:/data/:rw
+    networks:
+      linea:
+        ipv4_address: 11.11.11.118
+
   prover-v3: # prover compatible with the traces from zkbesu
     container_name: prover-v3
     hostname: prover-v3
@@ -291,6 +328,7 @@ services:
 #        condition: service_started
     ports:
       - "9545:9545"
+      - "9546:9546"
     healthcheck:
       test: ["CMD-SHELL", "curl -f http://localhost:9545/health || exit 1"]
       interval: 1s

docker/compose-tracing-v2.yml

@@ -56,6 +56,11 @@ services:
       file: compose-spec-l2-services.yml
       service: traces-node
 
+  conflation-backtesting-traces-node:
+    extends:
+      file: compose-spec-l2-services.yml
+      service: conflation-backtesting-traces-node
+
   prover-v3:
     extends:
       file: compose-spec-l2-services.yml

docker/config/conflation-backtesting-traces-node/conflation-backtesting-traces-node-config.toml

@@ -0,0 +1,56 @@
+data-path="/opt/besu/data"
+host-allowlist=["*"]
+sync-mode="FULL"
+p2p-port=30303
+
+min-gas-price=0
+
+# engine
+engine-host-allowlist=["*"]
+engine-rpc-port=8550
+engine-jwt-disabled=true
+
+# rpc
+rpc-http-enabled=true
+rpc-http-host="0.0.0.0"
+rpc-http-port=8545
+rpc-http-cors-origins=["*"]
+rpc-http-api=["ADMIN","DEBUG","NET","ETH","ENGINE","WEB3","PLUGINS","MINER","LINEA"]
+rpc-http-max-active-connections=200
+
+# ws
+rpc-ws-enabled=true
+rpc-ws-host="0.0.0.0"
+rpc-ws-port=8546
+rpc-ws-api=["ADMIN","TXPOOL","WEB3","ETH","NET","PERM"]
+rpc-ws-max-active-connections=200
+
+# graphql
+graphql-http-enabled=false
+
+# metrics
+metrics-enabled=true
+metrics-host="0.0.0.0"
+metrics-port=9545
+
+# database
+data-storage-format="BONSAI"
+
+# plugins
+plugins=["TracerReadinessPlugin","TracesEndpointServicePlugin","LineCountsEndpointServicePlugin","CaptureEndpointServicePlugin"]
+plugin-linea-conflated-trace-generation-traces-output-path="/data/conflation-backtesting/traces/v2/conflated"
+plugin-linea-rpc-concurrent-requests-limit=2
+plugin-linea-tracer-readiness-server-host="0.0.0.0"
+plugin-linea-tracer-readiness-server-port=8548
+plugin-linea-tracer-readiness-max-blocks-behind=5
+plugin-linea-l1l2-bridge-contract="0xe537D669CA013d86EBeF1D64e40fC74CADC91987"
+plugin-linea-l1l2-bridge-topic="e856c2b8bd4eb0027ce32eeaf595c21b0b6b4644b326e5b7bd80a1cf8db72e6c"
+plugin-linea-limitless-enabled=false
+
+cache-last-block-headers-preload-enabled=true
+cache-last-block-headers=50
+
+bonsai-limit-trie-logs-enabled=false
+bonsai-historical-block-limit=1024
+bonsai-parallel-tx-processing-enabled=false
+

docker/config/conflation-backtesting-traces-node/log4j.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="INFO" monitorInterval="2">
+  <Appenders>
+    <Console name="Console" target="SYSTEM_OUT">
+      <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSSZZZ} | %t | %-5level | %c{1} | %msg %throwable%n" />
+    </Console>
+  </Appenders>
+  <Loggers>
+    <!-- edit the package name/level below to add more logging to specific classes -->
+    <!-- no need to restart Besu as it will detect changes every 2s -->
+    <Logger name="org.hyperledger.besu" level="WARN" />
+    <!-- to avoid annoying message "INFO ... No sync target, waiting for peers. Current peers: 0" change to WARN-->
+    <Logger name="org.hyperledger.besu.ethereum.eth.sync.fullsync.FullSyncTargetManager" level="INFO" />
+    <Logger name="org.hyperledger.besu.ethereum.blockcreation" level="INFO" />
+    <Logger name="org.hyperledger.besu.consensus.merge.blockcreation" level="INFO" />
+    <Logger name="org.hyperledger.besu.ethereum.api.jsonrpc" level="TRACE" />
+    <Logger name="io.opentelemetry" level="WARN" />
+    <Root level="WARN">
+      <AppenderRef ref="Console"/>
+    </Root>
+  </Loggers>
+</Configuration>
+

docs/features/coordinator.md

@@ -120,6 +120,148 @@ Files use `.inprogress` suffix during processing. Naming pattern: `$startBlock-$
 
 If the coordinator goes down, blocks continue to be produced by the sequencer. On restart, the coordinator resumes from the last persisted state, re-submitting unfinalized blobs and aggregations.
 
+## Conflation Backtesting
+
+Conflation backtesting allows re-running the conflation and proof-request pipeline over a historical block range without affecting the live submission pipeline. It is useful for testing new blob compressor versions, batch sizing strategies, or conflation parameter changes against real historical data.
+
+### How It Works
+
+1. Submit one or more backtesting jobs via `conflation_createProverRequests`, each specifying a block range, blob compressor version, and the traces/state-manager endpoints to use.
+2. Each job spins up an isolated `ConflationBacktestingApp` instance that fetches trace counts from the given Traces API, compresses blobs using the specified compressor version, and writes prover request files to disk — identical in format to the live pipeline.
+3. Poll job status via `conflation_getReconflationJobsStatus` until `COMPLETED`.
+
+The `conflation-backtesting-traces-node` Docker service (see `docker/compose-spec-l2-services.yml`) provides a dedicated Besu node whose traces output is isolated to `/data/traces/v2/conflated-backtesting`, keeping backtesting traces separate from live pipeline traces.
+
+### JSON-RPC API
+
+#### `conflation_createProverRequests`
+
+Submits one or more backtesting jobs. Each element in `params` is an independent job. Returns a list of job IDs (one per submitted job).
+
+**Blob compressor versions:** `V1_2`, `V2`, `V3`
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "conflation_createProverRequests",
+  "params": [
+    {
+      "startBlockNumber": 1,
+      "endBlockNumber": 2,
+      "blobCompressorVersion": "V2",
+      "batchesFixedSize": null,
+      "parentBlobShnarf": null,
+      "tracesApi": {
+        "endpoint": "http://conflation-backtesting-traces-node:8545",
+        "version": "v2",
+        "requestLimitPerEndpoint": 1
+      },
+      "shomeiApi": {
+        "endpoint": "http://shomei:8888",
+        "version": "v0.0.4",
+        "requestLimitPerEndpoint": 1
+      }
+    }
+  ]
+}
+```
+
+**curl:**
+
+> Port `9546` is the coordinator's JSON-RPC API port (`json-rpc-port` under `[api]` in the coordinator config, mapped in `docker/compose-spec-l2-services.yml` as `"9546:9546"`).
+
+```bash
+curl -X POST http://localhost:9546 \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "conflation_createProverRequests",
+    "params": [
+      {
+        "startBlockNumber": 1,
+        "endBlockNumber": 2,
+        "blobCompressorVersion": "V2",
+        "batchesFixedSize": null,
+        "parentBlobShnarf": null,
+        "tracesApi": {
+          "endpoint": "http://conflation-backtesting-traces-node:8545",
+          "version": "beta-v5.0-rc6",
+          "requestLimitPerEndpoint": 1
+        },
+        "shomeiApi": {
+          "endpoint": "http://shomei:8888",
+          "version": "3.0.0",
+          "requestLimitPerEndpoint": 1
+        }
+      }
+    ]
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": ["1-2-hash"]
+}
+```
+
+#### `conflation_getReconflationJobsStatus`
+
+Polls the status of one or more jobs by ID. Returns `IN_PROGRESS` or `COMPLETED` for each.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "conflation_getReconflationJobsStatus",
+  "params": ["1-2-hash"]
+}
+```
+
+**curl:**
+
+```bash
+curl -X POST http://localhost:9546 \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "conflation_getReconflationJobsStatus",
+    "params": ["1-2-hash"]
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": ["COMPLETED"]
+}
+```
+
+### Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `startBlockNumber` | integer | ✓ | First block of the range to backtest (inclusive) |
+| `endBlockNumber` | integer | ✓ | Last block of the range to backtest (inclusive) |
+| `blobCompressorVersion` | string | ✓ | Compressor version to use: `V1_2`, `V2`, or `V3` |
+| `batchesFixedSize` | integer\|null | | Override batch size; `null` uses calculator-driven batching |
+| `parentBlobShnarf` | string\|null | | Hex-encoded parent shnarf to chain from; `null` starts fresh |
+| `tracesApi.endpoint` | string | ✓ | Traces API URL (typically the backtesting traces node) |
+| `tracesApi.version` | string | ✓ | Traces API version string |
+| `tracesApi.requestLimitPerEndpoint` | integer | ✓ | Max concurrent requests to the traces endpoint |
+| `shomeiApi.endpoint` | string | ✓ | State manager (Shomei) URL |
+| `shomeiApi.version` | string | ✓ | Shomei API version string |
+| `shomeiApi.requestLimitPerEndpoint` | integer | ✓ | Max concurrent requests to Shomei |
+
 ## Test Coverage
 
 | Test File | Runner | Validates |