Repository navigation
Description
Problem Statement
HashKey developers need Foundry's standalone local execution to begin from one deterministic B20 local genesis baseline while forked execution continues to preserve the remote chain's state. Today that baseline is represented as public fixed-size arrays of database-shaped tuples. Forge, Anvil, and several tests independently interpret those tuples, repeat the marker and storage application choreography, and separately remember when seeding is allowed.
This makes the behavior harder to change safely. The marker code and its hash can drift, tests bind to array positions instead of behavior, and adding or changing a profile-owned local genesis rule requires coordinated edits across multiple consumers. It also leaves the lifecycle contract implicit: the baseline must be applied once when a fresh standalone backing-state epoch is established, must not be replayed during later EVM creation, and must never be applied over a remote fork.
The current Anvil fork-to-standalone reset path exposes an additional correctness risk. Clearing the fork role does not by itself prove that the concrete database has lost its remote fallback and cached fork state. A state called FreshStandalone must actually use a clean local database; otherwise remote-only accounts, storage, or dynamic B20 token state can survive the reset.
Solution
Provide one profile-owned local genesis seam that accepts a resolved network profile, an explicit backing-state target, and a small database adapter. The module decides whether the profile requires portable local genesis state and, for HashKey standalone execution, applies the complete canonical B20 baseline. Forge and Anvil report only whether they are establishing a genuinely fresh standalone database or a remote fork and translate two generic mutation capabilities into their concrete databases.
The seam will hide the B20 marker recipe, feature set, slot derivation, operation count, and application choreography. It will be a successful no-op for remote forks and profiles without portable local genesis rules. It will be non-idempotent by contract and may only be invoked at backing-state establishment boundaries.
The migration will remove the public raw allocation representation and all consumers that index or iterate it. Tests will validate the canonical behavior through the shared seam, then validate Forge and Anvil only for their adapter translation and lifecycle responsibilities. Anvil's fork-to-standalone reset will establish a truly local database with no remote fallback before using the standalone target.
User Stories
- As a HashKey application developer, I want a standalone local node to start with the canonical B20 singleton markers, so that B20 contracts are available immediately in local development.
- As a HashKey application developer, I want the initial B20 feature admissions enabled in standalone execution, so that B20 asset, stablecoin, and policy workflows work from genesis.
- As a HashKey application developer, I want no dynamic B20 token accounts to be pre-created, so that token creation remains an execution-time behavior.
- As an Anvil user, I want resetting to standalone mode to restore the canonical B20 local genesis baseline, so that I can return to a known development state.
- As an Anvil user, I want resetting from a fork to standalone mode to remove all remote-only accounts and storage, so that the resulting node is genuinely local.
- As an Anvil user, I want resetting from a fork to standalone mode to remove remotely loaded dynamic B20 token state, so that fork cache cannot leak into a fresh local epoch.
- As an Anvil fork user, I want HashKey local genesis rules to perform no profile-owned writes against the fork, so that remote singleton code and feature storage are not replaced by local defaults.
- As an Anvil fork user, I want fork reset to continue using remote state without replaying the local B20 baseline, so that reset does not change network semantics.
- As a Forge user, I want a fresh non-fork backend to receive the same canonical B20 baseline as Anvil, so that Forge and Anvil agree on local HashKey behavior.
- As a Forge fork user, I want the local B20 baseline skipped, so that execution reflects the forked chain rather than local development defaults.
- As a governance test author, I want a deactivated B20 feature to remain deactivated when a later EVM is created, so that EVM reconstruction does not replay genesis state.
- As a governance test author, I want ordinary, inspected, nested, and existing-context EVM creation to inherit current state, so that runtime mutations are preserved.
- As a snapshot user, I want snapshot and revert to use normal database and journal semantics without replaying B20 genesis, so that snapshots restore exactly the captured state.
- As a Forge infrastructure user, I want cloned backends to preserve their current B20 state, so that cloning does not silently restore the original baseline.
- As a Forge infrastructure user, I want empty or derived reusable backends not to be mistaken for fresh standalone genesis, so that helper backends do not receive unintended B20 state.
- As an Anvil user with a custom genesis, I want unrelated account balances to be preserved when the profile applies B20-owned fields, so that local funding remains intact.
- As an Anvil user with a custom genesis, I want unrelated account storage to be preserved when B20 singleton code and nonce are patched, so that non-profile-owned state is not erased.
- As an Anvil user with a custom genesis, I want the existing precedence for profile-owned B20 code, nonce, and feature slots to remain unchanged, so that this refactor does not introduce a compatibility break.
- As an Ethereum profile user, I want local genesis behavior to remain unchanged, so that HashKey support does not affect standard Ethereum execution.
- As an Optimism profile user, I want local genesis behavior to remain unchanged, so that a shared EVM family does not imply B20 state.
- As a Celo profile user, I want local genesis behavior to remain unchanged, so that unrelated profile semantics are isolated.
- As a Tempo user, I want the existing specialized Tempo initialization path to remain intact, so that its chain ID, timestamp, hardfork, and test-account requirements are not forced through an unsuitable adapter.
- As a Foundry contributor, I want one canonical profile-owned local genesis entry point, so that profile applicability and target gating are not duplicated across backends.
- As a Foundry contributor, I want B20 marker bytes, nonce, feature membership, and slot derivation owned in one module, so that the canonical recipe cannot drift between consumers.
- As a Foundry contributor, I want database adapters to know only generic account and storage mutations, so that they do not depend on HashKey or B20 domain details.
- As a Foundry contributor, I want marker code hash derived from the complete code bytes by the adapter, so that code and hash cannot become inconsistent inputs.
- As a Foundry contributor, I want account patching to preserve non-owned fields, so that the adapter contract is explicit and reviewable.
- As a Foundry contributor, I want remote-fork no-op behavior testable without a live RPC dependency, so that the contract is deterministic and reliable in CI.
- As a Foundry contributor, I want adapter errors returned without string erasure, so that database failure context remains available to existing callers.
- As a Foundry contributor, I want application to stop after the first adapter error, so that a known failure is not followed by additional profile writes.
- As a Foundry contributor, I want the runtime reset failure model documented as non-atomic, so that this module does not make an unsupported rollback guarantee.
- As a test author, I want canonical B20 behavior tested through a recording adapter, so that tests do not depend on tuple layout or array indices.
- As a test author, I want Forge and Anvil adapter tests to pass through the same profile-owned seam, so that production translations cannot bypass the contract.
- As a test author, I want fork-to-standalone tests to assert remote-only state disappears, so that
FreshStandaloneis verified rather than inferred from a role flag. - As a maintainer, I want the legacy raw allocation API removed in the same migration series, so that a second shallow interface cannot continue accumulating callers.
- As a maintainer, I want legal CLI, JSON, RPC, tracing, and exit behavior unchanged, so that the architecture improvement is transparent to users.
- As a maintainer, I want builds without the HashKey capability to compile against the same high-level seam, so that production callers need no HashKey-specific conditional branches.
- As a future profile maintainer, I want portable account-and-storage genesis rules to reuse the same seam, so that adding a compatible profile does not require changing Forge and Anvil again.
Implementation Decisions
-
The highest test and behavior seam is a profile-owned local genesis operation. Profile selection and target gating happen once at this seam; Forge and Anvil do not contain HashKey-specific genesis branches.
-
The prototype established the following decision-rich interface shape:
enum ProfileGenesisTarget { FreshStandalone, RemoteFork, } trait LocalGenesisState { type Error; fn patch_account( &mut self, address: Address, code: Bytes, nonce: u64, ) -> Result<(), Self::Error>; fn set_storage( &mut self, address: Address, slot: U256, value: U256, ) -> Result<(), Self::Error>; } resolved_profile.apply_profile_genesis(target, &mut state)
Exact naming may change during implementation, but the interface must not expose a raw allocation, operation iterator, B20-specific write enum, mutable profile, or database-specific type.
-
FreshStandalonemeans the backing database is genuinely local, has no remote fallback, has no stale fork cache, and contains only the generic/user genesis for the new epoch before profile-owned state is applied. -
FreshStandalonemust not be derived from a booleanis_forkcheck alone. The lifecycle that establishes the concrete backing database must pass the target explicitly. -
RemoteForkmeans the profile-owned module performs zero adapter calls. This does not change the existing precedence of generic or user-provided genesis allocations on a fork. -
HashKey plus
FreshStandaloneapplies the complete canonical B20 local genesis baseline. -
HashKey plus
RemoteForkis a successful no-op. -
Profiles without portable local genesis rules are successful no-ops for either target.
-
Builds without the HashKey capability retain the same high-level interface and compile it as a no-op for available profiles.
-
The local genesis module owns the use of canonical singleton addresses in the genesis recipe, the marker code, marker nonce, initial feature set, feature-slot derivation, and application choreography.
-
Singleton addresses may remain shared network-semantic facts for tracing, inventory, protected-state classification, and other legitimate projections. The genesis patch associated with those addresses remains private to this module.
-
The module does not expose operation count or operation order as caller-visible behavior. Tests compare normalized canonical state rather than array positions.
-
The account adapter patches complete code and nonce while preserving balance, storage, and every field not explicitly owned by the capability.
-
The adapter derives code hash from code bytes. A separate code-hash input is prohibited.
-
The storage adapter replaces one slot without replacing account information or unrelated storage.
-
The interface is non-idempotent. Reapplying it can restore feature values that governance or tests intentionally changed, so it may only run while establishing a backing-state epoch.
-
Ordinary, inspected, nested, later, cloned, reusable, snapshot, and reverted execution paths do not call the local genesis seam.
-
Standalone startup calls the seam once with
FreshStandalone. -
Standalone reset calls it once only after establishing a genuinely fresh local backing database and reapplying generic/user genesis.
-
Initial fork and fork reset use
RemoteFork, producing no profile-owned writes. -
Anvil fork-to-standalone reset must replace or equivalently detach the remote-capable database before using
FreshStandalone. Clearing the fork role and callingclearon an existing forked database is insufficient. -
Profile-owned local genesis remains after generic/user genesis application, preserving the current precedence for canonical B20 code, nonce, and feature slots while retaining unrelated balance and storage.
-
The module returns the adapter's associated error directly and stops issuing writes after the first failure.
-
Initial construction or startup failure does not publish an executable backend.
-
Runtime Anvil reset remains non-atomic in this scope. A reset failure is returned as an RPC error and may leave cleared or partially reinitialized state. Rollback, quarantine, staging-and-swap, and fatal shutdown are separate concerns.
-
The public raw B20 genesis allocation, its getter, the HashKey state-plan variant, duplicated backend loops, marker literals in backend code, and tests coupled to allocation layout are removed by a hard cut.
-
The specialized Tempo initialization path remains separate because its required context is materially wider than account patching and single-slot storage writes.
-
No new warning, status output, JSON schema, RPC schema, or deprecation period is introduced.
Testing Decisions
- Good tests observe the shared profile-owned genesis behavior or a production lifecycle outcome. They do not read private allocation structures, assert tuple positions, or use the production initializer as both input and oracle.
- The primary contract test seam is the shared profile-owned genesis entry point with an in-memory recording adapter.
- Recording-adapter tests verify the normalized canonical singleton account patches, marker code, nonce, feature slots, and feature values without making operation order part of the contract.
- Recording-adapter tests verify that no dynamic B20 token account or storage is emitted.
- Recording-adapter tests verify zero adapter calls for
RemoteFork, non-HashKey profiles, and builds without the HashKey capability. - The recording adapter can fail at a configured domain operation. Tests cover an account-patch failure after prior success and a storage failure after successful account patches, asserting error identity and zero calls after failure.
- Forge adapter tests verify code-hash derivation, account-field preservation, single-slot storage behavior, and the canonical standalone baseline through the shared seam.
- Forge lifecycle tests retain the existing patterns for fresh backend construction, fork-backed construction, clone behavior, empty derived backends, and later EVM construction.
- A Forge lifecycle test changes feature admission and then creates normal, inspected, nested, or later EVM contexts, proving the baseline is not replayed.
- Anvil adapter tests verify the same account-field and storage preservation contract using its concrete database translation.
- Anvil integration tests follow the repository's existing isolated-node patterns for standalone startup, reset, fork reset, and profile transitions.
- Anvil standalone reset tests mutate B20 state before reset and verify the complete baseline is restored.
- Anvil fork tests use a local source node rather than a public RPC endpoint and verify the profile-owned module performs no local seed writes.
- Fork-preservation tests avoid conflicting user genesis unless the test is specifically asserting the existing generic/user genesis precedence.
- Fork-to-standalone tests verify more than the fork role flag: remote-only unrelated accounts, storage, cached state, and dynamic B20 token state must disappear.
- Snapshot/revert tests mutate B20 feature state after taking a snapshot, mutate it again, revert, and verify the snapshot value is restored without replaying genesis.
- Existing ABI-level tests remain the preferred way to verify feature admission from CLI and integration surfaces.
- Tests that must write a canonical raw storage slot use an independent fixed fixture rather than a production allocation getter.
- The complete non-HashKey/target matrix is tested at the shared module seam and is not duplicated in every production adapter integration suite.
- Existing Ethereum, Optimism, Celo, and Tempo lifecycle coverage remains in place to detect wiring regressions.
- CLI tests retain the repository's existing full-output and channel assertions: legal stdout, stderr, JSON, verbosity, quiet behavior, and exit status remain unchanged.
- Static deletion checks verify that the raw allocation type, getter, array-field indexing, and backend-local marker application loops no longer exist.
- Default and no-HashKey builds verify the shared interface does not leak a HashKey-only dependency.
- Focused tests run during each migration slice, followed by formatting, linting, relevant integration suites, and the workspace test suite before completion.
Out of Scope
- Changing the canonical B20 singleton addresses, marker bytecode, nonce, feature identifiers, slot derivation, or initial feature values.
- Pre-creating dynamic B20 tokens or their storage.
- Changing the B20 activation snapshot, precompile injection, trace identity, decoder, inventory, or protected-state rules.
- Moving Tempo initialization through the local genesis adapter.
- Adding a dynamic network plugin registry or a generic database CRUD framework.
- Introducing an operation-list API, public opaque allocation snapshot, or deprecated compatibility getter.
- Making the local genesis operation idempotent by inspecting current state.
- Adding user-genesis collision detection or changing the current precedence for profile-owned fields.
- Providing transactional multi-write application, runtime-reset rollback, staging-and-swap publication, backend quarantine, or fatal node shutdown after reset failure.
- Changing CLI or RPC output schemas, warnings, tracing, exit codes, or legal execution results.
- Refactoring unrelated state initialization, EVM construction, profile resolution, release gates, or generic family dispatch.
Further Notes
- The architecture contract has already been reviewed independently; the final review found no blocker or major issue.
- The key implementation blocker is the distinction between a cleared fork role and a genuinely fresh local database. The implementation is incomplete until fork-to-standalone reset proves there is no remote fallback or stale fork cache.
- The preferred migration order is: establish the shared seam and recording tests, migrate Forge, migrate Anvil together with the fresh-backing correction, migrate remaining test consumers, hard-delete the legacy allocation surface, then run regression gates.
- The raw allocation may exist only as a temporary same-series migration bridge. It is not part of the compatibility contract and must be removed before the feature is considered complete.
- Existing public-network-dependent test failures documented for this project remain unrelated to this specification; new tests for this work should use local deterministic infrastructure.
Activity
mowind commentedon Aug 4, 2026
Parent contract implemented by issues #66–#69. The shared local-genesis seam, Forge/Anvil migrations, fresh standalone backing reset, lifecycle/precedence coverage, and hard-cut legacy allocation removal are complete and pushed on v1.7.1-hsk-b20. Focused suites pass; the full workspace run only encountered documented unrelated environment failures.