docs: document kernelless simulations in the PXE by critesjosh · Pull Request #23399 · AztecProtocol/aztec-packages

critesjosh · 2026-05-19T14:42:36Z

Summary

Adds two docs pages explaining kernelless simulation in the Private eXecution Environment (PXE):

Concept: foundational-topics/pxe/kernelless_simulations.md covers what the PXE skips when skipKernels is true, the shape of SimulationOverrides, the stub account contracts, where kernelless does not apply (profileTx, simulateViaNode for public static calls, utility functions), and the gas-parity guarantees the e2e test actually proves.
How-to: aztec-js/how_to_simulate_without_signing.md is the recipe-oriented page for the symptoms in #20028: signing prompts on .simulate(), the min_revertible_side_effect_counter error from from: AztecAddress.ZERO, and the urge to deploy a no-op fee payment contract. It covers both dApp-side usage and the wallet-implementer pattern, using TestWallet.{initStubClasses,buildAccountOverrides,simulateViaEntrypoint} and the authwit-harvesting flow in e2e_kernelless_simulation.test.ts as the canonical snippets via #include_code.

Also:

Removes the stale "Until simulated simulations are implemented ([epic] Simulating Simulations #9133)" line from pxe/index.md and replaces it with a paragraph linking to the new concept page.
Cleans up two em-dashes elsewhere in pxe/index.md and the wallets-page paragraph that already mentioned the stub-account simulation.
Adds a tip box in how_to_read_data.md pointing readers with the signing-prompt symptom at the new how-to.
Adds // docs:start: / // docs:end: markers in yarn-project/end-to-end/src/test-wallet/test_wallet.ts and yarn-project/end-to-end/src/e2e_kernelless_simulation.test.ts so the how-to can pull the implementation as #include_code rather than inlining stale snippets.
Adds kernelless to docs-words.txt.

Test plan

yarn preprocess passes; every #include_code reference resolves.
yarn spellcheck passes.
Reviewed twice by codex (second opinion) against the actual source code; technical claims and snippet ranges verified.

Notes for reviewers

Inspired by the Slack thread following #20028, where a community integrator built a custom no-op fee payment contract to work around min_revertible_side_effect_counter must not be 0 on .simulate(). Grego pointed out that the PXE already supports the use case via kernelless simulation with a stub account override; this PR documents that.
The docs:start: markers in the test files are inert comments, but they sit inside yarn-project/. If the merge-train routing for this kind of mixed PR has a preferred home, happy to retarget.

## Summary Adds two docs pages explaining kernelless simulation in the Private eXecution Environment (PXE): - **Concept**: `foundational-topics/pxe/kernelless_simulations.md` covers what the PXE skips when `skipKernels` is true, the shape of `SimulationOverrides`, the stub account contracts, where kernelless does *not* apply (`profileTx`, `simulateViaNode` for public static calls, utility functions), and the gas-parity guarantees the e2e test actually proves. - **How-to**: `aztec-js/how_to_simulate_without_signing.md` is the recipe-oriented page for the symptoms in [#20028](#20028): signing prompts on `.simulate()`, the `min_revertible_side_effect_counter` error from `from: AztecAddress.ZERO`, and the urge to deploy a no-op fee payment contract. It covers both dApp-side usage and the wallet-implementer pattern, using `TestWallet.{initStubClasses,buildAccountOverrides,simulateViaEntrypoint}` and the authwit-harvesting flow in `e2e_kernelless_simulation.test.ts` as the canonical snippets via `#include_code`. Also: - Removes the stale "Until simulated simulations are implemented (#9133)" line from `pxe/index.md` and replaces it with a paragraph linking to the new concept page. - Cleans up two em-dashes elsewhere in `pxe/index.md` and the wallets-page paragraph that already mentioned the stub-account simulation. - Adds a tip box in `how_to_read_data.md` pointing readers with the signing-prompt symptom at the new how-to. - Adds `// docs:start:` / `// docs:end:` markers in `yarn-project/end-to-end/src/test-wallet/test_wallet.ts` and `yarn-project/end-to-end/src/e2e_kernelless_simulation.test.ts` so the how-to can pull the implementation as `#include_code` rather than inlining stale snippets. - Adds `kernelless` to `docs-words.txt`. ## Test plan - [x] `yarn preprocess` passes; every `#include_code` reference resolves. - [x] `yarn spellcheck` passes. - [x] Reviewed twice by codex (second opinion) against the actual source code; technical claims and snippet ranges verified. ## Notes for reviewers - Inspired by the Slack thread following [#20028](#20028), where a community integrator built a custom no-op fee payment contract to work around `min_revertible_side_effect_counter must not be 0` on `.simulate()`. Grego pointed out that the PXE already supports the use case via kernelless simulation with a stub account override; this PR documents that. - The `docs:start:` markers in the test files are inert comments, but they sit inside `yarn-project/`. If the merge-train routing for this kind of mixed PR has a preferred home, happy to retarget.

AztecBot · 2026-05-22T18:40:28Z

Flakey Tests

🤖 says: This CI run detected 1 tests that failed, but were tolerated due to a .test_patterns.yml entry.

\033FLAKED\033 (8;;http://ci.aztec-labs.com/a218f67105b96174�a218f67105b961748;;�):  yarn-project/end-to-end/scripts/run_test.sh simple src/e2e_p2p/broadcasted_invalid_block_proposal_slash.test.ts (251s) (code: 0) group:e2e-p2p-epoch-flakes