feat: let a consumer install the per-run hash seed

[LukaszRozmej]

Changes

The zkEVM build starts with fixed hash seeds and previously exposed no way for a guest to replace them. Add UInt256.SeedHashes(in UInt256 seed) to install a full-width 256-bit seed in both standard and zkEVM builds. Int256.GetHashCode delegates to UInt256 and follows the same seed.

• Both builds replace their hash state when called. Standard builds initially draw cryptographic randomness per process; zkEVM builds initially use constants. Install the seed before populating hash-keyed containers: reseeding invalidates their stored hashes and is not synchronized with concurrent hashing.
• Keep mutable seeds in the nested RunSeed type so UInt256's own statics remain immutable after initialization. Both builds cache the AES round keys there rather than rebuilding them per hash.
• The AES path uses the two raw 128-bit seed halves across its rounds. The scalar path mixes all four 64-bit seed limbs into the key before widening multiplication and folding. There is no 32-bit seed expansion or XOR reduction of the seed halves.
• Three properties of a bare low ^ high fold made collisions constructible rather than searchable once the seed is public, and all three are addressed: MultiplyFold carries its factors past the product (low ^ high ^ a ^ b), the scalar mixer folds each limb pair through MumFold rather than MultiplyFold, and FoldHash closes with a further MumFold against a constant no key can reach. See below.
• Standard hosts without AES now use the multiply mixer instead of XxHash3. The zkEVM scalar path also uses this mixer, with software widening multiplication where hardware intrinsics are unavailable. Hash values change on every build and every path. These are in-memory hashes with no persisted or cross-version meaning.
• Remove the unused GetXxHashCode, its dedicated test file, two unused imports, and the System.IO.Hashing package reference and central version. The packed library now has no consumer NuGet dependencies; SourceLink remains a private build dependency.

Payload-derived seeding is motivated by the proposed EIP-8025 update and zkevm-standards#41. The guest's new_payload_request_root is public and identical across retries and provers for the same payload. Hash-flooding protection depends on the seed not being known before an adversary chooses keys; this API does not provide private entropy or cryptographic authentication.

Mixer changes, and why a public seed needs them

A per-payload seed removes the precomputed colliding set EIP-8025 is about, but the guest's seed is
public, so it does not remove a set built for the payload in hand. Three properties of low ^ high made
that set free to construct rather than something to search for.

A zero product erased its factors. low ^ high is zero whenever either factor is, and the scalar
mixer XORs the seed into the key limbs before multiplying the pairs. So a key matching the seed in one
limb erased the limb folded with it, and matching one limb of each half collapsed every key onto a
single value. MultiplyFold carries the factors past the product, which is why the carry lives there
rather than in the mixer: fixing only the halves leaves MumFold(a, b) == 0 reachable through
a == 0x9E3779B97F4A7C15, collapsing every key with that low half onto hash 0 regardless of its high
half.

The product is commutative. Folding a pair without position-separating constants gave a half the
same value when its two seed-masked words were exchanged — a colliding pair for every key, requiring no
cancellation at all. MumFold's asymmetric constants separate the positions, so the limb pairs go
through it.

The carried factors chained. Carrying the factors past the product removes the constant output a
zero factor gave, but not the family: low ^ high ^ a ^ b with a zero factor returns the other factor
verbatim, so the fold becomes the identity rather than a constant, and three of those compose. With
K1 = 0x9E3779B97F4A7C15 and K2 = 0xBF58476D1CE4E5B9, u0 = s0^K1 and u2 = s2^K1 zero each half's
first factor, u1 = s1^K2^K1 carries the low half's output onto the outer fold's constant, and the hash
reduces to FoldHash(u3^s3) — so u3 = s3 ^ (t | t<<32) gives hash 0 for every t. The AES path is
reachable the same way: a known seed means known round keys, so picking the round key freely and
inverting both rounds reaches any mixer input, including one whose low word zeroes the final fold's
first factor.

An avalanche finaliser does not answer this. splitmix64's is a bijection with a cheap inverse, so an
adversary picks a preimage of any value that folds to zero. FoldHash therefore closes with another
MumFold, against a constant no key can reach: its factor is a fixed non-zero value, so the fold cannot
degenerate to the identity, and inverting it is the same problem the mixer already rests on. Cost is one
widening multiply per hash.

Measured on the zkEVM build with intrinsics disabled, so GetHashCode() takes the scalar mixer, 512
keys per case under one installed seed:

keys	low ^ high	with the carry
one limb matches the seed, its partner free	1 distinct	512
one limb of each half matches, partners free	1 distinct	512
a half's two seed-masked words exchanged	512 collisions	0
control: all four limbs free	512	512
single-bit input flips	64 / 64	64 / 64

Since the halves now fold through MumFold, the value that zeroes a factor is seed ^ constant rather
than the seed itself; the first two rows describe the input as it was before that routing change, and
the regression tests use the value that zeroes a factor today.

The chained family, 4096 keys per case, before and after the closing fold:

keys	carry only	with the closing fold
scalar mixer, a zeroed factor at every fold	1 distinct	4096
standard x64 AES path, same chain via round inversion	1 distinct	4096

What remains is the generic bound of a 32-bit hash, which is not specific to this mixer. With the seed
known, searching for a colliding set costs roughly 2^(32(k-1)/k) draws for a k-way set; measured on the
same build, a pair took a mean of 98,366 draws over 20 trials, three-way 2.8 M, four-way 31.6 M and
five-way 86.0 M. Flooding a bucket needs many keys in it, so that cost climbs steeply — which is the
difference the three fixes above make, since each property handed out a set of unbounded size for free.
This is an argument about three structural shortcuts, not a cryptanalysis of the multiply structure.

Code generation

Review measurements at 39276e3 found the standard AES wrapper at 109 bytes without a stack frame, versus 98 bytes with a stack slot in the base. Each round-key load is a 16-byte memory operand; the second round consumes the other seed half. Using Multiply64 removes the previous stack store/load around multiplication. Both scalar variants inline without calls (134 bytes for the hardware multiply form, 363 bytes for the software form). These are code-generation observations, not end-to-end throughput measurements, and they predate both fold changes: the carry adds two XOR instructions per fold, and the closing fold adds one widening multiply plus its XORs per hash.

Testing

UInt256HashSeedTests covers replacement, distribution, and every seed bit both individually and
paired with its counterpart 128 bits away. Existing hash tests exercise the public path and the scalar
mixer. The fixture draws a fresh random seed at teardown, since SeedHashes is write-only and a seed
left installed there would otherwise be inherited by whatever runs next.

Each fix is pinned by a test that fails without it:

• MultiplyHash_ZeroingAFoldFactorDoesNotEraseItsPartner constructs the cancellation family under the
  value that zeroes a factor and asserts it distributed. It replaces
  MultiplyHash_MatchingTheSeedDoesNotCancelALimb, which pinned nothing once the halves went through
  MumFold: a factor is key ^ seed ^ constant, so key[i] == seed[i] left it at K1/K2 and it
  could not be zero — reverting the carry left all four of its cases green. The replacement fails on all
  four limbs without the carry.
• MultiplyHash_ExchangingAHalfsWordsChangesTheHash covers the commutativity half.
• MultiplyHash_ChainingZeroedFoldFactorsDoesNotCollapse covers the chain, and fails with the closing
  fold removed.
• MultiplyHash_MatchesBigIntegerReference models the composition explicitly, which is what pins the
  halves going through MumFold and the closing fold being there at all.

Full suite, Release on x64, in the four configurations CI covers:

Build	Intrinsics	Passed	Failed	Skipped
Standard	on	588,571	0	0
Standard	off	588,570	0	1
zkEVM	on	588,571	0	0
zkEVM	off	588,570	0	1

The skip is the AES-only distribution test.

dotnet pack succeeds. Inspection of the resulting package confirms both impl/std and impl/zkevm assemblies and an empty consumer dependency group.

Consumer

Nethermind #13166 installs the full payload root into its own span mixers and uses UInt256Comparer for guest storage-slot maps. It still uses the published int256 package and does not yet call this API. A subsequent package upgrade and explicit UInt256.SeedHashes(in root) call are needed to seed the package's default comparer too. The version bump remains a separate PR.

[LukaszRozmej]

@claude review - is the issue solved now?

[kamilchodola]

@LukaszRozmej fixed conflicts and did a codex review as follows:

Findings
[Robustness rule: shared mutable state] UInt256.std.cs:17-22, same in the zkEVM file. SeedHashes writes three statics (a 32-byte struct and two vectors) with no synchronisation, while GetHashCode reads them on any thread. A hash computed concurrently with a reseed can combine limbs of the old and new seed, producing a value neither seed reproduces. The XML docs disclose this, so it may be an accepted exception, but the rule requires reporting it. A cheap fix that also removes the tearing entirely: keep the three values in one immutable sealed class instance and swap a single static reference. Readers then pay one pointer load and always see a consistent seed.

[Test quality: hot path with no benchmark] UInt256.cs:1343-1352. GetHashCode gains a widening multiply per call, and the seeds move from static readonly primitives, which Tier-1 JIT folds into immediates and a constant vector load, to mutable statics that must be loaded on every hash. The PR reports code size only and says so. There is no GetHashCode benchmark in the benchmark project. UInt256 is the key type of the storage-cell dictionaries in Nethermind, so a BenchmarkDotNet number for the AES path and the scalar path, before and after, belongs in the PR before the version bump ships it.

Summary
Findings: Robustness rule: 1, Test quality: 1
Total: 2