@aztec/end-to-end 0.0.1-commit.a072138 → 0.0.1-commit.a5db02d

package/README.md

@@ -1,26 +1,241 @@
-# End to End
+# End-to-end tests
 
-This package includes end-to-end tests that cover Aztec's main milestones.
-These can be run locally either by starting anvil on a different terminal.
+This package holds Aztec's end-to-end (e2e) tests: full-stack scenarios that spin up an Aztec node (or
+several), a PXE, and an L1 (anvil) and exercise the system the way a real deployment would. It is the
+integration layer above the per-package unit tests.
 
-```
-anvil -p 8545 --host 0.0.0.0 --chain-id 31337
-```
+> **Two audiences.** The top of this document is a quick orientation for humans. The
+> [Reference for agents](#reference-for-agents) section at the bottom is the detailed, exhaustive
+> version — read that when you are placing, moving, or wiring up a test.
 
-and then running
+## Quick start
 
-```
-yarn test
+Run a single test (spawns its own in-process anvil):
+
+```bash
+yarn test:e2e src/automine/token/access_control.parallel.test.ts
+yarn test:e2e src/single-node/block-building/block_building.test.ts -t 'rejects a private then private double-spend'
 ```
 
-Or by running
+Turn up logging with `LOG_LEVEL` (`verbose` is the useful default; `debug:sequencer,archiver` scopes it):
 
+```bash
+LOG_LEVEL=verbose yarn test:e2e src/single-node/proving/default_node.test.ts
 ```
-yarn test:integration
+
+Each run spawns anvil on port 8545, so two tests can only run side by side if each gets its own
+`ANVIL_PORT` (p2p tests additionally bind fixed p2p ports and can never run concurrently — see
+[`src/p2p/README.md`](src/p2p/README.md)). To shake flakiness out of a test,
+`scripts/deflaker.sh yarn test:e2e <file>` reruns it up to 100 times and stops at the first failure
+(output lands in `scripts/deflaker.log`).
+
+Compose-based tests (those under `src/composed/`) need a running local network — see
+[Compose / HA / web3signer tests](#compose--ha--web3signer-tests).
+
+## Test categories
+
+Tests are grouped by **node topology** — the shape of the network a test needs. The top-level folder is
+the category; the second level names the behavior under test. Each category owns a base class that builds
+its environment, so a test file only describes the scenario, not the wiring.
+
+| Category | Topology | A test belongs here when… | README |
+|---|---|---|---|
+| [`automine/`](src/automine/README.md) | One node, deterministic `AutomineSequencer` — one block per tx, no committee/prover/validator. Fast. | it exercises contract or protocol behavior that doesn't depend on real block-building or consensus (transfers, nested calls, note discovery, tx semantics). | yes |
+| [`single-node/`](src/single-node/README.md) | One node, production sequencer (interval block production), optional prover. | it asserts on sequencer, proving, partial-proof, L1-reorg, recovery, fee, or cross-chain behavior on a single sequencer. | yes |
+| [`multi-node/`](src/multi-node/README.md) | N validators on an in-memory mock-gossip bus. | it needs a committee: consensus, attestations, slashing, governance, or multi-validator block production. | yes |
+| [`p2p/`](src/p2p/README.md) | Real libp2p transport between nodes. | the networking transport itself is under test (gossip, rediscovery, req/resp). | yes |
+| [`infra/`](src/infra/README.md) | Targets a deployed/external network (local anvil or a public testnet). | its concern is deployment or network targeting, not a specific protocol behavior. | yes |
+
+A handful of tests live **outside** this package, next to the code they test — see
+[Tests that live elsewhere](#tests-that-live-elsewhere). Other non-category test groups (`composed/`,
+`guides/`, `bench/`) are described in the reference section.
+
+## Where does my test go?
+
+1. **Does it need real networking transport?** → `p2p/`.
+2. **Does it need a validator committee (consensus/slashing/governance)?** → `multi-node/`.
+3. **Does it assert on the production sequencer, proving, reorgs, fees, or cross-chain flows?** →
+   `single-node/`.
+4. **Is it pure contract/protocol behavior that's happy with one-block-per-tx?** → `automine/` (the
+   default home for most contract tests).
+5. **Is it really a unit/integration test of one package with no Aztec node?** → it probably belongs in
+   that package, not here (see [Tests that live elsewhere](#tests-that-live-elsewhere)).
+
+When in doubt, prefer `automine/` for contract behavior and `single-node/` for anything that watches the
+chain advance.
+
+---
+
+## Reference for agents
+
+This section is the detailed contract for adding, moving, and wiring tests. It assumes you've read the
+overview above.
+
+### Category base classes
+
+Each category centralizes its environment in a base class. The hierarchy:
+
+- `single-node/single_node_test_context.ts` → **`SingleNodeTestContext`**. Owns the environment
+  (in-process anvil + L1 deploy), node spawning (`createNonValidatorNode`, `createProverNode`), the
+  `ChainMonitor`, and the epoch/checkpoint/proof-window/reorg waiters.
+- `multi-node/multi_node_test_context.ts` → **`MultiNodeTestContext extends SingleNodeTestContext`**.
+  Adds the N-validator topology over a mock-gossip bus, inheriting the base environment and waiters.
+- `automine/automine_test_context.ts` → **`AutomineTestContext`**. A sibling of `SingleNodeTestContext`
+  (both wrap `fixtures/setup.ts:setup()`), but fixes the automine topology and makes `AUTOMINE_E2E_OPTS`
+  the default. Exposes `markProvenAndWarp`, `registerContract`, `applyManualParentChild`.
+- `p2p/p2p_network.ts` → **`P2PNetworkTest`**. Real libp2p; node creation goes through
+  `fixtures/setup_p2p_test.ts`.
+- `infra/` has no shared base — its tests target a network selected by `L1_CHAIN_ID` (local anvil in CI,
+  a public testnet with credentials).
+
+All of the above ultimately wrap `fixtures/setup.ts:setup(numberOfAccounts, opts)`, the single entry point
+that deploys L1 contracts, starts the node(s), and provisions a PXE and accounts.
+
+### Setup factories
+
+Categories expose thin factories over their base's static `setup`, named by what the test wants, so a test
+calls the factory instead of spreading option presets:
+
+- `single-node/setup.ts`: `setupWithProver` (fake in-process prover — the single-node default) and
+  `setupBlockProducer` (no prover; raises `aztecProofSubmissionEpochs` to `NO_REORG_SUBMISSION_EPOCHS`
+  (1024) so unproven blocks aren't pruned, and points the PXE at `syncChainTip: 'proposed'`).
+- `automine` tests call `AutomineTestContext.setup({ numberOfAccounts })` directly.
+
+### The harness pattern (domain setup on top of a category)
+
+A test suite with bespoke domain setup does **not** fork `setup()`. It subclasses the category base and
+overrides a `protected hydrateFromContext(context)` split out of `setup`, so it reuses the base's
+rollup/epoch-cache/chain-monitor/waiter/teardown machinery while adding its own domain state. Examples:
+
+- `single-node/prover/` → `FullProverTest` (real Barretenberg env) extends `SingleNodeTestContext`.
+- `single-node/fees/` → `FeesTest`; `single-node/cross-chain/` → `CrossChainMessagingTest`.
+- `automine/token/` → `TokenContractTest` and `BlacklistTokenContractTest` extend `AutomineTestContext`
+  and run their `TokenSimulator`/snapshot setup after `super.setup()`.
+
+When two suites share behavior: if their public APIs are nearly identical, use inheritance; if behavior
+overlaps but APIs differ, compose. Don't duplicate a category's environment wiring.
+
+### The `.parallel` suffix
+
+CI splits each `it` in a `.parallel.test.ts` file into its own docker job, running it in isolation via
+`jest --testNamePattern` (the names come from `extract_test_names` in `bootstrap.sh`, which matches
+`it`/`test` at **any** nesting depth, not just top level). When an `it` runs alone its enclosing
+`beforeAll`/`beforeEach` hooks still run, but sibling `it`s do not. Rules:
+
+- The `.parallel` suffix is for files whose `it`s are **independent**: every `it` must pass when run
+  entirely on its own. That holds only when all shared state is built in `beforeAll`/`beforeEach` and no
+  `it` reads or asserts on state produced by a sibling `it`.
+- A file with sequential or stateful `it`s (progressive mutation across `it`s, a describe-scope variable
+  assigned in one `it` and read in another, a note/token created in an earlier `it` and used later) stays
+  a plain `.test.ts` **even if it has many top-level `it`s** — it runs as one ordered job. Adding
+  `.parallel` to such a file breaks CI, because each `it` then runs without its predecessors.
+- A file with a single top-level `it` is a plain `.test.ts`.
+- `it`/`test` names in a `.parallel` file must avoid regex/shell-special characters —
+  `"` `(` `)` `[` `]` `{` `}` `$` `\` and backtick. The split passes each name to
+  `run_test.sh ... "<name>"` as a shell-quoted `--testNamePattern` regex: an embedded `"` closes the
+  quote early and hard-fails the job, while regex metacharacters (`(` `)` `[` `]` `+` `*` `?` `|` `{` `}`)
+  silently match zero tests so the shard runs nothing and passes green — a coverage gap that hides the
+  test. Plain `.test.ts` files run as one job and are unaffected, so any name is fine there.
+  (`.` `!` `#` `-` `:` `,` are safe in `.parallel` names.)
+- Each file has exactly one top-level `describe`, named to match its path
+  (e.g. `describe('automine/token/transfer', …)`).
+
+### CI test discovery — `bootstrap.sh`
+
+`end-to-end/bootstrap.sh` enumerates tests in two arrays, and a test must resolve through the relevant one
+or it **won't run in CI**:
+
+- `test_cmds` — the standard run. Covers each category with a recursive glob (e.g.
+  `src/automine/!(simulation)/**/*.test.ts`, `src/multi-node/**/*.test.ts`), so a new file or sub-folder
+  inside an existing category is picked up automatically; only a new top-level category needs its own glob
+  line. Tests with bespoke handling sit outside the globs: the `single-node/prover/` lanes at the top of
+  the function (real proofs and custom resources under `CI_FULL`, `FAKE_PROOFS=1` otherwise) and
+  `avm_simulator` (below).
+- `compat_test_cmds` — the forward/legacy-compat run (a subset). This one enumerates **single-level leaf
+  globs** (e.g. `src/automine/token/*.test.ts`), so a new sub-folder whose tests should run against legacy
+  contract artifacts needs its own line here.
+
+Bespoke handling to be aware of:
+
+- **`avm_simulator`** (`automine/simulation/avm_simulator.test.ts`) has a dedicated line in `test_cmds`
+  that sets `DUMP_AVM_INPUTS_TO_DIR` (feeds the downstream `avm_check_circuit` job) and is therefore
+  excluded from the generic `simulation/` glob there (`!(avm_simulator)`). In `compat_test_cmds` it runs
+  as a regular test (no dump line), so it is **not** excluded there.
+- **`kernelless_simulation`** is excluded from `compat_test_cmds` only.
+
+After editing the arrays, confirm every `*.test.ts` resolves through exactly one line (no duplicate, no
+omission — anything excluded via `!(...)` must be matched by its dedicated line). Per-test bash `TIMEOUT`
+overrides live in the `case` block in `test_cmds` and must stay in sync with the test's `jest.setTimeout`.
+
+### Flaky tests — `.test_patterns.yml`
+
+Flaky/owner entries live in `.test_patterns.yml` at the **git root** (not in this package), keyed on the
+test path. A bare entry flags the test as flaky whenever it fails; add `error_regex` to flag only on a
+matching message; `skip: true` disables it. Blanket regex entries (e.g. `src/automine/.*\.test\.ts`) are
+depth-agnostic and survive folder renames; path-specific entries must be updated when a file moves.
+
+### Compose / HA / web3signer tests
+
+`src/composed/` tests run against a **running local network** rather than an in-process stack, via
+`scripts/run_test.sh` in different modes:
+
+- `src/composed/*.test.ts` → `compose` mode (e.g. `e2e_persistence`, `uniswap_trade_on_l1_from_l2`,
+  `e2e_cheat_codes` — the compose variant, distinct from the relocated unit-style one).
+- `src/composed/web3signer/*.test.ts` → `web3signer` mode (remote-signer scenarios).
+- `src/composed/ha/*.test.ts` → `ha` mode (high-availability multi-process scenarios).
+- `src/guides/*.test.ts` → tutorial/guide flows; `src/bench/` → benchmarks (see `bench_cmds`).
+
+Run one compose test locally with `yarn test:compose <name>` (anvil + the test runner are spawned for
+you), or `docker-compose up` for separate containers.
+
+### Tests that live elsewhere
+
+Tests with **no Aztec node** that exercise one package belong in that package, not here:
+
+- L1 cheat-code behavior (`EthCheatCodes`/`RollupCheatCodes` against raw anvil) → `@aztec/ethereum`
+  (`ethereum/src/test/eth_cheat_codes.test.ts`).
+- The `SequencerPublisher` integration test (anvil + L1 deploy, no node) → `@aztec/sequencer-client`
+  (`sequencer-client/src/publisher/`).
+
+These run in their own package's test lane (both packages already run anvil-backed integration tests).
+
+### Support directories (not test categories)
+
+- `fixtures/` — the shared `setup()`, option presets (`fixtures.ts`), the named node-level waiters
+  (`wait_helpers.ts`), the span instrumentation (`timing.ts` — `testSpan`, zero-cost unless
+  `TEST_TIMING_FILE` is set), `l1_to_l2_messaging`, and common utils.
+- `shared/` — shared test bodies, the `CrossChainTestHarness`, and `timing_env.mjs`, a **custom jest
+  `testEnvironment`** referenced from this package's `package.json`. `yarn prepare` / the package-json
+  check will try to revert it to the default — don't let it.
+- `simulators/` — in-TS reference models (`TokenSimulator`, `LendingSimulator`) used to assert contract
+  behavior.
+- `test-wallet/`, `bench/`, `spartan/`, `quality_of_service/`, `forward-compatibility/` — helpers,
+  benchmarks, and network/ops tests outside the topology categories.
+
+### Running tests against legacy contract artifacts
+
+To verify that contracts deployed from a previous release still work against the current stack, set
+`CONTRACT_ARTIFACTS_VERSION` to a published version of `@aztec/noir-contracts.js` /
+`@aztec/noir-test-contracts.js`:
+
+```bash
+CONTRACT_ARTIFACTS_VERSION=4.1.3 yarn test:e2e src/automine/token/access_control.parallel.test.ts
 ```
 
-which will spawn the two processes.
+Only the JSON artifact files (`.../artifacts/*.json`) are redirected. The TypeScript wrapper classes
+(e.g. `TokenContract`) continue to load from the current workspace and use the current `@aztec/aztec.js` —
+so this exercises whether a deployed contract's ABI / bytecode / notes still work through the *new* client,
+not whether the legacy wrapper code still imports cleanly.
 
-You can also run this by `docker-compose up` which will spawn 2 different containers for Anvil and the test runner.
+The first run downloads the pinned packages into `.legacy-contracts/<version>/node_modules/` (cached across
+runs). A startup banner and a per-redirect line are printed to stderr so you can confirm the legacy
+artifacts were actually loaded:
+
+```
+[legacy-contracts][jest] CONTRACT_ARTIFACTS_VERSION=4.1.3
+[legacy-contracts][jest] redirecting @aztec/noir-contracts.js/artifacts/*.json -> .legacy-contracts/4.1.3/...
+[legacy-contracts][jest] redirected token_contract-Token.json -> /abs/.../.legacy-contracts/4.1.3/.../token_contract-Token.json
+```
 
-You can run a single test by running `yarn test:compose <test_name>`.
+When `CONTRACT_ARTIFACTS_VERSION` is unset the test run is byte-identical to the default behaviour. The
+cache is populated automatically on first use.

package/dest/automine/automine_test_context.d.ts

@@ -0,0 +1,85 @@
+import type { ContractArtifact } from '@aztec/aztec.js/abi';
+import type { AztecAddress } from '@aztec/aztec.js/addresses';
+import { type ContractBase } from '@aztec/aztec.js/contracts';
+import { Fr } from '@aztec/aztec.js/fields';
+import type { PublicKeys } from '@aztec/aztec.js/keys';
+import type { Logger } from '@aztec/aztec.js/log';
+import type { AztecNode } from '@aztec/aztec.js/node';
+import type { Wallet } from '@aztec/aztec.js/wallet';
+import type { CheatCodes } from '@aztec/aztec/testing';
+import { ChildContract } from '@aztec/noir-test-contracts.js/Child';
+import { ParentContract } from '@aztec/noir-test-contracts.js/Parent';
+import type { StatefulTestContract } from '@aztec/noir-test-contracts.js/StatefulTest';
+import type { PXEConfig } from '@aztec/pxe/config';
+import type { SequencerClient } from '@aztec/sequencer-client';
+import type { AztecNodeAdmin, AztecNodeDebug } from '@aztec/stdlib/interfaces/client';
+import { type EndToEndContext, type SetupOptions } from '../fixtures/setup.js';
+import type { TestWallet } from '../test-wallet/test_wallet.js';
+export type AutomineTestOpts = Partial<SetupOptions> & {
+    /** Number of accounts to create and deploy during setup. */
+    numberOfAccounts?: number;
+    /** Options forwarded to PXE creation. */
+    pxeOpts?: Partial<PXEConfig>;
+};
+/**
+ * Base class for the automine-sequencer test topology: a single in-process node running the
+ * deterministic {@link AUTOMINE_E2E_OPTS} preset (one block per submitted tx, synchronous L1 publish,
+ * no committee, no prover, no validator client). Owns the environment (in-proc anvil in automine mode
+ * plus the L1 deploy) and exposes the handles every automine test uses (`wallet`, `aztecNode`,
+ * `cheatCodes`, `sequencer`, `accounts`, `logger`).
+ *
+ * The sibling of {@link SingleNodeTestContext}: both wrap the same underlying `fixtures/setup.ts:setup()`
+ * but fix opposite sequencer topologies. Making {@link AUTOMINE_E2E_OPTS} the base default removes the
+ * per-test-file spread every automine test would otherwise repeat.
+ *
+ * Domain harnesses (the token simulators) compose on top by extending this base and overriding
+ * {@link setup} to run their domain steps after `super.setup()`.
+ */
+export declare class AutomineTestContext {
+    context: EndToEndContext;
+    logger: Logger;
+    wallet: TestWallet;
+    aztecNode: AztecNode & AztecNodeDebug;
+    aztecNodeAdmin: AztecNodeAdmin;
+    cheatCodes: CheatCodes;
+    sequencer: SequencerClient;
+    accounts: AztecAddress[];
+    defaultAccountAddress: AztecAddress;
+    parentContract: ParentContract;
+    childContract: ChildContract;
+    static setup<T extends AutomineTestContext>(this: new () => T, opts?: AutomineTestOpts): Promise<T>;
+    setup(opts?: AutomineTestOpts): Promise<void>;
+    /**
+     * Populates the context-derived handles from an already-built {@link EndToEndContext}. Split out of
+     * {@link setup} so domain harnesses that build the environment with their own bespoke `setup(...)`
+     * opts can still reuse the shared handle wiring.
+     */
+    protected hydrateFromContext(context: EndToEndContext): Promise<void>;
+    teardown(): Promise<void>;
+    /**
+     * Marks the current pending checkpoints as proven, then warps the L2 clock forward by `seconds`.
+     *
+     * Under {@link AUTOMINE_E2E_OPTS} a long warp crosses many epochs with no proofs being submitted, so
+     * without a prior `markAsProven()` the rollup contract's pruning window resets the chain tip to genesis
+     * and the warp's own empty-checkpoint propose fails with `Rollup__InvalidArchive`. Marking proven before
+     * warping keeps the pending chain alive. Composes the existing `cheatCodes.rollup.markAsProven` and
+     * `warpL2TimeAtLeastBy` with that required ordering.
+     */
+    markProvenAndWarp(seconds: number | bigint): Promise<void>;
+    /** Computes and registers a contract instance in the wallet without deploying it on-chain. */
+    registerContract<T extends ContractBase>(wallet: Wallet, contractArtifact: ContractArtifactClass<T>, opts?: {
+        salt?: Fr;
+        publicKeys?: PublicKeys;
+        initArgs?: any[];
+        constructorName?: string;
+        deployer?: AztecAddress;
+    }): Promise<T>;
+    /** Deploys a Parent and a Child contract from the default account for the nested-call tests. */
+    applyManualParentChild(): Promise<void>;
+}
+export type StatefulContractCtorArgs = Parameters<StatefulTestContract['methods']['constructor']>;
+export type ContractArtifactClass<T extends ContractBase> = {
+    at(address: AztecAddress, wallet: Wallet): T;
+    artifact: ContractArtifact;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXV0b21pbmVfdGVzdF9jb250ZXh0LmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvYXV0b21pbmUvYXV0b21pbmVfdGVzdF9jb250ZXh0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLGdCQUFnQixFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDNUQsT0FBTyxLQUFLLEVBQUUsWUFBWSxFQUFFLE1BQU0sMkJBQTJCLENBQUM7QUFDOUQsT0FBTyxFQUFFLEtBQUssWUFBWSxFQUE4QyxNQUFNLDJCQUEyQixDQUFDO0FBQzFHLE9BQU8sRUFBRSxFQUFFLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUM1QyxPQUFPLEtBQUssRUFBRSxVQUFVLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUN2RCxPQUFPLEtBQUssRUFBRSxNQUFNLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUNsRCxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUN0RCxPQUFPLEtBQUssRUFBRSxNQUFNLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUNyRCxPQUFPLEtBQUssRUFBRSxVQUFVLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUN2RCxPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0scUNBQXFDLENBQUM7QUFDcEUsT0FBTyxFQUFFLGNBQWMsRUFBRSxNQUFNLHNDQUFzQyxDQUFDO0FBQ3RFLE9BQU8sS0FBSyxFQUFFLG9CQUFvQixFQUFFLE1BQU0sNENBQTRDLENBQUM7QUFDdkYsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFDbkQsT0FBTyxLQUFLLEVBQUUsZUFBZSxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFDL0QsT0FBTyxLQUFLLEVBQUUsY0FBYyxFQUFFLGNBQWMsRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBR3RGLE9BQU8sRUFBRSxLQUFLLGVBQWUsRUFBRSxLQUFL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

package/dest/automine/automine_test_context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automine_test_context.d.ts","sourceRoot":"","sources":["../../src/automine/automine_test_context.ts"],"names":[],"mappings":"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"}

package/dest/automine/automine_test_context.js

@@ -0,0 +1,98 @@
+import { getContractInstanceFromInstantiationParams } from '@aztec/aztec.js/contracts';
+import { Fr } from '@aztec/aztec.js/fields';
+import { ChildContract } from '@aztec/noir-test-contracts.js/Child';
+import { ParentContract } from '@aztec/noir-test-contracts.js/Parent';
+import { AUTOMINE_E2E_OPTS } from '../fixtures/fixtures.js';
+import { setup, teardown } from '../fixtures/setup.js';
+/**
+ * Base class for the automine-sequencer test topology: a single in-process node running the
+ * deterministic {@link AUTOMINE_E2E_OPTS} preset (one block per submitted tx, synchronous L1 publish,
+ * no committee, no prover, no validator client). Owns the environment (in-proc anvil in automine mode
+ * plus the L1 deploy) and exposes the handles every automine test uses (`wallet`, `aztecNode`,
+ * `cheatCodes`, `sequencer`, `accounts`, `logger`).
+ *
+ * The sibling of {@link SingleNodeTestContext}: both wrap the same underlying `fixtures/setup.ts:setup()`
+ * but fix opposite sequencer topologies. Making {@link AUTOMINE_E2E_OPTS} the base default removes the
+ * per-test-file spread every automine test would otherwise repeat.
+ *
+ * Domain harnesses (the token simulators) compose on top by extending this base and overriding
+ * {@link setup} to run their domain steps after `super.setup()`.
+ */ export class AutomineTestContext {
+    context;
+    logger;
+    wallet;
+    aztecNode;
+    aztecNodeAdmin;
+    cheatCodes;
+    sequencer;
+    accounts;
+    defaultAccountAddress;
+    parentContract;
+    childContract;
+    static async setup(opts = {}) {
+        const test = new this();
+        await test.setup(opts);
+        return test;
+    }
+    async setup(opts = {}) {
+        const { numberOfAccounts = 1, pxeOpts, ...setupOpts } = opts;
+        const context = await setup(numberOfAccounts, {
+            ...AUTOMINE_E2E_OPTS,
+            fundSponsoredFPC: true,
+            ...setupOpts
+        }, pxeOpts);
+        await this.hydrateFromContext(context);
+    }
+    /**
+   * Populates the context-derived handles from an already-built {@link EndToEndContext}. Split out of
+   * {@link setup} so domain harnesses that build the environment with their own bespoke `setup(...)`
+   * opts can still reuse the shared handle wiring.
+   */ hydrateFromContext(context) {
+        this.context = context;
+        this.logger = context.logger;
+        this.wallet = context.wallet;
+        this.aztecNode = context.aztecNodeService;
+        this.aztecNodeAdmin = context.aztecNodeService;
+        this.cheatCodes = context.cheatCodes;
+        this.sequencer = context.sequencer;
+        this.accounts = context.accounts;
+        this.defaultAccountAddress = context.accounts[0];
+        return Promise.resolve();
+    }
+    async teardown() {
+        await teardown(this.context);
+    }
+    /**
+   * Marks the current pending checkpoints as proven, then warps the L2 clock forward by `seconds`.
+   *
+   * Under {@link AUTOMINE_E2E_OPTS} a long warp crosses many epochs with no proofs being submitted, so
+   * without a prior `markAsProven()` the rollup contract's pruning window resets the chain tip to genesis
+   * and the warp's own empty-checkpoint propose fails with `Rollup__InvalidArchive`. Marking proven before
+   * warping keeps the pending chain alive. Composes the existing `cheatCodes.rollup.markAsProven` and
+   * `warpL2TimeAtLeastBy` with that required ordering.
+   */ async markProvenAndWarp(seconds) {
+        await this.cheatCodes.rollup.markAsProven();
+        await this.cheatCodes.warpL2TimeAtLeastBy(this.aztecNode, seconds);
+    }
+    /** Computes and registers a contract instance in the wallet without deploying it on-chain. */ async registerContract(wallet, contractArtifact, opts = {}) {
+        const { salt, publicKeys, initArgs, constructorName, deployer } = opts;
+        const instance = await getContractInstanceFromInstantiationParams(contractArtifact.artifact, {
+            constructorArgs: initArgs ?? [],
+            constructorArtifact: constructorName,
+            salt: salt ?? Fr.random(),
+            publicKeys,
+            deployer
+        });
+        await wallet.registerContract(instance, contractArtifact.artifact);
+        return contractArtifact.at(instance.address, wallet);
+    }
+    /** Deploys a Parent and a Child contract from the default account for the nested-call tests. */ async applyManualParentChild() {
+        this.logger.info('Deploying parent and child contracts');
+        ({ contract: this.parentContract } = await ParentContract.deploy(this.wallet).send({
+            from: this.defaultAccountAddress
+        }));
+        ({ contract: this.childContract } = await ChildContract.deploy(this.wallet).send({
+            from: this.defaultAccountAddress
+        }));
+    }
+}

package/dest/automine/contracts/fixtures/storage_proof_fetcher.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmFnZV9wcm9vZl9mZXRjaGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvYXV0b21pbmUvY29udHJhY3RzL2ZpeHR1cmVzL3N0b3JhZ2VfcHJvb2ZfZmV0Y2hlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dest/automine/contracts/fixtures/storage_proof_fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage_proof_fetcher.d.ts","sourceRoot":"","sources":["../../../../src/automine/contracts/fixtures/storage_proof_fetcher.ts"],"names":[],"mappings":""}

package/dest/automine/contracts/fixtures/storage_proof_fetcher.js

@@ -0,0 +1,184 @@
+/**
+ * Fetches a ERC20 balance storage proof from the Ethereum mainnet and saves it to a Prover.toml compatible JSON.
+ * The JSON can be converted to toml for use with nargo, or used directly as a JSON file when used in
+ * Aztec contracts. This script is not using any Aztec library code, so it's easily portable.
+ */ import fs from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { createPublicClient, encodeAbiParameters, fromRlp, hexToBytes, http, keccak256 } from 'viem';
+import { mainnet } from 'viem/chains';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const RPC_URL = process.env.RPC_URL;
+const ERC20_CONTRACT = process.env.ERC20_CONTRACT || '0xdAC17F958D2ee523a2206206994597C13D831ec7';
+const HOLDER = process.env.HOLDER || '0x23878914EFE38d27C4D67Ab83ed1b93A74D4086a';
+const SLOT = BigInt(process.env.SLOT || '2');
+const BLOCK_TAG = process.env.BLOCK_NUMBER ? BigInt(process.env.BLOCK_NUMBER) : 'latest';
+const MAX_ACCOUNT_PATH = 15;
+const MAX_STORAGE_PATH = 10;
+function padTo(arr, len) {
+    return [
+        ...arr,
+        ...Array(len - arr.length).fill(0)
+    ].slice(0, len);
+}
+function toBytes(hex) {
+    return Array.from(hexToBytes(hex));
+}
+function bytesToU64s(bytes) {
+    const paddedBytes = padTo(bytes, 32);
+    return Array.from({
+        length: 4
+    }, (_, i)=>{
+        let val = 0n;
+        for(let j = 0; j < 8; j++){
+            val += BigInt(paddedBytes[i * 8 + j]) << BigInt(j * 8);
+        }
+        return val.toString();
+    });
+}
+function toBytesAndLen(val) {
+    if (val === 0n || val === 0) {
+        return {
+            bytes: [
+                0
+            ],
+            length: 0
+        };
+    }
+    let hex = val.toString(16);
+    if (hex.length % 2) {
+        hex = '0' + hex;
+    }
+    const bytes = toBytes(`0x${hex}`);
+    return {
+        bytes,
+        length: bytes.length
+    };
+}
+function parseNode(rlp) {
+    // Should be safe when working with branches and extensions without embedded children.
+    const decoded = fromRlp(rlp);
+    const node = {
+        rows: Array(16).fill(0).map(()=>Array(32).fill(0)),
+        row_exist: Array(16).fill(false),
+        node_type: 0
+    };
+    if (decoded.length === 17) {
+        for(let i = 0; i < 16; i++){
+            if (decoded[i] !== '0x') {
+                node.row_exist[i] = true;
+                node.rows[i] = padTo(toBytes(decoded[i]), 32);
+            }
+        }
+    } else if (decoded.length === 2) {
+        const keyBytes = toBytes(decoded[0]);
+        const prefix = keyBytes[0];
+        if (prefix >> 4 >= 2) {
+            throw new Error('Unsupported: leaf node in proof path');
+        }
+        node.node_type = 1;
+        // Extension header format expected by the noir code: check out storage_proof types.nr.
+        node.rows[0][0] = prefix >> 4;
+        node.rows[0][8] = prefix & 0x0f;
+        node.rows[0][16] = keyBytes.length - 1;
+        for(let i = 1; i < keyBytes.length && i < 32; i++){
+            node.rows[1][i - 1] = keyBytes[i];
+        }
+        node.rows[2] = padTo(toBytes(decoded[1]), 32);
+        node.row_exist[0] = node.row_exist[1] = node.row_exist[2] = true;
+    }
+    return node;
+}
+function parseProof(proof, maxLen) {
+    const nodes = proof.slice(0, -1).slice(0, maxLen).map(parseNode);
+    while(nodes.length < maxLen){
+        nodes.push({
+            rows: Array(16).fill(0).map(()=>Array(32).fill(0)),
+            row_exist: Array(16).fill(false),
+            node_type: 0
+        });
+    }
+    return nodes;
+}
+function nodeToLibFormat(node) {
+    return {
+        rows: node.rows.map(bytesToU64s),
+        row_exist: node.row_exist,
+        node_type: String(node.node_type)
+    };
+}
+async function main() {
+    if (!RPC_URL) {
+        throw new Error('RPC_URL is not set');
+    }
+    const storageKey = keccak256(encodeAbiParameters([
+        {
+            type: 'address'
+        },
+        {
+            type: 'uint256'
+        }
+    ], [
+        HOLDER,
+        SLOT
+    ]));
+    console.log(`Fetching storage proof for ${ERC20_CONTRACT}, holder ${HOLDER}, slot ${SLOT}`);
+    console.log(`Storage key: ${storageKey}`);
+    const client = createPublicClient({
+        chain: mainnet,
+        transport: http(RPC_URL)
+    });
+    const [blockNumber, proof, block] = await Promise.all([
+        client.getBlockNumber(),
+        client.getProof({
+            address: ERC20_CONTRACT,
+            storageKeys: [
+                storageKey
+            ],
+            blockNumber: BLOCK_TAG === 'latest' ? undefined : BLOCK_TAG
+        }),
+        client.getBlock({
+            blockNumber: BLOCK_TAG === 'latest' ? undefined : BLOCK_TAG
+        })
+    ]);
+    const storageProof = proof.storageProof[0];
+    console.log(`Block: ${blockNumber}, Account nodes: ${proof.accountProof.length}, Storage nodes: ${storageProof.proof.length}`);
+    console.log(`Value: ${storageProof.value}`);
+    // The -1 is because the last node in the proof is the leaf, which is excluded from path verification.
+    const accountPathLen = proof.accountProof.length - 1;
+    const storagePathLen = storageProof.proof.length - 1;
+    if (accountPathLen > MAX_ACCOUNT_PATH) {
+        throw new Error(`Account proof path length ${accountPathLen} exceeds MAX_ACCOUNT_PATH ${MAX_ACCOUNT_PATH}. Increase the limit.`);
+    }
+    if (storagePathLen > MAX_STORAGE_PATH) {
+        throw new Error(`Storage proof path length ${storagePathLen} exceeds MAX_STORAGE_PATH ${MAX_STORAGE_PATH}. Increase the limit.`);
+    }
+    const nonce = toBytesAndLen(proof.nonce);
+    const balance = toBytesAndLen(proof.balance);
+    const slotValue = toBytesAndLen(storageProof.value);
+    const data = {
+        account_nodes: parseProof(proof.accountProof, MAX_ACCOUNT_PATH).map(nodeToLibFormat),
+        account_node_length: String(accountPathLen),
+        storage_nodes: parseProof(storageProof.proof, MAX_STORAGE_PATH).map(nodeToLibFormat),
+        storage_node_length: String(storagePathLen),
+        account: {
+            nonce: padTo(nonce.bytes, 8).map(String),
+            nonce_length: String(nonce.length),
+            balance: padTo(balance.bytes, 32).map(String),
+            balance_length: String(balance.length),
+            address: toBytes(ERC20_CONTRACT).map(String),
+            storage_hash: bytesToU64s(toBytes(proof.storageHash)),
+            code_hash: bytesToU64s(toBytes(proof.codeHash))
+        },
+        slot: {
+            value: padTo(slotValue.bytes, 32).map(String),
+            value_length: String(slotValue.length)
+        },
+        slot_key: toBytes(storageKey).map(String),
+        root: bytesToU64s(toBytes(block.stateRoot)),
+        block_number: String(blockNumber)
+    };
+    fs.writeFileSync(join(__dirname, 'storage_proof.json'), JSON.stringify(data, null, 2));
+    console.log('storage_proof.json generated');
+}
+main().catch(console.error);