Implement zkVM compatibility #10048

rubo · 2025-12-26T20:16:24Z

Note

These changes are preliminary. The idea is to start a discussion on how to apply/re-implement the required changes correctly.

Changes

Brought the work done on the stateless execution from the mmenshikov/feature/stateless_execv2 branch
Added another version of Nethermind.Numerics.Int256 package for zkVM without randomization source like in Hash256. It'd be good to find a better solution.
Introduced conditional compilation to activate the abovementioned changes when needed (partially done)
Added workflows to test the build and execution of zkVM-specific code

Types of changes

What types of changes does your code introduce?

Bugfix (a non-breaking change that fixes an issue)
New feature (a non-breaking change that adds functionality)
Breaking change (a change that causes existing functionality not to work as expected)
Optimization
Refactoring
Documentation update
Build-related changes
Other: Description

Testing

Requires testing

Yes
No

If yes, did you write tests?

Yes
No

src/Nethermind/Nethermind.Core/Crypto/Sha2.cs

src/Nethermind/Nethermind.Core/Extensions/SpanExtensions.cs

src/Nethermind/Nethermind.Consensus/Stateless/WitnessCollector.cs

src/Nethermind/Nethermind.Consensus/Stateless/WitnessGeneratingBlockHashProvider.cs

src/Nethermind/Nethermind.Consensus/Stateless/WitnessGeneratingBlockProcessingEnv.cs

src/Nethermind/Nethermind.Consensus/Stateless/WitnessGeneratingBlockProcessingEnvFactory.cs

src/Nethermind/Nethermind.Consensus/Stateless/WitnessGeneratingWorldState.cs

src/Nethermind/Nethermind.Serialization.Rlp/TxDecoder.cs

Directory.Packages.props

LukaszRozmej · 2025-12-29T13:02:28Z

tools/StatelessExecution/Program.cs

+    static int Main(string[] args)
+    {
+        Witness witness = new Witness()
+        {
+            Codes = ToByteArrays(codes),
+            Headers = ToByteArrays(headers),
+            Keys = ToByteArrays(keys),
+            State = ToByteArrays(state)
+        };
+
+        BlockHeader suggestedBlockHeader = new BlockHeader(
+            suggestedBlockForRpc.ParentHash,
+            suggestedBlockForRpc.Sha3Uncles,
+            suggestedBlockForRpc.Miner,
+            suggestedBlockForRpc.Difficulty,
+            suggestedBlockForRpc.Number!.Value,
+            suggestedBlockForRpc.GasLimit,
+            (ulong)suggestedBlockForRpc.Timestamp,
+            suggestedBlockForRpc.ExtraData,
+            suggestedBlockForRpc.BlobGasUsed,
+            suggestedBlockForRpc.ExcessBlobGas,
+            suggestedBlockForRpc.ParentBeaconBlockRoot,
+            suggestedBlockForRpc.RequestsHash)
+        {
+            StateRoot = suggestedBlockForRpc.StateRoot,
+            TxRoot = suggestedBlockForRpc.TransactionsRoot,
+            ReceiptsRoot = suggestedBlockForRpc.ReceiptsRoot,
+            Bloom = suggestedBlockForRpc.LogsBloom,
+            GasUsed = suggestedBlockForRpc.GasUsed,
+            MixHash = suggestedBlockForRpc.MixHash,
+            BaseFeePerGas = suggestedBlockForRpc.BaseFeePerGas!.Value,
+            WithdrawalsRoot = suggestedBlockForRpc.WithdrawalsRoot,
+            ParentBeaconBlockRoot = suggestedBlockForRpc.ParentBeaconBlockRoot,
+            RequestsHash = suggestedBlockForRpc.RequestsHash,
+            BlobGasUsed = suggestedBlockForRpc.BlobGasUsed,
+            ExcessBlobGas = suggestedBlockForRpc.ExcessBlobGas,
+            Hash = suggestedBlockForRpc.Hash,
+        };
+
+        // suggestedBlockHeader.Hash = suggestedBlockHeader.CalculateHash();
+
+        BlockHeader? baseBlock = null;
+        foreach (var header in witness.DecodedHeaders)
+        {
+            if (header.Hash == suggestedBlockHeader.ParentHash)
+            {
+                baseBlock = header;
+            }
+        }
+
+        if (baseBlock is null)
+        {
+            // Invalid witness headers
+            return 4;
+        }
+


Is this a hardcoded block? Looks weird.
Can we make it proper?

cc @tanishqjasoria @deffrian

@LukaszRozmej I believe for ease of testing it was hardcoded. We can eventually make blocks passed through zk input arguments.
(NOT through args - current args will break NativeAOT actually).

Yes it should be passed through arguments.
What is the difference - arguments vs args that you mean?

There must be zkVM-specific mechanism to pass inputs/outputs. args[] can't be used because there is no actualy storage for it anywhere. Having args[] in the code will break the NativeAOT bootstrap in runtime.

yes, we had the version that took in arguments for witness and block through arguments, but we need something different for zkVM (as @maximmenshikov pointed out)

i think what we can do here is seperate this part in two tools?

StatelessExecution

this takes input through CLI and decodes it

then call the stateless execution module with these input

zkVM execution

the input is hardcodesd( can be changed when we have proper logic to provide input to zkVm)

then call the same stateless module as before

Makes sense, the 2. Will probably be different per zkVM, we already have a hook how to do it for ZISK

maximmenshikov · 2025-12-29T13:33:42Z

src/Nethermind/Nethermind.Core/Crypto/Hash256.cs

+#if ZKVM
+        98316501; // TODO: remove ssl
+#else
+        (uint)System.Security.Cryptography.RandomNumberGenerator.GetInt32(int.MinValue, int.MaxValue);


could be that it is solved by minipal fix, but need to double check

src/Nethermind/Nethermind.Serialization.Rlp/TxDecoder.cs

LukaszRozmej · 2025-12-29T16:59:27Z

pushed a commit, things to still be done:

Change Int256 package and unify it
Check SHA2 and potentially remove it -- replaced
Proper I/O read and write - this needs to be ZISK only -- needs clarification
Why we need to change PathUtils? -- removed
Pipeline to build and verify
Optional: Randomness, but we can do without it

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot · 2026-01-13T22:28:57Z

src/Nethermind/Nethermind.Serialization.Rlp/TxDecoder.cs

+    public void RegisterDecoder(ITxDecoder decoder) => RegisterDecoder(decoder.Type, decoder);
+
+    public void RegisterDecoder(TxType type, ITxDecoder decoder) => _decoders[(int)type] = decoder;


The RegisterDecoder method now has two overloads. The original method that takes only an ITxDecoder now delegates to the new method that takes both TxType and ITxDecoder. While this maintains backward compatibility, the implementation extracts the type from the decoder and then passes it back. Consider whether this indirection is necessary or if callers should be updated to use the explicit type parameter.

Copilot · 2026-01-13T22:28:57Z

src/Nethermind/Nethermind.Core/Extensions/SpanExtensions.cs

+        private static readonly uint s_instanceRandom =
+#if ZKVM
+            2098026241U;


The fixed value 2098026241U used for zkVM appears to be arbitrary. This should be documented with a comment explaining why this specific value was chosen, or consider using a named constant with a descriptive name.

Suggested change

private static readonly uint s_instanceRandom =

#if ZKVM

2098026241U;

#if ZKVM

// Fixed, deterministic seed used in zkVM builds where randomness must be reproducible and/or secure RNG

// may be restricted. The specific value is arbitrary but must remain constant across zkVM runs.

private const uint ZkvmInstanceRandomSeed = 2098026241U;

#endif

private static readonly uint s_instanceRandom =

#if ZKVM

ZkvmInstanceRandomSeed;

rubo added 8 commits December 21, 2025 21:05

Update Nethermind.Numerics.Int256 package

9a7f3a9

Apply revised zkVM changes to master

8d3f3ed

Merge branch 'master' into feature/zkvm-exp

c747133

Fix world state scoping

4851f0f

Merge branch 'master' into feature/zkvm-exp

af61750

Remove redundant stuff

3646fa4

Revert Rlp.RegisterDecoders changes

a7c1efb

Add preliminary conditional compilation

1b7ab14

rubo requested review from deffrian, maximmenshikov and tanishqjasoria December 26, 2025 20:16

rubo commented Dec 26, 2025

View reviewed changes

src/Nethermind/Nethermind.Core/Crypto/Sha2.cs Outdated Show resolved Hide resolved

rubo changed the title ~~Implement ZKVM compatibility~~ Implement zkVM compatibility Dec 26, 2025

rubo commented Dec 26, 2025

View reviewed changes

src/Nethermind/Nethermind.Core/Extensions/SpanExtensions.cs Show resolved Hide resolved

Merge branch 'master' into feature/zkvm

4f40ee9

LukaszRozmej requested changes Dec 29, 2025

View reviewed changes

maximmenshikov reviewed Dec 29, 2025

View reviewed changes

Remove witness generation

791ebb4

rubo force-pushed the feature/zkvm branch from c8f255e to 791ebb4 Compare December 29, 2025 15:33

Fix FastHash and optimize TxDecoder

da26309

rubo and others added 9 commits December 30, 2025 16:59

Update Nethermind.Numerics.Int256 package

30be30e

Fix formatting

6712aa8

Update Nethermind.Numerics.Int256 package

50368ce

Merge branch 'master' into feature/zkvm

17011c7

Add zkVM changes for SpanExtensions

1abf3fc

Replace SHA-256 implementation

4345bc5

Merge branch 'master' into feature/zkvm

1bf6776

Boost SHA-256 implementation

f1d5ac1

Add SHA-256 tests

cfd1c96

rubo added 3 commits January 8, 2026 18:33

Revert PathUtils changes

5f04eeb

Revert Rlp changes

c64e022

Merge branch 'master' into feature/zkvm

d4f7be9

rubo requested review from Copilot and removed request for tanishqjasoria January 13, 2026 22:18

Copilot started reviewing on behalf of rubo January 13, 2026 22:18 View session

Copilot AI reviewed Jan 14, 2026

View reviewed changes

		public void RegisterDecoder(ITxDecoder decoder) => RegisterDecoder(decoder.Type, decoder);

		public void RegisterDecoder(TxType type, ITxDecoder decoder) => _decoders[(int)type] = decoder;

Implement zkVM compatibility #10048

Are you sure you want to change the base?

Implement zkVM compatibility #10048

Uh oh!

Conversation

rubo commented Dec 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Types of changes

What types of changes does your code introduce?

Testing

Requires testing

If yes, did you write tests?

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maximmenshikov Dec 29, 2025 • 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!

LukaszRozmej commented Dec 29, 2025 • edited by rubo Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

rubo commented Dec 26, 2025 •

edited

Loading

maximmenshikov Dec 29, 2025 •

edited

Loading

LukaszRozmej commented Dec 29, 2025 •

edited by rubo

Loading