feat(scenarios): add an AMM swap scenario

[bdchatham]

Adds an amm scenario so a DeFi load profile has a contract to drive, and fixes
an existing gas limit that made every ERC721 mint fail.

The AMM contract

A constant-product pair with the storage and gas shape of a UniswapV2 swap: both
reserves, the caller's balance in each token, and an event. It reproduces the
cost, not the economics. There is no router, no fee split, no price oracle and no
minimum-output check.

Two design points are worth stating, because both were wrong in an earlier draft.

The balances wrap rather than check. Nothing reads them back, and a load
generator that fails on its own accounting stops measuring the chain. The draft
credited a short caller exactly what it then debited, which returns the slot to
the value it held. For a caller starting at zero, that is zero. A zero to
non-zero storage write costs four times one that changes a slot already holding a
value, and the default operation mix draws one direction, so that expensive write
would have landed on every swap of the run rather than on the first.

The reserves sit between a floor and a ceiling. The draft had only a floor.
Measured over a long run, the input side then grows without bound and the output
halves every 100,000 swaps, so the profile stops pricing anything like it did at
the start. The ceiling also keeps one oversized call from ending the pair: a swap
of 1e49 leaves the input reserve at 1e49, and the contract has no owner and no
reset. Measured, the next ordinary swap now resets that side to the floor and
pays out in full.

Gas

The limit is a required limit read from eth_estimateGas, not a receipt's
GasUsed. GasUsed is what the chain charges after the refund lands at the end
of execution, and a transaction has to carry the peak before it. Sizing from a
receipt put an earlier draft 20% under what its own swap needed, which fails the
transaction and burns the whole limit.

Measured over six accounts against the deployed binding, on a chain running the
default storage gas costs:

shape	required
an account's first swap	79,988
every later swap by that account	45,177

One limit has to cover the higher shape, so a run in steady state declares about
44% more gas than it spends. Priming both slots during prewarm would close that;
it needs a transaction class the prewarm path does not have yet, and PLT-1093
carries it.

The calibration assumes the default 20,000 for a zero to non-zero storage write.
Sei sets that as a chain parameter and the public chains charge about 74,700, so
these numbers are right for arctic-1 and wrong for pacific-1. That exposure is
the whole package rather than this constant, and PLT-1092 covers it.

The ERC721 fix

ERC721.go declared 22,460 gas for a mint, which is ERC20Noop's constant
copied. A mint needs 69,319 to a receiver holding none of the token. Every mint
the scenario sent landed in a block with a failed status having burned the whole
limit, and trackReceipts defaults to false, so the run reported each one as
sent.

It is fixed here rather than deferred because the tokenops profile this work
deploys uses that scenario, and shipping it broken would read as a chain
regression on the canary.

ERC20Noop is short by 455 gas and ERC20Conflict by 69,710. Neither appears in
a profile deployed today, so PLT-1091 carries them.

What is checked, and what is not

Every guard was broken on purpose before it was believed. Six mutations, six
caught: the ERC721 limit back to 22,460 and up to 200,000; the AMM limit down to
the steady shape and up past the band; the B-to-A leg made unreachable; the
operation stamp dropped.

The reserve bounds and the balance-slot property have no guard. They were
measured by hand and no test repeats the measurement, because the repo runs no
contract against an EVM in CI. A Go test on ethclient/simulated guards all
three and is written, but it adds about 35 indirect modules including the full
go-ethereum node stack, which is too large a dependency change to make in
passing. PLT-1094 carries the harness question and the parked test.

Verification

gofmt, go vet, staticcheck and golangci-lint run are clean. The full
suite passes. All seven tracked bindings regenerate byte-identical under the
pinned solc 0.8.19 and abigen 1.16.1, so check-bindings passes.

🤖 Generated with Claude Code

[cursor]

PR Summary

Low Risk
Changes are confined to load-generator scenarios, generated bindings, and gas constants; the ERC721 fix corrects failing txs rather than altering auth or production chain logic.

Overview
Adds an amm load scenario for DeFi-style workloads: a load-oriented constant-product pair (AMM.sol), generated bindings, and a scenario that issues swapAToB / swapBToA with profile-weightable operations (swap_a_to_b, swap_b_to_a). Config wires AMMOperations, registers amm in the scenario factory, and exports OperationNamesFor so tests can assert the full operation vocabulary; frozen-operation checks now cover every drawable name, not just each scenario’s default.

The contract targets UniswapV2-like gas/storage (reserves, per-caller balances, Swap event) with reserve floor/ceiling and wrapping balances so long runs stay stable and swaps don’t revert on bookkeeping. Swap gas is set from eth_estimateGas (85k) with tests guarding operation↔calldata alignment, mix weights, PRNG replay, and gas bounds.

Fixes ERC721 mint gas from 22,460 to 75,000 (measured cold mint ~69k), with a test so under-limited mints can’t silently “succeed” when receipt tracking is off.

^{Reviewed by Cursor Bugbot for commit 6c7e41d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[seidroid]

Adds a well-documented constant-product AMM scenario (contract, binding, scenario, operation set, tests) and raises the ERC721 mint gas limit from a value that made every mint fail. The code is correct and well tested for chains running default EVM storage costs; the main open items are the hard-coded gas limits on Sei's public chains and missing user-facing docs for the new scenario.

Findings: 0 blocking | 6 non-blocking | 2 posted inline

Blockers

• None at the file/PR level.

Non-blocking

• [suggestion] The new amm scenario and its operations keys (swap_a_to_b / swap_b_to_a) are not documented for operators: README's "Available Scenarios" list is not updated, and config/doc.go's "Operation baskets" section still names only storagerw as declaring a frozen operation vocabulary. Since the operation names and their declaration order are a frozen wire contract, amm's set is worth writing down alongside storagerw's.
• [suggestion] The scenario deploys exactly one pair, so every AMM transaction in a run writes the same two reserve slots (reserveA/reserveB). Under Sei's parallel execution that makes the whole AMM slice fully conflicting and serialized, which is faithful to a single UniswapV2 pair but not to a DeFi load profile spread across many pairs. Worth either documenting explicitly next to AMMScenario or leaving a note for a future multi-pair axis, so a profile author does not read AMM throughput as parallelizable DeFi load.
• 2 suggestion(s)/nit(s) flagged inline on specific lines.
• 2 non-blocking pre-existing issue(s) listed below under pre-existing issues.

Pre-existing issues

• [suggestion] generator/scenarios/ERC20Conflict.go and generator/scenarios/ERC20Noop.go carry the same under-sized hard-coded gas limits this PR fixes for ERC721 (the PR body measures ERC20Noop short by 455 gas and ERC20Conflict by 69,710). With trackReceipts defaulting to false, runs using those scenarios report failed, limit-burning transactions as sent. Tracked as PLT-1091.
• [suggestion] README's "Available Scenarios" list (README.md:145-151) was already stale before this PR — it omits StorageRW, Disperse, EVMTransferFast and EVMTransferNoop, so it is not a reliable index of what the factory registers.

[seidroid]

[suggestion] This limit is calibrated for the default 20,000 SSTORE_SET, and the comment above it states that pacific-1 and atlantic-2 charge ~74,700, putting an account's first swap near 185,000. On those chains every account's first swap will land with a failed status and burn the full 85,000, and with trackReceipts defaulting to false the run reports each one as sent — the exact silent failure mode the ERC721 change in this PR fixes.

I understand the exposure is package-wide and PLT-1092 covers it, so this need not block. But a brand-new scenario shipping a limit already known to fail on the two main public chains is worth at least a guard rather than only a comment: e.g. a one-time eth_estimateGas at deploy/bind time to size the constant (off the per-tx send path), or a startup warning when the scenario runs against a chain whose SSTORE_SET is above the default.

[seidroid]

[suggestion] Good fix — 22,460 was clearly wrong. Note the fix is only complete for chains running default storage costs: a mint writes _owners[tokenId] (always zero→non-zero) and _balances[to] (zero→non-zero for a fresh receiver), so on pacific-1/atlantic-2 at ~74,700 per zero→non-zero write a cold mint needs roughly 180k and still fails silently under 75,000. Worth stating that residual gap in this comment the way ammSwapGas does, so the next reader does not take the constant as chain-independent.

[bdchatham]

Both findings are correct, and both are fixed in #73 rather than here — flagging the trail, since a reviewer reading this PR alone sees suggestions against constants that still exist in this diff.

On ammSwapGas. Right, and your proposed fix is the one that shipped: a single eth_estimateGas at bind time, off the per-transaction send path. #73 does exactly that — a scenario declares GasEstimateCalls(), the preparation step prices them once after the contracts are bound, and the send path reads a number. ContractScenarioBase deliberately does not implement the method, so a scenario added without one does not compile.

One correction to the framing: the exposure is not limited to pacific-1 and atlantic-2. I measured arctic-1 by linear fit over eth_estimateGas and it charges the same ~74,695 per zero-to-value write. So this constant was failing on the deployment target too, not only on the public chains. Live quote for that swap on arctic-1 is 185,711.

On erc721MintGas. Also right, and more precisely than my own comment was — two zero-to-value writes, so ~180k on Sei. Measured live: 175,000.

Your ask was to state the residual in the comment. I'd argue deleting the constant beats documenting it, which is what #73 does. What the comment taught — that an estimate is a required limit rather than a receipt's GasUsed, and that the cost is bimodal per account — moved to the package doc, where it explains the design instead of defending a number.

At the top of the stack neither constant exists:

grep 'ammSwapGas|erc721MintGas'  ->  (empty)
AMM.go:99      limit, ok := s.GasLimitFor(op)
ERC721.go:79   limit, ok := s.GasLimitFor(config.OpERC721Mint)

Pulling that work down into this PR would defeat the point of stacking it, so I'm leaving this one as the scenario plus the constant fix it was.