Skip to content

refactor(evm): make family dispatch exhaustive #78

Closed
2 of 2 issues completed
Closed

Description

@mowind

Problem Statement

Foundry resolves each command to an immutable network profile and projects that profile to one of three closed EVM families: Ethereum, Optimism, or Tempo. Several EVM execution callers then translate that runtime family into a concrete Rust generic network type through local shadow enums or if / else if / else chains.

The current behavior is correct for the three existing families, and EVM construction rejects a profile that is paired with the wrong concrete family. However, some local projections treat every family that is not Tempo or Optimism as Ethereum. If a fourth EvmFamily is added, those callers will continue compiling and route the new family through Ethereum until construction rejects it at runtime. They therefore do not participate in the intended compile-time capability audit that should force every command to decide whether a new family is supported, unsupported, or requires specialized behavior.

The duplicated shadow enums and their mapping tests also create a second, shallower representation of information already owned by the canonical EvmFamily. This makes future family migrations less discoverable without providing a meaningful module seam.

Solution

Replace the EVM execution callers' shadow family projections and catch-all routing with direct, exhaustive matches on the canonical family carried by the resolved network profile.

This is a caller-local hardening refactor, not a workspace-wide dispatch module. Each command will keep its existing generic execution implementation and family-specific policy. Adding a new EvmFamily variant will make these direct matches fail to compile, forcing the implementation of that family to explicitly classify each command path.

The change will preserve the existing ownership model:

  • command profile resolution continues to own selector precedence, requirements, chain and fork inference, and exactly-once resolution;
  • the resolved network profile continues to own the canonical runtime family projection;
  • core EVM network bindings continue to associate each family with its concrete Alloy network and EVM factory;
  • EVM construction continues to validate profile-to-generic-family coherence before preparation;
  • Script continues to own Tempo batch validation and broadcast behavior;
  • Cast DA estimation, Cast RPC representation selection, Cast transaction construction, and Anvil execution normalization remain caller-local and are not moved into this change.

No macro, visitor framework, trait object, sum type, capability registry, plugin mechanism, or new dispatch interface will be introduced.

User Stories

  1. As a Foundry maintainer adding a new EVM family, I want every affected execution command to fail compilation until I classify the new family, so that unsupported behavior cannot be inherited accidentally.
  2. As a Forge maintainer, I want test execution to match directly on the canonical resolved family, so that Forge does not maintain a shadow family model.
  3. As a Cast maintainer, I want transaction replay to match directly on the canonical resolved family, so that a new family cannot silently enter the Ethereum replay path.
  4. As a Cast maintainer, I want local and traced calls to use the same canonical family decision as transaction replay without depending on a sibling command's private dispatch enum, so that command modules remain locally understandable.
  5. As a Chisel maintainer, I want REPL construction to match directly on the resolved family, so that every new family requires an explicit session-support decision.
  6. As a Script maintainer, I want Script's family selection to be exhaustive, so that a new family cannot silently inherit Ethereum script execution.
  7. As a Script user, I want Tempo batch mode and ordinary Tempo broadcast behavior to remain unchanged, so that dispatch hardening does not alter Script semantics.
  8. As a Script user on a non-Tempo network, I want the existing batch-mode rejection to remain unchanged, so that the refactor preserves diagnostics and exit behavior.
  9. As a HashKey user, I want HashKey profiles to continue executing through the Optimism EVM family while retaining their HashKey profile identity, so that B20 behavior remains intact.
  10. As a Celo user, I want Celo profiles to continue executing through the Ethereum EVM family while retaining Celo-specific profile semantics, so that existing behavior remains intact.
  11. As a Tempo user, I want Forge, Cast, Chisel, and Script to continue selecting Tempo-specific network bindings, so that typed transactions and EVM behavior do not regress.
  12. As an Optimism user, I want all affected commands to continue selecting OP-specific network bindings, so that OP transaction and execution semantics remain intact.
  13. As an Ethereum user, I want the default and explicit Ethereum profiles to continue selecting Ethereum bindings, so that the common path is unchanged.
  14. As a maintainer debugging profile mismatches, I want EVM construction's existing fail-closed validation to remain in place, so that direct caller matches are still protected against accidental wrong generic pairing.
  15. As a maintainer reviewing the code, I want family routing to use the canonical domain enum instead of local lookalike enums, so that there is one vocabulary for runtime EVM families.
  16. As a maintainer extending a command, I want command-specific capability policy to remain beside that command, so that a shared routing abstraction does not become a wide switchboard.
  17. As a Cast maintainer, I want RPC block, transaction, decoder, and DA representation paths to remain outside this EVM execution refactor, so that their different safety and capability contracts are not conflated with EVM construction.
  18. As an Anvil maintainer, I want Anvil's environment conversion, transaction conversion, factory selection, and halt normalization to remain owned by Anvil, so that typed execution differences are not erased behind an unsuitable common interface.
  19. As a contributor, I want compiler exhaustiveness to provide the migration inventory for future families at the affected execution leaves, so that required decisions are visible during development.
  20. As a contributor, I want obsolete shadow-enum mapping tests removed rather than reproduced against a new helper, so that tests describe externally meaningful behavior instead of implementation-shaped routing.
  21. As a release maintainer, I want stdout, stderr, JSON, RPC, exit-code, trace, broadcast, and session behavior to remain unchanged, so that this hardening refactor does not alter user-facing contracts.
  22. As a maintainer concerned about build characteristics, I want the refactor to preserve static dispatch and existing monomorphization, so that it adds no allocation, virtual dispatch, boxed futures, or runtime registry.
  23. As a future architecture reviewer, I want this cleanup to remain explicitly separate from the rejected workspace-wide dispatch-module candidate, so that syntax consolidation is not mistaken for a deep module.
  24. As an agent implementing this issue, I want a closed and focused scope, so that I can complete the hardening without refactoring unrelated network resolution or construction code.

Implementation Decisions

  • This issue is the explicitly authorized standalone maintenance follow-up to Candidate 5. It implements only the caller-local exhaustive-match cleanup; Candidate 5 remains rejected as a shared or deep dispatch module, and no migration series is created.
  • The canonical EvmFamily remains the only runtime family model. Affected execution callers will match directly on it.
  • Forge test execution will remove its local dispatch enum, projection helper, and helper-specific mapping tests.
  • Cast transaction replay will remove its local dispatch enum and projection helper.
  • Cast local/traced call execution will select the canonical family directly instead of importing a sibling command's private dispatch model.
  • Chisel execution will remove its local execution-kind enum, projection helper, and helper-specific mapping tests.
  • Script execution will replace its catch-all family routing with an exhaustive canonical-family decision while preserving the existing specialized Tempo branch and its batch flow.
  • Verify bytecode already uses a direct exhaustive family match and requires no structural change; it remains prior art for the affected execution callers.
  • Cast RPC block, transaction, raw-transaction decoding, and DA-estimation paths already use direct canonical-family matches. They are validation references, not migration targets.
  • Direct matches must name every current family and must not use wildcard arms, default arms, or a final catch-all branch that implies Ethereum.
  • HashKey remains an Optimism-family profile; no HashKey-specific execution arm will be added.
  • Celo remains an Ethereum-family profile; no Celo-specific execution arm will be added.
  • EVM construction's existing profile-to-generic-family validation remains unchanged as defense in depth.
  • Script retains ownership of Tempo batch support, non-Tempo batch rejection, ordinary Tempo broadcast, and verification continuation.
  • No shared dispatch helper, exported macro, visitor or operation trait, typed dispatch carrier, trait object, boxed future, executor sum type, capability registry, or plugin surface will be introduced.
  • No changes will be made to profile resolution precedence, network intent construction, fork identity lookup, concrete EVM network associations, precompile composition, local genesis, transaction-envelope selection, or Anvil construction.
  • Existing command result and diagnostic channels must remain unchanged.
  • The implementation should remove obsolete imports and tests that existed only for the shadow dispatch representations.
  • A source audit at completion must confirm that the removed shadow enum names and helpers no longer exist in the affected callers and that the migrated leaves use explicit canonical-family cases.

Testing Decisions

  • The highest existing behavior seams will be used; no new testing seam or dispatch interface will be created.
  • The primary compile-time seam is each affected command's direct exhaustive match on the canonical family. Rust exhaustiveness is the mechanism that turns a future family addition into a required migration decision.
  • Existing resolved-profile tests remain the source of truth for profile-to-family projection, including HashKey to Optimism and Celo to Ethereum. These facts will not be duplicated in command-local helper tests.
  • Existing EVM construction tests remain the source of truth for fail-closed profile-to-generic-family mismatch behavior.
  • Forge command/integration coverage should demonstrate that Ethereum, Optimism, Tempo, and HashKey profiles still reach the expected test execution behavior through the resolved-profile seam. Existing profile-resolution and HashKey test prior art should be reused rather than introducing a routing-only helper test.
  • Cast run and call coverage should continue testing command behavior through their command entry points and resolved-profile flow. Tests should not assert on a private dispatch enum or helper return value.
  • Chisel coverage should continue testing session construction and resolved profile persistence at the command/session seam. Tests should not recreate a local family mapping matrix solely for the removed enum.
  • Preserve the existing Tempo end-to-end checks for successful batch broadcast and atomic batch failure, and retain the existing ordinary Tempo script command coverage. Add one focused command-level regression test for non-Tempo --batch rejection, including failure status, empty stdout, and the existing stderr diagnostic. Do not introduce a routing-only Script helper or test-only dispatcher.
  • Verify's existing exhaustive dispatch and profile tests serve as structural prior art; no additional Verify behavior is required unless implementation changes it unexpectedly.
  • Cast RPC representation and DA tests remain out-of-scope implementation-wise but serve as prior art for direct canonical-family matching and caller-owned unsupported behavior.
  • Good tests assert externally observable command, session, construction, broadcast, trace, or diagnostic behavior. Tests must not assert source branch order, enum discriminants, helper names, or the number of match arms.
  • No test-only dispatcher, fake family registry, or public adapter will be added.
  • Focused tests for each modified command area should run during implementation, followed by formatting and relevant workspace checks.
  • Final validation must include a source audit for the removed shadow identifiers and catch-all projections in the affected leaves.

Acceptance Criteria

  1. Forge test execution directly exhaustively matches the canonical EvmFamily; its local shadow enum, projection helper, helper-only imports, and mapping test are removed.
  2. Cast run and Cast call each directly exhaustively match the canonical EvmFamily; Cast call no longer imports a dispatch enum or projection helper from Cast run.
  3. Chisel execution directly exhaustively matches the canonical EvmFamily; its execution-kind enum, projection helper, and helper-only mapping test are removed. Session identity persistence remains unchanged.
  4. Script directly exhaustively matches the canonical EvmFamily after its existing non-Tempo batch guard. The Tempo arm retains ordinary and batch broadcast plus verification continuation; Optimism and Ethereum retain their existing generic execution.
  5. Every migrated match explicitly names Ethereum, Optimism, and Tempo and has no wildcard/default arm or inferred Ethereum fallback.
  6. No shared helper, macro, trait, dispatcher, registry, sum type, or new public/test-only seam is introduced.
  7. Profile resolution, fork identity resolution, EVM construction, Cast RPC representation paths, Anvil, and Verify bytecode are unchanged.
  8. The helper-only Forge, Cast, and Chisel mapping tests are removed; existing command/profile/construction tests remain authoritative, and the focused non-Tempo Script batch-rejection regression is added.
  9. A final source audit finds no affected NetworkDispatchKind, network_dispatch_kind, ChiselExecutionKind, or chisel_execution_kind, and finds no catch-all family projection in the five migrated leaves.
  10. Formatting, focused tests for Forge, Cast, Chisel, and Script, and compilation with the HashKey feature enabled pass.

Out of Scope

  • Building a workspace-wide EVM family dispatch deep module.
  • Adding a new EVM family.
  • Adding runtime plugins or dynamic family registration.
  • Introducing an exported dispatch macro.
  • Introducing visitor, GAT, callback, or operation-object abstractions.
  • Erasing FoundryEvmNetwork behind trait objects or boxed executors.
  • Building an AnyFoundryEvmNetwork or related provider/executor sum-type graph.
  • Changing CommandProfileResolution, NetworkIntent, selector precedence, chain inference, or fork inference.
  • Changing the canonical profile-to-family mapping for Ethereum, Optimism, Tempo, HashKey, or Celo.
  • Changing EVM construction, profile-family validation, precompile injection, tracing, or local genesis behavior.
  • Refactoring Cast RPC block, transaction, decoding, DA estimation, access-list, estimate, make/send transaction, or token-transfer representation selection.
  • Refactoring Anvil family-specific environment, transaction, factory, pool, block, or halt normalization.
  • General cleanup of unrelated is_tempo() or is_optimism() branches that do not select the affected EVM execution generic type.
  • Compile-time or binary-size optimization; existing monomorphization is preserved.
  • User-facing CLI, RPC, configuration, output, or documentation changes.

Further Notes

The architecture review concluded that the repeated three-way routing does not pass the deletion test for a deep module: deleting a hypothetical shared dispatcher would only restore small caller-local matches, while profile resolution, EVM construction, Script policy, Cast capability policy, and Anvil normalization would remain in their current owners.

This issue intentionally implements only the maintenance debt uncovered by that review. It converts the affected catch-all execution projections into compiler-enforced exhaustive decisions without adding a new seam.

EVM execution and Alloy RPC representation are distinct leaf categories. Only execution paths that enter EVM construction receive profile-to-generic-family mismatch validation. RPC representation paths rely on their direct exhaustive matches and caller-owned behavior tests; they are not modified by this issue.

If a fourth independent EVM family is later proposed, the resulting compile errors at these migrated leaves should be treated as a capability checklist. Each command must explicitly choose supported, unsupported, or specialized behavior rather than inheriting a central default.

Activity

  1. mowind commented on Aug 5, 2026

    @mowind
    OwnerAuthor

    Closed via its two implementation tickets:

    • refactor(evm): harden uniform family dispatch #79 (refactor(evm): harden uniform family dispatch) — e7d3aad79: Forge test execution, Cast run, Cast call, and Chisel now match the canonical EvmFamily exhaustively; NetworkDispatchKind, network_dispatch_kind, ChiselExecutionKind, chisel_execution_kind, and their helper-only mapping tests are removed.
    • refactor(script): make family dispatch exhaustive #80 (refactor(script): make family dispatch exhaustive) — 7f08fecd7: Script matches the canonical EvmFamily after its non-Tempo batch guard; Tempo retains ordinary/batch broadcast and verification continuation; non-Tempo --batch rejection regression added.

    Final source audit confirms all five migrated leaves (Forge test, Cast run, Cast call, Chisel, Script) name Ethereum, Optimism, and Tempo explicitly with no wildcard/default/fallback, and no shadow dispatch names remain. Profile resolution, fork identity, EVM construction, Cast RPC representation paths, Anvil, and Verify bytecode are unchanged. Full workspace suite passes with the HashKey feature (only pre-existing failures remain).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentFully specified and ready for an AFK agent

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions