Tentative canonical guest program input support for Ethrex by jsign · Pull Request #44 · eth-act/ere-guests

jsign · 2026-04-27T22:36:04Z

This PR adds tentative support for the canonical EEST statelessInputBytes payload as a guest program input to the Ethrex stateless validator, alongside the existing legacy StatelessInput flow.

The goal is to start exercising the Ethrex guest with the canonical format that EEST's blockchain_test fixtures emit, without breaking the existing legacy fixture path used by the rest of the stack.

Ideally in the future, we would like to use this new Canonical stateless input in ere-guests since basically simplifies a lot of gymnastics we do today reg input preparation. This Canonical style is literally receiving fully prepared SSZ inputs from EEST fixtures, and mostly passing them directly to the guest program.

It is only implemented for Ethrex since I created a PR to support it lambdaclass/ethrex#6550.

Notes:

this PR shouldn't affect the current workload or zkboost, since we still support the now-named Legacy input style.
Reth is out of scope for now -- they don't even support any kind of SSZ input yet, and trying to support Canonical in their current style would simply add more tech debt to our repo that should eventually be removed after.

What changed

Host-side input construction (`stateless-validator-ethrex`)

introduced an Eip8025InputSource enum with two variants:
- Legacy { stateless_input, valid_block } — the existing path, unchanged in behaviour
- Canonical { ssz_input, chain_config } — accepts EEST statelessInputBytes directly
build_eip8025_input(...) now dispatches on the variant; the legacy path is moved to build_legacy(...) and a new build_canonical(...) rkyv-encodes the chain config and frames it together with the SSZ input
extracted the alloy_genesis::ChainConfig -> ethrex ChainConfig conversion into a shared to_ethrex_chain_config(...) helper so both paths use the same logic
added a new wire encoding encode_eip8025_canonical(ssz_input, rkyv_chain_config_bytes) producing [ssz_len: u32 LE][ssz_bytes][cfg_len: u32 LE][rkyv_chain_config_bytes]. This is a tentative format I created, but I think is quite solid. (ChainConfig isn't part of the specs, so this is why is passed "separately", but at least all the rest is proxied directly from the generated EEST fixture stateless input)

Fixture loading (`stateless-validator-debug`)

split fixture handling out into a new fixtures.rs module
StatelessValidatorFixture now wraps a FixtureInput::{Legacy, Canonical} enum
load_fixtures(path) auto-detects the JSON shape:
- legacy { name, stateless_input, success } → one fixture
- EEST blockchain_test map → one canonical fixture per (test, block) with a populated statelessInputBytes
chain_config_for_test(...) builds an alloy_genesis::ChainConfig from the EEST network + chainid + blobSchedule using reth_chainspec::create_chain_config and the ef-tests ForkSpec
Amsterdam is constructed manually because the pinned Reth stateless revision doesn't expose it yet — temporary workaround until upstream catches up. This allows to try make progress in ere-guests@main instead of other branches.
the Reth guest currently bails on canonical input (reth guest does not yet accept EEST canonical SSZ input); only Ethrex consumes it

…ming with versioning support

… JSON fixture path collection

Signed-off-by: Ignacio Hagopian <jsign.uy@gmail.com>

Co-authored-by: Copilot <copilot@github.com>

…pdated to conform to the specs

jsign

@han0110, I think this is ready for review without rush to gain a bit of time.

Still, for this PR to be merged we need to wait to see what happens with lambdaclass/ethrex#6550. Maybe that happens next week.

So mainly kind of half-opening for review. :)

jsign · 2026-05-01T14:59:55Z

+pub fn get_stateless_validator_output(
+    block_hash: B256,
+    success: bool,
+    chain_id: u64,


Technically is needed for the spec StatelessValidationResult.

This part of the API is a bit unstable, so not sure yet if this will be the final form. Opened a convo to explore this a bit more with this doc.

For now sticking to the current specs -- we can easily adjust whenever that convo comes to some conclusion and we change the specs.

This got already resolved in the latest release -- instead of chain_id : u64 we have a bit more comprehensive struct as input/output.

I think will take a bit of time for ELs to support this latest release, since it indirectly forces them to now support all changes in bal-devnet-7.

Leaving this as is now since it is the way that the latest v0.3.4 release works and most people are using/passing.

I soon can add a more focused PR supporting hte latest thing, or maybe if we are ambitious enough remove all this guest program wrappers and expect all ELs to return the output bytes themselves. Not sure yet how agressive we can be in shor term.

jsign · 2026-05-01T15:01:43Z

    HashMap::from([
        (
            b256!("e4bd1c4dc22a58a0a9a8e789e2c54b4ace2d1ebc16a605c3976723b52fc011f1"),
-            b256!("45328434f812b65daa21b4e8a3d6440d0da95fbd95a6c10b0a28f081cab53bd5"),


These things had to be updated since MAX_WITHDRAWALS_PER_PAYLOAD had the wrong value compared to the specs. The specs define a non-consensus compliant value for some testing framework problems.

Until those are fixed, we should stick to what the spec choose to allow running EEST tests properly.

So, since MAX_WITHDRAWALS_PER_PAYLOAD changes, that affects hash_tree_root results, thus why these updates are here.

jsign · 2026-05-01T15:02:56Z

+    /// Chain ID from the stateless validation chain configuration.
+    pub chain_id: u64,


https://github.com/ethereum/execution-specs/blob/ec23140720d6a9257a907c470ba1874623bd7b50/src/ethereum/forks/amsterdam/stateless_ssz.py#L166-L171 (at least for now)

jsign · 2026-05-01T15:03:19Z


 /// Limits
-pub const MAX_WITHDRAWALS_PER_PAYLOAD: usize = 16;
+pub const MAX_WITHDRAWALS_PER_PAYLOAD: usize = 65536; // Re-defined in EIP-8025 at least temporarily.


https://github.com/ethereum/execution-specs/blob/ec23140720d6a9257a907c470ba1874623bd7b50/src/ethereum/forks/amsterdam/stateless_ssz.py#L40-L43

I also resolved this problem in latest zkevm@v0.4.0 -- for now leaving it compatible with v0.3.4 since it is the thing most people are using. As said before, I can update this soon to the original value, or maybe we can nuke everything here and expect this be a responsibility of the EL.

jsign · 2026-05-01T15:04:27Z

TL;DR is that stateless-validator-debug now supports two fixtures:

The usual workload fixture -- nothing changed (called Legacy now)

Literal fixtures from EEST releases

For the later, basically each EEST test block has a statelessInputBytes and statelessOutputBytes. We use literally both to run guest and check correctness.

Ideally, asap, we can simply always use this canonical format which would be great. Simple format (just bytes), no manipulation in ere-guests, and all ELs receive the same. Meanwhile, we still support both.

jsign · 2026-05-01T15:10:32Z

+    if let Some(expected_output_bytes) = &summary.expected_output_bytes {
+        return handle_output_mismatch(
+            summary,
+            fixture_path,
+            expected_output_bytes,
+            allow_fixture_mismatch,
+        );
+    }


Reg checking the guest output -- if we have output bytes it means we ran an EEST fixture. Compare against the fixture statelessOutputBytes literally. If not, do what we did before.

jsign · 2026-05-01T15:12:12Z

-    stateless_input: &StatelessInput,
-    valid_block: bool,
-) -> anyhow::Result<Vec<u8>> {
+pub fn build_eip8025_input(source: Eip8025InputSource<'_>) -> anyhow::Result<Vec<u8>> {


Still single method to build Ethrex input, just that now we have these variants.

For workload/zkboost, they would just need to use Legacy as usual, and all should be okay. I think at some point we could make some helper to construct he canonical form from the eth_getBlock+debug_executionWitness and we could switch over everything to Canonical.

But trying to go a bit in steps to avoid complicating things too agressively.

jsign · 2026-05-01T15:12:28Z

+    ))
+}
+
+fn to_ethrex_chain_config(cfg: &alloy_genesis::ChainConfig) -> ChainConfig {


This is just extracted from below.

jsign · 2026-05-01T15:13:21Z

Explained a bit in the PR description. Can also be useful to see lambdaclass/ethrex#6550 but just "the expected thing" there.

han0110

So far LGTM! Will check again when the Ethrex PR is merged

han0110 · 2026-05-02T06:56:18Z


    fn decode_from_slice(slice: &[u8]) -> Result<Self, Self::Error> {
-        if slice.len() < STATELESS_VALIDATOR_OUTPUT_SIZE {
+        if slice.len() != STATELESS_VALIDATOR_OUTPUT_SIZE {


The check was loose to support ZisK that has fixed size output 256 bytes, but since we always hash the output so this never gets called.

I think we can leave it stricter as is, and to be compatible with our zkVM standard IO interface in the future, I'm thinking we can probably force the output to be [u8; 32] so this Decode impl can be even removed.

han0110 · 2026-05-02T07:14:45Z

Signed-off-by: Ignacio Hagopian <jsign.uy@gmail.com>

jsign · 2026-05-14T20:08:20Z

+pub fn get_stateless_validator_output(
+    block_hash: B256,
+    success: bool,
+    chain_id: u64,


This got already resolved in the latest release -- instead of chain_id : u64 we have a bit more comprehensive struct as input/output.

I think will take a bit of time for ELs to support this latest release, since it indirectly forces them to now support all changes in bal-devnet-7.

Leaving this as is now since it is the way that the latest v0.3.4 release works and most people are using/passing.

I soon can add a more focused PR supporting hte latest thing, or maybe if we are ambitious enough remove all this guest program wrappers and expect all ELs to return the output bytes themselves. Not sure yet how agressive we can be in shor term.

jsign · 2026-05-14T20:10:52Z


 /// Limits
-pub const MAX_WITHDRAWALS_PER_PAYLOAD: usize = 16;
+pub const MAX_WITHDRAWALS_PER_PAYLOAD: usize = 65536; // Re-defined in EIP-8025 at least temporarily.


I also resolved this problem in latest zkevm@v0.4.0 -- for now leaving it compatible with v0.3.4 since it is the thing most people are using. As said before, I can update this soon to the original value, or maybe we can nuke everything here and expect this be a responsibility of the EL.

jsign · 2026-05-14T20:12:08Z

+        /// Chain config sourced from the fixture.
+        chain_config: &'a alloy_genesis::ChainConfig,


As mentioned before, in zkevm@v0.4.0, now chain_config will be part of ssz_input, so this will get simpler soon when more people start targeting that release 😄

jsign · 2026-05-14T20:32:08Z

@han0110, added some boring extra commits compared to last review, plus some extra review comments (not that interesting either, just signaling good stuff happened pushing things in this repo to be simpler).

As we try to push ELs to stick to the latest standard, I think we can keep iterating on this changes topic to polish things better.

jsign and others added 12 commits April 27, 2026 19:20

tentative canonical guest program input support for Ethrex

ffe981c

fmt

33c8f47

Merge branch 'main' into jsign-tentative-canonical-guest-input-ethrex

804db0d

update ethrex dependencies to version 10.0.0 and enhance EIP-8025 fra…

25f729d

…ming with versioning support

refactor: streamline fixture path collection by introducing recursive…

ac2ccf9

… JSON fixture path collection

refactor: simplify success determination in load_fixtures function

dc6a4bd

jsign ethrex

f3e58b5

Signed-off-by: Ignacio Hagopian <jsign.uy@gmail.com>

cargo fetch

18284da

update ethrex

6e99f12

refactor:check statelessOutputBytes

e545819

fix MAX_WITHDRAWALS_PER_PAYLAOD constant value in EIP-8025

4dd4034

Co-authored-by: Copilot <copilot@github.com>

fix expected hash tree root given that max length of withdrwals was u…

68e93ef

…pdated to conform to the specs

jsign commented May 1, 2026

View reviewed changes

han0110 reviewed May 2, 2026

View reviewed changes

jsign added 3 commits May 14, 2026 16:54

Merge branch 'main' into jsign-tentative-canonical-guest-input-ethrex

00a6373

fix: update ethrex

40bb85c

fetch all

8a32ab0

Signed-off-by: Ignacio Hagopian <jsign.uy@gmail.com>

jsign commented May 14, 2026

View reviewed changes

jsign marked this pull request as ready for review May 14, 2026 20:31

jsign requested a review from han0110 May 14, 2026 20:31

han0110 approved these changes May 15, 2026

View reviewed changes

jsign merged commit fa2b127 into main May 15, 2026
41 checks passed

		/// Chain ID from the stateless validation chain configuration.
		pub chain_id: u64,

		/// Chain config sourced from the fixture.
		chain_config: &'a alloy_genesis::ChainConfig,

Conversation

jsign commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Host-side input construction (stateless-validator-ethrex)

Fixture loading (stateless-validator-debug)

Uh oh!

jsign left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsign May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

han0110 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsign May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsign commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jsign commented Apr 27, 2026 •

edited

Loading

Host-side input construction (`stateless-validator-ethrex`)

Fixture loading (`stateless-validator-debug`)

jsign May 14, 2026 •

edited

Loading

jsign May 14, 2026 •

edited

Loading

jsign commented May 14, 2026 •

edited

Loading