Skip to content

feat(shadow): XMSS prover-cost model for the Shadow simulator (default-off)#366

Merged
mananuf merged 3 commits into
devnet-5from
feat/shadow-sim-xmss-rates
Jul 3, 2026
Merged

feat(shadow): XMSS prover-cost model for the Shadow simulator (default-off)#366
mananuf merged 3 commits into
devnet-5from
feat/shadow-sim-xmss-rates

Conversation

@mananuf

@mananuf mananuf commented Jul 3, 2026

Copy link
Copy Markdown
Collaborator

Shadow simulator: XMSS prover-cost model (default-off)

Brings the Shadow prover-cost model into devnet-5 so the published
ghcr.io/geanlabs/gean:devnet5 image carries the --shadow-xmss-* flags. They
default to 0 (no-op), so a real devnet node is unaffected — but the fuzzer can
then drive the single :devnet5 tag directly (it passes non-zero rates), instead
of maintaining a separate :shadow image whose lifecycle silently decouples from
mainline.

Why

Shadow runs the real binary but doesn't charge CPU. gean's XMSS proving is the
slowest thing it does, so under Shadow it would run in ~0 virtual time and the
simulation would be wildly unrepresentative of real slot timing. Every other lean
client models this; this is gean's model.

What's included

  1. feat(shadow) — the cost model + flags. internal/shadow/ sizes a
    virtual-time sleep from a signatures/second rate (n-signature op sleeps
    n/rate seconds). Exposed via
    --shadow-xmss-{aggregate,verify-aggregated,verify}-signatures-rate; each
    defaults to 0. The sleeps sit after the real XMSS op and never alter its
    inputs, outputs, or validity decision — timing only. Aggregate + single-verify
    sleeps run off the Engine tick loop. docker-build also tags the image
    :shadow.
  2. feat(keygen) — genesis overrides. --genesis-time so a driver can anchor
    genesis to Shadow's virtual epoch (unix 946684800); otherwise a wall-clock
    genesis sits decades in the sim future and no slot fires.
  3. chore — incidental. Carried alongside the Shadow work, unrelated to the
    model: the gean-engineer command + gean-perf skill, an auto-rebase workflow,
    SECURITY.md, and .gitignore entries.

Relationship to #365

This branch previously contained the aggregation budget-trim fix. That landed
separately via #365, so this branch has been rebased on top of it and no
longer carries the fix — the diff here is purely the Shadow delta above.

Safety / verification

  • Interop-safe: default-off. A production node never passes the flags, so it
    never sleeps; consensus behavior is unchanged.
  • The rebased tree is byte-identical to the branch previously validated on
    Shadow (rate-8: finalization advanced uniformly across all nodes, aggregation at
    budget) — the rebase only re-parented it onto the post-fix(aggregation): bound per-pass aggregation to the session budget #365 devnet-5.
  • Known limitation (documented in internal/shadow / the maintenance notes):
    SleepVerifyAggregated currently runs on the Engine select loop, so a large
    aggregated-verify rate can skew tick timing. Keep that rate modest; moving it
    off-loop is follow-up work. The other two sleeps are off-loop.

mananuf added 3 commits July 3, 2026 06:21
Shadow runs the real binary but doesn't charge CPU, so gean's slow XMSS
proving would run in ~0 virtual time and the simulation would be unrepresentative.
Model the cost as virtual-time sleeps sized by signatures/second rates, exposed
via --shadow-xmss-{aggregate,verify-aggregated,verify}-signatures-rate. Every
rate defaults to 0 (no-op), so a production node is unaffected; the sleeps sit
after the real op and never change its inputs, outputs, or validity decision.
Aggregate + single-verify sleeps run off the Engine tick loop; docker-build also
tags the image :shadow for the fuzzer.
Shadow's virtual clock starts at unix 946684800 (2000-01-01), so a wall-clock
genesis sits decades in the sim future and no slot ever fires. Add --genesis-time
so a driver can anchor genesis to the sim epoch.
Incidental additions carried alongside the Shadow work: the gean-engineer
command + gean-perf skill, a workflow that keeps this branch rebased on main,
a SECURITY.md disclosure policy, and .gitignore entries.
@mananuf mananuf merged commit 81f12a9 into devnet-5 Jul 3, 2026
@mananuf mananuf deleted the feat/shadow-sim-xmss-rates branch July 3, 2026 05:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant