monad-developers · pdobacz · Aug 19, 2026 · Aug 19, 2026 · Aug 19, 2026 · Aug 20, 2026
@@ -1,3 +1,8 @@
+---
+name: adopt-upstream-eip
+description: Adopt a single upstream EIP into a work-in-progress Monad fork.
+---
+
 # Adopt Upstream EIP
 
 Adopt a single upstream EIP into a work-in-progress Monad fork and release

@@ -1,3 +1,8 @@
+---
+name: assess-eip
+description: Assess an EIP's implementation complexity and scope.
+---
+
 # Assess EIP
 
 Structured assessment of EIP implementation complexity. When invoked with an EIP number or description, perform the following analysis.

@@ -1,12 +1,25 @@
+---
+name: audit-config
+description: Check whether repository guidance and skills are still accurate.
+---
+
 # Audit Config
 
-Periodic verification skill to prevent CLAUDE.md and skills from going stale. Run this manually to check freshness (e.g., after a major refactor, before a release, or when onboarding).
+Periodic verification skill to prevent `AGENTS.md` and skills from going stale.
+Run this manually to check freshness (e.g., after a major refactor, before a
+release, or when onboarding).
 
 ## Checks to Perform
 
 ### 1. Verify File Paths
 
-Check that every file path or directory referenced in `CLAUDE.md` and `.claude/commands/*.md` still exists. Report any broken references.
+Check that every file path or directory referenced in `AGENTS.md` and
+`.agents/skills/*/SKILL.md` still exists. Report any broken references.
+
+Confirm that `CLAUDE.md` is a symlink to `AGENTS.md`. Confirm that every
+`.agents/skills/<name>/` directory has a corresponding
+`.claude/skills/<name>` symlink that points back to it, and that there are no
+orphaned Claude skill links.
 
 ### 2. Verify CLI Commands
 
@@ -28,7 +41,8 @@ Spot-check code patterns mentioned in skills against actual code:
 
 ### 4. Verify Fork List
 
-Check that the fork order and default branch mentioned in `CLAUDE.md` match reality by inspecting `src/ethereum/forks/` and git branch configuration.
+Check that the fork order and default branch mentioned in `AGENTS.md` match
+reality by inspecting `src/ethereum/forks/` and git branch configuration.
 
 ### 5. Verify Docs References
 

@@ -1,3 +1,8 @@
+---
+name: edit-workflow
+description: Apply repository conventions when editing GitHub Actions workflows.
+---
+
 # Edit Workflow
 
 GitHub Actions conventions. Run this skill before modifying workflow files in `.github/`.

@@ -1,3 +1,8 @@
+---
+name: eip-checklist
+description: Track EIP test coverage with the repository checklist system.
+---
+
 # EIP Checklist
 
 Guide for using the EIP testing checklist system to track test coverage. Run this skill when working on EIP test coverage or checklists.

@@ -1,3 +1,8 @@
+---
+name: enhance-ported-test
+description: Clean up and future-proof a ported static test.
+---
+
 # Enhance Ported Test
 
 Future-proof and clean up a test under `tests/ported_static/`. These tests were
@@ -125,7 +130,8 @@ to keep it.
 
 ### 2. Remove `gas_limit` from the transaction (if gas is not the subject)
 This is the common case and belongs early. Omitting `gas_limit` maxes out the
-gas the tx receives, so the body executes fully. See `write-test.md` "Transactions".
+gas the tx receives, so the body executes fully. See the [Transactions section]
+(../write-test/SKILL.md#transactions) of the `write-test` skill.
 - **Remove it** when the test is about *behavior* and just needs to run to
   completion. This also lets you delete any per-fork gas band-aids (e.g.
   `fork.is_eip_enabled(8037)` budget bumps) and often the `fork` param itself.
@@ -526,69 +532,11 @@ persists with the sentinel) plus the callee-side observable already
 separate the outcomes. Validated on
 `test_contract_creation_make_call_that_ask_more_gas_then_transaction_provided`.
 
-**Any *exact* budget off the intrinsic calculator needs the EIP-7623
-kwarg.** `transaction_intrinsic_cost_calculator()` returns `max(intrinsic,
-calldata_floor)`, but the floor is only compared against *after* execution —
-it is never deducted up front. So whenever the derived number stands for
-"gas taken before the first opcode" — a one-gas OOG boundary, an exact
-success budget, an EIP-3529 refund cap — pass
-`return_cost_deducted_prior_execution=True` if the transaction carries
-calldata. **The bug hides until an EIP-7981 fork:** the delta is 0 from
-Berlin through Osaka and 238 on Amsterdam for a 5-byte creation payload, so
-a boundary tuned without the kwarg passes on every fork that exists today
-and silently goes slack on the future one — and the symptom is an *OOG arm
-that stops OOG-ing*, i.e. a test that fails only once someone runs
-`--fork Amsterdam`.
-**Keep the default (no kwarg) when the number is a validity floor** rather
-than an execution budget: a tx whose `gas_limit` falls below
-`max(intrinsic, floor)` is rejected outright, which is a different outcome
-from running out of gas.
-Validated on `test_refund_suicide50procent_cap` and
-`test_transaction_collision_to_empty2`, whose OOG arm had been loosened to
-"half the store's cost" to work around this, with a comment misattributing
-it to a pre-Shanghai init-code word cost.
-
-**Read the trace when a derived budget does not line up.** `fill --traces
---evm-dump-dir <dir>` writes, per transaction, `input/txs.json`,
-`output/result.json` and a `trace-*.jsonl`. Subtracting the first trace
-entry's `gas` from the tx `gas` gives the intrinsic the EVM *actually*
-charged, which is what settles a disagreement with any calculator; on
-EIP-8037 forks the per-step `gasCost`/`stateGasCost` split shows where a
-composite's cost really lands. Far faster than bisecting `gas_limit` by
-re-filling, and it produced the 238 above in one run.
-
-**Gates are not costs, and `gas_cost()` only knows costs.** Several EVM
-rules are *preconditions on `gas_left`* rather than charges, so a budget
-derived from `gas_cost(fork)` is exactly right and still too small. The
-canonical one is EIP-2200 (Istanbul+): **any** `SSTORE` halts when it runs
-with `CALL_STIPEND` (2300) gas or less still available — including a
-100-gas dirty-warm rewrite. No amount of fixing `_calculate_sstore*` can
-express that, because it is not part of the price.
-
-*Tell it apart in a trace:* a gated halt shows `gasCost: 0x0` next to an
-`error`, while a genuine can't-afford shows the real cost. `SSTORE
-gas_left=2300 cost=0 OutOfGasError` is the signature.
-
-*Derive the headroom instead of padding.* The **last** gated op is the one
-running closest to empty, so it sets the requirement:
-```
-last_charge = Op.SSTORE(key_warm=True, original_value=…, current_value=…,
-                        new_value=…).gas_cost(fork)   # bare `55`, no PUSHes
-headroom    = fork.gas_costs().CALL_STIPEND - last_charge + 1
-gas_limit   = overhead + code.gas_cost(fork) + headroom
-```
-A bare opcode carrying only metadata prices the charge alone (same trick as
-`Op.RETURN(code_deposit_size=n)`). This is what turns "add 5,000 and hope"
-into a real one-gas boundary — and because it targets only the *last* gated
-op, it is invariant in how many precede it. Validated on
-`test_out_of_gas_contract_creation`, whose arms now straddle
-`gas_left = 2301` / `2300` exactly.
-
-*Same family, when an "impossible" budget is really a gate:* an
-`SSTORE` in a `STATICCALL` subtree, `RETURNDATACOPY` reading past the
-return buffer, stack under/overflow, an EIP-684 address collision. Each
-aborts the frame outright rather than charging for it, so the fix is
-always to model the gate, never to inflate the budget until it passes.
+**Refund-cap derivations need the EIP-7623 kwarg.** The EIP-3529 cap's
+base is the gas deducted before execution, which excludes the calldata
+floor: pass `return_cost_deducted_prior_execution=True` to the intrinsic
+calculator whenever the tx has calldata, or the derived `executed` (and
+the cap) overstate. Validated on `test_refund_suicide50procent_cap`.
 
 **A CREATE address collision burns the child's gas allowance** (the
 EIP-684 path): the withheld child grant is consumed, nothing is created,
@@ -609,27 +557,15 @@ a derived budget that must survive pre-Istanbul forks needs an explicit
 headroom constant for it (named, commented). Observed on
 `test_revert_depth_create_address_collision`'s ConstantinopleFix sweep.
 
-**Code-deposit cost comes from `Op.RETURN`'s metadata — never a per-byte
-formula.** Annotate the init code's terminator,
-`Op.RETURN(offset=o, size=n, code_deposit_size=n)`, and `gas_cost(fork)`
-includes the deposit charge, correct on both sides of the EIP-8037 boundary
-(10 bytes costs 2,000 before it; 15,306 after, once the per-byte price became
-state gas). The annotated and unannotated forms assemble to **identical
-bytes**, so building both yields an exact two-sided boundary out of the fork's
-own model, with no EIP branch:
-```
-child              = stage + Op.RETURN(offset=o, size=n)
-child_with_deposit = stage + Op.RETURN(offset=o, size=n, code_deposit_size=n)
-assert child.gas_cost(fork) <= granted < child_with_deposit.gas_cost(fork)
-```
-`fork.gas_costs().CODE_DEPOSIT_PER_BYTE` (200) is a **last resort**: it is the
-*pre-8037* constant and understates the real charge ~7.5x on 8037 forks. Use
-it only where understating is the safe direction — a *sufficiency* budget
-overshoots, an "is this unaffordable?" guard stays conservative — and never in
-a one-gas-short *boundary*, which it silently funds on Amsterdam. Branching on
-`fork.is_eip_enabled(8037)` to patch it up is the wrong fix; the metadata
-removes the branch entirely. Validated on
-`test_create_oog_after_init_code_returndata_size`.
+**EIP-8037 repriced the code deposit's regular part — boundaries beware.**
+On 8037 forks the deposit charges only the keccak word cost
+(`OPCODE_KECCAK256_PER_WORD * ceil32(len)/32`, ~6 gas) as regular gas plus
+`len * 1530` state; `fork.gas_costs().CODE_DEPOSIT_PER_BYTE` (200) is the
+*pre-8037* constant. Using 200/byte in a *sufficiency* budget merely
+overshoots (safe); using it in a one-gas-short *boundary* silently funds
+the deposit on Amsterdam. Branch on `fork.is_eip_enabled(8037)` for exact
+deposit boundaries. Validated on
+`test_create_oo_gafter_init_code_returndata_size`.
 
 **Match the intrinsic calculator's kwargs to the transaction's shape.**
 `fork.transaction_intrinsic_cost_calculator()()` defaults to

@@ -1,3 +1,8 @@
+---
+name: fill-tests
+description: Fill test fixtures with the repository fill command.
+---
+
 # Fill Tests
 
 CLI reference for the `fill` command. Run this skill before filling test fixtures. The `fill` command is pytest-based — all standard pytest flags work.

@@ -1,3 +1,8 @@
+---
+name: grammar-check
+description: Audit grammar in documentation and code comments.
+---
+
 # Grammar Check
 
 Audit grammar in documentation and code comments.

@@ -1,3 +1,8 @@
+---
+name: implement-eip
+description: Implement EIP specification changes using repository conventions.
+---
+
 # Implement EIP
 
 Patterns for implementing spec changes in `src/ethereum/forks/`. Run this skill before implementing an EIP or modifying fork code.
@@ -10,7 +15,7 @@ Each fork lives at `src/ethereum/forks/<fork_name>/`. Explore the latest fork di
 - `fork.py` — state transition functions
 - `blocks.py` — block structure and validation
 - `transactions.py` — transaction types and processing
-- `state.py` — state trie operations
+- `state_tracker.py` — fork-specific state tracking
 - `vm/instructions/__init__.py` — Ops enum + `op_implementation` dict
 - `vm/gas.py` — gas constants and calculations
 - `vm/precompiled_contracts/__init__.py` — precompile address constants

@@ -1,3 +1,8 @@
+---
+name: lint
+description: Run and fix the repository static analysis suite.
+---
+
 # Lint
 
 Run the full static analysis suite and fix issues. This matches the CI check on every PR.

@@ -0,0 +1,89 @@
+---
+name: merge-from-upstream
+description: Merge upstream execution-specs into the fork's from-upstream branch.
+---
+
+# Merge From Upstream
+
+Merge the current default branch of `ethereum/execution-specs` into the
+`from-upstream` branch of `monad-developers/execution-specs`, carry the
+applicable changes into the Monad forks, and verify the result. Run this
+skill before starting such work.
+
+The commit sequence is the deliverable as much as the merged tree is: a
+reviewer reads the conflict resolution and the Monad propagation as
+separate diffs, so never fold them into the merge commit or into each
+other.
+
+## 1. Prepare the branch
+
+- Check out `from-upstream`.
+- Verify it is not the head branch of a currently open PR.
+- Reset it to the `monad-developers/execution-specs` default branch.
+
+## 2. Record the fixture set baseline
+
+Collect the tests the `tests-monad` release job fills, with
+`--collect-only`, and save the result for the closing comparison. The
+fill parameters live under the `monad` key in
+`.github/configs/feature.yaml`; `.github/actions/build-fixtures` and the
+`fill-release` recipe in the `Justfile` add the rest.
+
+The `N/M tests collected` summary counts items before the filler drops
+the ones that generate no fixture for the fork range, so it overstates
+the release set. Take the node IDs, not that number.
+
+## 3. Merge
+
+- Fetch the upstream remote.
+- Merge upstream's default branch as a merge commit, **leaving the
+  conflicts unresolved in the merge commit**.
+- Stage the conflicted paths explicitly. Staging everything would also
+  commit untracked directories left behind by other branches.
+
+## 4. Resolve the conflicts
+
+Put the resolution in a separate commit after the merge commit.
+
+## 5. Propagate into the Monad forks
+
+Analyze the changes upstream made to its own forks (Amsterdam, Osaka,
+Prague and the rest). Filter them to those that apply to the `MONAD_*`
+forks inheriting those upstream forks, and apply those to the WET
+implementations in `src/ethereum/forks`.
+
+These files do not conflict, so nothing flags them. They still have to
+accommodate the upstream change whenever it applies — for instance
+because the Monad fork adopted the same EIP.
+
+Do these changes in a further commit.
+
+## 6. Stop for review
+
+If anything about the changes so far is doubtful, stop and request human
+review before verifying.
+
+## 7. Verify
+
+Lint, then fill. Base the fill on the `tests-monad` release command and
+pass `--maxfail 1` so breakage surfaces early. Fill fine-grained first,
+over the tests related to the touched files and features, then sweep the
+full set.
+
+A full sweep runs for hours. Split it into chunks that partition the
+collected set, so no single run is long enough to be interrupted, and
+check the chunk totals add up to the collected count.
+
+## 8. Fix what the verification finds
+
+Use follow-up commits: fold related changes together, keep unrelated
+changes separate.
+
+## 9. Report the fixture set change
+
+Collect the release tests again with `--collect-only`, compare against
+the step 2 baseline, and report the change in the resulting fixture set.
+
+## 10. Stop for review
+
+Once verification succeeds, stop and request human review.
@@ -1,3 +1,8 @@
+---
+name: pytester
+description: Write and run isolated pytester-based plugin tests.
+---
+
 # Pytester
 
 Guide for pytester-based plugin/CLI tests. Run before writing or modifying these tests.

@@ -1,3 +1,8 @@
+---
+name: write-docstring
+description: Write specification docstrings using repository conventions.
+---
+
 # Write Docstring
 
 Conventions for writing docstrings in `src/ethereum/`. Docstrings are the primary prose of the specification — they read as a narrative explaining how Ethereum works, not as traditional Python API documentation. They are rendered into HTML by docc, which parses them as **Markdown** (via mistletoe). Run this skill before writing or modifying docstrings.

@@ -1,3 +1,8 @@
+---
+name: write-test
+description: Write consensus tests using repository patterns and fixtures.
+---
+
 # Write Test
 
 Conventions and patterns for writing consensus tests. Run this skill before writing or modifying tests.

@@ -0,0 +1 @@
+../../.agents/skills/adopt-upstream-eip
@@ -0,0 +1 @@
+../../.agents/skills/assess-eip
@@ -0,0 +1 @@
+../../.agents/skills/audit-config
@@ -0,0 +1 @@
+../../.agents/skills/edit-workflow
@@ -0,0 +1 @@
+../../.agents/skills/eip-checklist
@@ -0,0 +1 @@
+../../.agents/skills/enhance-ported-test
@@ -0,0 +1 @@
+../../.agents/skills/fill-tests
@@ -0,0 +1 @@
+../../.agents/skills/grammar-check
@@ -0,0 +1 @@
+../../.agents/skills/implement-eip
@@ -0,0 +1 @@
+../../.agents/skills/lint
@@ -0,0 +1 @@
+../../.agents/skills/merge-from-upstream