diff --git a/MEGAETH-FORK.md b/MEGAETH-FORK.md index 4fbd4af500..341d1e90bb 100644 --- a/MEGAETH-FORK.md +++ b/MEGAETH-FORK.md @@ -8,7 +8,7 @@ Crate names stay `revm-*`; consumers switch to the fork through a `[patch.crates revm does not expose the hooks MegaETH needs (multi-dimensional gas, gas preserved on halt, read-only journal access). Without them, `mega-evm` had to wrap every opcode and copy upstream functions. -The fork adds those hooks as a thin layer; all MegaETH logic stays in `mega-evm`. +The fork adds those hooks, and the MegaETH accounting it carries today inside revm's forwarding and settlement, a set rule 2 names and bounds; every other MegaETH rule stays in `mega-evm`. ## Baseline @@ -36,9 +36,29 @@ The baseline moves only when the MegaETH node moves to a newer revm major (see T `reth`, `alloy-evm` and `revm-inspectors` are compiled against this fork unmodified; `op-revm` is forked separately at [megaeth-labs/op-revm](https://github.com/megaeth-labs/op-revm) and ported there. The `Semver` workflow checks every pull request against its base; a deviation passes only with the `api:exception` label, and the pull request body lists every deviating item with the consumers it was checked against. Each consumer's own CI builds against the tagged fork. -2. **Thin layer.** - The fork adds hooks and data; it does not implement MegaETH semantics. - If a change needs a design decision, it belongs in `mega-evm`. + The fork carries accepted exceptions, and each entry under Hooks names its own. + One changes the signature of an upstream function the fork picked with the EIP-8037 / EIP-2780 gas core: `pre_execution::apply_auth_list_eip2780`. + The fork's takes the context, the authorization list as `&[Eip7702AuthFacts]` and whether EIP-8037 is on, where upstream's takes the journal, an iterator of authorizations and the two state-gas prices, so that every authorization's charge is priced through `Host::state_gas_price` (see State-gas price). + The base line has no such function, so the change breaks no code written for it. + A consumer that runs the authorization phase through `pre_execution::apply_eip7702_auth_list` or `Handler::apply_eip7702_auth_list`, whose signatures are upstream's, is unaffected. + It affects code that calls `apply_auth_list_eip2780` itself, written for upstream's signature: it does not compile against the fork until it passes the context and the list `Eip7702AuthFacts::collect` builds. +2. **Hooks and data, and a bounded set of MegaETH accounting.** + The fork adds hooks and data. + It also carries a named, bounded set of MegaETH accounting inside revm's charges and settlement: + - withheld regular gas and its crossing record, which every regular charge reads; + - the history-gas dimension, charged reservoir-first, unwound with state gas, and charged for deployed code inside `return_create`; + - give-backs to the reservoir alone, which change where revm's refills, rollbacks and reservoir merges credit a give-back, and the legacy share of an opcode's state charge. + + Each item has its entry under Hooks, whose Default keeps upstream's results for a consumer that sets nothing. + Nothing else that implements MegaETH semantics enters the fork. + What a consumer decides per frame start, such as a budget, a charge the frame's failure gives back, an allowance or a part of the caller's reservoir it keeps, it keeps beside revm's gas, driven by the start lifecycle's hooks; the lifecycle carries no MegaETH figure, so it is a generic hook and the set does not grow with it (see Start lifecycle). + An addition to the set needs all of these, argued in its pull request: + - no hook that sees only the state revm exposes at that point can make the same decision, because the figure is read or written inside a charge, or has to be ordered with revm's own settlement; the pull request says why the consumer cannot keep it beside revm's gas; + - it is mechanism, not policy: every amount, share, price and limit comes from the consumer, through the gas schedule or a hook, and a detail the fork has to fix itself, such as a rounding, is named in its entry; + - zero, unlimited or none as its default leaves every result upstream's, and its entry states what a consumer that sets nothing pays for it, in bytes on the frame results and in instructions; + - its entry names the condition under which the fork drops it. + + A design decision still belongs in `mega-evm`: the fork carries the figures and moves them with the gas, and `mega-evm` decides what they are and what happens when one runs out. 3. **Cargo versions stay fixed between base-line moves.** The `[patch.crates-io]` mechanism only applies when the patched version satisfies the consumer's requirement, and pre-release suffixes do not satisfy `^40.0.3`. Releases are identified by git tags only. @@ -61,26 +81,52 @@ The baseline moves only when the MegaETH node moves to a newer revm major (see T A tag is the only identity a fork release has (rule 3), and the release workflow tags only commits whose `ci success` is green. Consumer tag pinning is not enforced mechanically; each consumer's `Cargo.lock` records the commit it built against. +## What the fork carries + +`git diff ..` is the fork's footprint on upstream (rule 4). +It falls into five classes, and the next base-line move (see Tracking upstream) treats each one differently. +The sizes are the lines of `crates/`, without tests, that `git blame ..` attributes to each class's commits. + +| Class | What | Size | At the next base-line move | +|---|---|---|---| +| Upstream gas core | The EIP-8037 / EIP-2780 gas core, picked from later upstream releases | about 2,600 lines | Goes away once the new base contains every pick; the sweep issues record which tag first contains each. The settlement code the fork's MegaETH accounting is written into is upstream's own (`handle_reservoir_remaining_gas`, `rollback_state_gas`, `return_create`), so that accounting is re-applied to the new base's versions of it. | +| Other upstream picks | Fixes and performance picks | about 140 lines | Goes away once the new base contains them; a pick the base lacks is picked again or dropped, as its sweep decides. A behaviour a switch takes back stays switchable (see Consumer switches). | +| Generic hooks | State-gas price, precompile price, code-deposit admission, the failed-charge record, the completed-write and frame-start hooks, the pending action, the frame-run-result hook and the start lifecycle | not counted | Each is proposed upstream, in a form upstream can take: without MegaETH vocabulary in its types, as an instruction-level helper rather than a `Host` method where one serves, and with no cost on the default path that upstream would not accept. It is carried until upstream has an equivalent (its Removal). | +| Consumer switches | Amsterdam opcodes and EIP-7708 below Amsterdam, the base line's journal semantics | about 300 lines | Carried until their Removal conditions. The Amsterdam switch is proposed in the shape of upstream's per-EIP activation switches, which already cover three of its four opcodes; the base line's journal semantics are not proposed. | +| MegaETH accounting (rule 2) | Withheld regular gas, the history-gas dimension, give-backs to the reservoir alone and the legacy share | about 800 lines | Carried and re-applied to the new base, or replaced: an item a later design keeps in `mega-evm` instead, with the same results for the consumer that uses it, leaves the fork, and its entry's Removal says when. | + ## Hooks -This section lists every hook and switch the fork carries. +This section lists every hook, switch and accessor the fork carries, and each item of rule 2's MegaETH accounting. Each entry names the API a consumer uses and what the fork guarantees about it. A hook's default keeps upstream's behaviour: a consumer that does not use it sees the same results. -Each entry's **Consumer** says who needs it and why it cannot be done outside the fork, its **Removal** the condition under which the fork drops it, and its **Default** what it costs a consumer that does not use it. +Each entry's **Consumer** says who uses it and why the fork carries it, its **Removal** the condition under which the fork drops it, and its **Default** what it costs a consumer that does not use it. + +A field a hook adds to a serialized type carries `serde(default)`, so in a format that carries field names, such as JSON, an encoding made before the field existed decodes with the default. +A format that encodes a struct by position, such as bincode, cannot read such an encoding, as with upstream's own field additions: it reads the old fields in their places and then looks for the new ones, so a value persisted in such a format must not cross an upgrade of the fork that adds a field. + +A gas schedule (`GasParams`) is a table of 256 entries, not named fields, so `serde(default)` cannot reach an entry: a table built raw (`GasParams::new`) or decoded from an encoding made before an entry existed holds zero there. +Every entry the fork adds is therefore zero by default, and zero is upstream's behaviour: such a table behaves as the default schedule does. +An id the fork once used for an entry is left unused rather than given a new meaning, so a table encoded then does not read as a setting: ids 246 to 254 are such ids. ### State-gas price - **API.** `Host::state_gas_price(&mut self, id: GasId, site: StateGasSite) -> Option` and `Host::state_gas_charge(&mut self, charge: StateGasCharge) -> Option`. The value types `StateGasSite` (`account`, `slot`) and `StateGasCharge` (`one`, `units`, `total`) in `revm_context_interface::cfg`. For the refund: `charged_state_gas_address` on `CreateInputs`, `CallOutcome` and `CreateOutcome`, and `FrameResult::refundable_state_gas_charge`. - `pre_execution::Eip7702AuthFacts`, the authorization list lifted out of the transaction so the authorization phase can hand the whole context to the hook. + `pre_execution::Eip7702AuthFacts`, the authorization list lifted out of the transaction so the authorization phase can hand the whole context to the hook, and the signature of `pre_execution::apply_auth_list_eip2780`, which takes the context and that list in place of upstream's journal, authorization iterator and two state-gas prices (an exception to rule 1). - **Contract.** Every EIP-8037 state-gas charge and every refund of one is priced through `state_gas_price`, so a charge and the refund that undoes it agree by construction. `site` names the account the charge lands on, and the storage slot for a slot-scoped charge; a creation is priced at the address it deploys at, the first frame's included. `None` reports a failed lookup: the implementation records the cause in the context error, and the charge site turns it into a fatal external error. - **Consumer.** mega-evm prices state gas by the storage bucket of the account or slot a charge lands on. Only the charge site knows the site, and the price must be the same at the charge and at its refund. - **Removal.** When upstream prices state gas through an equivalent hook, or when mega-evm prices every state-gas charge from the flat schedule. -- **Default.** Reads the flat schedule (`gas_params().get(id)`) and never fails, so every charge and refund is upstream's. +- **Default.** Reads the flat schedule (`gas_params().get(id)`) and never fails, so every price is upstream's, and so is every charge and refund but one. + With EIP-2780 on, the first frame's creation is checked and charged at the address it deploys at, which the caller's account nonce gives, where upstream's derives the address from the transaction's nonce. + The two agree while the nonce check is on. + With the nonce check off and a transaction nonce that differs from the caller's account nonce, as for an OP deposit, upstream's checks, charges and warms an address the transaction does not deploy at, and the fork's the address it deploys at. + There, whether the creation pays `create_state_gas` can differ from upstream's, and so can the gas of a later access to the other address, which upstream's leaves warm and the fork's leaves cold. The refund carries one address more in the frame inputs and outcomes, and under EIP-2780 an EIP-7702 transaction's authorization list is buffered before the authorization phase, one 88-byte entry per authorization that can apply. + `CallOutcome` and `CreateOutcome` are constructible by literal and carry `charged_state_gas_address`, which upstream's do not, so an outcome literal written for upstream's fields does not compile against the fork until it names it (`Address::ZERO` with nothing charged). ### History gas @@ -88,13 +134,34 @@ Each entry's **Consumer** says who needs it and why it cannot be done outside th `GasId::code_deposit_history_gas` and `GasParams::code_deposit_history_gas(len)`. - **Contract.** A history charge draws the same reservoir-first budget as a state-gas charge: the reservoir, then regular gas, withheld part first. It is booked on its own counter, so history gas can be reported and limited apart from state gas. - It unwinds with state gas: a frame that reverts or halts refills both in last-in-first-out order, and `refill_history` returns a spill before it tops up the reservoir. + It unwinds with state gas: a frame that reverts or halts refills both in last-in-first-out order, and `refill_history` returns a spill before it tops up the reservoir, unless give-backs go to the reservoir alone (see Give-backs to the reservoir alone and the legacy share). `return_create` charges `code_deposit_history_gas` for the deployed bytes after their state-gas charge. `ResultGas` has no field for it: `total_gas_spent` and `block_regular_gas_used` include it, and the `ResultGas` documentation says how a block-level consumer separates it. - **Consumer.** mega-evm charges history gas for the bytes a transaction appends to the chain's history. The code deposit is charged inside `return_create`, and only the tracker can unwind a frame's history charges with its state charges. - **Removal.** When upstream carries an equivalent gas dimension, or when mega-evm stops charging history gas. - **Default.** No schedule prices `code_deposit_history_gas`, and nothing else in the workspace charges history gas, so the counter stays zero and every result is upstream's. - The counter decodes as zero from encodings that predate it. + In a format that carries field names, the counter decodes as zero from encodings that predate it. + +### Give-backs to the reservoir alone and the legacy share + +- **API.** `CfgEnv::reservoir_only_give_backs` with `with_reservoir_only_give_backs`, and `Cfg::reservoir_only_give_backs` (default `false`). + On `GasTracker`, forwarded on `Gas`: `reservoir_only_give_backs`, `set_reservoir_only_give_backs`, `record_state_cost_with_legacy_share`, `consume_regular_paid_charges` and `halted_regular_paid`; on `GasTracker` alone, `add_regular_paid_of`. + `GasId::sstore_set_state_gas_legacy_share`, `new_account_state_gas_legacy_share`, `selfdestruct_new_account_state_gas_legacy_share` and `create_state_gas_legacy_share` (ids 245 to 242), with their `GasParams` accessors, and the `state_gas_with_legacy_share!` instruction macro. +- **Contract.** revm sets the switch on the transaction's gas (`Handler::tx_gas`) and on every frame's gas, and on the results it builds for a call or creation it answers without running a frame (`EthFrame::make_call_frame`, `make_create_frame`), from the configuration. + With it on, no give-back of state or history gas credits regular gas: `refill_reservoir` and `refill_history` top up the reservoir alone, `rollback_state_gas` sets the reservoir to `reservoir + state_gas_spent + history_gas_spent` and leaves regular gas as it was, and `absorb_returned_reservoir` takes the returned reservoir as the caller's without unwinding anything. + A frame's regular gas then rises within the frame only by the regular gas a child returns. + `state_gas_spilled` counts every part of a state or history charge regular gas paid in a frame and in the frames below it that returned to it, and no give-back lowers it: a child adds its count to its caller's however it ended (`handle_reservoir_remaining_gas`, `add_regular_paid_of`). + A halt takes the part of the count no halt below consumed yet out of the reservoir the rollback set, which leaves the reservoir the frame received, and records the whole count as consumed (`consume_regular_paid_charges`, `halted_regular_paid`), before it spends the regular gas; the record travels up with the count, so a caller's own halt does not take a halted child's part out a second time. + After a halt of the transaction's frame, `settle_first_frame` gives back only the part of the EIP-2780 first-frame charge the reservoir paid: that charge is the last made before the frame, and every charge there draws the reservoir first, so the part regular gas paid is the last `min(charge, paid)` of what the transaction's count held before the frame's joined it. + The legacy share is the part of an opcode's state charge regular gas pays before the reservoir pays any of it: `SSTORE`'s fresh slot, a value `CALL`'s new account, a `SELFDESTRUCT`'s new beneficiary and a `CREATE`'s or `CREATE2`'s created account each take `min(charge, entry)` of their schedule entry from regular gas, withheld part first, before the reservoir; a value call's and a creation's before the forward is computed. + A frame whose regular gas cannot pay the share and what the reservoir cannot pay runs out of gas, whatever the reservoir holds. + The share is state gas, counted with its charge and given back with it, and the switch and the shares are independent: with the switch off a share is part of the spill a give-back unwinds. +- **Consumer.** mega-evm keeps a frame's regular gas from rising within the frame by gas spent on state and history, and keeps creating state at its pre-Amsterdam price in regular gas when a transaction carries a reservoir. + Every refill, rollback and reservoir merge that credits regular gas is inside revm: an `SSTORE` that writes a slot back refills inside its instruction, and a frame's rollback and the merge of its reservoir into its caller's are revm's settlement, so no hook that sees the gas afterwards can tell what revm credited; and a value call's and a creation's share must come off regular gas before the opcode computes its forward. +- **Removal.** When upstream's EIP-8037 credits every give-back to the reservoir and takes a legacy share from regular gas, as ethereum/EIPs#12581 proposes, or when mega-evm stops doing either. +- **Default.** The switch is off and every share entry is zero, so every result is upstream's: `record_state_cost_with_legacy_share` with a share of zero is `record_state_cost`, `consume_regular_paid_charges` changes nothing, a failed child's count, which its rollback zeroed, is not added, and `halted_regular_paid` stays zero. + The switch is a `bool` in a word the tracker already had; the record of what halts consumed is a word of its own, so `GasTracker` is 96 bytes and `Gas` 112, `InterpreterResult` 152, `CallOutcome` and `FrameResult` 216 and `CreateOutcome` 200 (64-bit targets), still copied inline; in a format that carries field names the two decode as `false` and zero from encodings that predate them. + In instructions, a give-back, a rollback and a merge read one `bool`, a value call that creates an account and the three other share sites read one schedule entry, and every frame's construction reads the switch from the configuration once. ### Amsterdam opcodes and transfer logs below Amsterdam @@ -138,7 +205,7 @@ Each entry's **Consumer** says who needs it and why it cannot be done outside th - a regular charge (`record_regular_cost`, `record_cost_unsafe`), whether or not the withheld part would have paid it; - a state or history charge whose spill past the reservoir regular gas cannot pay (`record_state_cost`, `record_history_cost`), whether the reservoir paid nothing or part of it; the record is regular gas alone, and the reservoir is left as it was; - a forward to a child that regular gas cannot pay (`record_withheld_first_cost`), which only a call before EIP-150 can fail; - - an out-of-gas halt of the interpreter with no record there, before the halt zeroes the frame's gas: a cold access the instruction refused before its charge because the frame could not pay it (an account read, `SLOAD`, `SSTORE`, `SELFDESTRUCT`, a call's target and the account it delegates to), or an out-of-gas a consumer's instruction returned itself; a record already there is the failure that caused the halt, and is kept; + - an out-of-gas halt of the interpreter with no record there, before the halt zeroes the frame's gas: a cold access the instruction refused before its charge because the frame could not pay it (an account read, `SLOAD`, `SSTORE`, `SELFDESTRUCT`, a call's target and the account it delegates to), an out-of-gas a consumer's instruction returned itself, or one an instruction hook asked for (see Completed-write hook and Frame-start hook); a record already there is the failure that caused the halt, and is kept; - a precompile run that needs more gas than the frame has: the frame's whole gas limit, as nothing ran. The failed deduction took nothing, so the record is all the regular gas the frame had; the unchecked charge records it before the spendable part wraps, and a failure with nothing left records `Some(0)`. @@ -151,7 +218,8 @@ Each entry's **Consumer** says who needs it and why it cannot be done outside th - **Consumer.** mega-evm's gas detention reads what a halting frame burned. An `OutOfGas` halt zeroes the frame's regular gas inside the interpreter, before the frame's result reaches any boundary mega-evm owns. - **Removal.** When upstream keeps a halting frame's regular gas readable, or when mega-evm no longer reads what a halting frame burned. - **Default.** Each record is written on the failure side only: the tracker's in cold, out-of-line functions, the interpreter's in its cold out-of-gas halt, the handler's on a precompile's out-of-gas. A deduction or load that succeeds runs the same code. - It is two words: the tracker is 88 bytes, and a copy of the tracker, and of every `Gas` and frame result that holds one, is 16 bytes larger. + It takes two words of the tracker, a number and a flag, and the flag's word also holds the start mark (see Start lifecycle); every copy of the tracker, and of every `Gas` and frame result that holds one, carries both words. + Encoded, the record is an optional number in the field's place. Where measured (callgrind, the fork's release profile), the field left a transfer and a precompile call unchanged and cost about 0.1% of the instructions of a creation; the records written on the failure side add nothing measurable. ### Precompile price @@ -170,7 +238,7 @@ Each entry's **Consumer** says who needs it and why it cannot be done outside th - **Coverage.** Every precompile the crate defines carries its price function, so every precompile of every set `Precompiles::new` returns answers. A precompile built with `Precompile::new` carries none and answers `None`. A precompile that wraps a built-in must price itself from the price function of the run it wraps, and price its own refusals at `0`; `with_required_gas`'s documentation shows the pattern, and such a wrapper needs a differential test against its own run. - Outstanding: the port to the op-revm fork. At `v20.0.0-mega.2` its nine size-limited wrappers (the BN254 pairing and the BLS12-381 G1 MSM, G2 MSM and pairing, across its hardforks) are built with `Precompile::new` and answer `None`. + A precompile defined outside this repository that wraps a revm run must price itself from the run it wraps, as the op-revm fork's size-limited wrappers do; that fork's `MEGAETH-FORK.md` ("Precompile prices") carries their guard. - **Guard.** `ecrecover`, `sha256`, `ripemd160` and `blake2f` repeat literals their runs keep private; the differential test `required_gas_matches_every_builtin_run`, run under every backend, fails when a run's gas changes and its price does not. - **Consumer.** mega-evm holds a precompile call to an allowance below its forward and must tell a crossing from a plain out-of-gas without running it. A precompile's gas rule is private to its run. - **Removal.** When upstream exposes a precompile's price before the run, or when mega-evm stops holding precompile calls to an allowance. @@ -190,7 +258,7 @@ Each entry's **Consumer** says who needs it and why it cannot be done outside th The deposit's charges, and with them its state-gas price lookup through `Host::state_gas_price`, are made before it is offered, so that lookup is made whether or not the deposit is admitted; a refusal does not undo what the lookup recorded. - **Reach.** The hook is on the context `return_create` is called with, so a consumer that wraps `EthFrame`, runs `process_next_action` from its own `frame_run`, or customises `Handler` reaches it by implementing `ContextTr` for its context. A context that wraps another and implements `ContextTr` by hand must forward the method, or it gets the admitting default. -- **Consumer.** mega-evm refuses a deposit its own rules reject, after revm's checks and charges and before the creation commits. That point is inside `return_create`, between its last charge and the checkpoint commit. +- **Consumer.** mega-evm refuses a deposit its own rules reject, after revm's checks and charges and before the creation commits, and counts the deployed code against the creating frame's budget there. That point is inside `return_create`, between its last charge and the checkpoint commit. - **Removal.** When upstream has an equivalent admission point, or when mega-evm stops refusing deposits. - **Default.** `return_create` compiles to the same code, on its own and inlined into the handler on the plain and the inspected path. Inlined into a consumer's own function, the admitting default may shift its block layout; where measured, that cost one unconditional branch on one out-of-gas path and changed no success path. @@ -204,22 +272,234 @@ Each entry's **Consumer** says who needs it and why it cannot be done outside th - **Removal.** When no consumer needs to reproduce revm 40.0.3's journal. - **Default.** Off, which is the picked behaviour; the journal reads one `bool` when it warms a cold slot and when it records a code change. +### Completed-write hook + +- **API.** `Host::write_completed(&mut self, write: CompletedWrite<'_>, gas: &mut GasTracker) -> WriteVerdict`, whose default continues. + `CompletedWrite` (`Sstore`, `Log`, `SelfDestruct`, with the write's account and what the instruction knows of it; `SelfDestruct` also carries `balance`, the destructed account's balance before the write) and `WriteVerdict` (`Continue`, `OutOfGas`, `Revert(Bytes)`), in `revm_context_interface::host`. + `CompletedWrite` is exhaustive on purpose: mega-evm matches it to meter each write, so a new kind is a compile error in every consumer that matches it rather than a write that passes a wildcard arm un-metered, and adding one is an `api:exception` change. + Its variants' fields are exhaustive too: a consumer that builds a variant, or matches one naming every field without `..`, names every field, `SelfDestruct`'s `balance` included, and a field added to a variant is an `api:exception` change as a new kind is. +- **Contract.** `SSTORE`, `LOG0`–`LOG4` and `SELFDESTRUCT` call it once the write is in the journal and every charge the instruction makes has been made, its refund included, so only on the instruction's success path, on the plain and the inspected path. + `gas` is the running frame's tracker. The hook may debit and credit it, and the instruction uses it as the hook left it: nothing is charged after the hook. A charge the hook makes that fails records as any failed charge does (see The failed-charge record), whatever the verdict. + `Continue` ends the instruction as it would have ended. `OutOfGas` fails it as a failed charge does: the frame halts out of gas, and the halt records the regular gas the hook left unless a failed charge already did. `Revert(output)` ends the frame as a `Revert` with `output`, on its gas as the hook left it; a `SELFDESTRUCT` so reverted does not self-destruct. + Only these instructions call it: a write the journal records any other way (a value transfer and its log, deployed code, an inspector's or a precompile's write) is not offered. + A destruction changes only balances, no nonce and no code. So with the journal at the hook, `SelfDestruct`'s `balance` rebuilds both accounts as they were before the write: the destructed account held `balance`, and a beneficiary that is another account held its balance less `balance`, since it got all of it. + When the beneficiary is the destructed account itself, the account's balance after the write says whether the spec burned the balance or left it. +- **Consumer.** mega-evm meters each completed write against its per-transaction limits and charges its history. Without the hook it wraps the three instructions and stages what its `Host` saw. + It counts an account's write record while the account's info differs from what the transaction loaded. A destruction's two accounts can look the same after the write whether or not they had changed before it (loaded with 5, now 0, from 5 or from 7), so it needs the balance before the write, which only the instruction reads before the write. +- **Removal.** When upstream exposes an equivalent point, or when mega-evm stops metering writes. +- **Default.** Continues and touches nothing. The facts are references to values the instruction holds anyway, except `SelfDestruct`'s `balance`, which the instruction reads for the hook from the running frame's own account just before the write. The journal holds that account warm, so the read loads nothing cold. + Where measured (callgrind, the fork's release profile), `SSTORE` and `LOG0`–`LOG4` compile to the same code as without the hook. The read costs a `SELFDESTRUCT` 119 instructions, one warm journal lookup (+1.5% of a transaction that self-destructs a contract). It is a `Host::load_account_info_skip_cold_load` call that upstream's instruction does not make, so a `Host` that counts or refuses loads sees one more per `SELFDESTRUCT`. + +### Frame-start hook + +- **API.** `Host::frame_starting(&mut self, start: &mut FrameStart, gas: &mut GasTracker) -> bool`, whose default returns `true`. + `FrameStart` (`#[non_exhaustive]`, built with `FrameStart::new`: `kind`, `caller`, `target`, `value`, `forward`, and `reservoir`, which `new` leaves `None`) and `FrameStartKind` (`Call`, `CallCode`, `DelegateCall`, `StaticCall`, `Create`, `Create2`), in `revm_context_interface::host`. + `FrameStartKind` is exhaustive on purpose, as `CompletedWrite` is: mega-evm matches it to charge each start, so a new kind is a compile error in every consumer that matches it rather than a start that passes a wildcard arm uncharged, and adding one is an `api:exception` change. +- **Contract.** `CALL`, `CALLCODE`, `DELEGATECALL`, `STATICCALL`, `CREATE` and `CREATE2` call it after every charge they make and after the forward is taken from the caller's gas, before they build the frame's input, on the plain and the inspected path. + `forward` is the regular gas taken: the frame's gas limit without a value call's stipend. `value` is the value transferred, zero for `DELEGATECALL` and `STATICCALL`. + `target` is the account the frame runs as: the account called for `CALL` and `STATICCALL`, the calling frame's own for `CALLCODE` and `DELEGATECALL`, and for `CREATE` and `CREATE2` the address the creation would take. + Whether a creation takes it is the outcome's to say (`CreateOutcome::address`): a creation that lands on an account that already has code or a nonce, one the handler refuses after the hook (an inspector changed the caller's balance), and one an inspector's `create` or a consumer's `frame_init` answers without a frame take none, though their start named the address. A consumer that counts the created account from `target` settles that count on the outcome. + A creation's address is computed once, into the creation's input, and the handler builds the frame at it without computing it again. With EIP-8037 on, the instruction's EIP-8037 branch computes it. With EIP-8037 off, the instruction computes it after the same checks, reading the caller's balance and nonce from the journal. + It is `None` only for a creation the handler fails before it takes an address: an endowment above the caller's balance, a caller's nonce at its maximum, or a creating frame at the depth limit. Such a creation reaches the hook only with EIP-8037 off; with it on, the instruction ends the creation before the hook. + The address is fixed when the hook sees it. Something that changes the caller's nonce between the instruction and the frame does not move it, as on upstream's EIP-8037 path. An inspector that changes the creation's caller, scheme or init code (`CreateInputs::set_call`, `set_scheme`, `set_init_code`) clears it, and the handler computes the new one. + `gas` is the caller's tracker. The hook may debit and credit it, and the instruction uses it as the hook left it: nothing is charged after the hook, and the frame's input copies the reservoir the hook left in it, so a frame the handler runs and one it answers without running (a precompile) both start from that reservoir. A charge the hook makes that fails records as any failed charge does, whatever the answer. + `start` is the hook's to name the child's reservoir on (`reservoir`), if it takes that out of `gas` itself; the instruction reads nothing else back from it. + `FrameStart::reservoir` is `None` when the hook is called. `None` leaves the frame's input a copy of the reservoir in `gas`, which the caller keeps while the child runs, as upstream's instructions do. `Some(r)` means the hook took the child's reservoir out of `gas` itself: the frame's input carries `r` instead, and the caller keeps what the hook left it. The instruction does not check `r` against what the hook took. + Either way the child's settlement replaces the caller's reservoir with the one the child returns, as upstream's does; a consumer that kept part of the caller's reservoir adds it back when revm settles the child (`FrameSettle::held_reservoir`, see Start lifecycle). + `true` hands the start to the handler, which may still refuse it (call depth, balance) or answer it without a frame; what the hook did to `gas` stands either way. `false` fails the instruction out of gas and starts no frame: the forward stays taken unless the hook gave it back, and the halt records the regular gas the hook left unless a failed charge already did. + A creation the instruction ends before its forward (EIP-8037's checks of the endowment, the nonce and the depth) is not offered. +- **Consumer.** mega-evm charges a start's write records after the forward and before the frame inherits the caller's reservoir. Without the hook it wraps the call and creation instructions, rewrites the reservoir revm already copied into the input, and takes the input back when the charge fails. + It counts the created account's record only when the transaction has not changed that account already (funded it, say), so it needs the address at the start. A `CREATE2`'s address depends on the init-code hash, which only the instruction has. +- **Removal.** When upstream exposes an equivalent point, or when mega-evm stops charging frame starts. +- **Default.** Returns `true` and touches nothing. + Where measured (callgrind, the fork's release profile), a call runs one instruction more than without the hook: the store of the forward its helper returns, about 0.05% of a call to a contract that stops. + For `CREATE` and `CREATE2` the hook's only cost is the start's address. + With EIP-8037 off, the default spec's path, the address costs a warm journal read of the caller and the three checks: 149 instructions per `CREATE` and 147 per `CREATE2` from a contract (+0.95% and +0.73%). The read is a `Host::load_account_info_skip_cold_load` call that upstream's instruction does not make, so a `Host` that counts or refuses loads sees one more per creation. + The instruction computes the address and a `CREATE2`'s init-code hash, and the handler reuses them, so a creation the handler builds or fails computes the same hashes as upstream's. + A start that never reaches the handler's frame building computes them for the hook alone: one hash for a `CREATE`, two for a `CREATE2`. That is a start the hook refuses, and a creation answered without a frame, by an inspector's `create` or by a consumer's own `frame_init`. Upstream's EIP-8037 path computes them before the hook in the same way. + With EIP-8037 on, the start reads the address the EIP-8037 branch already computed from the input; that path was not measured. + `CreateInputs`' derived `PartialEq` compares the cached address and hash, which the input of a creation the instruction starts holds with EIP-8037 on and off, so it compares unequal to an otherwise equal input that has computed nothing, and to its own serde round trip, which skips the cache. + A consumer tells a creation from a call by `kind`, not by `target`: `target` is `None` only for the creations the Contract names, and for every other start an address, which for a creation is the one it would take. + +### The pending action + +- **API.** No new item: upstream's `LoopControl::set_action` on a frame's interpreter, which `Interpreter::run_plain` (and `run_plain_as_output`) and `revm_inspector::inspect_instructions` honour before their first instruction, and which `InspectorEvmTr::inspect_frame_init` reads before it hands a new frame to `Inspector::initialize_interp`. +- **Contract.** An action set on a frame's interpreter before the frame runs is what the run returns, before any instruction runs. That is an action set once `frame_init` built the frame, or once `frame_return_result` put a child's result into its caller. + The plain and the inspected run return it alike: no instruction executes, so the frame's gas, stack, memory and program counter are as they were when it was set, and the inspected run calls neither `Inspector::step` nor `step_end` for that run. + The handler then processes it as any instruction's action (`process_next_action`): a `NewFrame` starts a child, a `Return` ends the frame on its result, as an instruction's return would. + A run that starts with no action set runs as upstream's: the inspector's `step` comes before each instruction, and an action the inspector sets in `step` ends the run after that `step`, as upstream's does. + A frame whose action is set when it is built is not handed to `initialize_interp`, and runs no `step` before that action: the action `frame_init` set is the frame's, which no inspector can replace, and the inspector sees the frame's start and end, as it sees a precompile's answer. + If that action starts a child and the frame resumes with no action set, the frame runs its code with a `step` before each instruction, never having been handed to `initialize_interp`. + An action an inspector sets in `initialize_interp` on any other frame is pending when the run starts, so it is returned the same way, without a `step`; upstream's inspected run calls `step` once before returning it, and returns the action as that `step` left it (see Baseline behaviour the fork changes). + One action at a time: `set_action` asserts in a debug build that none is pending, so a consumer sets an action only on a frame that has none. +- **Consumer.** mega-evm makes some of a frame's actions outside an instruction: the creation and the answer of a system contract's call, and the stop of a frame that a child left over a limit when it returns. They come back through the frame's run, so the loop starts the next frame or ends the frame, and an inspector sees the frame end. + Without the check, the plain run executes the frame's code before it returns the action, so mega-evm overrides `frame_run`, and the inspected run shows an inspector a `step` of an instruction that never runs. + Without the `initialize_interp` rule, an inspector that halts the frame of a system contract's call there trips `set_action`'s assertion in a debug build, and in a release build replaces the creation mega-evm set with its halt. +- **Removal.** When upstream's runs check for a pending action before their first instruction and its inspected frame start does not hand a frame with one to `initialize_interp`, or when mega-evm makes no action outside an instruction. +- **Default.** revm sets no action before a run, so the check finds none, every frame revm builds is handed to `initialize_interp`, and every run is upstream's, callbacks included, for a consumer and an inspector that set none. + Where measured (callgrind, the fork's release profile), the check costs about three instructions per frame run on the plain path: 6.03 per `CALL` (+0.23% on a transaction of 64 calls) and 6.12 per nested `CREATE`, which each run two frames (the child, and the caller's resume); 2 or 3 for a transaction whose one frame runs code; nothing for a transfer to an account without code or a precompile's answer, which run no frame. The inspected path, which also reads the action once per new frame before `initialize_interp`, was not measured. + +### Frame-run result hook + +- **API.** `EvmTr::frame_run_result(&mut self, result: &mut ::FrameResult) -> Result<(), ContextDbError>`, whose default does nothing. +- **Contract.** The handler loops hand it the result of each frame that ran and returns, once, as the frame's run left it: after `process_next_action` processed the frame's last action (`return_create`'s checks and charges included, for a creation), with the frame still on top of the stack. + Whether the frame is marked finished differs by path and frame type, so the hook does not rely on it: revm's `frame_run` marks it before the plain loop calls the hook, the inspected run marks a frame with an `EthFrame` after the inspector's end callbacks, as upstream's does, and a frame without one is marked by its own `frame_run`, before the hook. + On the plain path `Handler::run_exec_loop` calls it when `frame_run` returns a result. On the inspected path `InspectorEvmTr::inspect_frame_run` calls it before the inspector's `call_end` or `create_end` and its `frame_end`, and also for a frame without an `EthFrame`, whose run calls no inspector. On both, it runs before `frame_return_result`. + What it leaves in `result` is what everything after it sees: the inspector's end callbacks, `frame_return_result` and so the caller, and `last_frame_result` for the transaction's frame. An error it returns ends the transaction as an error of `frame_run` would. It leaves the frame stack as it found it. + A frame that returns a pending action (see The pending action) ran, and its result reaches it. + A result given without a run does not reach it: `frame_init` returns those (a start the handler refuses, a precompile's answer, an inspector's answer from `frame_start`, `call` or `create`, and an answer of a consumer's own `frame_init`). The consumer's `frame_init` has them first, and an inspector's answer is the inspector's. + It is on `EvmTr` because both calls reach it there: the inspected run is a provided method of `InspectorEvmTr`, which extends `EvmTr`, and has the EVM but not the handler. + The plain call is in the handler's loop, not in `Evm::frame_run`, and the inspected call is in the provided `inspect_frame_run`. So an EVM type that wraps revm's `Evm`, delegates `frame_run` to it and keeps the provided `inspect_frame_run` has its own `frame_run_result` called on both paths. + An override of `run_exec_loop` or of `inspect_frame_run` calls it at the same point itself. An `inspect_frame_run` that delegates to an inner EVM's reaches the inner EVM's `frame_run_result`, not its own, and runs the inner EVM's `frame_end` before the outer type sees the result. +- **Consumer.** mega-evm decides how a frame that crossed its compute limit ends: its out-of-gas becomes a revert carrying the limit's output, with its gas put back. That has to happen once, before an inspector sees the frame end, on both paths. The plain path could do it in `frame_return_result`, but the inspected run calls `frame_end` before that, so a tracer would see the out-of-gas the caller never gets. +- **Removal.** When upstream has an equivalent point between a frame's last action and the inspector's end of it, or when mega-evm rewrites no frame's end. +- **Default.** Does nothing, so every result and every callback is upstream's. + Where measured (callgrind, the fork's release profile), the default compiles to nothing on the plain path: the costs measured under The pending action are that check's. The inspected path was not measured. + +### Start lifecycle + +- **API.** + On `Host`, each with a no-op default: `frame_split(&mut self, split: &FrameSplit)`, `frame_settle(&mut self, settle: &FrameSettle, gas: &mut GasTracker)` and `frame_lifecycle_end(&mut self, end: LifecycleEnd)`. + `FrameSplit` (`id`, `parent`, `depth`), `FrameSettle` (`id`, `depth`, `status`, `created`, `inspector_answer`, `gas_replaced`, `outcome_rebuilt`, `held_reservoir`), `SettleStatus` (`Ok`, `Revert`, `Halt`) and `LifecycleEnd` (`Settled`, `Discarded`), in `revm_context_interface::host`. + `FrameSplit` and `FrameSettle` are `#[non_exhaustive]` and have no public constructor: only the record builds them (`FrameStack::open_start`, `FrameStack::close_start`), so a hook is called by hand only with a value the record made, and a field added later breaks no consumer. + `SettleStatus` and `LifecycleEnd` are exhaustive. + `revm_handler::lifecycle`: `open_frame_start`, `open_transaction_start`, `Returning` and `close_frame_start`, `close_transaction_start`, `finish_transaction`, `discard_transaction`, `mark_for_end_callbacks` and `check_end_callbacks`. + On `FrameStack`, the record: `open_start`, `close_start`, `pending_start`, `running_start`, `lifecycle_active`, `lifecycle_settled`, and its two boundaries `settle_lifecycle` and `discard_lifecycle`. + `StartLifecycleError` (`Exhausted`, `Stale`, `NotOpen`, `NoParent`, `Unsettled`; `#[non_exhaustive]`), `PendingStart` (its fields are private: the identity can be read and not written, and only the three flags can be set), `StartMark` and `OutcomeMark`. + `GasTracker::start_mark` and `set_start_mark`, and `start_mark` on `CallOutcome` and `CreateOutcome` (a field). + `LocalContextTr::lifecycle_mirror`, `LifecycleMirror` and `LifecycleEvent` (`Split`, `Settle`, `End`), the debug mirror (below). The types and the method exist in every profile. +- **Contract.** A *start* is one frame's beginning with the identity revm gave it; revm pairs every start it opens with exactly one settlement, last in first out, and the consumer does not pair them. + *Where revm opens one.* + - Where it consumes a `NewFrame` action, so the child's start opens against the frame on top of the stack, its caller, at that frame's depth plus one, which is the init's depth: + the plain `Evm::frame_run` opens it as the frame consumes the action, before `process_next_action` builds the init, and `InspectorEvmTr::inspect_frame_run` right after `process_next_action` returns the init. + Nothing a consumer can observe happens between the two positions. + - Where it makes the transaction's first frame: `Handler::execution` and `InspectorHandler::inspect_execution`. + - In the default `Handler::runtime_oog_result`, for the stand-in result of a transaction whose EIP-2780 runtime phase ran out of gas. + + It opens before `EvmTr::frame_init` on the plain path and before `InspectorEvmTr::inspect_frame_init` on the inspected one, and so before an inspector's `frame_start`, `call` and `create`: an answer made in any of them, an inspector's or a consumer's own, settles on a start that is already open. + An action an inspector drops or replaces in `step_end` is replaced before revm consumes it, so a start it dropped was never opened, and a clone of the input opens its own. + A frame init revm answers without running a frame (a precompile, a start it refuses) opens a start and settles it like any other. + + *Where revm settles one.* + - `Evm::frame_return_result`, after `return_result` applied revm's own settlement, closes the returning child's start, held in the slot of the caller on top of the stack (the caller's own start stays open), and calls `frame_settle` with the caller's tracker. + - `Handler::last_frame_result`, after `settle_first_frame`, closes the transaction's start and calls `frame_settle` with the transaction's tracker, and after a halt revm consumes the hook's net credit of regular gas and keeps the gas its own settlement left. + + `frame_split` is handed the start's `id`, a per-transaction number revm allocates from 1 with a checked add and never reuses within the transaction; the `parent` identity, the start of the frame that makes this one, `None` for the transaction's frame; the `depth`, read from revm's frame record and never from `interpreter.input`, which an inspector can write; and nothing else: a start's kind, caller, target, value and forward are the frame's own input. + Whether the consumer's `frame_init` is handed that input after the split is conditional: when initialisation reaches it, it receives the input as an inspector's `frame_start`, `call` or `create` left it; an inspector that answers the start does so before `frame_init` is called, and the stand-in for a runtime out-of-gas transaction has no init at all, so a start can split and settle with no `frame_init` between. + What a consumer charges or keeps for an instruction's start it does at `frame_starting`, before the split; the transaction's start does not pass through `frame_starting`. + `frame_settle` is handed the same `id` and `depth` back, and the `status` (`Ok`, `Revert` or `Halt`), `created` (for a creation, whether it took an address), the three flags (below) and `held_reservoir`, the reservoir the caller held before revm settled the child into it. + + *The reservoir.* revm forwards and settles the reservoir as upstream does: the child's input copies the caller's reservoir, or carries the reservoir the frame-start hook named (`FrameStart::reservoir`), and the settlement replaces the caller's reservoir with the one the child returns, once that has unwound the caller's outstanding spill, or as it is when give-backs go to the reservoir alone. + A consumer that keeps part of the caller's reservoir for it takes that part in `frame_starting` and names the rest as the child's, and adds `held_reservoir` back to the caller's reservoir in `frame_settle`. + The caller then holds what the child returned on top of the part it kept, whatever refills the settlement made, since the unwinding and every refill read the spill and their own amount, never the reservoir. + The transaction's frame, and the stand-in for a runtime out-of-gas transaction, are handed a copy of the transaction's reservoir, which the transaction's gas keeps until the settlement replaces it, so there `held_reservoir` is that copy: a consumer adds back only what it kept. + `frame_lifecycle_end` is called once at the end of a transaction's lifecycle: `Settled` at the successful boundary, with every start settled, and `Discarded` when a fatal error ends the transaction and the open starts are dropped unsettled. + A transaction that ends before any start opened emits neither. + + *The record* is revm's `FrameStack`, which no inspector callback is handed: a per-transaction counter of identities, a slot for the transaction's start and one slot per frame on the stack for the start of the child that frame is making, at most one. + A child's parent is the start in the slot of the frame under it, and its depth is one more than its caller's. + Both boundaries reset it. + + *The lifecycle helpers.* A handler or an EVM type that replaces a method revm opens or settles in calls the helper that method calls: + + | It overrides or reimplements | It calls | + |---|---| + | `Handler::execution` or `InspectorHandler::inspect_execution` | `open_frame_start` where it makes the first frame's init | + | `Handler::runtime_oog_result`, building its own stand-in | `open_transaction_start` before it returns | + | `EvmTr::frame_run` or `InspectorEvmTr::inspect_frame_run` | `open_frame_start` after `process_next_action` returns an init | + | `EvmTr::frame_return_result` | `lifecycle::Returning::new(&result, caller)` before `return_result` consumes the result, then `lifecycle::close_frame_start` after it | + | `Handler::last_frame_result` | `close_transaction_start` right after `settle_first_frame`, given the reservoir the caller's gas held before the settlement | + | `Handler::execution_result` | `finish_transaction`, after the context's recorded error is taken and before the output is built | + | `Handler::catch_error` | `discard_transaction`, first | + + `finish_transaction` is the successful boundary (`FrameStack::settle_lifecycle`): with every start settled it emits `LifecycleEnd::Settled` and resets the record. + `discard_transaction` is the fatal boundary (`FrameStack::discard_lifecycle`): it emits `Discarded` only if a lifecycle is under way, resets the record, and is idempotent, so a cleanup that runs twice emits once. It resets the lifecycle only; the frame stack is cleared separately (see Reuse after an uncaught error). + `close_frame_start` and `close_transaction_start` hand the settlement to `frame_settle` with the caller's tracker and the transaction's, and `close_transaction_start` applies the halt rule after the hook: it consumes only the hook's net regular-gas credit, and a hook that credits nothing or debits leaves the gas as it is. + A call sits where the mainnet method makes it and passes what that method passes. + + *Fatal errors.* The record refuses these in every build, debug and release alike, as a `ContextError::Custom` carrying the error's `Display`, which fails the transaction and which `catch_error` reports: + - `Stale`: a start opened where one is still open, so a boundary or a settlement was missed; + - `NoParent`: a child start under a frame with no start of its own, so a runner drove the transaction's frame without opening its start; + - `NotOpen`: a settlement found no start open; + - `Exhausted`: the transaction opened 4,294,967,295 starts; the start does not open; + - `Unsettled`: `finish_transaction` found a start open. It discards the lifecycle, emits `Discarded` and fails the transaction, so the `catch_error` that reports the error owes no second end. + + The only `debug_assert!`s are on the helpers' own preconditions: the transaction's start opens and closes on an empty frame stack. + + *The marks and the flags.* Before it calls an inspector's end callbacks (`call_end`, `create_end`, `frame_end`) revm writes the start's identity on the result's tracker (`StartMark`, a `u32`, with `GasTracker::set_start_mark`) and a mark of the start on the outcome (`OutcomeMark`, a `u16`, `(id − 1) mod 65535 + 1`, never zero) (`mark_for_end_callbacks`); after them it reads both (`check_end_callbacks`). A consumer has no reason to set a mark. + `gas_replaced` is set on the start when the tracker's mark is no longer the start's, `outcome_rebuilt` when the outcome's is not, and `inspector_answer` when `frame_start`, `call` or `create` answered the start. + A constructor (`Gas::new`, `CallOutcome::new`, `CreateOutcome::new`) and a literal that names the mark as `Default::default()` leave it zero, so a value built afresh is always seen; a copy of another start's value is seen unless the two identities are a multiple of 65,535 apart, and a copy made in the previous transaction at the same sequence position is not. + A tracker an inspector saved before the marking carries none, so restoring it at an end callback sets `gas_replaced` even when it came from the same start. + The flags say what an inspector did, never what the consumer did: the consumer's own answers are made in `frame_init`, before any end callback, and are never flagged. + Only the inspected path marks and flags; the plain path leaves all three clear. + Both marks take no part in equality, hashing, `Debug` or serde: they compare equal always, hash to nothing, are skipped by serde and decode as none, and `GasTracker`, `CallOutcome` and `CreateOutcome` have a hand-written `Debug` that lists the other fields in declaration order, so its output is the derived output without the mark, and `GasTracker`'s encoding has no mark. + A change to a field of those three types changes that `Debug` too. + An inspector can forge a mark or call a hook by hand through the `&mut` context: a forged mark changes only the flags, and a hand call desynchronises the consumer's own stack from the record without touching the record or its checks; both are outside the contract. + + *Reuse after an uncaught error.* `Handler::run_without_catch_error` skips the cleanup `catch_error` does. + A caller that drops its error must do all of it before it reuses the EVM: `discard_transaction`, clearing the local context, discarding the journal (`discard_tx`) and clearing the frame stack. + A frame stack left as the error left it makes the next transaction's opening a child under a frame whose start was discarded, and it fails with `NoParent`; a record left open fails the next opening with `Stale`. + Calling `catch_error` does all of it. + + *A hand-driven first frame.* A runner that makes and runs the transaction's first frame itself, or settles one it made, opens the transaction's start first (`open_frame_start` with the frame's init, or `open_transaction_start` for a frame it never initialises), then closes it with `last_frame_result` or `close_transaction_start`, and ends the lifecycle with `execution_result` or `finish_transaction`. + Without the open, its first child fails with `NoParent` and a direct settlement with `NotOpen`. + A test that settles a first frame by hand does the same. + + *The debug mirror.* A debug build keeps, in `LocalContext`, a `LifecycleMirror` of the hooks' order that `Context`'s own hooks feed and that panics when an event does not fit: a root split is at depth 0, a child's parent is the identity on top and its depth one more, a settle pops its own identity and depth, and `Settled` finds the mirror empty. It holds the events as `LifecycleEvent`s (`events()`) and the open starts (`open()`). + The type and `LocalContextTr::lifecycle_mirror` exist in every profile, and a consumer's own ledger can be a `LifecycleMirror`; only `LocalContext`'s field and `Context`'s three hook overrides are debug-only, and a release build holds no mirror and calls none. + It runs only where a local context returns it from `lifecycle_mirror` (the default returns `None`), and it resets at every root split, so a simulation on a cloned context or an independent EVM nested in an inspector callback checks itself from its own root. + A consumer's own ledger follows the same rule: it is initialised at the root split, not at construction or at clone time, and dropped at either end. + A context type that wraps `Context` and implements `Host` itself forwards the three hooks to the inner context, or the mirror never runs; the record and its checks run either way. +- **Consumer.** A consumer that keeps per-start accounting keeps an entry for each start on a stack of its own, drives it only by `frame_split` and `frame_settle`, and ends it at `frame_lifecycle_end`; it does not pair a start with its settlement itself. + A consumer that pairs them from the frames it sees breaks when an inspector replaces an interpreter, rewrites an input's depth or drops an action. + The flags are what such a consumer needs of an inspector's answers, rewrites and rebuilds to settle them as it would without the inspector. + The lifecycle carries no MegaETH figure; what a start's entry holds is the consumer's. +- **Removal.** When upstream exposes an equivalent pairing of a frame's start with its settlement, or when mega-evm keeps no accounting per start. +- **Default.** The hooks do nothing and are inlined away, the flags are set on the inspected path and read by no one, and every result and every callback is upstream's. + What a consumer that sets nothing pays is revm's own record and the marks, in bytes: the record adds 40 bytes to `FrameStack`, which grows from 40 to 80 bytes per EVM, and a slot of 8 bytes (`PendingStart`) on the heap and reused: the slots are sized with the frame stack's capacity (for zero-sized frames, one per frame that made a child), grown when a child first opens past them and never shrunk: a boundary neither resizes nor frees the slots, a successful end does not scan them, and discarding open children clears the retained slots, at a cost proportional to their retained length. + The marks sit in the padding of the values they ride on, so they add nothing to `GasTracker`, `Gas`, `InterpreterResult`, `CallOutcome`, `FrameResult` and `CreateOutcome` (96, 112, 152, 216, 216 and 200 bytes on 64-bit targets with the give-back record), and a release build's `LocalContext` stays 32 bytes; a debug build's is larger for the mirror. + In instructions, a start costs a checked increment, a slot write and a parent read, a settlement a slot take, a transaction one reset at each boundary (and, after a discard with open children, one clear of the retained slots), and an inspected frame's end two stores and two compares; the cost per frame, in instructions, is measured separately and not given here. + Where measured, the three hooks leave no symbol in an unstripped optimised build; what the loop gains is a call to `FrameStack::open_start`. + `Host`, `LocalContextTr` and `FrameStack` gain only default methods and private fields, and `revm_handler` a module, so they break no code written for upstream's. + Three exceptions to that compatibility are carried, each an `api:exception` item. + A pull request that introduces such an exception lists it and checks the consumers against it. + What a consumer does for each: + - The outcomes' public `start_mark` field (`CallOutcome` and `CreateOutcome`): a consumer that builds an outcome by literal names it as `start_mark: Default::default()`, or builds it with the constructors. It extends the exception the outcome literals already carry for the state-gas refund's address (see State-gas price). + - `LocalContext` gains a private field in a debug build, so a debug build cannot build it with a struct literal; a consumer builds it with `LocalContext::default()` or `new`. A release build's is unchanged. + - A behaviour change no compiler finds: a runner that drives the transaction's frame, or settles it, without `Handler::execution` and `Handler::last_frame_result` must open and close the transaction's start (see A hand-driven first frame); otherwise the record refuses it with `NoParent` or `NotOpen`. + +### The original account info by reference + +- **API.** `revm_state::Account::original_info_ref(&self) -> &AccountInfo`. +- **Contract.** It returns what `Account::original_info` returns, by reference, cloning nothing: the info the account holds as its original, or the default info for an account whose original was never set. +- **Consumer.** mega-evm tells whether a transaction changed an account by comparing the account's info with its original, for every frame start, value transfer and destruction it counts. `original_info` returns a copy, and copying the info's code moves the code's reference count up and down; the original is a private field, so only the crate can lend it. +- **Removal.** When upstream has an equivalent accessor, or when mega-evm stops comparing an account with its original. +- **Default.** Nothing in this workspace calls it, so every result is upstream's. The default info it lends an account without an original is built on the first such read and kept for the process. + ## Baseline behaviour the fork changes Picked upstream fixes change revm 40.0.3's results where 40.0.3 was wrong; that is why they are taken (see Tracking upstream), and each pick's pull request says what it changes. +Once a consumer spec that runs on the fork is sealed, a pick that changes a result it can reach lands behind a switch that keeps the sealed result, or is not taken (see Tracking upstream). A pick that changes what the journal records lands with a switch back to the base line (see revm 40.0.3's journal semantics). -One pick changes what the top-level entry points do with the journal, and has no switch: +One pick changes what the top-level entry points do with the journal, and has no switch. +The pending-action check changes what an inspector that sets an action before a frame runs sees and gets, and has no switch either: - **The journal is finalized on an error.** `ExecuteCommitEvm::transact_commit`, `ExecuteEvm::replay`, `InspectEvm::inspect_tx` and `inspect`, `InspectCommitEvm::inspect_tx_commit` and `inspect_commit`, and the four `inspect_system_call` variants clear the journal when execution returns an error. revm 40.0.3 left it holding the failed transaction's warm set and touched accounts, which leaked into the next transaction run on the same EVM. Upstream #3780, carried verbatim with the EIP-8037 / EIP-2780 gas core. There is no switch: a consumer that must keep the journal after an error uses the entry points that do not finalize (`transact_one`, `inspect_one_tx`, `system_call_one`) and finalizes itself. +- **An action an inspector sets in `initialize_interp` is returned without a `step`.** The inspected run returns an action pending when it starts before its first `Inspector::step` (see The pending action). + Only an inspector that sets an action before a frame runs, by halting the frame or setting its next action in `initialize_interp`, is affected: it loses that run's first `step`, and with it whatever that `step` would have done. + revm 40.0.3 called `step` once first, at the frame's first instruction, and then returned the action as that `step` left it, without running the instruction. + An inspector whose `step` only observes sees one `step` fewer and gets the same result, since no instruction runs on either. + An inspector whose `step` edits the pending action (`LoopControl::action`), or changes the context or the state, gets a different result: the frame returns the action `initialize_interp` set, and the `step`'s changes are not made. ## Tracking upstream The fork keeps its crate versions at the revm version the MegaETH node pins, today `40.0.3`; a newer upstream tag would bump every crate's major, so the fork takes single upstream commits until the node moves. Taken: changes to the EIP-8037 / EIP-2780 gas core whatever their prefix; fixes that change execution results (gas, state, logs, halt reasons, precompile output, bytecode analysis, serialized formats); correctness and safety fixes relevant to the consumers, including undefined behaviour, missing out-of-gas checks, panics, and dependency or build failures; performance improvements to execution, precompiles and the database; each with the test-fixture bump that comes with it. +A change that moves an execution result is taken this way only until the consumer spec that runs on the fork is sealed; after that it follows the sealed-spec rule below, whatever its kind. Not taken: tooling-only changes, feature-gated additions the consumers do not use, and change/revert pairs, after checking that no taken commit depends on them. Picks are batched by crate or subsystem, one pull request per batch, so one reviewer can read a whole batch. The fork has no benchmark gate: a performance pick must leave execution results unchanged under the crate tests and the EEST run, and cite upstream's benchmark numbers in the pull request body. @@ -227,7 +507,17 @@ A pick that touches a precompile is tested under mutually exclusive feature sets A pick that breaks the public API needs `api:exception`, the deviating items listed in the pull request body, and a check of every consumer that uses them. An upstream change that upstream later reverted but the fork still needs lands as a fork-owned opt-in switch (`mega:hook`) whose default keeps upstream's behaviour. A picked upstream fix that changes journal semantics lands with an opt-in switch back to the base line's behaviour when a consumer reproduces the base line exactly; the switch defaults to the picked behaviour, the consumer that needs the base line sets it, and nothing else reads it. `CfgEnv::legacy_journal_semantics` (the cold-slot re-baseline and the `CodeChange` revert of revm 40.0.3) is the first. + +**Sealed specs.** Once a consumer spec that runs on the fork is sealed, the fork must not move that spec's results. +A pick that changes an execution result the sealed spec can reach then lands behind a switch, or is not taken. +The switch follows the `legacy_journal_semantics` pattern: it keeps the result the spec was sealed with, its default is the picked behaviour, which is upstream's, and the consumer turns it on for each sealed spec, so a later spec can take the fix by leaving it off. +A pick that cannot be put behind such a switch is not taken while a sealed spec runs on the fork, and its sweep records why. +A pick that changes only results no sealed spec reaches, such as a fix to a feature the sealed specs leave off, lands without a switch, and its pull request says why no sealed spec reaches it. +A pick lands without a switch only with both of these in its pull request: a code-based argument that names the behaviour the pick changes and shows that no sealed spec reaches it, and targeted regression tests for that behaviour. +The consumer's outcome check on each sealed spec, run against the pick, is supporting evidence and is recorded too; a fixture corpus shows only the cases it reaches, so passing it does not define the pick as safe. + Every pick is applied verbatim: `git show -U0 | git patch-id --verbatim` gives the same id for the pick and its upstream commit unless the pick's message records a conflict resolution; the pull request body, which becomes the squash message, lists each pick's `(cherry picked from commit )` line and its conflicts. +A pick that lands behind a switch keeps the verbatim pick as its own branch commit, followed by the switch in a commit of its own, and the squash message records the switch as the pick's conflict resolution. For every upstream tag, a maintainer sweeps `..` across the whole repository, fixtures, manifests and lockfile included, and records each commit as taken, candidate (with an owner and a disposition) or excluded (with the reason), with both tag SHAs, in the issue titled `Sweep ` that the nightly workflow opens when the tag appears. The pull request that carries the picks links that issue; a sweep that takes nothing is closed with its classification in the issue. @@ -245,7 +535,7 @@ Every pull request carries exactly one `mega:` label and one `api:` label; the ` | Label | Meaning | |---|---| | `mega:cherry-pick` | Upstream commits brought into the fork unchanged apart from recorded conflicts | -| `mega:hook` | A hook or data field added in the thin layer | +| `mega:hook` | A hook, data field or switch, or an item of rule 2's MegaETH accounting | | `mega:vendor` | A vendored crate (`crates/op-revm`) added or updated | | `mega:ci` | Workflows, `scripts/mega`, the fork documents | | `mega:rebase` | The base line moves to a new upstream tag | diff --git a/REVIEW.md b/REVIEW.md index 37bd3d8fa4..9ba1400776 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -9,8 +9,9 @@ It is read by the automated reviewer as well as by people. 1. **Superset.** The public API of every published crate stays a superset of the crates.io baseline recorded in `scripts/mega/crates.txt`. The `Semver` workflow checks API changes against the pull request base; reviewers check baseline compatibility and the documented exceptions. A PR that must break the superset carries the `api:exception` label and lists in its body every deviating item with the consumers it was checked against (`reth`, `alloy-evm`, `revm-inspectors`, the `op-revm` fork). -2. **Thin layer.** The fork adds hooks and data, never MegaETH semantics. +2. **Hooks and data, and rule 2's set.** The fork adds hooks and data, and no MegaETH semantics beyond the bounded set of accounting `MEGAETH-FORK.md` rule 2 names. If a change makes a design decision (a price, a limit, a policy), ask for it to move to `mega-evm` and for the fork to expose only the hook it needs. + A change that adds to rule 2's set must argue every condition rule 2 lists, the first above all: why a hook on the state revm exposes cannot make the same decision. 3. **`no_std`.** No unguarded `std::`, no new dependency that enables `std` by default, no allocation in a path that did not allocate before. The CI checks both riscv targets; the reviewer checks the intent. 4. **One topic per PR, conventional prefix on every fork-authored commit.** Fork-authored commits and PR titles start with `feat`, `fix`, `chore`, `docs`, `ci` or `test` and say what changed; cherry-picked commits keep upstream's subject (`MEGAETH-FORK.md` rule 4); `git log --oneline ..main` (`` from `scripts/mega/base.txt`) is the fork's changelog and must stay readable. @@ -20,8 +21,8 @@ It is read by the automated reviewer as well as by people. | Label | Look for | |---|---| -| `mega:cherry-pick` | The title names the upstream commit (`chore: cherry-pick upstream — `) or, for a batch, the upstream pull requests (`chore: cherry-pick upstream fixes #a #b …`); branch commits keep upstream's subject; a batch stays within one crate or subsystem; a precompile pick reports its tests under mutually exclusive feature sets (the `std`-only fallback run, the default set, all features, and the backend feature it changes); the body links the `Sweep <tag>` issue, lists the `-x` trailers and, for a performance pick, cites the upstream benchmark reference; the diff equals the upstream diff apart from conflicts the message records; nothing MegaETH-specific rides along | -| `mega:hook` | New logic in new files where practical; upstream files get a `mod` line or a call site; a default implementation keeps existing behaviour byte for byte; a new serialized field carries `serde(default)` so payloads that predate it still decode | +| `mega:cherry-pick` | The title names the upstream commit (`chore: cherry-pick upstream <sha> — <title>`) or, for a batch, the upstream pull requests (`chore: cherry-pick upstream fixes #a #b …`); branch commits keep upstream's subject; a batch stays within one crate or subsystem; a precompile pick reports its tests under mutually exclusive feature sets (the `std`-only fallback run, the default set, all features, and the backend feature it changes); the body links the `Sweep <tag>` issue, lists the `-x` trailers and, for a performance pick, cites the upstream benchmark reference; the diff equals the upstream diff apart from conflicts the message records; nothing MegaETH-specific rides along; once a consumer spec is sealed, a pick that moves a result that spec reaches carries the switch that keeps it, or is not taken, and a pick without a switch carries a code-based argument that no sealed spec reaches the changed behaviour, with targeted regression tests (the consumer's outcome check is supporting evidence) (`MEGAETH-FORK.md`, Tracking upstream) | +| `mega:hook` | New logic in new files where practical; upstream files get a `mod` line or a call site; a default implementation keeps existing behaviour byte for byte; a new serialized field carries `serde(default)`, so that in a format that carries field names (JSON) payloads that predate it decode with the default; a positional format (bincode) cannot read them whatever the attribute, as `MEGAETH-FORK.md` (Hooks) says | | `mega:vendor` | The vendored crate keeps its upstream version number and a note of the upstream commit it was taken from; its own tests run in CI | | `mega:ci` | Workflows pin action SHAs; nothing requires a secret the repository does not have; the local equivalent of every job is documented | | `mega:rebase` | `scripts/mega/base.txt`, `scripts/mega/crates.txt`, `rust-toolchain.toml` and the baseline table move together; the upstream tag comes in as a merge commit, not a rebase; the merged tree is compared with the new tag and carried picks reconciled; the PR carries `api:exception` for upstream's own API changes | diff --git a/crates/context/interface/src/cfg.rs b/crates/context/interface/src/cfg.rs index 9c9effe5e6..dd2ac171d2 100644 --- a/crates/context/interface/src/cfg.rs +++ b/crates/context/interface/src/cfg.rs @@ -124,6 +124,14 @@ pub trait Cfg { fn legacy_journal_semantics(&self) -> bool { false } + + /// Returns whether every give-back of state or history gas credits the reservoir alone + /// (`GasTracker::reservoir_only_give_backs`), which revm sets on the transaction's gas and on + /// every frame's. Default is `false`, EIP-8037's tracker. + #[inline] + fn reservoir_only_give_backs(&self) -> bool { + false + } } /// What bytecode analysis to perform @@ -264,5 +272,6 @@ mod tests { let cfg = RequiredOnly(GasParams::default()); assert!(!cfg.legacy_journal_semantics()); assert!(!cfg.enable_amsterdam_eip7708()); + assert!(!cfg.reservoir_only_give_backs()); } } diff --git a/crates/context/interface/src/cfg/gas.rs b/crates/context/interface/src/cfg/gas.rs index 8582e8ae8a..c99ee931ea 100644 --- a/crates/context/interface/src/cfg/gas.rs +++ b/crates/context/interface/src/cfg/gas.rs @@ -3,9 +3,14 @@ use crate::{cfg::gas_params, cfg::GasParams, Transaction}; use primitives::hardfork::SpecId; +#[cfg(feature = "serde")] +mod encoding; mod failed_charge; +mod give_backs; +mod mark; mod withheld; +pub use mark::{OutcomeMark, StartMark}; pub use withheld::WithheldCrossing; /// Tracker for gas during execution. @@ -38,7 +43,8 @@ pub use withheld::WithheldCrossing; /// of them lands inside a frame rather than at a frame boundary: `SSTORE`'s refill when it /// restores a slot to its original zero (0→x→0). A consumer that holds the spendable part at an /// allowance limits it at a frame's start and again after each credit: when a child returns, and -/// after `SSTORE`. +/// after `SSTORE`. With [`reservoir_only_give_backs`](Self::reservoir_only_give_backs) set only the +/// first of them credits regular gas. /// /// Releasing the withheld part ([`release_withheld`](Self::release_withheld)) is not needed to /// conserve gas: the gas a child returns is its [`remaining`](Self::remaining), withheld part @@ -55,8 +61,37 @@ pub use withheld::WithheldCrossing; /// checks it. Above it, a rollback no longer restores the reservoir exactly and can burn or mint /// gas at the boundary. Reaching it takes a transaction gas limit above `i64::MAX` /// (about 9.2 × 10^18). -#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] -#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +/// +/// With [`reservoir_only_give_backs`](Self::reservoir_only_give_backs) set, which is off by +/// default, no give-back of state or history gas credits regular gas: a refill, the rollback of a +/// failed frame and a reservoir a child returns all land in the reservoir, so `remaining` rises +/// only by the regular gas a child returns. `state_gas_spilled` then counts every part of a state +/// or history charge that regular gas paid, and no give-back lowers it; a halt reads it to give the +/// frame back the reservoir it received. +/// +/// A state charge can take a legacy share from regular gas before it draws the reservoir +/// ([`record_state_cost_with_legacy_share`](Self::record_state_cost_with_legacy_share)); a share of +/// zero, the default schedule's for every charge, is [`record_state_cost`](Self::record_state_cost). +/// +/// Encoded, the tracker has a field per figure, in the order below; the failed-charge record, +/// a number and a flag in memory, is encoded as an optional number in its place. +/// +/// A field the fork added decodes with its default from an encoding made before it existed only +/// in a format that carries field names, such as JSON, as each field says. A format that encodes +/// a struct by position, such as bincode, cannot read an encoding made before a field was added, +/// as with upstream's own field additions: it reads the old fields in their places and then +/// looks for the new ones, so a tracker persisted in such a format must not cross an upgrade of +/// this crate that adds a field. +/// +/// The tracker also carries the [`StartMark`] revm writes on a frame result's tracker before an +/// inspector's end callbacks. The mark is no part of the tracker's value: equality, hashing, the +/// debug output and the encoding leave it out, and a decoded tracker carries none. +#[derive(Clone, Copy, Default, PartialEq, Eq, Hash)] +#[cfg_attr( + feature = "serde", + derive(serde::Serialize, serde::Deserialize), + serde(from = "encoding::Encoded", into = "encoding::Encoded") +)] pub struct GasTracker { /// Gas Limit, gas_limit: u64, @@ -86,6 +121,13 @@ pub struct GasTracker { /// halt) the spilled portion is credited back to `remaining` in last-in- /// first-out order by [`Self::rollback_state_gas`]; on success it is /// propagated to the parent frame so a later parent rollback can return it. + /// + /// With [`reservoir_only_give_backs`](Self::reservoir_only_give_backs) set it is the state and + /// history gas regular gas paid in this frame and in every frame below it that returned to + /// it, a legacy share included: no give-back lowers it, and a child adds its own to its + /// caller's however it ends. A halt takes the part of it no halt below consumed yet out of the + /// reservoir ([`consume_regular_paid_charges`](Self::consume_regular_paid_charges), + /// [`halted_regular_paid`](Self::halted_regular_paid)). state_gas_spilled: u64, /// Net history gas spent so far. /// @@ -105,8 +147,8 @@ pub struct GasTracker { /// `code_deposit_history_gas` a price, so a chain that does not price history bytes behaves /// exactly as it did before this field existed. /// - /// Encodings made before this field existed decode it as zero. - #[cfg_attr(feature = "serde", serde(default))] + /// In a format that carries field names, such as JSON, encodings made before this field existed + /// decode it as zero. history_gas_spent: i64, /// Refunded gas. Used to refund the gas to the caller at the end of execution. refunded: i64, @@ -117,8 +159,8 @@ pub struct GasTracker { /// but never by a regular charge. Zero unless a consumer withholds gas; while it is zero, every /// method behaves as it did before this field existed. /// - /// Encodings made before this field existed decode it as zero. - #[cfg_attr(feature = "serde", serde(default))] + /// In a format that carries field names, such as JSON, encodings made before this field existed + /// decode it as zero. withheld: u64, /// The record of the last failed regular charge the withheld part would have paid /// ([`withheld_crossing`](Self::withheld_crossing)): the regular gas left before that @@ -131,14 +173,58 @@ pub struct GasTracker { /// position, such as bincode, cannot tell the two records apart and reads the old one as the /// regular gas left, so a record persisted in such a format must not cross an upgrade of this /// crate. - #[cfg_attr(feature = "serde", serde(default))] withheld_crossing: Option<WithheldCrossing>, /// The regular gas left, spendable and withheld parts together, before the last charge that - /// failed ([`failed_charge_remaining`](Self::failed_charge_remaining)). + /// failed ([`failed_charge_remaining`](Self::failed_charge_remaining)), if + /// `failed_charge_recorded` is set, and zero otherwise. + /// + /// In a format that carries field names, such as JSON, encodings made before this field existed + /// decode it as `None`. + failed_charge_remaining: u64, + /// Whether `failed_charge_remaining` holds a record. A flag apart from the record rather than + /// an `Option`, whose tag would take a word of its own, so it shares a word with + /// `start_mark`. + failed_charge_recorded: bool, + /// Whether every give-back of state or history gas credits the reservoir alone + /// ([`reservoir_only_give_backs`](Self::reservoir_only_give_backs)). A flag that shares the word + /// of `failed_charge_recorded` and `start_mark`, so the tracker's size is unchanged. /// - /// Encodings made before this field existed decode it as `None`. - #[cfg_attr(feature = "serde", serde(default))] - failed_charge_remaining: Option<u64>, + /// In a format that carries field names, such as JSON, encodings made before this field existed + /// decode it as `false`. + reservoir_only_give_backs: bool, + /// With [`reservoir_only_give_backs`](Self::reservoir_only_give_backs) set, the part of + /// `state_gas_spilled` that halts already consumed: what frames below this one that halted, or + /// that returned to it from frames that halted below them, paid of state and history gas from + /// regular gas ([`halted_regular_paid`](Self::halted_regular_paid)). Zero with it off. + /// + /// In a format that carries field names, such as JSON, encodings made before this field existed + /// decode it as zero. + halted_regular_paid: u64, + /// The start revm marked this tracker for ([`start_mark`](Self::start_mark)). It fits padding + /// the tracker already had, in the word `failed_charge_recorded` takes, so the tracker's size + /// is unchanged. No part of the tracker's value, and not encoded. + start_mark: StartMark, +} + +impl core::fmt::Debug for GasTracker { + /// The output the derive gives the tracker's figures, in their order; the mark is left out. + fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { + f.debug_struct("GasTracker") + .field("gas_limit", &self.gas_limit) + .field("remaining", &self.remaining) + .field("reservoir", &self.reservoir) + .field("state_gas_spent", &self.state_gas_spent) + .field("state_gas_spilled", &self.state_gas_spilled) + .field("history_gas_spent", &self.history_gas_spent) + .field("refunded", &self.refunded) + .field("withheld", &self.withheld) + .field("withheld_crossing", &self.withheld_crossing) + .field("failed_charge_remaining", &self.failed_charge_remaining) + .field("failed_charge_recorded", &self.failed_charge_recorded) + .field("reservoir_only_give_backs", &self.reservoir_only_give_backs) + .field("halted_regular_paid", &self.halted_regular_paid) + .finish() + } } impl GasTracker { @@ -155,10 +241,28 @@ impl GasTracker { refunded: 0, withheld: 0, withheld_crossing: None, - failed_charge_remaining: None, + failed_charge_remaining: 0, + failed_charge_recorded: false, + reservoir_only_give_backs: false, + halted_regular_paid: 0, + start_mark: StartMark::NONE, } } + /// The start revm marked this tracker for before an inspector's end callbacks, or + /// [`StartMark::NONE`]. + #[inline] + pub const fn start_mark(&self) -> StartMark { + self.start_mark + } + + /// Marks this tracker for a start. revm marks a start's result before an inspector's end + /// callbacks and reads the mark after them; a consumer has no reason to set it. + #[inline] + pub const fn set_start_mark(&mut self, mark: StartMark) { + self.start_mark = mark; + } + /// Creates a new `GasTracker` with the given used gas and reservoir. /// Remaining gas saturates at zero when used gas exceeds the gas limit. #[inline] @@ -232,8 +336,16 @@ impl GasTracker { /// This only reconciles the funding pools. The child's signed /// `state_gas_spent` has already accounted for the refill and is merged /// separately by the frame handler. + /// + /// With [`reservoir_only_give_backs`](Self::reservoir_only_give_backs) set nothing is + /// unwound: the returned reservoir becomes this frame's reservoir as it is, and regular gas is + /// left as it was. #[inline] pub const fn absorb_returned_reservoir(&mut self, reservoir: u64) { + if self.reservoir_only_give_backs { + self.reservoir = reservoir; + return; + } let to_remaining = if reservoir < self.state_gas_spilled { reservoir } else { @@ -415,8 +527,18 @@ impl GasTracker { /// last-in-first-out order: `remaining` is credited up to `state_gas_spilled`, the rest tops up /// the reservoir, and the net history gas falls by the full `amount` — below zero when the /// matching charge was made by a parent frame, which the merge on return reconciles. + /// + /// With [`reservoir_only_give_backs`](Self::reservoir_only_give_backs) set the whole `amount` + /// tops up the reservoir, and `remaining` and `state_gas_spilled` are left as they were. #[inline] pub const fn refill_history(&mut self, amount: u64) { + if self.reservoir_only_give_backs { + self.reservoir = self.reservoir.saturating_add(amount); + self.history_gas_spent = self + .history_gas_spent + .saturating_sub(saturating_signed(amount)); + return; + } let to_remaining = if amount < self.state_gas_spilled { amount } else { @@ -447,12 +569,26 @@ impl GasTracker { /// On revert the resulting `remaining` (including the refilled spill) is /// returned to the parent; on halt the caller additionally zeroes `remaining` /// so the spilled gas is consumed while the reservoir is left untouched. + /// + /// With [`reservoir_only_give_backs`](Self::reservoir_only_give_backs) set every charge the + /// frame made, net of the give-backs it received, goes into the reservoir, whichever pool + /// paid it: the reservoir becomes `reservoir + state_gas_spent + history_gas_spent`, and + /// `remaining` and `state_gas_spilled` are left as they were. That is a reverted frame's + /// reservoir; a halting frame's caller then consumes the part regular gas paid + /// ([`consume_regular_paid_charges`](Self::consume_regular_paid_charges)), which leaves the + /// reservoir the frame received. #[inline] pub const fn rollback_state_gas(&mut self) { // The two nets are summed before they meet the reservoir: a frame that took back a parent's // state charge after its own history charge spilled holds less reservoir than its state // net is negative, and adding the terms one at a time would clamp at zero part-way. let charged = self.state_gas_spent.saturating_add(self.history_gas_spent); + if self.reservoir_only_give_backs { + self.reservoir = self.reservoir.saturating_add_signed(charged); + self.state_gas_spent = 0; + self.history_gas_spent = 0; + return; + } self.reservoir = self .reservoir .saturating_add_signed(charged) @@ -480,8 +616,18 @@ impl GasTracker { /// (`remaining`) last, the refill credits the pool charged last first: /// `remaining` is credited up to `state_gas_spilled` and any remainder tops /// up the reservoir. + /// + /// With [`reservoir_only_give_backs`](Self::reservoir_only_give_backs) set the whole `amount` + /// tops up the reservoir, and `remaining` and `state_gas_spilled` are left as they were. #[inline] pub const fn refill_reservoir(&mut self, amount: u64) { + if self.reservoir_only_give_backs { + self.reservoir = self.reservoir.saturating_add(amount); + self.state_gas_spent = self + .state_gas_spent + .saturating_sub(saturating_signed(amount)); + return; + } let to_remaining = if amount < self.state_gas_spilled { amount } else { @@ -681,6 +827,25 @@ mod tests { assert_eq!(parent.reservoir(), 500); } + /// A returned reservoir replaces the caller's, once it has unwound the caller's outstanding + /// spill, last in first out: what the caller held beside it does not stay. + #[test] + fn test_a_returned_reservoir_replaces_the_callers() { + // The caller holds the 1,000 it gave the child, which returns 700 of it. + let mut caller = GasTracker::new(1_000, 1_000, 1_000); + caller.absorb_returned_reservoir(700); + assert_eq!((caller.reservoir(), caller.remaining()), (700, 1_000)); + + // A spill of 150 outstanding (a successful child's, merged before the absorb): the + // returned 100 unwinds 100 of it, and the 20 the caller held goes with the replace. + let mut spilled = GasTracker::new(1_000, 850, 20); + spilled.add_state_gas_spilled(150); + spilled.absorb_returned_reservoir(100); + assert_eq!(spilled.reservoir(), 0); + assert_eq!(spilled.remaining(), 950); + assert_eq!(spilled.state_gas_spilled(), 50); + } + /// Copying the counter through its getter and setter, as `PrecompileOutput` does for state gas, /// keeps a negative net. #[test] diff --git a/crates/context/interface/src/cfg/gas/encoding.rs b/crates/context/interface/src/cfg/gas/encoding.rs new file mode 100644 index 0000000000..8108b7f617 --- /dev/null +++ b/crates/context/interface/src/cfg/gas/encoding.rs @@ -0,0 +1,143 @@ +//! The encoding of a [`GasTracker`]. +//! +//! In memory the failed-charge record is a number and a flag, and the flag shares a word with the +//! tracker's start mark, which is not encoded. Encoded, the tracker keeps the fields, names and +//! order the derived encoding had: the failed-charge record is an optional number in its place. +//! +//! A format that carries field names, such as JSON, decodes an encoding made before a field +//! existed with the field's default. A format that encodes by position, such as bincode, does not +//! (see [`GasTracker`]). + +use super::{GasTracker, WithheldCrossing}; + +/// A [`GasTracker`] as it is encoded: its fields in their order, with the defaults an encoding +/// made before a field existed decodes to in a format that carries field names. Each field of the +/// tracker documents its own. +#[derive(serde::Serialize, serde::Deserialize)] +#[serde(rename = "GasTracker")] +pub(super) struct Encoded { + gas_limit: u64, + remaining: u64, + reservoir: u64, + state_gas_spent: i64, + state_gas_spilled: u64, + #[serde(default)] + history_gas_spent: i64, + refunded: i64, + #[serde(default)] + withheld: u64, + #[serde(default)] + withheld_crossing: Option<WithheldCrossing>, + #[serde(default)] + failed_charge_remaining: Option<u64>, + #[serde(default)] + reservoir_only_give_backs: bool, + #[serde(default)] + halted_regular_paid: u64, +} + +impl From<GasTracker> for Encoded { + fn from(tracker: GasTracker) -> Self { + Self { + gas_limit: tracker.gas_limit, + remaining: tracker.remaining, + reservoir: tracker.reservoir, + state_gas_spent: tracker.state_gas_spent, + state_gas_spilled: tracker.state_gas_spilled, + history_gas_spent: tracker.history_gas_spent, + refunded: tracker.refunded, + withheld: tracker.withheld, + withheld_crossing: tracker.withheld_crossing, + failed_charge_remaining: tracker.failed_charge_remaining(), + reservoir_only_give_backs: tracker.reservoir_only_give_backs, + halted_regular_paid: tracker.halted_regular_paid, + } + } +} + +impl From<Encoded> for GasTracker { + fn from(encoded: Encoded) -> Self { + let mut tracker = Self { + gas_limit: encoded.gas_limit, + remaining: encoded.remaining, + reservoir: encoded.reservoir, + state_gas_spent: encoded.state_gas_spent, + state_gas_spilled: encoded.state_gas_spilled, + history_gas_spent: encoded.history_gas_spent, + refunded: encoded.refunded, + withheld: encoded.withheld, + withheld_crossing: encoded.withheld_crossing, + failed_charge_remaining: 0, + failed_charge_recorded: false, + reservoir_only_give_backs: encoded.reservoir_only_give_backs, + halted_regular_paid: encoded.halted_regular_paid, + start_mark: super::StartMark::NONE, + }; + tracker.set_failed_charge_remaining(encoded.failed_charge_remaining); + tracker + } +} + +#[cfg(test)] +mod tests { + use super::super::GasTracker; + + /// A tracker with every field away from its default: part of its regular gas withheld, a + /// crossing and a failed charge recorded, a state charge spilled past the reservoir, a + /// refund, give-backs that credit the reservoir alone, and a halted child's count. + fn every_field_set() -> GasTracker { + let mut tracker = GasTracker::new(1_000, 400, 300); + tracker.set_reservoir_only_give_backs(true); + let mut halted = GasTracker::new(10, 10, 0); + halted.set_reservoir_only_give_backs(true); + assert!(halted.record_state_cost(4)); + halted.rollback_state_gas(); + halted.consume_regular_paid_charges(); + tracker.add_regular_paid_of(&halted); + tracker.withhold(100); + assert!(!tracker.record_regular_cost(350)); + assert!(tracker.record_state_cost(500)); + tracker.record_refund(-3); + tracker + } + + /// The encoding has the fields, the names and the order the derived encoding gave the + /// tracker's figures, so a format that encodes by position finds every field in its place; the + /// failed-charge record is an optional number. + #[test] + fn test_the_encoding_keeps_its_fields_and_their_order() { + assert_eq!( + serde_json::to_string(&every_field_set()).unwrap(), + concat!( + r#"{"gas_limit":1000,"remaining":200,"reservoir":0,"state_gas_spent":500,"#, + r#""state_gas_spilled":204,"history_gas_spent":0,"refunded":-3,"withheld":0,"#, + r#""withheld_crossing":{"remaining":400},"failed_charge_remaining":400,"#, + r#""reservoir_only_give_backs":true,"halted_regular_paid":4}"#, + ) + ); + assert_eq!( + serde_json::to_string(&GasTracker::new(1_000, 1_000, 0)).unwrap(), + concat!( + r#"{"gas_limit":1000,"remaining":1000,"reservoir":0,"state_gas_spent":0,"#, + r#""state_gas_spilled":0,"history_gas_spent":0,"refunded":0,"withheld":0,"#, + r#""withheld_crossing":null,"failed_charge_remaining":null,"#, + r#""reservoir_only_give_backs":false,"halted_regular_paid":0}"#, + ) + ); + } + + /// Every field round-trips, a failed charge of zero apart from none. + #[test] + fn test_the_encoding_round_trips() { + let mut zero_left = GasTracker::new(1_000, 0, 0); + assert!(!zero_left.record_regular_cost(1)); + for tracker in [every_field_set(), zero_left, GasTracker::default()] { + let encoded = serde_json::to_string(&tracker).unwrap(); + assert_eq!( + serde_json::from_str::<GasTracker>(&encoded).unwrap(), + tracker, + "{encoded}" + ); + } + } +} diff --git a/crates/context/interface/src/cfg/gas/failed_charge.rs b/crates/context/interface/src/cfg/gas/failed_charge.rs index 25a2ae6c3f..5c64f846e6 100644 --- a/crates/context/interface/src/cfg/gas/failed_charge.rs +++ b/crates/context/interface/src/cfg/gas/failed_charge.rs @@ -28,7 +28,9 @@ impl GasTracker { /// /// The interpreter records it too when it halts a frame out of gas with no record there: a /// cold access the instruction refused before its charge, because the frame could not pay it, - /// or an out-of-gas a consumer's instruction returned itself. The handler records it where a + /// an out-of-gas a consumer's instruction returned itself, or one an instruction hook asked + /// for ([`Host::write_completed`](crate::Host::write_completed), + /// [`Host::frame_starting`](crate::Host::frame_starting)). The handler records it where a /// precompile runs out of gas: the frame's whole gas limit, as nothing ran. A consumer that /// builds an out-of-gas result itself can record the same with /// [`set_failed_charge_remaining`](Self::set_failed_charge_remaining). @@ -45,7 +47,11 @@ impl GasTracker { /// record is left on a creation that returns successfully. #[inline] pub const fn failed_charge_remaining(&self) -> Option<u64> { - self.failed_charge_remaining + if self.failed_charge_recorded { + Some(self.failed_charge_remaining) + } else { + None + } } /// Sets the record returned by [`failed_charge_remaining`](Self::failed_charge_remaining), @@ -57,7 +63,20 @@ impl GasTracker { /// failure, the record survives [`spend_all`](Self::spend_all). #[inline] pub const fn set_failed_charge_remaining(&mut self, remaining: Option<u64>) { + match remaining { + Some(remaining) => self.record_failed_charge(remaining), + None => { + self.failed_charge_remaining = 0; + self.failed_charge_recorded = false; + } + } + } + + /// Records `remaining` as the regular gas left before a failed charge. + #[inline] + const fn record_failed_charge(&mut self, remaining: u64) { self.failed_charge_remaining = remaining; + self.failed_charge_recorded = true; } /// Records a failed regular charge of `cost` against `spendable`: the regular gas left, @@ -72,7 +91,7 @@ impl GasTracker { #[inline(never)] pub(super) const fn regular_charge_failed(&mut self, cost: u64, spendable: u64) { let remaining = spendable.saturating_add(self.withheld); - self.failed_charge_remaining = Some(remaining); + self.record_failed_charge(remaining); // `cost > spendable`, so a withheld part that covers the difference is never zero, and // neither is the regular gas left. if cost - spendable <= self.withheld { @@ -92,7 +111,7 @@ impl GasTracker { #[cold] #[inline(never)] pub(super) const fn withheld_first_cost_failed(&mut self) { - self.failed_charge_remaining = Some(self.remaining.saturating_add(self.withheld)); + self.record_failed_charge(self.remaining.saturating_add(self.withheld)); } } @@ -344,11 +363,11 @@ mod tests { assert_eq!(tracker.failed_charge_remaining(), None); } - /// The record round-trips, a zero included, and encodings made before it existed decode with - /// none. + /// The record round-trips, a zero included, and JSON encodings made before it existed decode + /// with none. #[cfg(feature = "serde")] #[test] - fn test_serde_round_trip_and_older_payloads() { + fn test_serde_round_trip_and_older_json_payloads() { for regular in [0, 400] { let mut tracker = GasTracker::new(1_000, regular, 0); fail(&mut tracker, regular + 1, false); diff --git a/crates/context/interface/src/cfg/gas/give_backs.rs b/crates/context/interface/src/cfg/gas/give_backs.rs new file mode 100644 index 0000000000..325900d523 --- /dev/null +++ b/crates/context/interface/src/cfg/gas/give_backs.rs @@ -0,0 +1,376 @@ +//! Give-backs to the reservoir alone, and the legacy share of a state charge. +//! +//! The switch that makes every give-back of state or history gas credit a [`GasTracker`]'s +//! reservoir and never its regular gas, the count of what regular gas paid for state and history +//! and the part of it halts consumed, and the charge that takes a legacy share from regular gas before the +//! reservoir. The tracker's own documentation describes how each give-back is credited with the +//! switch on and off. + +use super::GasTracker; + +impl GasTracker { + /// Whether every give-back of state or history gas credits the reservoir alone. Off by + /// default, which is EIP-8037's tracker. + /// + /// With it on, no give-back credits regular gas, whichever pool paid the charge it gives back: + /// a refill ([`refill_reservoir`](Self::refill_reservoir), + /// [`refill_history`](Self::refill_history)), a failed frame's rollback + /// ([`rollback_state_gas`](Self::rollback_state_gas)) and a reservoir a child returns + /// ([`absorb_returned_reservoir`](Self::absorb_returned_reservoir)) land in the reservoir, so a + /// frame's `remaining` rises within the frame only by the regular gas a child returns. + /// [`state_gas_spilled`](Self::state_gas_spilled) counts what regular gas paid of state and + /// history charges in the frame and in the frames below it that returned to it, however they + /// ended, and no give-back lowers it. A halt consumes the frame's regular gas and the part of + /// its charges regular gas paid, and gives it back the reservoir it received + /// ([`consume_regular_paid_charges`](Self::consume_regular_paid_charges)). + #[inline] + pub const fn reservoir_only_give_backs(&self) -> bool { + self.reservoir_only_give_backs + } + + /// Sets whether every give-back of state or history gas credits the reservoir alone; see + /// [`reservoir_only_give_backs`](Self::reservoir_only_give_backs). revm sets it on the + /// transaction's gas and on every frame's from `Cfg::reservoir_only_give_backs`. + #[inline] + pub const fn set_reservoir_only_give_backs(&mut self, on: bool) { + self.reservoir_only_give_backs = on; + } + + /// Records a state gas cost that takes a legacy share from regular gas before it draws the + /// reservoir. + /// + /// The share is `min(cost, legacy_share)`: it is drawn from `remaining` first, withheld part + /// first ([`record_withheld_first_cost`](Self::record_withheld_first_cost)); the rest of the + /// charge is then paid as [`record_state_cost`](Self::record_state_cost) pays it, from the + /// reservoir and, past it, from `remaining` again. The share and that spill are one deduction + /// from `remaining`, booked on [`state_gas_spilled`](Self::state_gas_spilled), and the whole + /// charge is state gas. + /// + /// Returns `false` if `remaining` cannot pay the share and the spill together, whatever the + /// reservoir holds, leaving the tracker's gas untouched and recording the regular gas left + /// ([`failed_charge_remaining`](Self::failed_charge_remaining)). A share of zero is + /// [`record_state_cost`](Self::record_state_cost). + #[inline] + #[must_use = "In case of not enough gas, the interpreter should halt with an out-of-gas error"] + pub const fn record_state_cost_with_legacy_share( + &mut self, + cost: u64, + legacy_share: u64, + ) -> bool { + let share = if legacy_share < cost { + legacy_share + } else { + cost + }; + let rest = cost - share; + let from_reservoir = if self.reservoir < rest { + self.reservoir + } else { + rest + }; + let from_regular = cost - from_reservoir; + if from_regular != 0 && !self.record_withheld_first_cost(from_regular) { + return false; + } + self.reservoir -= from_reservoir; + self.state_gas_spent = self + .state_gas_spent + .saturating_add(super::saturating_signed(cost)); + self.state_gas_spilled = self.state_gas_spilled.saturating_add(from_regular); + true + } + + /// The part of [`state_gas_spilled`](Self::state_gas_spilled) that halts below this frame + /// already consumed, with [`reservoir_only_give_backs`](Self::reservoir_only_give_backs) set: + /// what frames that halted paid of state and history gas from regular gas, which their halts + /// took out of the reservoirs they returned. Zero with it off. + #[inline] + pub const fn halted_regular_paid(&self) -> u64 { + self.halted_regular_paid + } + + /// Consumes, after [`rollback_state_gas`](Self::rollback_state_gas) of a frame that halts, the + /// part of its state and history charges regular gas paid that no halt below it consumed yet: + /// the reservoir gives up `state_gas_spilled` less + /// [`halted_regular_paid`](Self::halted_regular_paid), so it holds the reservoir the frame + /// received, and what regular gas paid is consumed with the regular gas the halt spends. The + /// count stays, all of it now consumed, for the caller to add to its own. + /// + /// The rollback put every charge into the reservoir only with + /// [`reservoir_only_give_backs`](Self::reservoir_only_give_backs) set. With it off the rollback + /// credited the spill to `remaining` and zeroed it, so there is nothing left to take and this + /// changes nothing. + #[inline] + pub const fn consume_regular_paid_charges(&mut self) { + if !self.reservoir_only_give_backs { + return; + } + let unconsumed = self + .state_gas_spilled + .saturating_sub(self.halted_regular_paid); + self.reservoir = self.reservoir.saturating_sub(unconsumed); + self.halted_regular_paid = self.state_gas_spilled; + } + + /// Adds what a returning `child`'s regular gas paid of state and history gas to this frame's + /// count, with the part of it halts consumed, however the child ended + /// ([`reservoir_only_give_backs`](Self::reservoir_only_give_backs) set): no give-back lowers + /// the count, and a halted child's part is spent like the rest. + #[inline] + pub const fn add_regular_paid_of(&mut self, child: &GasTracker) { + self.state_gas_spilled = self + .state_gas_spilled + .saturating_add(child.state_gas_spilled); + self.halted_regular_paid = self + .halted_regular_paid + .saturating_add(child.halted_regular_paid); + } +} + +#[cfg(test)] +mod tests { + use super::GasTracker; + + /// A tracker with `remaining` regular gas and `reservoir`, its give-backs to the reservoir + /// alone when `on`. + fn tracker(remaining: u64, reservoir: u64, on: bool) -> GasTracker { + let mut tracker = GasTracker::new(remaining, remaining, reservoir); + tracker.set_reservoir_only_give_backs(on); + tracker + } + + /// `(remaining, reservoir, state_spent, history_spent, spilled)`. + const fn figures(tracker: &GasTracker) -> (u64, u64, i64, i64, u64) { + ( + tracker.remaining(), + tracker.reservoir(), + tracker.state_gas_spent(), + tracker.history_gas_spent(), + tracker.state_gas_spilled(), + ) + } + + /// The switch is off on every tracker built, and is no part of a tracker that has it off. + #[test] + fn test_the_switch_is_off_by_default() { + assert!(!GasTracker::new(1_000, 1_000, 0).reservoir_only_give_backs()); + assert!(!GasTracker::default().reservoir_only_give_backs()); + let mut on = GasTracker::default(); + on.set_reservoir_only_give_backs(true); + assert!(on.reservoir_only_give_backs()); + assert_ne!( + on, + GasTracker::default(), + "the switch is part of the tracker's value" + ); + } + + /// A refill of state gas regular gas paid credits regular gas first with the switch off, and + /// the reservoir alone with it on, the spill count standing. + #[test] + fn test_a_state_refill_credits_the_reservoir_alone_with_the_switch_on() { + for on in [false, true] { + let mut gas = tracker(1_000, 100, on); + assert!(gas.record_state_cost(300)); + assert_eq!(figures(&gas), (800, 0, 300, 0, 200)); + gas.refill_reservoir(300); + let expected = if on { + (800, 300, 0, 0, 200) + } else { + (1_000, 100, 0, 0, 0) + }; + assert_eq!(figures(&gas), expected, "switch on: {on}"); + } + } + + /// A refill of history gas follows the same rule as a refill of state gas. + #[test] + fn test_a_history_refill_credits_the_reservoir_alone_with_the_switch_on() { + for on in [false, true] { + let mut gas = tracker(1_000, 100, on); + assert!(gas.record_history_cost(300)); + gas.refill_history(300); + let expected = if on { + (800, 300, 0, 0, 200) + } else { + (1_000, 100, 0, 0, 0) + }; + assert_eq!(figures(&gas), expected, "switch on: {on}"); + } + } + + /// A reservoir a child returns unwinds the caller's spill with the switch off, and becomes the + /// caller's reservoir as it is with it on. + #[test] + fn test_a_returned_reservoir_unwinds_nothing_with_the_switch_on() { + for on in [false, true] { + let mut gas = tracker(1_000, 0, on); + assert!(gas.record_state_cost(300)); + gas.absorb_returned_reservoir(500); + let expected = if on { + (700, 500, 300, 0, 300) + } else { + (1_000, 200, 300, 0, 0) + }; + assert_eq!(figures(&gas), expected, "switch on: {on}"); + } + } + + /// With the switch on a revert puts every charge the frame made, net of what it was given + /// back, into the reservoir, whichever pool paid it, and keeps the count of what regular gas + /// paid; regular gas is left as it was. With it off the spill goes back to regular gas. + #[test] + fn test_a_rollback_puts_every_charge_into_the_reservoir_with_the_switch_on() { + for on in [false, true] { + let mut gas = tracker(1_000, 100, on); + assert!(gas.record_state_cost(300)); + assert!(gas.record_history_cost(50)); + gas.refill_reservoir(20); + gas.rollback_state_gas(); + let expected = if on { + // 100 − 100 − 0 + 20 (refill) + 330 (net) = 350 of reservoir; 750 regular left. + (750, 350, 0, 0, 250) + } else { + (1_000, 100, 0, 0, 0) + }; + assert_eq!(figures(&gas), expected, "switch on: {on}"); + } + } + + /// After a halting frame's rollback, consuming what regular gas paid leaves the reservoir the + /// frame received with the switch on, and keeps the count, all of it now consumed, for the + /// caller; with it off it changes nothing, where the rollback already credited the spill to + /// regular gas and zeroed it. + #[test] + fn test_a_halt_gives_back_the_reservoir_the_frame_received() { + for on in [false, true] { + let mut gas = tracker(1_000, 100, on); + assert!(gas.record_state_cost(300)); + assert!(gas.record_history_cost(50)); + gas.refill_reservoir(300); + assert!(gas.record_state_cost_with_legacy_share(200, 80)); + gas.rollback_state_gas(); + gas.consume_regular_paid_charges(); + gas.spend_all(); + assert_eq!(gas.reservoir(), 100, "switch on: {on}"); + // Regular gas paid 200 and 50 past the reservoir, then the share of 80. + let paid = if on { 330 } else { 0 }; + assert_eq!(gas.state_gas_spilled(), paid, "switch on: {on}"); + assert_eq!(gas.halted_regular_paid(), paid, "switch on: {on}"); + assert_eq!(gas.remaining(), 0, "switch on: {on}"); + } + } + + /// A halt consumes only what no halt below it consumed: a frame whose child halted adds the + /// child's count with the record that the child's halt consumed it, so its own halt leaves the + /// reservoir it received rather than taking the child's part out a second time. + #[test] + fn test_a_halt_after_a_halted_child_consumes_the_childs_part_once() { + let mut parent = tracker(10_000, 500, true); + // 500 from the reservoir, 200 from regular gas. + assert!(parent.record_state_cost(700)); + let mut child = tracker(1_000, 0, true); + assert!(child.record_state_cost(40)); + child.rollback_state_gas(); + child.consume_regular_paid_charges(); + child.spend_all(); + assert_eq!( + ( + child.reservoir(), + child.state_gas_spilled(), + child.halted_regular_paid() + ), + (0, 40, 40) + ); + + parent.add_regular_paid_of(&child); + assert_eq!( + (parent.state_gas_spilled(), parent.halted_regular_paid()), + (240, 40) + ); + parent.rollback_state_gas(); + parent.consume_regular_paid_charges(); + assert_eq!(parent.reservoir(), 500, "the reservoir the parent received"); + assert_eq!( + (parent.state_gas_spilled(), parent.halted_regular_paid()), + (240, 240) + ); + } + + /// A legacy share is paid from regular gas before the reservoir, which pays the rest; the + /// regular part is counted as paid by regular gas, and the whole charge is state gas. + #[test] + fn test_a_legacy_share_comes_from_regular_gas_before_the_reservoir() { + let mut gas = tracker(1_000, 500, true); + assert!(gas.record_state_cost_with_legacy_share(300, 100)); + assert_eq!(figures(&gas), (900, 300, 300, 0, 100)); + + // The share is capped at the charge. + let mut gas = tracker(1_000, 500, true); + assert!(gas.record_state_cost_with_legacy_share(60, 100)); + assert_eq!(figures(&gas), (940, 500, 60, 0, 60)); + + // What the reservoir cannot pay after the share spills onto regular gas too. + let mut gas = tracker(1_000, 150, true); + assert!(gas.record_state_cost_with_legacy_share(300, 100)); + assert_eq!(figures(&gas), (850, 0, 300, 0, 150)); + } + + /// A share regular gas cannot pay is an out-of-gas whatever the reservoir holds, and leaves the + /// tracker's gas untouched with the failure recorded; so is a share and a spill it cannot pay + /// together. + #[test] + fn test_a_legacy_share_regular_gas_cannot_pay_runs_out_of_gas() { + let mut gas = tracker(99, 1_000, true); + let before = figures(&gas); + assert!(!gas.record_state_cost_with_legacy_share(300, 100)); + assert_eq!(figures(&gas), before); + assert_eq!(gas.failed_charge_remaining(), Some(99)); + + let mut gas = tracker(149, 150, true); + assert!(!gas.record_state_cost_with_legacy_share(300, 100)); + assert_eq!(gas.failed_charge_remaining(), Some(149)); + } + + /// The share draws the withheld part first, as a spill does. + #[test] + fn test_a_legacy_share_draws_the_withheld_part_first() { + let mut gas = tracker(1_000, 500, true); + gas.withhold(300); + assert!(gas.record_state_cost_with_legacy_share(300, 100)); + assert_eq!(gas.withheld(), 200); + assert_eq!(gas.spendable(), 700); + } + + /// A share of zero is the charge EIP-8037 makes, with the switch on or off. + #[test] + fn test_a_legacy_share_of_zero_is_the_plain_state_charge() { + for on in [false, true] { + for (remaining, reservoir, cost) in + [(1_000, 500, 300), (1_000, 100, 300), (200, 50, 300)] + { + let mut plain = tracker(remaining, reservoir, on); + let mut shared = plain; + assert_eq!( + plain.record_state_cost(cost), + shared.record_state_cost_with_legacy_share(cost, 0) + ); + assert_eq!(plain, shared, "{remaining} {reservoir} {cost} {on}"); + } + } + } + + /// A give-back never lowers the count of what regular gas paid with the switch on, so a frame + /// that paid a slot from regular gas and wrote it back still counts what it paid. + #[test] + fn test_no_give_back_lowers_the_count_of_what_regular_gas_paid() { + let mut gas = tracker(1_000, 0, true); + assert!(gas.record_state_cost_with_legacy_share(300, 100)); + assert!(gas.record_history_cost(40)); + gas.refill_reservoir(300); + gas.refill_history(40); + gas.absorb_returned_reservoir(500); + assert_eq!(gas.state_gas_spilled(), 340); + assert_eq!(gas.remaining(), 660); + } +} diff --git a/crates/context/interface/src/cfg/gas/mark.rs b/crates/context/interface/src/cfg/gas/mark.rs new file mode 100644 index 0000000000..e5025fba69 --- /dev/null +++ b/crates/context/interface/src/cfg/gas/mark.rs @@ -0,0 +1,129 @@ +//! The marks revm writes on a frame's result just before an inspector's end callbacks, and reads +//! just after, to tell whether the callbacks put another value in the result's place: the +//! [`StartMark`] on the result's gas tracker and the [`OutcomeMark`] on its outcome. +//! +//! A mark takes no part in the value it rides on: marks always compare equal and hash to nothing, +//! and the tracker and the outcomes leave them out of their debug output and their encoding (a +//! decoded value carries none). So a marked tracker or outcome compares, hashes, prints and encodes +//! as the same value unmarked. Each fits padding of the type that carries it, so neither grows. + +/// The mark of a start on a gas tracker: the start's identity, or none. +/// +/// revm marks the tracker of a start's result for the start before an inspector's end callbacks; +/// a tracker that does not carry the mark after them is one the callbacks put in its place +/// ([`FrameSettle::gas_replaced`](crate::host::FrameSettle::gas_replaced)). A copy of the +/// tracker carries the mark with it. +#[derive(Clone, Copy, Default)] +pub struct StartMark(u32); + +impl StartMark { + /// No mark, as every tracker is built. + pub const NONE: Self = Self(0); + + /// The mark of the start `id`. + #[inline] + pub const fn for_start(id: u32) -> Self { + Self(id) + } + + /// Whether this is the mark of the start `id`. + #[inline] + pub const fn is_for(self, id: u32) -> bool { + self.0 != 0 && self.0 == id + } +} + +/// The mark of a start on a call's or creation's outcome: 16 bits of the start's identity, or +/// none. +/// +/// revm marks the outcome of a start's result for the start before an inspector's end callbacks; +/// an outcome that does not carry the mark after them is one the callbacks put in its place +/// ([`FrameSettle::outcome_rebuilt`](crate::host::FrameSettle::outcome_rebuilt)), such as one a +/// constructor built around the same result. A start's mark is never none, so a built outcome +/// never carries it; two starts share a mark only when their identities are a multiple of 65,535 +/// apart. +#[derive(Clone, Copy, Default)] +pub struct OutcomeMark(u16); + +impl OutcomeMark { + /// No mark, as every constructor builds an outcome. + pub const NONE: Self = Self(0); + + /// The mark of the start `id`: `(id - 1) % 65535 + 1`, never none. + #[inline] + pub const fn for_start(id: u32) -> Self { + Self((id.wrapping_sub(1) % 65535 + 1) as u16) + } + + /// Whether this is the mark of the start `id`. + #[inline] + pub const fn is_for(self, id: u32) -> bool { + self.0 == Self::for_start(id).0 + } +} + +macro_rules! transparent_mark { + ($mark:ident) => { + impl PartialEq for $mark { + #[inline] + fn eq(&self, _: &Self) -> bool { + true + } + } + + impl Eq for $mark {} + + impl core::hash::Hash for $mark { + #[inline] + fn hash<H: core::hash::Hasher>(&self, _: &mut H) {} + } + + impl core::fmt::Debug for $mark { + fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { + f.write_str(stringify!($mark)) + } + } + }; +} + +transparent_mark!(StartMark); +transparent_mark!(OutcomeMark); + +#[cfg(test)] +mod tests { + use super::{OutcomeMark, StartMark}; + + #[test] + fn test_a_start_mark_names_its_start_only() { + let mark = StartMark::for_start(7); + assert!(mark.is_for(7)); + assert!(!mark.is_for(8)); + assert!(!StartMark::NONE.is_for(0), "no mark names no start"); + } + + /// The outcome's mark is never none for a start, and two starts share one only 65,535 + /// identities apart. + #[test] + fn test_an_outcome_mark_is_never_none_and_repeats_every_65535_starts() { + for id in [ + 1u32, + 2, + 65_534, + 65_535, + 65_536, + 65_537, + 131_070, + 131_071, + u32::MAX - 1, + u32::MAX, + ] { + assert!(!OutcomeMark::NONE.is_for(id), "id {id} has no mark"); + assert!(OutcomeMark::for_start(id).is_for(id), "id {id}"); + if id > 1 { + assert!(!OutcomeMark::for_start(id).is_for(id - 1), "id {id}"); + } + } + assert!(OutcomeMark::for_start(1).is_for(65_536)); + assert!(!OutcomeMark::for_start(1).is_for(65_535)); + } +} diff --git a/crates/context/interface/src/cfg/gas/withheld.rs b/crates/context/interface/src/cfg/gas/withheld.rs index 875eef9769..b7373e0359 100644 --- a/crates/context/interface/src/cfg/gas/withheld.rs +++ b/crates/context/interface/src/cfg/gas/withheld.rs @@ -236,12 +236,14 @@ mod tests { assert_eq!(size_of::<Option<WithheldCrossing>>(), size_of::<u64>()); } - /// The tracker is 88 bytes: 72 with the withheld part and its record, and two words more for - /// the failed-charge record. Copies of the tracker, and of every `Gas` and frame result that - /// holds one, grow with it, so a new field is measured before this changes. + /// The tracker is 96 bytes: 72 with the withheld part and its record, two words more for the + /// failed-charge record, whose second word also holds the start mark and the give-back switch, + /// and one for the part of what regular gas paid of state and history that halts consumed. + /// Copies of the tracker, and of every `Gas` and frame result that holds one, grow with it, so + /// a new field is measured before this changes. #[test] - fn test_the_tracker_is_88_bytes() { - assert_eq!(size_of::<GasTracker>(), 88); + fn test_the_tracker_is_96_bytes() { + assert_eq!(size_of::<GasTracker>(), 96); } /// Withholding moves gas between the parts and leaves the total alone. @@ -644,10 +646,10 @@ mod tests { assert_eq!(parts(&tracker), (650, 250, 900)); } - /// Encodings made before the withheld part existed decode with nothing withheld. + /// JSON encodings made before the withheld part existed decode with nothing withheld. #[cfg(feature = "serde")] #[test] - fn test_serde_round_trip_and_older_payloads() { + fn test_serde_round_trip_and_older_json_payloads() { let mut tracker = withheld_600(); assert!(!tracker.record_regular_cost(401)); let encoded = serde_json::to_value(tracker).unwrap(); diff --git a/crates/context/interface/src/cfg/gas_params.rs b/crates/context/interface/src/cfg/gas_params.rs index 91785e0afb..7c4c0d856f 100644 --- a/crates/context/interface/src/cfg/gas_params.rs +++ b/crates/context/interface/src/cfg/gas_params.rs @@ -814,6 +814,38 @@ impl GasParams { .saturating_mul(len as u64) } + /// The most of the state gas of a slot an `SSTORE` fills that regular gas pays before the + /// reservoir ([`GasId::sstore_set_state_gas_legacy_share`]). Zero unless the schedule sets it. + #[inline] + pub fn sstore_set_state_gas_legacy_share(&self) -> u64 { + self.get(GasId::sstore_set_state_gas_legacy_share()) + } + + /// The most of the state gas of the account a value `CALL` creates that regular gas pays + /// before the reservoir ([`GasId::new_account_state_gas_legacy_share`]). Zero unless the + /// schedule sets it. + #[inline] + pub fn new_account_state_gas_legacy_share(&self) -> u64 { + self.get(GasId::new_account_state_gas_legacy_share()) + } + + /// The most of the state gas of the account a `SELFDESTRUCT` creates for its beneficiary that + /// regular gas pays before the reservoir + /// ([`GasId::selfdestruct_new_account_state_gas_legacy_share`]). Zero unless the schedule sets + /// it. + #[inline] + pub fn selfdestruct_new_account_state_gas_legacy_share(&self) -> u64 { + self.get(GasId::selfdestruct_new_account_state_gas_legacy_share()) + } + + /// The most of the state gas of the account a `CREATE` or `CREATE2` creates that regular gas + /// pays before the reservoir ([`GasId::create_state_gas_legacy_share`]). Zero unless the + /// schedule sets it. + #[inline] + pub fn create_state_gas_legacy_share(&self) -> u64 { + self.get(GasId::create_state_gas_legacy_share()) + } + /// Used in [GasParams::initial_tx_gas] to calculate the eip7702 per-auth cost. /// /// Pre-Amsterdam this is the pessimistic bundled `PER_EMPTY_ACCOUNT_COST` @@ -1276,6 +1308,18 @@ impl GasId { x if x == Self::tx_account_write_cost().as_u8() => "tx_account_write_cost", x if x == Self::tx_create_access_cost().as_u8() => "tx_create_access_cost", x if x == Self::code_deposit_history_gas().as_u8() => "code_deposit_history_gas", + x if x == Self::sstore_set_state_gas_legacy_share().as_u8() => { + "sstore_set_state_gas_legacy_share" + } + x if x == Self::new_account_state_gas_legacy_share().as_u8() => { + "new_account_state_gas_legacy_share" + } + x if x == Self::selfdestruct_new_account_state_gas_legacy_share().as_u8() => { + "selfdestruct_new_account_state_gas_legacy_share" + } + x if x == Self::create_state_gas_legacy_share().as_u8() => { + "create_state_gas_legacy_share" + } _ => "unknown", } } @@ -1351,6 +1395,14 @@ impl GasId { "tx_account_write_cost" => Some(Self::tx_account_write_cost()), "tx_create_access_cost" => Some(Self::tx_create_access_cost()), "code_deposit_history_gas" => Some(Self::code_deposit_history_gas()), + "sstore_set_state_gas_legacy_share" => Some(Self::sstore_set_state_gas_legacy_share()), + "new_account_state_gas_legacy_share" => { + Some(Self::new_account_state_gas_legacy_share()) + } + "selfdestruct_new_account_state_gas_legacy_share" => { + Some(Self::selfdestruct_new_account_state_gas_legacy_share()) + } + "create_state_gas_legacy_share" => Some(Self::create_state_gas_legacy_share()), _ => None, } } @@ -1641,6 +1693,39 @@ impl GasId { pub const fn code_deposit_history_gas() -> GasId { Self::new(255) } + + /// The legacy share of the state gas of a slot an `SSTORE` fills: the most of that charge + /// regular gas pays before the reservoir pays any of it + /// ([`GasTracker::record_state_cost_with_legacy_share`](crate::cfg::gas::GasTracker::record_state_cost_with_legacy_share)). + /// + /// Zero on every schedule defined here, which makes the charge the one EIP-8037 makes. A chain + /// that keeps what creating state costs in regular gas when a transaction carries a reservoir + /// sets it. A fork id, allocated down from the top of the table below the ids the fork retired. + pub const fn sstore_set_state_gas_legacy_share() -> GasId { + Self::new(245) + } + + /// The legacy share of the state gas of the account a value `CALL` creates for its target: + /// the most of that charge regular gas pays before the reservoir pays any of it, as + /// [`sstore_set_state_gas_legacy_share`](Self::sstore_set_state_gas_legacy_share) is for a + /// slot. Zero on every schedule defined here. + pub const fn new_account_state_gas_legacy_share() -> GasId { + Self::new(244) + } + + /// The legacy share of the state gas of the account a `SELFDESTRUCT` creates for its + /// beneficiary, as [`sstore_set_state_gas_legacy_share`](Self::sstore_set_state_gas_legacy_share) + /// is for a slot. Zero on every schedule defined here. + pub const fn selfdestruct_new_account_state_gas_legacy_share() -> GasId { + Self::new(243) + } + + /// The legacy share of the state gas of the account a `CREATE` or `CREATE2` creates, as + /// [`sstore_set_state_gas_legacy_share`](Self::sstore_set_state_gas_legacy_share) is for a + /// slot. Zero on every schedule defined here. + pub const fn create_state_gas_legacy_share() -> GasId { + Self::new(242) + } } #[cfg(test)] @@ -1714,18 +1799,46 @@ mod tests { ); // The known GasIds are upstream's indices 1-49 (0 is unused) plus the fork's - // `code_deposit_history_gas` at 255, allocated from the top of the table so upstream's - // next sequential id does not collide with it. Every one of them has a name. - let expected_ids: HashSet<u8> = (1..=49).chain([255]).collect(); + // `code_deposit_history_gas` at 255 and the four legacy shares at 242-245, allocated from + // the top of the table so upstream's next sequential id does not collide with them. Every + // one of them has a name. + let expected_ids: HashSet<u8> = (1..=49).chain(242..=245).chain([255]).collect(); assert_eq!(named_ids, expected_ids); assert_eq!( unique_names.len(), - 50, - "Expected 50 unique GasIds, found {}", + 54, + "Expected 54 unique GasIds, found {}", unique_names.len() ); } + /// A forward of 98/100 of the regular gas to a child, `remaining - remaining * 2 / 100` rounded + /// down, is upstream's `call_stipend_reduction` with the quotient 50 in place of EIP-150's 64: + /// the two agree on every amount, so a chain that forwards 98/100 of its regular gas needs no + /// fork change, only the schedule entry. + #[test] + fn test_a_call_stipend_reduction_of_50_forwards_98_per_cent() { + let mut params = GasParams::new_spec(SpecId::OSAKA); + params.override_gas([(GasId::call_stipend_reduction(), 50)]); + let ninety_eight = + |remaining: u64| (remaining as u128 - remaining as u128 * 2 / 100) as u64; + let amounts = (0..10_000) + .chain([1_000_000, 16_777_216, 30_000_000, 1 << 40]) + .chain([u64::MAX - 49, u64::MAX - 1, u64::MAX]); + for remaining in amounts { + assert_eq!( + params.call_stipend_reduction(remaining), + ninety_eight(remaining), + "{remaining}" + ); + } + // Worked examples: 98% of 1,000 is 980; of 1,049 is 1,028.02, and the rule keeps 1,029: it + // takes 2% rounded down (20) away. + assert_eq!(params.call_stipend_reduction(1_000), 980); + assert_eq!(params.call_stipend_reduction(1_049), 1_029); + assert_eq!(params.call_stipend_reduction(99), 98); + } + #[test] fn test_max_refund_quotient_defaults_and_override() { let frontier = GasParams::new_spec(SpecId::FRONTIER); diff --git a/crates/context/interface/src/host.rs b/crates/context/interface/src/host.rs index 297662fe63..ad89af4623 100644 --- a/crates/context/interface/src/host.rs +++ b/crates/context/interface/src/host.rs @@ -1,7 +1,13 @@ //! Host interface for external blockchain state access. +mod instruction_hooks; +mod lifecycle; + +pub use instruction_hooks::{CompletedWrite, FrameStart, FrameStartKind, WriteVerdict}; +pub use lifecycle::{FrameSettle, FrameSplit, LifecycleEnd, SettleStatus}; + use crate::{ - cfg::{GasId, GasParams, StateGasCharge, StateGasSite}, + cfg::{gas::GasTracker, GasId, GasParams, StateGasCharge, StateGasSite}, context::{SStoreResult, SelfDestructResult, StateLoad}, journaled_state::{AccountInfoLoad, AccountLoad}, }; @@ -94,6 +100,92 @@ pub trait Host { .map(|unit_price| charge.total(unit_price)) } + /* Instruction hooks */ + + /// Called by `SSTORE`, `LOG0`–`LOG4` and `SELFDESTRUCT` once `write` is in the journal and + /// every charge the instruction makes has been made, so only when the instruction completes. + /// `gas` is the running frame's. + /// + /// The hook may debit and credit `gas`, and the instruction uses it as the hook left it, + /// charging nothing after the hook; a charge the hook makes that fails records as any failed + /// charge does ([`GasTracker::failed_charge_remaining`]), whatever the verdict. + /// [`WriteVerdict::Continue`] ends the instruction as it would have ended. + /// [`WriteVerdict::OutOfGas`] fails it as a failed charge does: the frame halts out of gas, + /// and the halt records the regular gas the hook left unless a failed charge already did. + /// [`WriteVerdict::Revert`] ends the frame as a `Revert` with the verdict's output, on its gas + /// as the hook left it; a `SELFDESTRUCT` so reverted does not self-destruct. + /// + /// The default continues and touches nothing. + #[inline] + fn write_completed(&mut self, write: CompletedWrite<'_>, gas: &mut GasTracker) -> WriteVerdict { + let _ = (write, gas); + WriteVerdict::Continue + } + + /// Called by `CALL`, `CALLCODE`, `DELEGATECALL`, `STATICCALL`, `CREATE` and `CREATE2` once + /// every charge the instruction makes has been made and the forward + /// ([`FrameStart::forward`]) has been taken from `gas`, the running frame's, and before the + /// frame's input is built. + /// + /// The hook may debit and credit `gas`, and the instruction uses it as the hook left it, + /// charging nothing after the hook: the frame's input copies the reservoir in `gas`, or + /// carries the child's reservoir the hook names on `start` if it took that out of `gas` itself + /// ([`FrameStart::reservoir`]). A charge the hook makes that fails records as any failed + /// charge does ([`GasTracker::failed_charge_remaining`]), whatever the answer. + /// `true` goes on to start the frame, which the handler may still refuse or answer without + /// running it. `false` fails the instruction out of gas and starts no frame: the forward stays + /// taken unless the hook gave it back, and the halt records the regular gas the hook left + /// unless a failed charge already did. + /// + /// The default returns `true` and touches nothing. + #[inline] + fn frame_starting(&mut self, start: &mut FrameStart, gas: &mut GasTracker) -> bool { + let _ = (start, gas); + true + } + + /* Start lifecycle */ + + /// Called when revm opens a start ([`FrameSplit`]): it consumed a frame's init and + /// initialises the frame next. A frame's `NewFrame` action opens a child start under the + /// frame's own; the transaction's frame, or the stand-in for one that never runs, opens the + /// transaction's start, the first of its lifecycle. + /// + /// Every start opened is closed once by [`frame_settle`](Self::frame_settle), innermost first, + /// unless the lifecycle is discarded ([`frame_lifecycle_end`](Self::frame_lifecycle_end)). A + /// start revm never opened, such as a `NewFrame` an inspector dropped, is never settled. + /// + /// The default touches nothing. + #[inline] + fn frame_split(&mut self, split: &FrameSplit) { + let _ = split; + } + + /// Called when revm settles the start `settle.id` into its caller's `gas`, after revm's own + /// settlement of the frame's result. + /// + /// The hook may debit and credit `gas`, which goes on as the hook left it, but for a halted + /// transaction's frame: there revm then consumes the hook's net credit of regular gas, the + /// regular gas `gas` holds above what revm's own settlement left in it, and keeps the gas that + /// settlement left. A hook that debits keeps its debit. + /// + /// The default touches nothing. + #[inline] + fn frame_settle(&mut self, settle: &FrameSettle, gas: &mut GasTracker) { + let _ = (settle, gas); + } + + /// Called once when a transaction's lifecycle ends: [`LifecycleEnd::Settled`] at the + /// successful boundary, every start settled, or [`LifecycleEnd::Discarded`] at the fatal one, + /// the starts still open discarded. Not called for a transaction that failed before its start + /// opened. + /// + /// The default touches nothing. + #[inline] + fn frame_lifecycle_end(&mut self, end: LifecycleEnd) { + let _ = end; + } + /* Database */ /// Block hash, calls `ContextTr::journal_mut().db().block_hash(number)` diff --git a/crates/context/interface/src/host/instruction_hooks.rs b/crates/context/interface/src/host/instruction_hooks.rs new file mode 100644 index 0000000000..35cb0a235e --- /dev/null +++ b/crates/context/interface/src/host/instruction_hooks.rs @@ -0,0 +1,157 @@ +//! Hooks an instruction calls on the [`Host`](super::Host) at a point inside it: once a state write +//! is complete ([`Host::write_completed`](super::Host::write_completed)), and once a frame's forward +//! is taken, before the frame's input is built ([`Host::frame_starting`](super::Host::frame_starting)). +//! +//! Both hooks get the running frame's [`GasTracker`](crate::cfg::gas::GasTracker), and may debit +//! and credit it; the instruction goes on with the gas as the hook left it. Their defaults touch +//! nothing and let the instruction go on. + +use crate::context::{SStoreResult, SelfDestructResult}; +use primitives::{Address, Bytes, StorageKey, U256}; + +/// A state write an instruction completed: the write is in the journal, and every charge the +/// instruction makes has been made. +/// +/// Exhaustive on purpose: a new variant is a breaking change, so that every consumer handles every +/// kind of write. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum CompletedWrite<'a> { + /// `SSTORE` wrote slot `key` of `address`. + Sstore { + /// The account whose storage was written. + address: Address, + /// The slot written. + key: StorageKey, + /// The slot's original, present and new values, as the journal reported them. + result: &'a SStoreResult, + }, + /// `LOG0`–`LOG4` appended a log for `address`. + Log { + /// The account that logged. + address: Address, + /// The number of topics, `0` to `4`. + topics: u8, + /// The length of the log's data, in bytes. + data_len: u64, + }, + /// `SELFDESTRUCT` destructed `address` in favour of `target`. + /// + /// The write changes no account's nonce or code, only balances: `address`'s info before it is + /// its info after it with [`balance`](CompletedWrite::SelfDestruct::balance) as its balance, + /// and `target`'s, when it is another account, its info after it less that balance. With the + /// journal at the hook, that gives both accounts' change across the write. + SelfDestruct { + /// The account destructed. + address: Address, + /// The beneficiary. + target: Address, + /// The balance `address` held before the write. When `target` is another account, the + /// write moved all of it to `target`. When `target` is `address`, the write burned it or + /// left it, as the spec and EIP-6780 decide, and the account's balance after the write + /// tells which. + balance: U256, + /// What the journal reported. + result: &'a SelfDestructResult, + }, +} + +/// What an instruction does once [`Host::write_completed`](super::Host::write_completed) has seen +/// its write. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum WriteVerdict { + /// The instruction ends as it would without the hook. + Continue, + /// The instruction fails out of gas, as a failed charge does. + OutOfGas, + /// The frame ends as a `Revert` with this output, on its gas as the hook left it. + Revert(Bytes), +} + +/// The kind of frame an instruction is about to start. +/// +/// Exhaustive on purpose: a new variant is a breaking change, so that every consumer handles every +/// kind of start. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum FrameStartKind { + /// `CALL`. + Call, + /// `CALLCODE`. + CallCode, + /// `DELEGATECALL`. + DelegateCall, + /// `STATICCALL`. + StaticCall, + /// `CREATE`. + Create, + /// `CREATE2`. + Create2, +} + +/// A frame an instruction is about to start: every charge the instruction makes has been made, the +/// gas it forwards has been taken from the caller, and the frame's input is not built yet. +/// +/// The hook is handed it mutably to name the child's [`reservoir`](Self::reservoir) if it takes +/// that itself; the instruction reads nothing else back. +/// +/// Built with [`FrameStart::new`], so a later field is not a breaking change. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[non_exhaustive] +pub struct FrameStart { + /// The kind of frame. + pub kind: FrameStartKind, + /// The frame's caller: the account the frame sees as `CALLER`. + pub caller: Address, + /// The account the frame runs as. For a `CALL` or `STATICCALL`, the account called; for a + /// `CALLCODE` or `DELEGATECALL`, the calling frame's own account, which runs the called + /// account's code. + /// + /// For a `CREATE` or `CREATE2`, the address the creation would take, computed once: the + /// handler builds the frame at the same address without computing it again. Whether the + /// creation takes it is the outcome's to say (`CreateOutcome::address`): a creation that + /// lands on an account that already has code or a nonce, one the handler refuses after the + /// hook, and one an inspector or a consumer answers without a frame take none, though the + /// start named the address. `None` only for a creation the handler fails before it takes an + /// address, which reaches the hook only when EIP-8037 is off: an endowment above the caller's + /// balance, a caller's nonce at its maximum, or a creating frame at the depth limit. With + /// EIP-8037 on, the instruction ends such a creation before the hook. + pub target: Option<Address>, + /// The value the start transfers; zero for `DELEGATECALL` and `STATICCALL`. + pub value: U256, + /// The regular gas the instruction took from the caller for the frame: the frame's gas limit + /// without a value call's stipend, which the caller does not pay. + pub forward: u64, + /// The child's reservoir, when the hook took it out of the caller's reservoir itself. `None` + /// when the hook is called. + /// + /// `None` leaves the forward to the instruction, whose frame's input copies the caller's + /// reservoir as the hook left it, and the caller keeps it, as upstream's instructions do. + /// `Some` is the reservoir the frame's input carries in its place, and the caller keeps the + /// reservoir the hook left it. The instruction does not check the amount against what the hook + /// took. + /// + /// Either way the child's settlement replaces the caller's reservoir with the one the child + /// returns. A hook that kept part of the caller's reservoir for it adds that back when the + /// child settles ([`FrameSettle::held_reservoir`](super::FrameSettle::held_reservoir)). + pub reservoir: Option<u64>, +} + +impl FrameStart { + /// A frame start. + #[inline] + pub const fn new( + kind: FrameStartKind, + caller: Address, + target: Option<Address>, + value: U256, + forward: u64, + ) -> Self { + Self { + kind, + caller, + target, + value, + forward, + reservoir: None, + } + } +} diff --git a/crates/context/interface/src/host/lifecycle.rs b/crates/context/interface/src/host/lifecycle.rs new file mode 100644 index 0000000000..e9900e900f --- /dev/null +++ b/crates/context/interface/src/host/lifecycle.rs @@ -0,0 +1,91 @@ +//! The start lifecycle revm keeps for a transaction, as the [`Host`](super::Host) hooks see it. +//! +//! A start opens where revm consumes a frame's init, just before it initialises the frame +//! ([`Host::frame_split`](super::Host::frame_split)), and closes where revm settles the frame's +//! result into its caller ([`Host::frame_settle`](super::Host::frame_settle)). The transaction's +//! lifecycle ends at one of two boundaries ([`Host::frame_lifecycle_end`](super::Host::frame_lifecycle_end)): +//! the successful one, where every start opened has settled, or the fatal one, where the starts +//! still open are discarded. +//! +//! revm owns the pairing. It allocates each start's identity, keeps the open starts in its frame +//! stack ([`FrameStack`](crate::FrameStack)), which no inspector is handed, and settles each +//! start it opened once, innermost first. The values here are built by that record only. + +/// What became of a start revm settles into its caller, read from the frame's result. +/// +/// Exhaustive on purpose: a new variant is a breaking change, so that every consumer handles every +/// kind of settlement. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum SettleStatus { + /// The frame succeeded. + Ok, + /// The frame reverted. + Revert, + /// The frame halted. + Halt, +} + +/// How a transaction's lifecycle ended. +/// +/// Exhaustive on purpose: a new variant is a breaking change, so that every consumer handles every +/// end. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum LifecycleEnd { + /// The successful boundary: every start opened in the transaction settled. + Settled, + /// The fatal boundary: an error ended the transaction, and the starts still open are + /// discarded unsettled. + Discarded, +} + +/// A start revm opened: the frame it makes is the next one revm initialises. +/// +/// Built by revm's record only, so a later field is not a breaking change. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +#[non_exhaustive] +pub struct FrameSplit { + /// The start's identity: a sequence number revm allocated in this transaction, from 1, and + /// never reused in it. + pub id: u32, + /// The identity of the start the calling frame runs for, `None` for the transaction's own + /// frame. + pub parent: Option<u32>, + /// The depth of the frame the start makes, from the frame's init: 0 for the transaction's + /// frame. + pub depth: usize, +} + +/// A start revm settled into its caller: the caller's gas has absorbed the frame's result. +/// +/// Built by revm's record only, so a later field is not a breaking change. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +#[non_exhaustive] +pub struct FrameSettle { + /// The identity revm allocated for the start when it opened ([`FrameSplit::id`]). + pub id: u32, + /// The depth of the frame the start made. + pub depth: usize, + /// What became of the frame. + pub status: SettleStatus, + /// For a creation, whether it took an address; `None` for a call. + pub created: Option<bool>, + /// An inspector answered the start: its `frame_start`, `call` or `create` returned the + /// result, so no frame ran. + pub inspector_answer: bool, + /// An inspector's end callbacks (`frame_end`, `call_end`, `create_end`) replaced the result's + /// gas tracker with one revm did not mark for this start. + pub gas_replaced: bool, + /// An inspector's end callbacks replaced the result's outcome with one revm did not mark for + /// this start, such as one a constructor built around the same result. + pub outcome_rebuilt: bool, + /// The reservoir the caller's gas held just before revm settled the result into it. + /// + /// revm's settlement replaces the caller's reservoir with the one the frame returns, once that + /// has unwound the caller's outstanding spill. A consumer that kept part of the caller's + /// reservoir when the start was made ([`FrameStart::reservoir`](super::FrameStart::reservoir)) + /// adds this back to it here, which gives the caller what the frame returned on top of the + /// part it kept, since the unwinding and every refill read the spill, not the reservoir. The + /// transaction's frame is handed a copy of the transaction's reservoir, which this then is: a + /// consumer adds back only what it kept. + pub held_reservoir: u64, +} diff --git a/crates/context/interface/src/lib.rs b/crates/context/interface/src/lib.rs index 7452846d66..2df6af9591 100644 --- a/crates/context/interface/src/lib.rs +++ b/crates/context/interface/src/lib.rs @@ -25,5 +25,8 @@ pub use database_interface::{erased_error::ErasedError, DBErrorMarker, Database} pub use either; pub use host::{DummyHost, Host}; pub use journaled_state::JournalTr; -pub use local::{FrameStack, FrameToken, LocalContextTr, OutFrame}; +pub use local::{ + FrameStack, FrameToken, LifecycleEvent, LifecycleMirror, LocalContextTr, OutFrame, + PendingStart, StartLifecycleError, +}; pub use transaction::{Transaction, TransactionType}; diff --git a/crates/context/interface/src/local.rs b/crates/context/interface/src/local.rs index a231888358..93438be113 100644 --- a/crates/context/interface/src/local.rs +++ b/crates/context/interface/src/local.rs @@ -5,11 +5,22 @@ use core::{ }; use std::{rc::Rc, string::String, vec::Vec}; +mod lifecycle; +mod mirror; + +pub use lifecycle::{PendingStart, StartLifecycleError}; +pub use mirror::{LifecycleEvent, LifecycleMirror}; + /// Non-empty, item-pooling Vec. +/// +/// It also keeps the transaction's start lifecycle: the open start of the transaction and of each +/// frame on the stack, which pairs every settlement with the start it closes +/// ([`open_start`](Self::open_start), [`close_start`](Self::close_start)). #[derive(Debug, Clone)] pub struct FrameStack<T> { stack: Vec<T>, index: Option<usize>, + lifecycle: lifecycle::StartLifecycle, } impl<T> Default for FrameStack<T> { @@ -26,6 +37,7 @@ impl<T> FrameStack<T> { Self { stack: Vec::with_capacity(8), index: None, + lifecycle: Default::default(), } } @@ -37,7 +49,11 @@ impl<T> FrameStack<T> { { let mut stack = Vec::with_capacity(len); stack.resize_with(len, T::default); - Self { stack, index: None } + Self { + stack, + index: None, + lifecycle: Default::default(), + } } /// Initializes the stack with a single item. @@ -224,6 +240,16 @@ pub trait LocalContextTr { /// Clear the local context. fn clear(&mut self); + /// The lifecycle mirror this local context keeps, if any: a debug check that the context's + /// lifecycle hooks feed ([`LifecycleMirror`]). revm's own local context keeps one in debug + /// builds only. + /// + /// The default keeps none. + #[inline] + fn lifecycle_mirror(&mut self) -> Option<&mut LifecycleMirror> { + None + } + /// Set the error message for a precompile error, if any. /// /// This is used to bubble up precompile error messages when the diff --git a/crates/context/interface/src/local/lifecycle.rs b/crates/context/interface/src/local/lifecycle.rs new file mode 100644 index 0000000000..47a82e5488 --- /dev/null +++ b/crates/context/interface/src/local/lifecycle.rs @@ -0,0 +1,635 @@ +//! The start lifecycle revm keeps in its [`FrameStack`]: the open start of the transaction and +//! of each frame on the stack, with the sequence their identities come from. +//! +//! The record decides nothing a consumer computes: it pairs every settlement with the start it +//! closes, and refuses every step that would break the pairing ([`StartLifecycleError`]). + +use super::FrameStack; +use crate::host::{FrameSettle, FrameSplit, LifecycleEnd, SettleStatus}; +use std::vec::Vec; + +/// A start revm opened and has not settled, with what an inspector did to it so far. +/// +/// Its identity is the record's: it can be read, not changed. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] +pub struct PendingStart { + id: u32, + inspector_answer: bool, + gas_replaced: bool, + outcome_rebuilt: bool, +} + +impl PendingStart { + /// The start's identity ([`FrameSplit::id`]). + #[inline] + pub const fn id(&self) -> u32 { + self.id + } + + /// Whether an inspector answered the start ([`FrameSettle::inspector_answer`]). + #[inline] + pub const fn inspector_answer(&self) -> bool { + self.inspector_answer + } + + /// Whether an inspector's end callbacks replaced the result's gas + /// ([`FrameSettle::gas_replaced`]). + #[inline] + pub const fn gas_replaced(&self) -> bool { + self.gas_replaced + } + + /// Whether an inspector's end callbacks rebuilt the result's outcome + /// ([`FrameSettle::outcome_rebuilt`]). + #[inline] + pub const fn outcome_rebuilt(&self) -> bool { + self.outcome_rebuilt + } + + /// Records that an inspector answered the start. + #[inline] + pub const fn set_inspector_answer(&mut self) { + self.inspector_answer = true; + } + + /// Records that an inspector's end callbacks replaced the result's gas. + #[inline] + pub const fn set_gas_replaced(&mut self) { + self.gas_replaced = true; + } + + /// Records that an inspector's end callbacks rebuilt the result's outcome. + #[inline] + pub const fn set_outcome_rebuilt(&mut self) { + self.outcome_rebuilt = true; + } +} + +/// Why the start lifecycle refused a step. Each is a fatal error of the transaction: the step +/// would have paired a settlement with the wrong start, or with none. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +#[non_exhaustive] +pub enum StartLifecycleError { + /// The transaction's sequence of identities is exhausted: it has opened `u32::MAX` starts. + Exhausted, + /// A start opened where one is still open: a settlement or a boundary was missed, such as an + /// error dropped without the cleanup that discards the lifecycle. + Stale, + /// A settlement found no open start: the start was never opened, or already settled. + NotOpen, + /// A child start opened under a frame that has no start of its own: a runner drove the + /// transaction's frame without opening the transaction's start first. + NoParent, + /// The successful boundary found a start still open: a settlement was missed. + Unsettled, +} + +impl core::fmt::Display for StartLifecycleError { + fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { + f.write_str(match self { + Self::Exhausted => "start lifecycle: the transaction's identities are exhausted", + Self::Stale => "start lifecycle: a start opened where one is still open", + Self::NotOpen => "start lifecycle: a settlement found no open start", + Self::NoParent => { + "start lifecycle: a child start opened under a frame with no start (open the \ + transaction's start first)" + } + Self::Unsettled => "start lifecycle: the transaction ended with a start open", + }) + } +} + +impl core::error::Error for StartLifecycleError {} + +/// The record: the transaction's start and the open start of each frame on the stack, the child +/// it is making. +#[derive(Clone, Debug, Default)] +pub(super) struct StartLifecycle { + /// The last identity allocated in the transaction, 0 before the first. The first start opened + /// is always the transaction's, so a lifecycle is under way exactly when this is not 0. + last: u32, + /// How many of `children`'s slots hold an open start. + open_children: u32, + /// The transaction's start. + root: Option<PendingStart>, + /// The open start of the frame at each stack index. Its length grows with the room the frame + /// stack has ([`FrameStack::frame_room`]), or by the slots the frames need for zero-sized + /// frames, and never shrinks, so frames and transactions reuse the slots without resizing. + children: Vec<Option<PendingStart>>, +} + +impl StartLifecycle { + #[inline] + const fn active(&self) -> bool { + self.last != 0 + } + + /// The slot the next start opens in, and the next settlement closes: the transaction's on an + /// empty stack, else that of the frame on top, at `index`. + #[inline] + fn slot(&mut self, index: Option<usize>) -> Option<&mut Option<PendingStart>> { + match index { + None => Some(&mut self.root), + Some(i) => self.children.get_mut(i), + } + } + + #[inline] + const fn any_open(&self) -> bool { + self.root.is_some() || self.open_children != 0 + } + + #[inline] + fn reset(&mut self) { + self.last = 0; + self.root = None; + if self.open_children != 0 { + self.discard_children(); + } + } + + /// Empties the children's slots, which only a discarded lifecycle leaves open. + #[cold] + #[inline(never)] + fn discard_children(&mut self) { + self.children.fill(None); + self.open_children = 0; + } + + /// Gives the record `len` slots: a slot for every frame the stack has room for, at the first + /// child start and the first after the frame stack grew. + #[cold] + #[inline(never)] + fn grow_children(&mut self, len: usize) { + self.children.resize(len, None); + } +} + +impl<T> FrameStack<T> { + /// How many frames the stack has room for before its vector reallocates: the slots the record + /// gives the children when it grows, so that it grows with the stack. A vector of zero-sized + /// frames never reallocates and reports a capacity of `usize::MAX`, which names no room: the + /// record then grows by the slots its frames need. + #[inline] + const fn frame_room(&self) -> usize { + if size_of::<T>() == 0 { + 0 + } else { + self.stack.capacity() + } + } + + /// Opens the start of the frame the next init makes, at `depth`: the child of the frame on + /// top of the stack, or the transaction's start when the stack is empty. Returns the split to + /// hand to [`Host::frame_split`](crate::Host::frame_split). + /// + /// A frame has at most one open start, and so has the transaction. A failed open changes + /// nothing. + /// + /// # Errors + /// + /// [`StartLifecycleError::Exhausted`] once the transaction opened `u32::MAX` starts, + /// [`StartLifecycleError::Stale`] when the slot already holds an open start, and + /// [`StartLifecycleError::NoParent`] when the frame on top has no start of its own. + #[inline] + pub fn open_start(&mut self, depth: usize) -> Result<FrameSplit, StartLifecycleError> { + let room = self.frame_room(); + let record = &mut self.lifecycle; + let id = record + .last + .checked_add(1) + .ok_or(StartLifecycleError::Exhausted)?; + let start = Some(PendingStart { + id, + ..Default::default() + }); + let parent = match self.index { + None => { + if record.root.is_some() { + return Err(StartLifecycleError::Stale); + } + record.root = start; + None + } + Some(i) => { + let parent = match i { + 0 => record.root, + _ => record.children.get(i - 1).copied().flatten(), + }; + let Some(parent) = parent else { + return Err(StartLifecycleError::NoParent); + }; + if i >= record.children.len() { + record.grow_children(room.max(i + 1)); + } + let slot = &mut record.children[i]; + if slot.is_some() { + return Err(StartLifecycleError::Stale); + } + *slot = start; + record.open_children += 1; + Some(parent.id) + } + }; + record.last = id; + Ok(FrameSplit { id, parent, depth }) + } + + /// Closes the start the next settlement closes ([`pending_start`](Self::pending_start)), that + /// of a frame at `depth` which settled with `status`, into a caller whose gas held + /// `held_reservoir` just before. Returns the settlement to hand to + /// [`Host::frame_settle`](crate::Host::frame_settle), with what the start's record says an + /// inspector did to it. + /// + /// # Errors + /// + /// [`StartLifecycleError::NotOpen`] when no start is open there. + #[inline] + pub fn close_start( + &mut self, + depth: usize, + status: SettleStatus, + created: Option<bool>, + held_reservoir: u64, + ) -> Result<FrameSettle, StartLifecycleError> { + let record = &mut self.lifecycle; + let start = match self.index { + None => record.root.take(), + Some(i) => { + let start = record.children.get_mut(i).and_then(Option::take); + if start.is_some() { + record.open_children -= 1; + } + start + } + } + .ok_or(StartLifecycleError::NotOpen)?; + Ok(FrameSettle { + id: start.id, + depth, + status, + created, + inspector_answer: start.inspector_answer, + gas_replaced: start.gas_replaced, + outcome_rebuilt: start.outcome_rebuilt, + held_reservoir, + }) + } + + /// The start the next settlement closes: the open start of the frame on top of the stack, the + /// child it is making, or the transaction's start when the stack is empty. + #[inline] + pub fn pending_start(&mut self) -> Option<&mut PendingStart> { + self.lifecycle.slot(self.index).and_then(Option::as_mut) + } + + /// The start the frame on top of the stack runs for: the open start of the frame below it, or + /// the transaction's start for the frame at the bottom. + #[inline] + pub fn running_start(&mut self) -> Option<&mut PendingStart> { + match self.index? { + 0 => self.lifecycle.root.as_mut(), + i => self + .lifecycle + .children + .get_mut(i - 1) + .and_then(Option::as_mut), + } + } + + /// Whether a transaction's lifecycle is under way: its first start opened, and neither + /// boundary ended it. + #[inline] + pub const fn lifecycle_active(&self) -> bool { + self.lifecycle.active() + } + + /// Whether every start opened in the transaction has settled. + #[inline] + pub const fn lifecycle_settled(&self) -> bool { + !self.lifecycle.any_open() + } + + /// The successful boundary: ends the lifecycle and resets the record for the next + /// transaction. Returns the end to hand to + /// [`Host::frame_lifecycle_end`](crate::Host::frame_lifecycle_end), + /// [`LifecycleEnd::Settled`], or `None` when no lifecycle was under way. + /// + /// # Errors + /// + /// [`StartLifecycleError::Unsettled`] when a start is still open. The record is left as it + /// is, for [`discard_lifecycle`](Self::discard_lifecycle). + #[inline] + pub fn settle_lifecycle(&mut self) -> Result<Option<LifecycleEnd>, StartLifecycleError> { + if self.lifecycle.any_open() { + return Err(StartLifecycleError::Unsettled); + } + let end = self.lifecycle.active().then_some(LifecycleEnd::Settled); + self.lifecycle.reset(); + Ok(end) + } + + /// The fatal boundary: discards the starts still open, ends the lifecycle and resets the + /// record for the next transaction. Returns the end to hand to + /// [`Host::frame_lifecycle_end`](crate::Host::frame_lifecycle_end), + /// [`LifecycleEnd::Discarded`], or `None` when no lifecycle was under way, so a second discard + /// owes nothing. + /// + /// It resets the lifecycle only: the frame stack's index is [`clear`](Self::clear)'s. + #[inline] + #[must_use = "a lifecycle that was under way owes the consumer its end"] + pub fn discard_lifecycle(&mut self) -> Option<LifecycleEnd> { + let end = self.lifecycle.active().then_some(LifecycleEnd::Discarded); + self.lifecycle.reset(); + end + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// A stack with frames at indices `0..frames`, as revm's loop builds it. + fn stack(frames: usize) -> FrameStack<u8> { + let mut stack = FrameStack::new_prealloc(frames.max(1)); + if frames > 0 { + let token = stack.start_init().consume(); + unsafe { stack.end_init(token) }; + for _ in 1..frames { + let token = stack.get_next().consume(); + unsafe { stack.push(token) }; + } + } + stack + } + + fn split(id: u32, parent: Option<u32>, depth: usize) -> FrameSplit { + FrameSplit { id, parent, depth } + } + + /// Opens the transaction's start and one child per frame, as a nested run does. + fn open_nested(stack: &mut FrameStack<u8>, frames: usize) { + stack.clear(); + stack.open_start(0).unwrap(); + for i in 0..frames { + stack.index = Some(i); + stack.open_start(i + 1).unwrap(); + } + } + + #[test] + fn test_a_nested_run_opens_one_start_per_frame_under_its_parent() { + let mut stack = stack(2); + stack.clear(); + assert_eq!(stack.open_start(0), Ok(split(1, None, 0))); + stack.index = Some(0); + assert_eq!(stack.open_start(1), Ok(split(2, Some(1), 1))); + stack.index = Some(1); + assert_eq!(stack.open_start(2), Ok(split(3, Some(2), 2))); + assert!(stack.lifecycle_active()); + assert!(!stack.lifecycle_settled()); + assert_eq!(stack.running_start().map(|s| s.id()), Some(2)); + assert_eq!(stack.pending_start().map(|s| s.id()), Some(3)); + } + + #[test] + fn test_each_settlement_closes_the_start_of_its_slot_innermost_first() { + let mut stack = stack(2); + open_nested(&mut stack, 2); + let settled = stack.close_start(2, SettleStatus::Revert, None, 7).unwrap(); + assert_eq!( + (settled.id, settled.depth, settled.status), + (3, 2, SettleStatus::Revert) + ); + assert_eq!(settled.held_reservoir, 7); + stack.index = Some(0); + let settled = stack + .close_start(1, SettleStatus::Ok, Some(true), 0) + .unwrap(); + assert_eq!((settled.id, settled.created), (2, Some(true))); + stack.clear(); + assert_eq!( + stack + .close_start(0, SettleStatus::Halt, None, 0) + .map(|s| s.id), + Ok(1) + ); + assert!(stack.lifecycle_settled()); + assert!( + stack.lifecycle_active(), + "only a boundary ends the lifecycle" + ); + } + + #[test] + fn test_identities_are_never_reused_within_a_transaction() { + let mut stack = stack(1); + open_nested(&mut stack, 1); + stack.close_start(1, SettleStatus::Ok, None, 0).unwrap(); + assert_eq!( + stack.open_start(1).map(|s| s.id), + Ok(3), + "the frame's second child" + ); + stack.close_start(1, SettleStatus::Ok, None, 0).unwrap(); + stack.clear(); + stack.close_start(0, SettleStatus::Ok, None, 0).unwrap(); + assert_eq!(stack.settle_lifecycle(), Ok(Some(LifecycleEnd::Settled))); + assert_eq!( + stack.open_start(0).map(|s| s.id), + Ok(1), + "the next transaction restarts" + ); + } + + #[test] + fn test_a_second_start_in_an_occupied_slot_is_stale() { + let mut stack = stack(1); + open_nested(&mut stack, 1); + assert_eq!(stack.open_start(1), Err(StartLifecycleError::Stale)); + stack.clear(); + assert_eq!(stack.open_start(0), Err(StartLifecycleError::Stale)); + stack.index = Some(0); + assert_eq!( + stack.pending_start().map(|s| s.id()), + Some(2), + "nothing changed" + ); + } + + #[test] + fn test_a_child_under_a_frame_with_no_start_has_no_parent() { + let mut stack = stack(2); + assert_eq!(stack.open_start(1), Err(StartLifecycleError::NoParent)); + stack.clear(); + stack.open_start(0).unwrap(); + stack.index = Some(1); + assert_eq!(stack.open_start(2), Err(StartLifecycleError::NoParent)); + assert!(stack.pending_start().is_none(), "nothing opened"); + } + + #[test] + fn test_a_settlement_with_nothing_open_is_refused() { + let mut stack = stack(1); + stack.clear(); + assert_eq!( + stack.close_start(0, SettleStatus::Ok, None, 0), + Err(StartLifecycleError::NotOpen) + ); + stack.open_start(0).unwrap(); + stack.close_start(0, SettleStatus::Ok, None, 0).unwrap(); + assert_eq!( + stack.close_start(0, SettleStatus::Ok, None, 0), + Err(StartLifecycleError::NotOpen), + "a start settles once" + ); + stack.index = Some(0); + assert_eq!( + stack.close_start(1, SettleStatus::Ok, None, 0), + Err(StartLifecycleError::NotOpen), + "a frame that made no child" + ); + } + + #[test] + fn test_an_exhausted_sequence_opens_nothing() { + let mut stack = stack(1); + open_nested(&mut stack, 0); + stack.lifecycle.last = u32::MAX - 1; + stack.index = Some(0); + assert_eq!( + stack.open_start(1).map(|s| s.id), + Ok(u32::MAX), + "the last identity" + ); + stack.close_start(1, SettleStatus::Ok, None, 0).unwrap(); + assert_eq!(stack.open_start(1), Err(StartLifecycleError::Exhausted)); + assert!(stack.pending_start().is_none(), "nothing opened"); + assert_eq!(stack.discard_lifecycle(), Some(LifecycleEnd::Discarded)); + stack.clear(); + assert_eq!( + stack.open_start(0).map(|s| s.id), + Ok(1), + "the next transaction restarts" + ); + } + + #[test] + fn test_the_successful_boundary_needs_every_start_settled() { + let mut stack = stack(1); + open_nested(&mut stack, 1); + stack.close_start(1, SettleStatus::Ok, None, 0).unwrap(); + stack.clear(); + assert_eq!( + stack.settle_lifecycle(), + Err(StartLifecycleError::Unsettled) + ); + assert!( + stack.lifecycle_active(), + "the record is left for the discard" + ); + assert_eq!(stack.pending_start().map(|s| s.id()), Some(1)); + stack.close_start(0, SettleStatus::Ok, None, 0).unwrap(); + assert_eq!(stack.settle_lifecycle(), Ok(Some(LifecycleEnd::Settled))); + assert!(!stack.lifecycle_active()); + assert_eq!( + stack.settle_lifecycle(), + Ok(None), + "no lifecycle is under way" + ); + } + + #[test] + fn test_the_fatal_boundary_discards_once() { + let mut stack = stack(2); + open_nested(&mut stack, 2); + assert_eq!(stack.discard_lifecycle(), Some(LifecycleEnd::Discarded)); + assert_eq!( + stack.discard_lifecycle(), + None, + "a second discard owes nothing" + ); + assert!(stack.lifecycle_settled() && !stack.lifecycle_active()); + assert_eq!(stack.index(), Some(1), "the frame stack is clear's"); + stack.clear(); + assert_eq!(stack.open_start(0).map(|s| s.id), Ok(1)); + } + + /// The children's slots are sized with the frame stack and outlive the transaction: no + /// boundary shrinks them, and a discard empties them. + #[test] + fn test_the_slots_outlive_the_transaction() { + // Two frames on a stack with room for eight. + let mut stack = FrameStack::<u8>::new_prealloc(8); + let token = stack.start_init().consume(); + unsafe { stack.end_init(token) }; + let token = stack.get_next().consume(); + unsafe { stack.push(token) }; + open_nested(&mut stack, 2); + let slots = stack.lifecycle.children.len(); + assert!( + slots >= stack.stack.capacity(), + "the first child gives a slot to every frame the stack has room for: {slots} of {}", + stack.stack.capacity() + ); + assert_eq!(stack.discard_lifecycle(), Some(LifecycleEnd::Discarded)); + assert_eq!(stack.lifecycle.children.len(), slots); + assert!(stack.lifecycle.children.iter().all(Option::is_none)); + + open_nested(&mut stack, 2); + stack.close_start(2, SettleStatus::Ok, None, 0).unwrap(); + stack.index = Some(0); + stack.close_start(1, SettleStatus::Ok, None, 0).unwrap(); + stack.clear(); + stack.close_start(0, SettleStatus::Ok, None, 0).unwrap(); + assert_eq!(stack.settle_lifecycle(), Ok(Some(LifecycleEnd::Settled))); + assert_eq!(stack.lifecycle.children.len(), slots); + } + + /// A stack of zero-sized frames, whose vector reports a capacity of `usize::MAX`, opens its + /// children as any stack does. + #[test] + fn test_a_stack_of_zero_sized_frames_opens_its_children() { + let mut stack = FrameStack::<()>::new_prealloc(1); + assert_eq!(stack.open_start(0).map(|s| s.id), Ok(1)); + let token = stack.start_init().consume(); + unsafe { stack.end_init(token) }; + assert_eq!(stack.open_start(1).map(|s| s.id), Ok(2)); + } + + /// A stack of zero-sized frames gets one slot per frame a child opened under, the slots its + /// frames need, rather than the slots its vector's capacity would name. + #[test] + fn test_a_stack_of_zero_sized_frames_grows_its_slots_by_the_frames() { + let mut stack = FrameStack::<()>::new_prealloc(4); + stack.open_start(0).unwrap(); + let token = stack.start_init().consume(); + unsafe { stack.end_init(token) }; + for depth in 1..=4 { + if depth > 1 { + let token = stack.get_next().consume(); + unsafe { stack.push(token) }; + } + assert_eq!(stack.open_start(depth).map(|s| s.id), Ok(depth as u32 + 1)); + } + assert_eq!(stack.lifecycle.children.len(), 4); + assert_eq!(stack.discard_lifecycle(), Some(LifecycleEnd::Discarded)); + assert!(stack.lifecycle.children.iter().all(Option::is_none)); + } + + #[test] + fn test_what_an_inspector_did_reaches_the_settlement() { + let mut stack = stack(1); + open_nested(&mut stack, 1); + let pending = stack.pending_start().unwrap(); + pending.set_inspector_answer(); + pending.set_outcome_rebuilt(); + let running = stack.running_start().unwrap(); + running.set_gas_replaced(); + let child = stack.close_start(1, SettleStatus::Ok, None, 0).unwrap(); + assert!(child.inspector_answer && child.outcome_rebuilt && !child.gas_replaced); + stack.clear(); + let root = stack.close_start(0, SettleStatus::Ok, None, 0).unwrap(); + assert!(!root.inspector_answer && !root.outcome_rebuilt && root.gas_replaced); + } +} diff --git a/crates/context/interface/src/local/mirror.rs b/crates/context/interface/src/local/mirror.rs new file mode 100644 index 0000000000..0316825e66 --- /dev/null +++ b/crates/context/interface/src/local/mirror.rs @@ -0,0 +1,228 @@ +//! A consumer-side check of the start lifecycle: a stack driven only by the lifecycle hooks, as a +//! consumer's own ledger would be, which asserts that every event the hooks receive fits it. +//! +//! revm's own context keeps one in its local context in debug builds and feeds it from its +//! [`Host`](crate::Host) hooks ([`LocalContextTr::lifecycle_mirror`](super::LocalContextTr::lifecycle_mirror)); +//! a release build keeps none. + +use crate::host::{FrameSettle, FrameSplit, LifecycleEnd}; +use std::vec::Vec; + +/// An event of the start lifecycle, as a hook received it. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum LifecycleEvent { + /// [`Host::frame_split`](crate::Host::frame_split). + Split(FrameSplit), + /// [`Host::frame_settle`](crate::Host::frame_settle). + Settle(FrameSettle), + /// [`Host::frame_lifecycle_end`](crate::Host::frame_lifecycle_end). + End(LifecycleEnd), +} + +/// The starts the hooks reported open, innermost last, and the events of the lifecycle under way +/// or, once it ended, of the last one. +/// +/// It lives in the context, so a context cloned for a simulation carries a copy. The simulation's +/// first event is its own transaction's start, which resets the copy: each execution is checked +/// from its own first start, and the original context's mirror is untouched. +#[derive(Clone, Debug, Default)] +pub struct LifecycleMirror { + open: Vec<(u32, usize)>, + events: Vec<LifecycleEvent>, +} + +impl LifecycleMirror { + /// Checks a split and pushes its start. The transaction's start, the one with no parent, + /// begins a lifecycle: it must be at depth 0, and it resets the mirror. A child start's + /// parent must be the start on top, one frame shallower. + /// + /// # Panics + /// + /// When the split does not fit. + pub fn split(&mut self, split: &FrameSplit) { + match split.parent { + None => { + assert_eq!( + split.depth, 0, + "start lifecycle: the transaction's start {} at depth {}", + split.id, split.depth + ); + self.open.clear(); + self.events.clear(); + } + Some(parent) => { + let top = self.open.last().copied(); + assert_eq!( + top.map(|(id, _)| id), + Some(parent), + "start lifecycle: start {} opened under {parent} while {top:?} was on top", + split.id + ); + assert_eq!( + top.map(|(_, depth)| depth + 1), + Some(split.depth), + "start lifecycle: start {} at depth {} under a parent at {top:?}", + split.id, + split.depth + ); + } + } + self.open.push((split.id, split.depth)); + self.events.push(LifecycleEvent::Split(*split)); + } + + /// Checks a settlement and pops its start, which must be the one on top, at the same depth. + /// + /// # Panics + /// + /// When the settlement does not fit. + pub fn settle(&mut self, settle: &FrameSettle) { + let top = self.open.pop(); + assert_eq!( + top, + Some((settle.id, settle.depth)), + "start lifecycle: settled ({}, depth {}) while {top:?} was on top", + settle.id, + settle.depth + ); + self.events.push(LifecycleEvent::Settle(*settle)); + } + + /// Checks the end of a lifecycle: a settled one leaves no start open. Either end empties the + /// stack. + /// + /// # Panics + /// + /// When a lifecycle ends settled with a start open. + pub fn end(&mut self, end: LifecycleEnd) { + if end == LifecycleEnd::Settled { + assert!( + self.open.is_empty(), + "start lifecycle: settled with starts open: {:?}", + self.open + ); + } + self.open.clear(); + self.events.push(LifecycleEvent::End(end)); + } + + /// The events of the lifecycle under way or, once it ended, of the last one. + pub fn events(&self) -> &[LifecycleEvent] { + &self.events + } + + /// The starts open, innermost last, as `(identity, depth)`. + pub fn open(&self) -> &[(u32, usize)] { + &self.open + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::host::SettleStatus; + + fn split(id: u32, parent: Option<u32>, depth: usize) -> FrameSplit { + FrameSplit { id, parent, depth } + } + + fn settle(id: u32, depth: usize) -> FrameSettle { + FrameSettle { + id, + depth, + status: SettleStatus::Ok, + created: None, + inspector_answer: false, + gas_replaced: false, + outcome_rebuilt: false, + held_reservoir: 0, + } + } + + #[test] + fn test_a_paired_lifecycle_fits() { + let mut mirror = LifecycleMirror::default(); + mirror.split(&split(1, None, 0)); + mirror.split(&split(2, Some(1), 1)); + mirror.settle(&settle(2, 1)); + mirror.settle(&settle(1, 0)); + mirror.end(LifecycleEnd::Settled); + assert!(mirror.open().is_empty()); + assert_eq!(mirror.events().len(), 5); + } + + #[test] + fn test_the_transactions_start_resets_what_a_clone_brought() { + let mut mirror = LifecycleMirror::default(); + mirror.split(&split(1, None, 0)); + mirror.split(&split(2, Some(1), 1)); + let mut simulation = mirror.clone(); + simulation.split(&split(1, None, 0)); + assert_eq!(simulation.open(), &[(1, 0)]); + assert_eq!( + simulation.events(), + &[LifecycleEvent::Split(split(1, None, 0))] + ); + assert_eq!( + mirror.open(), + &[(1, 0), (2, 1)], + "the original is untouched" + ); + } + + #[test] + fn test_a_discarded_lifecycle_may_leave_starts_open() { + let mut mirror = LifecycleMirror::default(); + mirror.split(&split(1, None, 0)); + mirror.end(LifecycleEnd::Discarded); + assert!(mirror.open().is_empty()); + } + + #[test] + #[should_panic(expected = "the transaction's start 1 at depth 5")] + fn test_a_transaction_start_off_depth_zero_does_not_fit() { + LifecycleMirror::default().split(&split(1, None, 5)); + } + + #[test] + #[should_panic(expected = "start 2 at depth 3 under a parent at Some((1, 0))")] + fn test_a_child_off_its_parents_depth_does_not_fit() { + let mut mirror = LifecycleMirror::default(); + mirror.split(&split(1, None, 0)); + mirror.split(&split(2, Some(1), 3)); + } + + #[test] + #[should_panic(expected = "start 3 opened under 1 while Some((2, 1)) was on top")] + fn test_a_child_under_another_start_does_not_fit() { + let mut mirror = LifecycleMirror::default(); + mirror.split(&split(1, None, 0)); + mirror.split(&split(2, Some(1), 1)); + mirror.split(&split(3, Some(1), 1)); + } + + #[test] + #[should_panic(expected = "settled (1, depth 0) while Some((2, 1)) was on top")] + fn test_a_settlement_out_of_order_does_not_fit() { + let mut mirror = LifecycleMirror::default(); + mirror.split(&split(1, None, 0)); + mirror.split(&split(2, Some(1), 1)); + mirror.settle(&settle(1, 0)); + } + + #[test] + #[should_panic(expected = "settled (1, depth 27) while Some((1, 0)) was on top")] + fn test_a_settlement_off_its_splits_depth_does_not_fit() { + let mut mirror = LifecycleMirror::default(); + mirror.split(&split(1, None, 0)); + mirror.settle(&settle(1, 27)); + } + + #[test] + #[should_panic(expected = "settled with starts open: [(1, 0)]")] + fn test_a_settled_end_with_a_start_open_does_not_fit() { + let mut mirror = LifecycleMirror::default(); + mirror.split(&split(1, None, 0)); + mirror.end(LifecycleEnd::Settled); + } +} diff --git a/crates/context/src/cfg.rs b/crates/context/src/cfg.rs index 09a1ba63f1..1b2c1da3c3 100644 --- a/crates/context/src/cfg.rs +++ b/crates/context/src/cfg.rs @@ -186,6 +186,13 @@ pub struct CfgEnv<SPEC = SpecId> { /// [`CfgEnv::enable_amsterdam_eip7708`] does. #[cfg_attr(feature = "serde", serde(default))] pub legacy_journal_semantics: bool, + /// Credits every give-back of state or history gas to the reservoir alone, never to regular + /// gas: a refill, a failed frame's rollback and a reservoir a child returns. revm sets it on + /// the transaction's gas and on every frame's (`GasTracker::reservoir_only_give_backs`). For a + /// chain that keeps a frame's regular gas from rising within the frame; `false`, EIP-8037's + /// tracker, by default. + #[cfg_attr(feature = "serde", serde(default))] + pub reservoir_only_give_backs: bool, } impl CfgEnv { @@ -307,6 +314,7 @@ impl<SPEC> CfgEnv<SPEC> { amsterdam_eip7708_disabled: self.amsterdam_eip7708_disabled, amsterdam_eip8246_delayed_clear_disabled: self.amsterdam_eip8246_delayed_clear_disabled, legacy_journal_semantics: self.legacy_journal_semantics, + reservoir_only_give_backs: self.reservoir_only_give_backs, } } @@ -372,6 +380,13 @@ impl<SPEC> CfgEnv<SPEC> { self.legacy_journal_semantics = enable; self } + + /// Credits every give-back of state or history gas to the reservoir alone; see + /// [`CfgEnv::reservoir_only_give_backs`]. + pub const fn with_reservoir_only_give_backs(mut self, enable: bool) -> Self { + self.reservoir_only_give_backs = enable; + self + } } impl<SPEC: Into<SpecId> + Clone> CfgEnv<SPEC> { @@ -413,6 +428,7 @@ impl<SPEC: Into<SpecId> + Clone> CfgEnv<SPEC> { amsterdam_eip7708_disabled: false, amsterdam_eip8246_delayed_clear_disabled: false, legacy_journal_semantics: false, + reservoir_only_give_backs: false, } } @@ -647,6 +663,11 @@ impl<SPEC: Into<SpecId> + Clone> Cfg for CfgEnv<SPEC> { fn legacy_journal_semantics(&self) -> bool { self.legacy_journal_semantics } + + #[inline] + fn reservoir_only_give_backs(&self) -> bool { + self.reservoir_only_give_backs + } } impl<SPEC: Default + Into<SpecId> + Clone> Default for CfgEnv<SPEC> { diff --git a/crates/context/src/context.rs b/crates/context/src/context.rs index acf70ce460..bcf1b8f333 100644 --- a/crates/context/src/context.rs +++ b/crates/context/src/context.rs @@ -438,6 +438,33 @@ impl< LOCAL: LocalContextTr, > Host for Context<BLOCK, TX, CFG, DB, JOURNAL, CHAIN, LOCAL> { + /* Start lifecycle: in debug builds, the local context's mirror checks every event. */ + + #[cfg(debug_assertions)] + fn frame_split(&mut self, split: &context_interface::host::FrameSplit) { + if let Some(mirror) = self.local.lifecycle_mirror() { + mirror.split(split); + } + } + + #[cfg(debug_assertions)] + fn frame_settle( + &mut self, + settle: &context_interface::host::FrameSettle, + _gas: &mut context_interface::cfg::gas::GasTracker, + ) { + if let Some(mirror) = self.local.lifecycle_mirror() { + mirror.settle(settle); + } + } + + #[cfg(debug_assertions)] + fn frame_lifecycle_end(&mut self, end: context_interface::host::LifecycleEnd) { + if let Some(mirror) = self.local.lifecycle_mirror() { + mirror.end(end); + } + } + /* Block */ fn basefee(&self) -> U256 { diff --git a/crates/context/src/local.rs b/crates/context/src/local.rs index 1026721b73..0fdede1fd9 100644 --- a/crates/context/src/local.rs +++ b/crates/context/src/local.rs @@ -1,4 +1,6 @@ //! Local context that is filled by execution. +#[cfg(debug_assertions)] +use context_interface::LifecycleMirror; use context_interface::LocalContextTr; use core::cell::RefCell; use std::{rc::Rc, string::String, vec::Vec}; @@ -10,6 +12,10 @@ pub struct LocalContext { pub shared_memory_buffer: Rc<RefCell<Vec<u8>>>, /// Optional precompile error message to bubble up. pub precompile_error_message: Option<String>, + /// The start lifecycle's mirror, in debug builds only + /// ([`LocalContextTr::lifecycle_mirror`]). + #[cfg(debug_assertions)] + lifecycle_mirror: LifecycleMirror, } impl Default for LocalContext { @@ -17,6 +23,8 @@ impl Default for LocalContext { Self { shared_memory_buffer: Rc::new(RefCell::new(Vec::with_capacity(1024 * 4))), precompile_error_message: None, + #[cfg(debug_assertions)] + lifecycle_mirror: LifecycleMirror::default(), } } } @@ -28,6 +36,12 @@ impl LocalContextTr for LocalContext { self.precompile_error_message = None; } + #[cfg(debug_assertions)] + #[inline] + fn lifecycle_mirror(&mut self) -> Option<&mut LifecycleMirror> { + Some(&mut self.lifecycle_mirror) + } + fn shared_memory_buffer(&self) -> &Rc<RefCell<Vec<u8>>> { &self.shared_memory_buffer } diff --git a/crates/database/src/states/bundle_account.rs b/crates/database/src/states/bundle_account.rs index 4254770dbd..0c9c537da5 100644 --- a/crates/database/src/states/bundle_account.rs +++ b/crates/database/src/states/bundle_account.rs @@ -372,6 +372,6 @@ impl BundleAccount { } }; - account_revert.and_then(|acc| if acc.is_empty() { None } else { Some(acc) }) + account_revert.filter(|acc| !acc.is_empty()) } } diff --git a/crates/handler/src/evm.rs b/crates/handler/src/evm.rs index a62b2e15c9..70a69faf04 100644 --- a/crates/handler/src/evm.rs +++ b/crates/handler/src/evm.rs @@ -1,11 +1,16 @@ use crate::{ - instructions::InstructionProvider, item_or_result::FrameInitOrResult, EthFrame, FrameResult, - ItemOrResult, PrecompileProvider, + instructions::InstructionProvider, + item_or_result::FrameInitOrResult, + lifecycle::{close_frame_start, Returning}, + EthFrame, FrameResult, ItemOrResult, PrecompileProvider, }; use auto_impl::auto_impl; use context::{ContextTr, Database, Evm, FrameStack}; use context_interface::context::ContextError; -use interpreter::{interpreter::EthInterpreter, interpreter_action::FrameInit, InterpreterResult}; +use interpreter::{ + interpreter::EthInterpreter, interpreter_action::FrameInit, InterpreterAction, + InterpreterResult, +}; /// Type alias for database error within a context pub type ContextDbError<CTX> = ContextError<ContextTrDbError<CTX>>; @@ -113,12 +118,54 @@ pub trait EvmTr { /// Run the frame from the top of the stack. Returns the frame init or result. /// /// If frame has returned result it would mark it as finished. + /// + /// A frame init it returns opens the child's start under the frame's own + /// ([`lifecycle::open_frame_start`](crate::lifecycle::open_frame_start)); a + /// reimplementation makes the same call for the init it consumed. fn frame_run( &mut self, ) -> Result<FrameInitOrResult<Self::Frame>, ContextDbError<Self::Context>>; + /// Receives the result of the frame on top of the stack as it leaves the frame's own run, + /// before anything else sees it. What it leaves in `result` is what the inspector and the + /// caller see. + /// + /// The handler loops call it once for each frame that ran and returns, after the frame's + /// last action was processed, while the frame is still on top of the stack: + /// `Handler::run_exec_loop` when [`frame_run`](EvmTr::frame_run) returns a result, and the + /// provided inspected run (`InspectorEvmTr::inspect_frame_run`) before the inspector's + /// `call_end`, `create_end` and `frame_end`. On both paths it runs before + /// [`frame_return_result`](EvmTr::frame_return_result). + /// + /// Whether the frame is marked finished differs by path and frame type, so an implementation + /// does not rely on the mark: `frame_run` marks it before the plain loop calls this, and the + /// inspected run marks a frame with an `EthFrame` after the inspector's end callbacks. + /// + /// The calls are on the EVM the loops run, so an EVM type that delegates `frame_run` to an + /// inner EVM still has its own method called. An override of `run_exec_loop` or of + /// `inspect_frame_run` calls it at the same point itself; one that delegates + /// `inspect_frame_run` to an inner EVM reaches the inner EVM's method instead. + /// + /// A result given without a run does not reach it: [`frame_init`](EvmTr::frame_init) + /// returns those (a start the handler refuses, a precompile's answer, an inspector's answer), + /// so `frame_init`, or the inspector, has them first. + /// + /// The default does nothing. + #[inline] + fn frame_run_result( + &mut self, + result: &mut <Self::Frame as FrameTr>::FrameResult, + ) -> Result<(), ContextDbError<Self::Context>> { + let _ = result; + Ok(()) + } + /// Returns the result of the frame to the caller. Frame is popped from the frame stack. /// Consumes the frame result or returns it if there is more frames to run. + /// + /// A result returned into a caller closes the start the caller opened for it + /// ([`lifecycle::close_frame_start`](crate::lifecycle::close_frame_start)); a + /// reimplementation makes the same call after it returns the result. fn frame_return_result( &mut self, result: <Self::Frame as FrameTr>::FrameResult, @@ -195,7 +242,8 @@ where })) } - /// Run the frame from the top of the stack. Returns the frame init or result. + /// Run the frame from the top of the stack. Returns the frame init or result, and opens the + /// start of a frame init. #[inline] fn frame_run(&mut self) -> Result<FrameInitOrResult<Self::Frame>, ContextDbError<CTX>> { let frame = self.frame_stack.get(); @@ -208,14 +256,27 @@ where context, ); - frame.process_next_action(context, action).inspect(|i| { - if i.is_result() { - frame.set_finished(true); - } - }) + // The frame's `NewFrame` action is consumed here: the child's start opens before the + // action becomes the child's init, whose depth is one below the frame's. Reading only the + // action's kind and the frame's depth leaves the init to be built in the return value. + let frame = if let InterpreterAction::NewFrame(_) = &action { + let depth = frame.depth + 1; + crate::lifecycle::open_start(&mut self.ctx, &mut self.frame_stack, depth)?; + self.frame_stack.get() + } else { + frame + }; + frame + .process_next_action(&mut self.ctx, action) + .inspect(|i| { + if i.is_result() { + frame.set_finished(true); + } + }) } - /// Returns the result of the frame to the caller. Frame is popped from the frame stack. + /// Returns the result of the frame to the caller, and closes its start. Frame is popped from + /// the frame stack. #[inline] fn frame_return_result( &mut self, @@ -227,9 +288,12 @@ where if self.frame_stack.index().is_none() { return Ok(Some(result)); } - self.frame_stack - .get() - .return_result::<_, ContextDbError<Self::Context>>(&mut self.ctx, result)?; + let caller = self.frame_stack.get(); + let returning = Returning::new(&result, caller); + caller.return_result::<_, ContextDbError<Self::Context>>(&mut self.ctx, result)?; + close_frame_start(&mut self.ctx, &mut self.frame_stack, returning, |caller| { + caller + })?; Ok(None) } } diff --git a/crates/handler/src/execution.rs b/crates/handler/src/execution.rs index 56b8a38bce..6b25be989b 100644 --- a/crates/handler/src/execution.rs +++ b/crates/handler/src/execution.rs @@ -12,6 +12,9 @@ use primitives::{Address, TxKind}; use state::Bytecode; use std::boxed::Box; +mod first_frame; +pub use first_frame::settle_first_frame; + /// Creates the first [`FrameInput`] from the transaction and the /// transaction-level `gas`, forwarding all remaining regular gas and the /// reservoir to the frame. diff --git a/crates/handler/src/execution/first_frame.rs b/crates/handler/src/execution/first_frame.rs new file mode 100644 index 0000000000..bfada2891f --- /dev/null +++ b/crates/handler/src/execution/first_frame.rs @@ -0,0 +1,104 @@ +//! The settlement of the transaction's frame into the transaction-level gas, which +//! [`Handler::last_frame_result`](crate::Handler::last_frame_result) makes on mainnet and a chain's +//! own handler makes by calling it. + +use crate::{frame::handle_reservoir_remaining_gas, FrameResult}; +use context::result::FromStringError; +use context_interface::{context::take_error, ContextTr, Database}; +use interpreter::GasTracker; +use std::string::ToString; + +/// Settles the transaction's frame, the first frame, into the transaction-level `gas`, every step +/// of [`Handler::last_frame_result`](crate::Handler::last_frame_result) but the last: the copy of +/// `gas` into `frame_result`, which is the caller's. +/// +/// The steps, each with the halt rule it takes: +/// - `gas` spends all its regular gas, which was forwarded to the frame, and the frame settles +/// into it as a child settles into its caller ([`handle_reservoir_remaining_gas`]): a failing +/// frame rolls back its state gas and history gas, a halt consumes its regular gas, and what +/// the frame left returns to `gas`, its reservoir in place of the one `gas` gave it; +/// - the EIP-2780 refundable first-frame charge is refunded when no account leaf was created, +/// priced through [`Host::state_gas_charge`](context_interface::Host::state_gas_charge) as it +/// was charged; after a halt the regular gas the refund credited is consumed. With give-backs +/// to the reservoir alone ([`GasTracker::reservoir_only_give_backs`]) a refund credits no regular +/// gas, so after a halt only the part of the charge the reservoir paid returns, into the +/// reservoir, and the part regular gas paid is consumed with the regular gas. +/// +/// A chain whose handler overrides `last_frame_result` calls this rather than copying the mainnet +/// body, so a step the fork adds here reaches its handler too. It applies its own rules to `gas` +/// after this returns and then copies `gas` into the frame's result, as op-revm's handler does +/// with its pre-Regolith deposit rule. +/// +/// Inlined, so `last_frame_result` compiles to the code it had while these steps were its body. +/// +/// # Errors +/// +/// A failure the context recorded before the EIP-2780 refund is returned first, so a failing +/// refund lookup cannot overwrite it. A failed lookup returns the cause the context recorded, or +/// an error saying the lookup failed. +#[inline(always)] +pub fn settle_first_frame<CTX, ERROR>( + context: &mut CTX, + frame_result: &mut FrameResult, + gas: &mut GasTracker, +) -> Result<(), ERROR> +where + CTX: ContextTr, + ERROR: From<<CTX::Db as Database>::Error> + FromStringError, +{ + let instruction_result = frame_result.instruction_result(); + + // What the transaction's regular gas paid of the charges made before the frame, read before + // the frame's own count joins it below. + let paid_before_the_frame = gas.state_gas_spilled(); + + // All regular gas was forwarded to the first frame: consume it on the + // transaction-level gas; the settle below returns the frame's unused + // part. + gas.spend_all(); + + // Settle the frame into the transaction-level gas like a parent frame. + handle_reservoir_remaining_gas( + instruction_result, + gas, + frame_result.gas_mut().tracker_mut(), + ); + + // Refund the EIP-2780 refundable first-frame charge when no account + // leaf was created, exactly like `EthFrame::return_result` refunds + // the upfront CALL/CREATE state charges of inner frames. + if let Some(charge) = frame_result.refundable_state_gas_charge() { + // A failure the frame already recorded (a failed code deposit lookup, say) is + // returned first, as `EthFrame::return_result` does for inner frames, so a failing + // refund lookup cannot overwrite it. + take_error::<ERROR, _>(context.error())?; + // Priced through the same hook the charge went through. A failed lookup surfaces as + // an external error: the hook recorded the cause. + let Some(charge) = context.state_gas_charge(charge) else { + take_error::<ERROR, _>(context.error())?; + return Err(ERROR::from_string( + "state gas price lookup failed".to_string(), + )); + }; + // With give-backs to the reservoir alone, the part of the charge regular gas paid stays + // spent after a halt. The charge is the last one made before the frame, and every charge + // made there draws the reservoir first, so that part is the last of what the + // transaction's regular gas paid for state and history before the frame. Without the + // switch the refill below credits that part to `remaining`, which the halt consumes. + let consumed = if instruction_result.is_halt() && gas.reservoir_only_give_backs() { + core::cmp::min(charge, paid_before_the_frame) + } else { + 0 + }; + gas.refill_reservoir(charge); + // Unlike an inner frame's caller, the transaction ends here: an + // exceptional halt consumes all regular gas, including the + // spilled portion the refill just credited back to `remaining`. + if instruction_result.is_halt() { + gas.spend_all(); + gas.set_reservoir(gas.reservoir().saturating_sub(consumed)); + } + } + + Ok(()) +} diff --git a/crates/handler/src/frame.rs b/crates/handler/src/frame.rs index dc645c1540..0a79750ee3 100644 --- a/crates/handler/src/frame.rs +++ b/crates/handler/src/frame.rs @@ -18,7 +18,7 @@ use interpreter::{ interpreter_types::ReturnData, CallInput, CallInputs, CallOutcome, CallValue, CreateInputs, CreateOutcome, CreateScheme, FrameInput, Gas, GasTracker, InputsImpl, InstructionResult, Interpreter, InterpreterAction, - InterpreterResult, InterpreterTypes, SharedMemory, + InterpreterResult, InterpreterTypes, OutcomeMark, SharedMemory, }; use primitives::{ constants::CALL_STACK_LIMIT, @@ -159,8 +159,10 @@ impl EthFrame<EthInterpreter> { let reservoir_remaining_gas = inputs.reservoir; let charged_new_account_state_gas = inputs.charged_new_account_state_gas; let charged_state_gas_address = inputs.target_address; - let gas = + let reservoir_only_give_backs = ctx.cfg().reservoir_only_give_backs(); + let mut gas = Gas::new_with_regular_gas_and_reservoir(inputs.gas_limit, reservoir_remaining_gas); + gas.set_reservoir_only_give_backs(reservoir_only_give_backs); let return_result = |instruction_result: InstructionResult| { Ok(ItemOrResult::Result(FrameResult::Call(CallOutcome { @@ -174,6 +176,7 @@ impl EthFrame<EthInterpreter> { precompile_call_logs: Vec::new(), charged_new_account_state_gas, charged_state_gas_address, + start_mark: OutcomeMark::NONE, }))) }; @@ -209,7 +212,10 @@ impl EthFrame<EthInterpreter> { let is_static = inputs.is_static; let gas_limit = inputs.gas_limit; - if let Some(result) = precompiles.run(ctx, &inputs).map_err(ERROR::from_string)? { + if let Some(mut result) = precompiles.run(ctx, &inputs).map_err(ERROR::from_string)? { + result + .gas + .set_reservoir_only_give_backs(reservoir_only_give_backs); let mut logs = Vec::new(); if result.result.is_ok() { // Preserve the reservoir on the result gas so it can be reimbursed. @@ -228,6 +234,7 @@ impl EthFrame<EthInterpreter> { precompile_call_logs: logs, charged_new_account_state_gas, charged_state_gas_address, + start_mark: OutcomeMark::NONE, }))); } @@ -241,7 +248,8 @@ impl EthFrame<EthInterpreter> { } // Create interpreter and executes call and push new CallStackFrame. - this.get(EthFrame::invalid).clear( + let frame = this.get(EthFrame::invalid); + frame.clear( FrameData::Call(CallFrame { return_memory_range: inputs.return_memory_offset.clone(), }), @@ -256,6 +264,10 @@ impl EthFrame<EthInterpreter> { reservoir_remaining_gas, checkpoint, ); + frame + .interpreter + .gas + .set_reservoir_only_give_backs(reservoir_only_give_backs); Ok(ItemOrResult::Item(this.consume())) } @@ -274,6 +286,7 @@ impl EthFrame<EthInterpreter> { ) -> Result<ItemOrResult<FrameToken, FrameResult>, ERROR> { let reservoir_remaining_gas = inputs.reservoir(); let spec = context.cfg().spec().into(); + let reservoir_only_give_backs = context.cfg().reservoir_only_give_backs(); // EIP-8037 refund for the CREATE opcode's upfront `create_state_gas` is // applied uniformly in `return_result` when the create fails (revert, // halt, or early-fail with `address == None`), so early-fail results @@ -283,18 +296,21 @@ impl EthFrame<EthInterpreter> { // — because the created address is not derivable here on the early-fail paths. let charged_state_gas_address = inputs.charged_state_gas_address(); let return_error = |e| { + let mut gas = Gas::new_with_regular_gas_and_reservoir( + inputs.gas_limit(), + reservoir_remaining_gas, + ); + gas.set_reservoir_only_give_backs(reservoir_only_give_backs); Ok(ItemOrResult::Result(FrameResult::Create(CreateOutcome { result: InterpreterResult { result: e, - gas: Gas::new_with_regular_gas_and_reservoir( - inputs.gas_limit(), - reservoir_remaining_gas, - ), + gas, output: Bytes::new(), }, address: None, charged_create_state_gas, charged_state_gas_address, + start_mark: OutcomeMark::NONE, }))) }; @@ -356,7 +372,8 @@ impl EthFrame<EthInterpreter> { }; let gas_limit = inputs.gas_limit(); - this.get(EthFrame::invalid).clear( + let frame = this.get(EthFrame::invalid); + frame.clear( FrameData::Create(CreateFrame { created_address }), FrameInput::Create(inputs), depth, @@ -369,6 +386,10 @@ impl EthFrame<EthInterpreter> { reservoir_remaining_gas, checkpoint, ); + frame + .interpreter + .gas + .set_reservoir_only_give_backs(reservoir_only_give_backs); Ok(ItemOrResult::Item(this.consume())) } @@ -626,6 +647,14 @@ impl EthFrame<EthInterpreter> { /// - net state gas, net history gas, the spilled portion, and the refund counter /// persist only on success; on revert/halt the child's state changes roll back /// and contribute nothing. +/// +/// With [`GasTracker::reservoir_only_give_backs`] set, a failing child's rollback puts every +/// charge it made into its reservoir, and none into its regular gas: a revert returns the unspent +/// regular gas and a reservoir that holds those charges, and a halt consumes the regular gas with +/// what it paid of the charges ([`GasTracker::consume_regular_paid_charges`]) and returns the +/// reservoir the child received. The parent adopts the returned reservoir without unwinding +/// anything, and adds the regular gas the child paid for state and history to its own count on a +/// revert as on a success, since that gas is not given back to regular gas. #[inline] pub const fn handle_reservoir_remaining_gas( instruction_result: InstructionResult, @@ -640,7 +669,10 @@ pub const fn handle_reservoir_remaining_gas( if instruction_result.is_halt() { // Exceptional halt consumes the child's regular gas (including the spill // just credited back by `rollback_state_gas`); the reservoir is left - // restored to the inherited value for the parent. + // restored to the inherited value for the parent. With give-backs to the reservoir + // alone, the rollback put what regular gas paid into the reservoir, which the halt takes + // out again; otherwise nothing is left to take. + child_gas.consume_regular_paid_charges(); child_gas.spend_all(); } @@ -648,6 +680,15 @@ pub const fn handle_reservoir_remaining_gas( if instruction_result.is_ok_or_revert() { parent_gas.erase_cost(child_gas.remaining()); } + // What the child's regular gas paid for state and history. With give-backs to the reservoir + // alone, however the child ended: no give-back lowers the count, and a halt's part comes with + // the record that the halt consumed it. Otherwise on a success, so a later rollback of the + // parent can return it; a failure's rollback zeroed it. + if child_gas.reservoir_only_give_backs() { + parent_gas.add_regular_paid_of(child_gas); + } else if instruction_result.is_ok_or_revert() { + parent_gas.add_state_gas_spilled(child_gas.state_gas_spilled()); + } if instruction_result.is_ok() { // Parent may have already charged state gas (e.g. new_account + create) // before creating the child frame, so add rather than overwrite. The @@ -659,7 +700,6 @@ pub const fn handle_reservoir_remaining_gas( .state_gas_spent() .saturating_add(child_gas.state_gas_spent()), ); - parent_gas.add_state_gas_spilled(child_gas.state_gas_spilled()); // History gas rides the same success-only merge, signed for the same reason: a // failing child rolled it back along with its state gas, so it contributes // nothing. Zero on any chain that never charges history gas. @@ -872,4 +912,247 @@ mod tests { assert_eq!(parent.state_gas_spent(), 0); assert_eq!(parent.state_gas_spilled(), 0); } + + /// Settles `child` into `parent` as revm does, then adds back the reservoir `parent` held + /// while the child ran, as a consumer that kept part of `parent`'s reservoir for it does. + fn settle_and_add_back( + result: InstructionResult, + parent: &mut GasTracker, + child: &mut GasTracker, + ) { + let held = parent.reservoir(); + handle_reservoir_remaining_gas(result, parent, child); + parent.set_reservoir(parent.reservoir() + held); + } + + /// The reservoir a child returns replaces its caller's: what the child left when it succeeded, + /// the whole reservoir it was given when it reverted or halted, the child's state charges + /// undone. Regular gas settles as it did. + #[test] + fn test_the_reservoir_a_child_returns_replaces_its_callers() { + for result in [ + InstructionResult::Stop, + InstructionResult::Revert, + InstructionResult::OutOfGas, + ] { + let mut parent = GasTracker::new(10_000, 10_000, 1_000); + assert!(parent.record_regular_cost(5_000)); + let mut child = GasTracker::new(5_000, 5_000, parent.reservoir()); + assert!(child.record_state_cost(300)); + + handle_reservoir_remaining_gas(result, &mut parent, &mut child); + + let (reservoir, state) = if result.is_ok() { + (700, 300) + } else { + (1_000, 0) + }; + assert_eq!(parent.reservoir(), reservoir, "{result:?}"); + assert_eq!(parent.state_gas_spent(), state, "{result:?}"); + let regular = if result.is_ok_or_revert() { + 10_000 + } else { + 5_000 + }; + assert_eq!(parent.remaining(), regular, "{result:?}"); + } + } + + /// A consumer that keeps part of a caller's reservoir gives the child the rest, and adds what + /// the caller held back once revm replaced the caller's reservoir with the child's: the caller + /// ends with what the child returned on top of the part it kept. A child that spends more than + /// its share spills onto its regular gas, as a frame with no reservoir left does, though its + /// caller kept part of the reservoir: the share is the child's whole reservoir. A caller's + /// later rollback restores the reservoir it started with and gives the spill back to regular + /// gas. + #[test] + fn test_a_child_spills_past_its_share_and_a_rollback_restores_the_callers_reservoir() { + let mut a = GasTracker::new(10_000, 10_000, 1_000); + assert!(a.record_regular_cost(10_000)); + let mut b = GasTracker::new(10_000, 10_000, a.reservoir()); + assert!(b.record_regular_cost(5_000)); + // 98% of 1,000 forwarded, 20 kept. + b.set_reservoir(20); + let mut c = GasTracker::new(5_000, 5_000, 980); + assert!(c.record_state_cost(1_000)); + assert_eq!( + (c.reservoir(), c.remaining(), c.state_gas_spilled()), + (0, 4_980, 20) + ); + + settle_and_add_back(InstructionResult::Stop, &mut b, &mut c); + assert_eq!(b.reservoir(), 20, "the part B kept is back"); + assert_eq!(b.state_gas_spilled(), 20); + assert_eq!(b.remaining(), 9_980); + + handle_reservoir_remaining_gas(InstructionResult::Revert, &mut a, &mut b); + assert_eq!(a.reservoir(), 1_000); + assert_eq!(a.remaining(), 10_000); + assert_eq!(a.state_gas_spent(), 0); + } + + /// A caller that kept part of its reservoir holds it beside the spill of a child that spent + /// past its share, which a whole forward cannot produce. A refill in the caller then keeps + /// EIP-8037's order, regular gas up to the outstanding spill first and the reservoir after, + /// whichever paid the charge it undoes: a charge the caller paid from its kept reservoir comes + /// back as regular gas. The sum of the two is conserved, and a rollback restores the reservoir + /// the caller started with. With the whole reservoir forwarded, the caller's charge spills + /// too, and its refill returns where the charge was taken. + #[test] + fn test_a_refill_beside_a_kept_reservoir_and_a_childs_spill_credits_regular_gas_first() { + // (reservoir, remaining, spilled, state gas spent) of a tracker. + let figures = |gas: &GasTracker| { + ( + gas.reservoir(), + gas.remaining(), + gas.state_gas_spilled(), + gas.state_gas_spent(), + ) + }; + for (forwarded, after_child, after_charge, after_refill) in [ + // 98%: B keeps 20 and C spills 20; B's charge comes from its reservoir, the refill + // goes to its regular gas. + ( + 980, + (20, 9_980, 20, 1_000), + (10, 9_980, 20, 1_010), + (10, 9_990, 10, 1_000), + ), + // The whole reservoir: B keeps none and C spills 0; B's charge spills, and the refill + // undoes that spill. + ( + 1_000, + (0, 10_000, 0, 1_000), + (0, 9_990, 10, 1_010), + (0, 10_000, 0, 1_000), + ), + ] { + // B holds 1,000 of reservoir and forwards 5,000 of regular gas; C charges 1,000. + let mut b = GasTracker::new(10_000, 10_000, 1_000); + assert!(b.record_regular_cost(5_000)); + let mut c = GasTracker::new(5_000, 5_000, forwarded); + assert!(c.record_state_cost(1_000)); + if forwarded < 1_000 { + b.set_reservoir(1_000 - forwarded); + settle_and_add_back(InstructionResult::Stop, &mut b, &mut c); + } else { + handle_reservoir_remaining_gas(InstructionResult::Stop, &mut b, &mut c); + } + assert_eq!(figures(&b), after_child, "{forwarded}: after C"); + + // B writes a slot, 10 of state gas, and puts it back, a refill of 10. + assert!(b.record_state_cost(10)); + assert_eq!(figures(&b), after_charge, "{forwarded}: after B's charge"); + b.refill_reservoir(10); + assert_eq!(figures(&b), after_refill, "{forwarded}: after B's refill"); + assert_eq!( + b.reservoir() + b.remaining(), + 10_000, + "{forwarded}: the sum is conserved" + ); + + b.rollback_state_gas(); + assert_eq!( + (b.reservoir(), b.remaining()), + (1_000, 10_000), + "{forwarded}: B's rollback restores what it started with" + ); + } + } + /// A tracker with give-backs to the reservoir alone. + fn reservoir_only(limit: u64, reservoir: u64) -> GasTracker { + let mut gas = GasTracker::new(limit, limit, reservoir); + gas.set_reservoir_only_give_backs(true); + gas + } + + /// `(remaining, reservoir, state_spent, spilled)` of a tracker. + const fn figures(gas: &GasTracker) -> (u64, u64, i64, u64) { + ( + gas.remaining(), + gas.reservoir(), + gas.state_gas_spent(), + gas.state_gas_spilled(), + ) + } + + /// With give-backs to the reservoir alone, the sibling refill of the first test lands in the + /// reservoir the sibling returns, and its caller's regular gas stays what the first child left + /// it: the reservoir is adopted without unwinding the regular gas the first child paid. + #[test] + fn test_with_give_backs_to_the_reservoir_a_sibling_refill_leaves_regular_gas_spent() { + const STATE_GAS: u64 = 200; + const CHILD_GAS: u64 = 500; + + let mut parent = reservoir_only(1_000, 0); + assert!(parent.record_regular_cost(CHILD_GAS)); + let mut child_a = reservoir_only(CHILD_GAS, 0); + assert!(child_a.record_state_cost(STATE_GAS)); + handle_reservoir_remaining_gas(InstructionResult::Stop, &mut parent, &mut child_a); + assert_eq!(figures(&parent), (800, 0, 200, 200)); + + assert!(parent.record_regular_cost(CHILD_GAS)); + let mut child_b = reservoir_only(CHILD_GAS, parent.reservoir()); + child_b.refill_reservoir(STATE_GAS); + handle_reservoir_remaining_gas(InstructionResult::Stop, &mut parent, &mut child_b); + assert_eq!( + figures(&parent), + (800, 200, 0, 200), + "the refill is reservoir, and what regular gas paid stays counted" + ); + } + + /// With give-backs to the reservoir alone a child that succeeds hands back what it left of + /// both pools; one that reverts puts every charge it made, net of the give-backs it received, + /// into the reservoir it returns; one that halts returns the reservoir it received and consumes + /// its regular gas with what it paid of the charges. However the child ends, its caller counts + /// what the child's regular gas paid as its own, and, after a halt, that the halt consumed it. + #[test] + fn test_with_give_backs_to_the_reservoir_a_failed_child_returns_its_charges_as_reservoir() { + for (result, expected) in [ + (InstructionResult::Stop, (9_700, 50, 1_250, 300)), + (InstructionResult::Revert, (9_700, 1_300, 0, 300)), + (InstructionResult::OutOfGas, (5_000, 1_000, 0, 300)), + ] { + let mut parent = reservoir_only(10_000, 1_000); + assert!(parent.record_regular_cost(5_000)); + let mut child = reservoir_only(5_000, parent.reservoir()); + // 1,000 of the charge from the reservoir and 300 from regular gas; 50 given back. + assert!(child.record_state_cost(1_300)); + child.refill_reservoir(50); + + handle_reservoir_remaining_gas(result, &mut parent, &mut child); + + assert_eq!(figures(&parent), expected, "{result:?}"); + let consumed = if result.is_halt() { 300 } else { 0 }; + assert_eq!(parent.halted_regular_paid(), consumed, "{result:?}"); + } + } + + /// A reverted grandchild's reservoir, which holds what its regular gas paid, stays in the + /// reservoir of the frame it returned into: when that frame reverts too, it returns its own + /// charges and the grandchild's on top of the reservoir it received; when it halts, it returns + /// the reservoir it received and nothing more. + #[test] + fn test_with_give_backs_to_the_reservoir_a_failed_frame_keeps_a_failed_childs_reservoir() { + for (result, reservoir) in [ + (InstructionResult::Revert, 1_200), + (InstructionResult::OutOfGas, 1_000), + ] { + let mut a = reservoir_only(10_000, 1_000); + assert!(a.record_regular_cost(5_000)); + let mut b = reservoir_only(5_000, a.reservoir()); + assert!(b.record_state_cost(200)); + assert!(b.record_regular_cost(2_000)); + let mut c = reservoir_only(2_000, b.reservoir()); + // 800 from the reservoir C received, 200 from its regular gas. + assert!(c.record_state_cost(1_000)); + handle_reservoir_remaining_gas(InstructionResult::Revert, &mut b, &mut c); + assert_eq!(figures(&b), (4_800, 1_000, 200, 200)); + + handle_reservoir_remaining_gas(result, &mut a, &mut b); + + assert_eq!(a.reservoir(), reservoir, "{result:?}"); + } + } } diff --git a/crates/handler/src/handler.rs b/crates/handler/src/handler.rs index 19c26b4faf..805b6f3f08 100644 --- a/crates/handler/src/handler.rs +++ b/crates/handler/src/handler.rs @@ -1,7 +1,6 @@ use crate::{ evm::FrameTr, - execution, - frame::handle_reservoir_remaining_gas, + execution, lifecycle, post_execution::{self, build_result_gas}, pre_execution::{self, apply_eip7702_auth_list, PreExecutionOutput}, validation, EvmTr, FrameResult, ItemOrResult, @@ -15,11 +14,10 @@ use context_interface::{ context::{take_error, ContextError}, journaled_state::JournalCheckpoint, result::{HaltReasonTr, InvalidHeader, InvalidTransaction, ResultGas}, - Cfg, ContextTr, Database, Host, JournalTr, Transaction, + Cfg, ContextTr, Database, JournalTr, Transaction, }; use interpreter::{interpreter_action::FrameInit, GasTracker, InitialAndFloorGas, SharedMemory}; use primitives::{TxKind, U256}; -use std::string::ToString; /// Trait for errors that can occur during EVM execution. /// @@ -161,6 +159,9 @@ pub trait Handler { /// [Handler::pre_execution], [Handler::execution], [Handler::post_execution]. /// /// Returns any errors without catching them or calling [`Handler::catch_error`]. + /// A caller that drops an error makes `catch_error`'s cleanup before it reuses + /// the EVM, the frame stack's included: see the start lifecycle's "Reuse after + /// an error" ([`lifecycle`]). #[inline] fn run_without_catch_error( &mut self, @@ -211,14 +212,18 @@ pub trait Handler { /// The gas limit is the transaction gas limit, `remaining` is the regular /// gas budget left after the intrinsic gas (constrained by the EIP-8037 /// `TX_MAX_GAS_LIMIT` cap) and `reservoir` is the state gas pool, so the - /// intrinsic gas is accounted as already spent. + /// intrinsic gas is accounted as already spent. Whether its give-backs credit the reservoir + /// alone is the configuration's (`Cfg::reservoir_only_give_backs`), as it is for every frame's + /// gas. #[inline] fn tx_gas(&self, evm: &mut Self::Evm, init_and_floor_gas: &InitialAndFloorGas) -> GasTracker { let ctx = evm.ctx_ref(); let tx_gas_limit = ctx.tx().gas_limit(); let (remaining, reservoir) = init_and_floor_gas .initial_gas_and_reservoir(tx_gas_limit, ctx.cfg().tx_gas_limit_cap()); - GasTracker::new(tx_gas_limit, remaining, reservoir) + let mut gas = GasTracker::new(tx_gas_limit, remaining, reservoir); + gas.set_reservoir_only_give_backs(ctx.cfg().reservoir_only_give_backs()); + gas } /// Prepares the EVM state for execution. @@ -271,6 +276,9 @@ pub trait Handler { /// ([`Handler::runtime_oog_result`]). /// /// Always calls [Handler::last_frame_result] to handle returned gas from the call. + /// + /// The first frame's init opens the transaction's start + /// ([`lifecycle::open_frame_start`]), which `last_frame_result` closes. #[inline] fn execution( &mut self, @@ -289,6 +297,8 @@ pub trait Handler { }; // The runtime gas phase is complete: commit its state changes. evm.ctx().journal_mut().checkpoint_commit(); + // The transaction's start opens with the frame init revm made for it. + lifecycle::open_frame_start(evm, &first_frame_input)?; // Run execution loop let mut frame_result = self.run_exec_loop(evm, first_frame_input)?; @@ -307,6 +317,10 @@ pub trait Handler { /// skipped, all regular gas is consumed (the reservoir is returned), and /// the runtime state changes were already reverted when the phase bailed /// out. + /// + /// The stand-in opens the transaction's start + /// ([`lifecycle::open_transaction_start`]) and settles on it as the + /// transaction's frame would. #[inline] fn runtime_oog_result( &mut self, @@ -320,6 +334,9 @@ pub trait Handler { // result; the settle below consumes all regular gas and returns the // reservoir. *gas = self.tx_gas(evm, init_and_floor_gas); + // The stand-in settles as the transaction's frame would, so it opens the transaction's + // start. + lifecycle::open_transaction_start(evm)?; let tx_gas_limit = evm.ctx().tx().gas_limit(); let reservoir = gas.reservoir(); let mut frame_result = match evm.ctx().tx().kind() { @@ -502,6 +519,14 @@ pub trait Handler { /// /// The settled transaction-level gas is written back to the frame result, /// which carries it into the post-execution phase. + /// + /// The settlement is [`execution::settle_first_frame`]. It is followed by the close of the + /// transaction's start ([`lifecycle::close_transaction_start`], given the + /// reservoir the gas held before the settlement). An override calls both + /// rather than copying this body, and copies the gas into the frame result + /// itself. + /// + /// [`handle_reservoir_remaining_gas`]: crate::handle_reservoir_remaining_gas #[inline] fn last_frame_result( &mut self, @@ -509,44 +534,11 @@ pub trait Handler { frame_result: &mut <<Self::Evm as EvmTr>::Frame as FrameTr>::FrameResult, parent_gas: &mut GasTracker, ) -> Result<(), Self::Error> { - let instruction_result = frame_result.instruction_result(); - - // All regular gas was forwarded to the first frame: consume it on the - // transaction-level gas; the settle below returns the frame's unused - // part. - parent_gas.spend_all(); - - // Settle the frame into the transaction-level gas like a parent frame. - handle_reservoir_remaining_gas( - instruction_result, - parent_gas, - frame_result.gas_mut().tracker_mut(), - ); - - // Refund the EIP-2780 refundable first-frame charge when no account - // leaf was created, exactly like `EthFrame::return_result` refunds - // the upfront CALL/CREATE state charges of inner frames. - if let Some(charge) = frame_result.refundable_state_gas_charge() { - // A failure the frame already recorded (a failed code deposit lookup, say) is - // returned first, as `EthFrame::return_result` does for inner frames, so a failing - // refund lookup cannot overwrite it. - take_error::<Self::Error, _>(evm.ctx().error())?; - // Priced through the same hook the charge went through. A failed lookup surfaces as - // an external error: the hook recorded the cause. - let Some(charge) = evm.ctx().state_gas_charge(charge) else { - take_error::<Self::Error, _>(evm.ctx().error())?; - return Err(Self::Error::from_string( - "state gas price lookup failed".to_string(), - )); - }; - parent_gas.refill_reservoir(charge); - // Unlike an inner frame's caller, the transaction ends here: an - // exceptional halt consumes all regular gas, including the - // spilled portion the refill just credited back to `remaining`. - if instruction_result.is_halt() { - parent_gas.spend_all(); - } - } + // Settle the frame into the transaction-level gas like a parent frame, and refund what + // its failure gives back; then close the transaction's start. + let held_reservoir = parent_gas.reservoir(); + execution::settle_first_frame::<_, Self::Error>(evm.ctx(), frame_result, parent_gas)?; + lifecycle::close_transaction_start(evm, frame_result, parent_gas, held_reservoir)?; // The frame result carries the transaction-level gas onward to the // post-execution phase. @@ -589,7 +581,10 @@ pub trait Handler { ItemOrResult::Result(result) => result, } } - ItemOrResult::Result(result) => result, + ItemOrResult::Result(mut result) => { + evm.frame_run_result(&mut result)?; + result + } }; if let Some(result) = evm.frame_return_result(result)? { @@ -655,6 +650,11 @@ pub trait Handler { /// /// This method, retrieves the final state from the journal, converts internal results to the external output format. /// Internal state is cleared and EVM is prepared for the next transaction. + /// + /// It is the start lifecycle's successful boundary: after the recorded error is + /// taken, every start the transaction opened must have settled + /// ([`lifecycle::finish_transaction`]), or the transaction fails with a fatal + /// error. An override makes the same call in the same place. #[inline] fn execution_result( &mut self, @@ -663,6 +663,8 @@ pub trait Handler { result_gas: ResultGas, ) -> Result<ExecutionResult<Self::HaltReason>, Self::Error> { take_error::<Self::Error, _>(evm.ctx().error())?; + // The successful boundary: every start the transaction opened has settled. + lifecycle::finish_transaction(evm)?; let exec_result = post_execution::output(evm.ctx(), result, result_gas); @@ -678,12 +680,18 @@ pub trait Handler { /// /// Ensures the journal state is properly cleared before propagating the error. /// On happy path journal is cleared in [`Handler::execution_result`] method. + /// + /// It is the start lifecycle's fatal boundary: the starts still open are + /// discarded ([`lifecycle::discard_transaction`]) in the cleanup every error + /// reaches. An override makes the same call in its cleanup. #[inline] fn catch_error( &self, evm: &mut Self::Evm, error: Self::Error, ) -> Result<ExecutionResult<Self::HaltReason>, Self::Error> { + // The fatal boundary: the starts still open are discarded. + lifecycle::discard_transaction(evm); // clean up local context. Initcode cache needs to be discarded. evm.ctx().local_mut().clear(); evm.ctx().journal_mut().discard_tx(); diff --git a/crates/handler/src/lib.rs b/crates/handler/src/lib.rs index 7ee2311c6d..80a5b28329 100644 --- a/crates/handler/src/lib.rs +++ b/crates/handler/src/lib.rs @@ -20,6 +20,7 @@ pub mod handler; /// EVM instruction set implementations and tables. pub mod instructions; mod item_or_result; +pub mod lifecycle; mod mainnet_builder; mod mainnet_handler; /// Post-execution operations including gas refunds and state finalization. diff --git a/crates/handler/src/lifecycle.rs b/crates/handler/src/lifecycle.rs new file mode 100644 index 0000000000..fbbf5bc443 --- /dev/null +++ b/crates/handler/src/lifecycle.rs @@ -0,0 +1,380 @@ +//! The start lifecycle: revm's pairing of every frame start with its settlement. +//! +//! A start opens where revm consumes a frame's init, just before it initialises the frame: a +//! frame's `NewFrame` action, consumed by [`EvmTr::frame_run`] (and by the inspector's +//! `inspect_frame_run`), opens a child start under the frame's own ([`open_frame_start`]); the +//! transaction's frame opens the transaction's start in [`Handler::execution`] (and the +//! inspector's `inspect_execution`), and so does the stand-in [`Handler::runtime_oog_result`] +//! builds for a frame that never runs ([`open_transaction_start`]). +//! +//! A start closes where revm settles the frame's result into its caller: a child's in +//! [`EvmTr::frame_return_result`], after `EthFrame::return_result` ([`close_frame_start`]), and +//! the transaction's in [`Handler::last_frame_result`], after +//! [`settle_first_frame`](crate::execution::settle_first_frame) ([`close_transaction_start`]). +//! +//! The lifecycle ends at one of the transaction's two boundaries: the successful one in +//! [`Handler::execution_result`], where every start must have settled ([`finish_transaction`]), +//! and the fatal one in [`Handler::catch_error`], which discards the starts still open +//! ([`discard_transaction`]). +//! +//! The record is revm's frame stack ([`FrameStack`]), which no inspector is handed. Each step is +//! handed to the context's lifecycle hooks ([`Host::frame_split`], [`Host::frame_settle`], +//! [`Host::frame_lifecycle_end`]). A step the record refuses ([`StartLifecycleError`]) is a fatal +//! error of the transaction in every build. +//! +//! An inspector's end callbacks may put another gas tracker or another outcome in a result's +//! place. revm marks the result for its start before them ([`mark_for_end_callbacks`]) and checks +//! the marks after them ([`check_end_callbacks`]), and an inspector's answer to a start is +//! recorded on it too ([`PendingStart::set_inspector_answer`]): the settlement reports all three +//! ([`FrameSettle`](context_interface::host::FrameSettle)). +//! +//! A chain's handler that overrides one of these methods makes the call the mainnet method makes, +//! in the same place: [`close_transaction_start`] in `last_frame_result`, [`finish_transaction`] +//! in `execution_result` and [`discard_transaction`] in `catch_error`. An EVM that reimplements +//! `frame_run` or `inspect_frame_run` calls [`open_frame_start`] for the init it consumed, and one +//! that reimplements `frame_return_result` calls [`close_frame_start`]. A runner that drives the +//! transaction's frame itself, outside [`Handler::execution`], opens the transaction's start first +//! ([`open_frame_start`] with the frame's init, or [`open_transaction_start`] for a frame it never +//! initialises). +//! +//! # Reuse after an error +//! +//! [`Handler::run`] hands an error to [`Handler::catch_error`], whose cleanup discards the +//! lifecycle, the journal's transaction, the local context and the frame stack. A caller of +//! [`Handler::run_without_catch_error`] that drops an error must make the same cleanup before it +//! reuses the EVM: call `catch_error`, or call [`discard_transaction`], discard the journal's +//! transaction, clear the local context and clear the frame stack ([`FrameStack::clear`]). +//! Discarding the lifecycle alone is not enough: a frame left on the stack makes the next +//! transaction's start a child of a frame with no start, which the record refuses. +//! +//! [`Handler::execution`]: crate::Handler::execution +//! [`Handler::runtime_oog_result`]: crate::Handler::runtime_oog_result +//! [`Handler::last_frame_result`]: crate::Handler::last_frame_result +//! [`Handler::execution_result`]: crate::Handler::execution_result +//! [`Handler::catch_error`]: crate::Handler::catch_error +//! [`Handler::run`]: crate::Handler::run +//! [`Handler::run_without_catch_error`]: crate::Handler::run_without_catch_error + +use crate::{evm::ContextDbError, EthFrame, EvmTr, FrameResult}; +use context_interface::{ + context::ContextError, host::SettleStatus, FrameStack, Host, PendingStart, StartLifecycleError, +}; +use interpreter::{ + interpreter::EthInterpreter, interpreter_action::FrameInit, GasTracker, OutcomeMark, StartMark, +}; +use std::string::ToString; + +/// A refused step as the transaction's fatal error. +#[cold] +fn fatal<E>(error: StartLifecycleError) -> ContextError<E> { + ContextError::Custom(error.to_string()) +} + +/// What a settlement reports of `result`'s status. +#[inline] +const fn settle_status(result: &FrameResult) -> SettleStatus { + let result = result.instruction_result(); + if result.is_ok() { + SettleStatus::Ok + } else if result.is_revert() { + SettleStatus::Revert + } else { + SettleStatus::Halt + } +} + +/// For a creation's `result`, whether it took an address; `None` for a call's. +#[inline] +const fn created(result: &FrameResult) -> Option<bool> { + match result { + FrameResult::Call(_) => None, + FrameResult::Create(outcome) => Some(outcome.address.is_some()), + } +} + +/// Opens the start of the frame `init` makes, which revm consumed and initialises next: the child +/// of the frame on top of the stack, or the transaction's start when the stack is empty. Hands it +/// to [`Host::frame_split`]. +/// +/// # Errors +/// +/// The record's refusal ([`FrameStack::open_start`]), as a fatal error. +#[inline] +pub fn open_frame_start<EVM: EvmTr + ?Sized>( + evm: &mut EVM, + init: &FrameInit, +) -> Result<(), ContextDbError<EVM::Context>> { + let (ctx, _, _, frame_stack) = evm.all_mut(); + open_start(ctx, frame_stack, init.depth) +} + +/// Opens the start of the frame at `depth` the next init makes, as [`open_frame_start`] does, from +/// the pieces of an EVM: for a frame run that opens the start as the frame consumes its +/// `NewFrame` action, before the init is built. +#[inline] +pub(crate) fn open_start<CTX, F, E>( + ctx: &mut CTX, + frame_stack: &mut FrameStack<F>, + depth: usize, +) -> Result<(), ContextError<E>> +where + CTX: Host + ?Sized, +{ + let split = frame_stack.open_start(depth).map_err(fatal)?; + ctx.frame_split(&split); + Ok(()) +} + +/// Opens the transaction's start for a transaction frame revm does not initialise: the stand-in +/// for a frame that never runs, or the frame of a runner that settles one it built itself. Hands +/// it to [`Host::frame_split`]. The frame stack must be empty. +/// +/// # Errors +/// +/// The record's refusal ([`FrameStack::open_start`]), as a fatal error. +#[inline] +pub fn open_transaction_start<EVM: EvmTr + ?Sized>( + evm: &mut EVM, +) -> Result<(), ContextDbError<EVM::Context>> { + let (ctx, _, _, frame_stack) = evm.all_mut(); + debug_assert!( + frame_stack.index().is_none(), + "the transaction's start opens on an empty frame stack" + ); + let split = frame_stack.open_start(0).map_err(fatal)?; + ctx.frame_split(&split); + Ok(()) +} + +/// A frame's result on its way into its caller: what its settlement reports, read before +/// `EthFrame::return_result` consumes it ([`close_frame_start`]). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Returning { + depth: usize, + status: SettleStatus, + created: Option<bool>, + held_reservoir: u64, +} + +impl Returning { + /// `result`, about to be returned into `caller`, the frame on top of the stack. + #[inline] + pub const fn new(result: &FrameResult, caller: &EthFrame<EthInterpreter>) -> Self { + Self { + depth: caller.depth + 1, + status: settle_status(result), + created: created(result), + held_reservoir: caller.interpreter.gas.reservoir(), + } + } +} + +/// Closes the start of the frame whose result was just returned into the frame on top of +/// `frame_stack`, its caller, after `EthFrame::return_result` settled it, and hands the settlement +/// to [`Host::frame_settle`] with the caller's gas. `caller` reaches the caller's `EthFrame` from +/// the stack's frame. +/// +/// # Errors +/// +/// [`StartLifecycleError::NotOpen`] when the caller has no open start, as a fatal error. +#[inline] +pub fn close_frame_start<CTX, F, E>( + ctx: &mut CTX, + frame_stack: &mut FrameStack<F>, + returning: Returning, + caller: impl FnOnce(&mut F) -> &mut EthFrame<EthInterpreter>, +) -> Result<(), ContextError<E>> +where + CTX: Host + ?Sized, +{ + let settle = frame_stack + .close_start( + returning.depth, + returning.status, + returning.created, + returning.held_reservoir, + ) + .map_err(fatal)?; + let caller = caller(frame_stack.get()); + ctx.frame_settle(&settle, caller.interpreter.gas.tracker_mut()); + Ok(()) +} + +/// Closes the transaction's start into the transaction-level `gas`, after +/// [`settle_first_frame`](crate::execution::settle_first_frame) settled `result` into it, and +/// hands the settlement to [`Host::frame_settle`]. `held_reservoir` is the reservoir `gas` held +/// before that settlement. The frame stack must be empty. +/// +/// After a halt, the regular gas the hook credited to `gas` is consumed, so a halted transaction +/// keeps none of its settlement hook's regular credits. What revm's own settlement left in `gas` +/// is left as it is: a hook that credits nothing, the default, changes no figure. +/// +/// # Errors +/// +/// [`StartLifecycleError::NotOpen`] when the transaction's start is not open, as a fatal error. +#[inline] +pub fn close_transaction_start<EVM: EvmTr + ?Sized>( + evm: &mut EVM, + result: &FrameResult, + gas: &mut GasTracker, + held_reservoir: u64, +) -> Result<(), ContextDbError<EVM::Context>> { + let status = settle_status(result); + let (ctx, _, _, frame_stack) = evm.all_mut(); + debug_assert!( + frame_stack.index().is_none(), + "the transaction's start closes on an empty frame stack" + ); + let settle = frame_stack + .close_start(0, status, created(result), held_reservoir) + .map_err(fatal)?; + let settled = gas.remaining(); + ctx.frame_settle(&settle, gas); + if status == SettleStatus::Halt { + consume_hook_credit(gas, settled); + } + Ok(()) +} + +/// Consumes the regular gas a halted transaction's settlement hook credited to `gas`: what `gas` +/// holds above `settled`, the regular gas revm's settlement left in it before the hook. A hook +/// that credited nothing, or debited, leaves `gas` as it is. +#[inline] +const fn consume_hook_credit(gas: &mut GasTracker, settled: u64) { + if gas.remaining() > settled { + gas.set_remaining(settled); + } +} + +/// The successful boundary: every start the transaction opened must have settled. Ends the +/// lifecycle ([`LifecycleEnd::Settled`](context_interface::host::LifecycleEnd::Settled), handed to +/// [`Host::frame_lifecycle_end`] when a lifecycle was under way) and resets the record for the +/// next transaction. +/// +/// # Errors +/// +/// [`StartLifecycleError::Unsettled`] when a start is still open, a missed settlement, as a fatal +/// error. The lifecycle is then discarded +/// ([`LifecycleEnd::Discarded`](context_interface::host::LifecycleEnd::Discarded)), so the handler's +/// `catch_error` that reports the error owes no second end. +#[inline] +pub fn finish_transaction<EVM: EvmTr + ?Sized>( + evm: &mut EVM, +) -> Result<(), ContextDbError<EVM::Context>> { + let (ctx, _, _, frame_stack) = evm.all_mut(); + match frame_stack.settle_lifecycle() { + Ok(end) => { + if let Some(end) = end { + ctx.frame_lifecycle_end(end); + } + Ok(()) + } + Err(error) => { + if let Some(end) = frame_stack.discard_lifecycle() { + ctx.frame_lifecycle_end(end); + } + Err(fatal(error)) + } + } +} + +/// The fatal boundary: discards the starts still open, ends the lifecycle +/// ([`LifecycleEnd::Discarded`](context_interface::host::LifecycleEnd::Discarded), handed to +/// [`Host::frame_lifecycle_end`] when a lifecycle was under way) and resets the record for the +/// next transaction. Idempotent: a lifecycle already ended owes nothing. +/// +/// It resets the lifecycle only. Before the EVM runs another transaction, the frame stack must be +/// cleared too, as [`Handler::catch_error`](crate::Handler::catch_error) does (see the module's +/// "Reuse after an error"). +#[inline] +pub fn discard_transaction<EVM: EvmTr + ?Sized>(evm: &mut EVM) { + let (ctx, _, _, frame_stack) = evm.all_mut(); + if let Some(end) = frame_stack.discard_lifecycle() { + ctx.frame_lifecycle_end(end); + } +} + +/// Marks `result`, the result of `start`, for the start, just before an inspector's end +/// callbacks (`frame_end`, `call_end`, `create_end`): its gas tracker with a [`StartMark`] and its +/// outcome with an [`OutcomeMark`]. Neither mark is part of the values' public semantics. +#[inline] +pub const fn mark_for_end_callbacks(result: &mut FrameResult, start: &PendingStart) { + let id = start.id(); + result + .gas_mut() + .tracker_mut() + .set_start_mark(StartMark::for_start(id)); + let mark = OutcomeMark::for_start(id); + match result { + FrameResult::Call(outcome) => outcome.start_mark = mark, + FrameResult::Create(outcome) => outcome.start_mark = mark, + } +} + +/// Records on `start`, just after an inspector's end callbacks, what they put in place of +/// `result`'s gas tracker and outcome: a tracker without the start's mark +/// ([`PendingStart::set_gas_replaced`]) and an outcome without it +/// ([`PendingStart::set_outcome_rebuilt`]). A callback that edits the values in place, or copies +/// them, keeps the marks. +#[inline] +pub const fn check_end_callbacks(result: &FrameResult, start: &mut PendingStart) { + let id = start.id(); + if !result.gas().tracker().start_mark().is_for(id) { + start.set_gas_replaced(); + } + let outcome_mark = match result { + FrameResult::Call(outcome) => outcome.start_mark, + FrameResult::Create(outcome) => outcome.start_mark, + }; + if !outcome_mark.is_for(id) { + start.set_outcome_rebuilt(); + } +} + +#[cfg(test)] +mod tests { + use super::consume_hook_credit; + use interpreter::GasTracker; + + /// A transaction's gas whose settlement left it `remaining` regular gas, after a hook credited + /// it `credit` more. + fn credited(remaining: u64, credit: u64) -> GasTracker { + let mut gas = GasTracker::new(1_000, remaining, 0); + gas.erase_cost(credit); + gas + } + + #[test] + fn test_a_halt_consumes_only_what_the_hook_credited() { + let mut gas = credited(1, 40); + consume_hook_credit(&mut gas, 1); + assert_eq!(gas.remaining(), 1, "the settlement's own gas is kept"); + + let mut gas = credited(0, 40); + consume_hook_credit(&mut gas, 0); + assert_eq!(gas.remaining(), 0); + } + + #[test] + fn test_a_halt_leaves_gas_a_hook_did_not_credit() { + let mut gas = credited(7, 0); + consume_hook_credit(&mut gas, 7); + assert_eq!(gas.remaining(), 7, "nothing credited, nothing consumed"); + + let mut gas = credited(7, 0); + assert!(gas.record_regular_cost(3)); + consume_hook_credit(&mut gas, 7); + assert_eq!(gas.remaining(), 4, "a debit stands"); + } + + #[test] + fn test_a_halt_consumes_a_credit_to_the_withheld_part_too() { + let mut gas = GasTracker::new(1_000, 10, 0); + gas.withhold(4); + let settled = gas.remaining(); + gas.erase_cost(5); + consume_hook_credit(&mut gas, settled); + assert_eq!(gas.remaining(), 10); + assert_eq!(gas.withheld(), 4, "the withheld part is kept"); + } +} diff --git a/crates/handler/tests/failed_charge.rs b/crates/handler/tests/failed_charge.rs index 93b77d946b..40df8f48d0 100644 --- a/crates/handler/tests/failed_charge.rs +++ b/crates/handler/tests/failed_charge.rs @@ -92,7 +92,10 @@ impl Handler for Observer { ItemOrResult::Item(_) => continue, ItemOrResult::Result(result) => result, }, - ItemOrResult::Result(result) => result, + ItemOrResult::Result(mut result) => { + evm.frame_run_result(&mut result)?; + result + } }; record(&result); if let Some(result) = evm.frame_return_result(result)? { diff --git a/crates/handler/tests/frame_result_size.rs b/crates/handler/tests/frame_result_size.rs new file mode 100644 index 0000000000..1993afde35 --- /dev/null +++ b/crates/handler/tests/frame_result_size.rs @@ -0,0 +1,19 @@ +//! The size of a frame result and of the values it is built from. + +use interpreter::{CallOutcome, CreateOutcome, Gas, InterpreterResult}; +use revm_handler::FrameResult; + +/// A frame result is 216 bytes on a 64-bit target, and the values it is built from are what that +/// takes. The handler moves frame results through its wrappers several times per frame, and past +/// about 256 bytes each move is a library copy rather than an inline one, so a field added to any +/// of them is measured before this changes. +#[cfg(target_pointer_width = "64")] +#[test] +fn test_a_frame_result_is_216_bytes() { + use core::mem::size_of; + assert_eq!(size_of::<Gas>(), 112); + assert_eq!(size_of::<InterpreterResult>(), 152); + assert_eq!(size_of::<CallOutcome>(), 216); + assert_eq!(size_of::<CreateOutcome>(), 200); + assert_eq!(size_of::<FrameResult>(), 216); +} diff --git a/crates/handler/tests/history_gas.rs b/crates/handler/tests/history_gas.rs index af45f91b10..0db5493e0d 100644 --- a/crates/handler/tests/history_gas.rs +++ b/crates/handler/tests/history_gas.rs @@ -248,7 +248,10 @@ impl Handler for Observer { ItemOrResult::Item(_) => continue, ItemOrResult::Result(result) => result, }, - ItemOrResult::Result(result) => result, + ItemOrResult::Result(mut result) => { + evm.frame_run_result(&mut result)?; + result + } }; self.record(&result); if let Some(result) = evm.frame_return_result(result)? { diff --git a/crates/handler/tests/reservoir_only_give_backs.rs b/crates/handler/tests/reservoir_only_give_backs.rs new file mode 100644 index 0000000000..6237b63d32 --- /dev/null +++ b/crates/handler/tests/reservoir_only_give_backs.rs @@ -0,0 +1,568 @@ +//! Give-backs to the reservoir alone (`Cfg::reservoir_only_give_backs`) and the legacy share of a +//! state charge, through the mainnet handler on Amsterdam. +//! +//! With the switch off and every legacy share zero, which is the default, the handler is +//! EIP-8037's: the rest of this crate's tests run that way. These pin what the switch and the +//! shares change, each against the same transaction without them. + +use bytecode::opcode::{ + CALL, CODECOPY, CREATE, GAS, INVALID, MSTORE, POP, PUSH0, PUSH1, PUSH20, PUSH4, RETURN, REVERT, + SELFDESTRUCT, SSTORE, STOP, +}; +use context::{ + result::{EVMError, ExecutionResult, HaltReason}, + Context, ContextSetters, Evm, TxEnv, +}; +use context_interface::{cfg::GasId, Cfg, ContextTr, Database}; +use database::{CacheDB, EmptyDB, BENCH_CALLER}; +use interpreter::{interpreter_action::FrameInit, GasTracker, InstructionResult}; +use primitives::{address, eip8037, hardfork::SpecId, Address, Bytes, TxKind, U256}; +use revm_handler::{ + instructions::EthInstructions, post_execution, EthPrecompiles, EvmTr, FrameResult, Handler, + ItemOrResult, MainContext, MainnetContext, MainnetEvm, +}; +use state::{AccountInfo, Bytecode}; +use std::cell::Cell; + +type Db = CacheDB<EmptyDB>; +type DbError = <Db as Database>::Error; +type TestContext = MainnetContext<Db>; +type TestEvm = MainnetEvm<TestContext>; +type TestError = EVMError<DbError>; + +/// Contract the transaction calls. +const CONTRACT: Address = address!("0x000000000000000000000000000000000000c0de"); +/// Contract [`CONTRACT`] calls. +const CHILD: Address = address!("0x000000000000000000000000000000000000c41d"); +/// An address the state holds no account for. +const EMPTY: Address = address!("0x000000000000000000000000000000000000e3e3"); + +/// Regular gas budget of a transaction; the gas limit above it is the reservoir. +const REGULAR_CAP: u64 = 2_000_000; +/// A reservoir that pays every state charge here. +const RESERVOIR: u64 = 1_000_000; + +/// State gas of a fresh slot. +const SSTORE_SET: u64 = eip8037::SSTORE_SET_BYTES * eip8037::CPSB_GLAMSTERDAM; +/// State gas of a new or created account. +const NEW_ACCOUNT: u64 = eip8037::NEW_ACCOUNT_BYTES * eip8037::CPSB_GLAMSTERDAM; + +/// The legacy shares a chain that keeps its pre-Amsterdam prices in regular gas would set. +const SLOT_SHARE: u64 = 10_000; +const CALL_SHARE: u64 = 25_000; +const SELFDESTRUCT_SHARE: u64 = 16_000; +const CREATE_SHARE: u64 = 20_000; + +/// Bytecode under construction. +#[derive(Default)] +struct Code(Vec<u8>); + +impl Code { + fn op(mut self, op: u8) -> Self { + self.0.push(op); + self + } + + /// Pushes `value` as a four-byte word, so the gas the code costs does not depend on it. + fn push(mut self, value: u64) -> Self { + let value = u32::try_from(value).expect("test amounts fit in four bytes"); + self.0.push(PUSH4); + self.0.extend_from_slice(&value.to_be_bytes()); + self + } + + fn push_address(mut self, address: Address) -> Self { + self.0.push(PUSH20); + self.0.extend_from_slice(address.as_slice()); + self + } + + /// Writes `value` to slot zero. + fn sstore(self, value: u64) -> Self { + self.push(value).push(0).op(SSTORE) + } + + /// `CALL(gas, to, value, 0, 0, 0, 0)`, dropping the success flag; `gas` of `None` forwards + /// all the call may. + fn call(self, gas: Option<u64>, to: Address, value: u64) -> Self { + let code = self + .op(PUSH0) + .op(PUSH0) + .op(PUSH0) + .op(PUSH0) + .push(value) + .push_address(to); + let code = match gas { + Some(gas) => code.push(gas), + None => code.op(GAS), + }; + code.op(CALL).op(POP) + } + + /// `CREATE` with [`initcode`], which this code carries after its last instruction. + fn create_and_stop(self) -> Self { + let initcode = initcode(); + let len = initcode.len() as u64; + let with_offset = |offset| { + Code(self.0.clone()) + .push(len) + .push(offset) + .op(PUSH0) + .op(CODECOPY) + .push(len) + .op(PUSH0) + .op(PUSH0) + .op(CREATE) + .op(POP) + .op(STOP) + }; + // Four-byte pushes keep the prefix length independent of the offset it carries. + let offset = with_offset(0).0.len() as u64; + let mut code = with_offset(offset); + code.0.extend_from_slice(&initcode); + code + } + + fn revert(self) -> Self { + self.op(PUSH0).op(PUSH0).op(REVERT) + } + + fn build(self) -> Bytecode { + Bytecode::new_raw(Bytes::from(self.0)) + } +} + +/// Initcode that deploys one `STOP` byte. +fn initcode() -> Vec<u8> { + vec![PUSH1, STOP, PUSH0, MSTORE, PUSH1, 1, PUSH1, 31, RETURN] +} + +/// A frame's gas as it returned, before its caller settled it. +#[derive(Clone, Copy, Debug)] +struct Returned { + result: InstructionResult, + gas: GasTracker, +} + +/// The mainnet handler, recording gas as frames return and settle. +#[derive(Default)] +struct Observer { + returned: Vec<Returned>, + settled: Cell<Option<GasTracker>>, +} + +impl Observer { + fn record(&mut self, result: &FrameResult) { + self.returned.push(Returned { + result: result.instruction_result(), + gas: *result.gas().tracker(), + }); + } +} + +impl Handler for Observer { + type Evm = TestEvm; + type Error = TestError; + type HaltReason = HaltReason; + + /// The default loop, recording each frame result before it goes back to its caller. + fn run_exec_loop( + &mut self, + evm: &mut TestEvm, + first_frame_input: FrameInit, + ) -> Result<FrameResult, TestError> { + if let ItemOrResult::Result(result) = evm.frame_init(first_frame_input)? { + self.record(&result); + return Ok(result); + } + loop { + let result = match evm.frame_run()? { + ItemOrResult::Item(init) => match evm.frame_init(init)? { + ItemOrResult::Item(_) => continue, + ItemOrResult::Result(result) => result, + }, + ItemOrResult::Result(mut result) => { + evm.frame_run_result(&mut result)?; + result + } + }; + self.record(&result); + if let Some(result) = evm.frame_return_result(result)? { + return Ok(result); + } + } + } + + /// Records the settled transaction-level gas, then refunds as the default does. + fn refund( + &self, + evm: &mut TestEvm, + exec_result: &mut FrameResult, + eip7702_refund: i64, + ) -> Result<(), TestError> { + self.settled.set(Some(*exec_result.gas().tracker())); + post_execution::refund( + evm.ctx().cfg().gas_params(), + exec_result.gas_mut(), + eip7702_refund, + ); + Ok(()) + } +} + +/// What the observed handler saw of one transaction. +struct Run { + result: ExecutionResult, + /// Every frame's gas as it returned, innermost first. + returned: Vec<Returned>, + /// The transaction-level gas once the first frame settled into it. + settled: GasTracker, +} + +impl Run { + /// The transaction's own frame, as it returned. + fn top(&self) -> Returned { + *self.returned.last().expect("the transaction ran a frame") + } + + /// The one frame [`CONTRACT`] started, as it returned. + fn child(&self) -> Returned { + assert_eq!(self.returned.len(), 2, "one child and the top frame"); + self.returned[0] + } +} + +/// How a run is configured: the switch, and whether the schedule sets the legacy shares. +#[derive(Clone, Copy, Debug)] +struct Setting { + reservoir_only: bool, + shares: bool, +} + +const UPSTREAM: Setting = Setting { + reservoir_only: false, + shares: false, +}; +const SATIN: Setting = Setting { + reservoir_only: true, + shares: true, +}; +const RESERVOIR_ONLY: Setting = Setting { + reservoir_only: true, + shares: false, +}; + +fn context(db: Db, setting: Setting) -> TestContext { + Context::mainnet().with_db(db).modify_cfg_chained(|cfg| { + cfg.set_spec_and_mainnet_gas_params(SpecId::AMSTERDAM); + cfg.tx_gas_limit_cap = Some(REGULAR_CAP); + cfg.reservoir_only_give_backs = setting.reservoir_only; + if setting.shares { + cfg.gas_params.override_gas([ + (GasId::sstore_set_state_gas_legacy_share(), SLOT_SHARE), + (GasId::new_account_state_gas_legacy_share(), CALL_SHARE), + ( + GasId::selfdestruct_new_account_state_gas_legacy_share(), + SELFDESTRUCT_SHARE, + ), + (GasId::create_state_gas_legacy_share(), CREATE_SHARE), + ]); + } + }) +} + +fn run(ctx: TestContext, tx: TxEnv) -> Run { + let spec = ctx.cfg.spec; + let instructions = EthInstructions::new_mainnet_with_spec(spec); + let mut evm: TestEvm = Evm::new(ctx, instructions, EthPrecompiles::new(spec)); + evm.ctx.set_tx(tx); + + let mut observer = Observer::default(); + let result = observer.run(&mut evm).expect("transaction runs"); + Run { + result, + returned: observer.returned, + settled: observer.settled.get().expect("post-execution ran"), + } +} + +/// A funded sender, [`CONTRACT`] holding `contract` and a balance of `balance`, and [`CHILD`] +/// holding `child`. +fn db(contract: Code, balance: u64, child: Code) -> Db { + let mut db = Db::default(); + db.insert_account_info( + BENCH_CALLER, + AccountInfo::from_balance(U256::from(10u128.pow(21))), + ); + for (address, code, balance) in [(CONTRACT, contract, balance), (CHILD, child, 0)] { + let code = code.build(); + db.insert_account_info( + address, + AccountInfo::new(U256::from(balance), 1, code.hash_slow(), code), + ); + } + db +} + +fn tx(kind: TxKind, data: Vec<u8>, gas_limit: u64) -> TxEnv { + TxEnv::builder_for_bench() + .kind(kind) + .data(Bytes::from(data)) + .gas_price(0) + .gas_limit(gas_limit) + .build_fill() +} + +/// Runs a call to [`CONTRACT`] with `reservoir` above the regular budget. +fn call(setting: Setting, contract: Code, balance: u64, child: Code, reservoir: u64) -> Run { + run( + context(db(contract, balance, child), setting), + tx(TxKind::Call(CONTRACT), Vec::new(), REGULAR_CAP + reservoir), + ) +} + +/// `(regular gas left, reservoir)` of a tracker. +const fn pools(gas: &GasTracker) -> (u64, u64) { + (gas.remaining(), gas.reservoir()) +} + +/// The handler gives the transaction's gas and every frame's the switch the configuration sets. +#[test] +fn test_every_frames_gas_carries_the_configured_switch() { + for setting in [UPSTREAM, RESERVOIR_ONLY] { + let run = call( + setting, + Code::default().call(Some(100_000), CHILD, 0).op(STOP), + 0, + Code::default().op(STOP), + RESERVOIR, + ); + assert_eq!(run.returned.len(), 2); + for returned in &run.returned { + assert_eq!( + returned.gas.reservoir_only_give_backs(), + setting.reservoir_only, + "{setting:?}" + ); + } + assert_eq!( + run.settled.reservoir_only_give_backs(), + setting.reservoir_only + ); + } +} + +/// A fresh slot's legacy share comes from regular gas before the reservoir pays the rest: the +/// frame ends with the share less regular gas and the share more reservoir, the charge and the +/// total the same. +#[test] +fn test_a_fresh_slot_takes_its_legacy_share_from_regular_gas_first() { + let code = || Code::default().sstore(1).op(STOP); + let plain = call(RESERVOIR_ONLY, code(), 0, Code::default(), RESERVOIR); + let shared = call(SATIN, code(), 0, Code::default(), RESERVOIR); + + let (regular, reservoir) = pools(&plain.top().gas); + assert_eq!(reservoir, RESERVOIR - SSTORE_SET); + assert_eq!( + pools(&shared.top().gas), + (regular - SLOT_SHARE, reservoir + SLOT_SHARE) + ); + assert_eq!(shared.top().gas.state_gas_spent(), SSTORE_SET as i64); + assert_eq!( + shared.result.gas().total_gas_spent(), + plain.result.gas().total_gas_spent() + ); +} + +/// A frame whose regular gas cannot pay a fresh slot's legacy share runs out of gas, whatever +/// its reservoir holds; one regular gas more pays it. +#[test] +fn test_a_legacy_share_regular_gas_cannot_pay_is_an_out_of_gas() { + let child = || Code::default().sstore(1).op(STOP); + // What the child spends of its regular gas without a share. + let measured = call( + RESERVOIR_ONLY, + Code::default().call(Some(100_000), CHILD, 0).op(STOP), + 0, + child(), + RESERVOIR, + ); + let returned = measured.child(); + assert_eq!(returned.result, InstructionResult::Stop); + let regular = returned.gas.limit() - returned.gas.remaining(); + + for (forward, result) in [ + (regular + SLOT_SHARE - 1, InstructionResult::OutOfGas), + (regular + SLOT_SHARE, InstructionResult::Stop), + ] { + let run = call( + SATIN, + Code::default().call(Some(forward), CHILD, 0).op(STOP), + 0, + child(), + RESERVOIR, + ); + assert_eq!(run.child().result, result, "forward {forward}"); + } +} + +/// The share of a value call's new account is taken before the forward is computed, so the +/// child is forwarded 63/64 of what the share left. +#[test] +fn test_a_value_calls_new_account_share_is_taken_before_the_forward() { + let contract = || Code::default().call(None, EMPTY, 1).op(STOP); + let plain = call(RESERVOIR_ONLY, contract(), 1, Code::default(), RESERVOIR); + let shared = call(SATIN, contract(), 1, Code::default(), RESERVOIR); + + let forward = |remaining: u64| remaining - remaining / 64; + let plain_limit = plain.child().gas.limit(); + let shared_limit = shared.child().gas.limit(); + let stipend = 2_300; + // Invert the plain forward to the regular gas the caller held before it. + let held = (0..64) + .map(|r| (plain_limit - stipend) * 64 / 63 + r) + .find(|held| forward(*held) == plain_limit - stipend) + .expect("the forward inverts"); + assert_eq!(shared_limit - stipend, forward(held - CALL_SHARE)); + assert_eq!( + shared.top().gas.reservoir() - plain.top().gas.reservoir(), + CALL_SHARE, + "regular gas paid the share, and the reservoir the rest" + ); +} + +/// The share of a creation's account is taken before the forward is computed. +#[test] +fn test_a_creations_account_share_is_taken_before_the_forward() { + let contract = || Code::default().create_and_stop(); + let plain = call(RESERVOIR_ONLY, contract(), 0, Code::default(), RESERVOIR); + let shared = call(SATIN, contract(), 0, Code::default(), RESERVOIR); + let forward = |remaining: u64| remaining - remaining / 64; + + let plain_limit = plain.child().gas.limit(); + let held = (0..64) + .map(|r| plain_limit * 64 / 63 + r) + .find(|held| forward(*held) == plain_limit) + .expect("the forward inverts"); + assert_eq!(shared.child().gas.limit(), forward(held - CREATE_SHARE)); +} + +/// A `SELFDESTRUCT` that creates its beneficiary takes that account's share from regular gas +/// before the reservoir. +#[test] +fn test_a_selfdestructs_new_beneficiary_takes_its_share_from_regular_gas_first() { + let contract = || Code::default().push_address(EMPTY).op(SELFDESTRUCT); + let plain = call(RESERVOIR_ONLY, contract(), 1, Code::default(), RESERVOIR); + let shared = call(SATIN, contract(), 1, Code::default(), RESERVOIR); + + let (regular, reservoir) = pools(&plain.top().gas); + assert_eq!(reservoir, RESERVOIR - NEW_ACCOUNT); + assert_eq!( + pools(&shared.top().gas), + (regular - SELFDESTRUCT_SHARE, reservoir + SELFDESTRUCT_SHARE) + ); +} + +/// A slot written and written back gives its state gas back into the reservoir with the switch +/// on, though regular gas paid it, and to regular gas with the switch off. +#[test] +fn test_a_slot_written_back_gives_its_state_gas_to_the_reservoir() { + let code = || Code::default().sstore(1).sstore(0).op(STOP); + let upstream = call(UPSTREAM, code(), 0, Code::default(), 0); + let reservoir_only = call(RESERVOIR_ONLY, code(), 0, Code::default(), 0); + + let (regular, reservoir) = pools(&upstream.top().gas); + assert_eq!(reservoir, 0); + assert_eq!( + pools(&reservoir_only.top().gas), + (regular - SSTORE_SET, SSTORE_SET) + ); + assert_eq!( + reservoir_only.top().gas.state_gas_spilled(), + SSTORE_SET, + "what regular gas paid stays counted" + ); + assert_eq!( + reservoir_only.result.gas().total_gas_spent(), + upstream.result.gas().total_gas_spent(), + "the reservoir returns to the sender with the regular gas" + ); +} + +/// A child that pays a fresh slot from regular gas and reverts returns that charge in its +/// reservoir with the switch on, and as regular gas with it off: its caller holds the charge's +/// less regular gas and the charge more reservoir. +#[test] +fn test_a_reverting_child_returns_its_regular_paid_charge_as_reservoir() { + let contract = || Code::default().call(Some(500_000), CHILD, 0).op(STOP); + let child = || Code::default().sstore(1).revert(); + let upstream = call(UPSTREAM, contract(), 0, child(), 0); + let reservoir_only = call(RESERVOIR_ONLY, contract(), 0, child(), 0); + + assert_eq!(upstream.child().result, InstructionResult::Revert); + let (regular, reservoir) = pools(&upstream.top().gas); + assert_eq!(reservoir, 0); + assert_eq!( + pools(&reservoir_only.top().gas), + (regular - SSTORE_SET, SSTORE_SET) + ); + assert_eq!( + reservoir_only.top().gas.state_gas_spilled(), + SSTORE_SET, + "the caller counts what the child's regular gas paid" + ); +} + +/// A child that pays a fresh slot from regular gas and halts returns the reservoir it received, +/// with the switch on as with it off: what regular gas paid is consumed with its regular gas, and +/// its caller ends with the pools it has without the switch. With the switch on the caller counts +/// what the halted child's regular gas paid, and that the halt consumed it. +#[test] +fn test_a_halting_child_returns_the_reservoir_it_received() { + let contract = || Code::default().call(Some(500_000), CHILD, 0).op(STOP); + let child = || Code::default().sstore(1).op(INVALID); + let upstream = call(UPSTREAM, contract(), 0, child(), 0); + let reservoir_only = call(RESERVOIR_ONLY, contract(), 0, child(), 0); + + assert_eq!(upstream.child().result, InstructionResult::InvalidFEOpcode); + assert_eq!(upstream.top().gas.reservoir(), 0); + assert_eq!(pools(&reservoir_only.top().gas), pools(&upstream.top().gas)); + assert_eq!(reservoir_only.top().gas.state_gas_spilled(), SSTORE_SET); + assert_eq!(reservoir_only.top().gas.halted_regular_paid(), SSTORE_SET); + assert_eq!(upstream.top().gas.state_gas_spilled(), 0); +} + +/// A creation whose init code pays a fresh slot from regular gas before it halts: the frame's own +/// count joins the transaction's at the settlement, and the created account's state gas still +/// comes back for exactly the part the reservoir paid of it, read off what regular gas paid before +/// the frame, not off the count the frame added to. +#[test] +fn test_a_halting_first_frame_that_paid_a_slot_gives_back_only_what_the_reservoir_paid() { + let reservoir = NEW_ACCOUNT / 3; + let init_code = Code::default().sstore(1).op(INVALID).0; + for setting in [UPSTREAM, RESERVOIR_ONLY] { + let run = run( + context(db(Code::default(), 0, Code::default()), setting), + tx(TxKind::Create, init_code.clone(), REGULAR_CAP + reservoir), + ); + assert_eq!(run.top().result, InstructionResult::InvalidFEOpcode); + assert_eq!(pools(&run.settled), (0, reservoir), "{setting:?}"); + } +} + +/// A creation transaction whose frame halts gives back, with the switch on, the part of its +/// created account's state gas the reservoir paid, and consumes the part regular gas paid, as the +/// tracker without the switch does. +#[test] +fn test_a_halting_first_frame_gives_back_only_what_the_reservoir_paid_of_its_charge() { + let reservoir = NEW_ACCOUNT / 3; + for setting in [UPSTREAM, RESERVOIR_ONLY] { + let run = run( + context(db(Code::default(), 0, Code::default()), setting), + tx(TxKind::Create, vec![INVALID], REGULAR_CAP + reservoir), + ); + assert_eq!(run.top().result, InstructionResult::InvalidFEOpcode); + assert_eq!(pools(&run.settled), (0, reservoir), "{setting:?}"); + assert!(matches!(run.result, ExecutionResult::Halt { .. })); + } +} diff --git a/crates/handler/tests/reservoir_settlement.rs b/crates/handler/tests/reservoir_settlement.rs new file mode 100644 index 0000000000..7af0a7c56b --- /dev/null +++ b/crates/handler/tests/reservoir_settlement.rs @@ -0,0 +1,1178 @@ +//! A child frame's EIP-8037 reservoir, as the mainnet handler forwards and settles it, and as a +//! consumer that keeps part of it for the caller settles it through the start lifecycle. +//! +//! A frame start copies its caller's reservoir into the child's input, and the caller keeps it +//! while the child runs; the child's return replaces the caller's reservoir with what the child +//! left, once that has unwound the caller's outstanding spill. That is upstream's forward and +//! settlement, and the default. +//! +//! A consumer that keeps part of the reservoir for the caller takes it in the frame-start hook, +//! names the child's reservoir on the start (`FrameStart::reservoir`), and adds back the reservoir +//! the caller held (`FrameSettle::held_reservoir`) when revm settles the child. The tests here keep +//! 2% that way, through [`KeepingContext`], and get the figures a forward of 98% that adds the +//! child's return to the part the caller kept gives. +//! +//! The transactions run on Amsterdam with a gas limit [`RESERVOIR`] above the regular cap, so they +//! start with a reservoir. The frames charge state gas through an instruction of the test's own, +//! `CHARGE`, which stands in for a write's state charge, and through `SSTORE`. The handler is the +//! mainnet one, observed through overrides that leave its behaviour alone: each frame's reservoir +//! as it starts, and as it returns before its caller settles it. + +use bytecode::opcode::{ + CALL, CREATE, DELEGATECALL, INVALID, MSTORE, POP, PUSH0, PUSH1, PUSH2, PUSH20, PUSH3, REVERT, + SSTORE, STOP, +}; +use context::{ + result::{EVMError, ExecutionResult}, + BlockEnv, CfgEnv, Context, ContextError, ContextSetters, ContextTr, Evm, Journal, LocalContext, + TxEnv, +}; +use context_interface::{ + cfg::{gas::InitialAndFloorGas, GasId, GasParams, StateGasSite}, + context::{SStoreResult, SelfDestructResult, StateLoad}, + host::{FrameSettle, FrameSplit, FrameStart, LifecycleEnd, LoadError}, + journaled_state::AccountInfoLoad, + Cfg, Database, Host, +}; +use database::{CacheDB, EmptyDB, BENCH_CALLER}; +use interpreter::{ + interpreter::EthInterpreter, interpreter_action::FrameInit, FrameInput, GasTracker, + Instruction, InstructionContext, InstructionExecResult, InstructionResult, +}; +use primitives::{ + address, constants::CALL_STACK_LIMIT, hardfork::SpecId, Address, Bytes, Log, StorageKey, + StorageValue, TxKind, B256, U256, +}; +use revm_handler::{ + instructions::EthInstructions, system_call::SystemCallTx, EthFrame, EthPrecompiles, EvmTr, + FrameResult, Handler, ItemOrResult, MainContext, MainnetContext, MainnetHandler, +}; +use state::{AccountInfo, Bytecode}; + +type Db = CacheDB<EmptyDB>; +type DbError = <Db as Database>::Error; +type TestContext = KeepingContext; +type TestEvm = + Evm<TestContext, (), EthInstructions<EthInterpreter, TestContext>, EthPrecompiles, EthFrame>; +type TestError = EVMError<DbError>; +type Mainnet = MainnetHandler<TestEvm, TestError, EthFrame<EthInterpreter>>; + +const SPEC: SpecId = SpecId::AMSTERDAM; +const GAS_LIMIT: u64 = 3_000_000; +/// The reservoir a transaction starts with: the regular cap is set this far below +/// [`GAS_LIMIT`], and no transaction here pays state gas in its intrinsic cost. +const RESERVOIR: u64 = 1_000_000; +/// What `CHARGE` charges as state gas. +const CHARGED: u64 = 1_000; +/// The share of a caller's reservoir a consumer that keeps part of it forwards. +const PERCENT: u64 = 98; +/// State gas of a new storage slot on Amsterdam's schedule. +const SLOT: u64 = 97_920; + +/// The account the transaction calls. +const PARENT: Address = address!("0x00000000000000000000000000000000000c0de0"); +/// Charges and stops. +const OK: Address = address!("0x0000000000000000000000000000000000000c00"); +/// Charges and reverts. +const REVERTER: Address = address!("0x000000000000000000000000000000000000c0fd"); +/// Charges and halts. +const HALTER: Address = address!("0x000000000000000000000000000000000000c0fe"); +/// Charges, calls [`OK`] and reverts. +const NESTER: Address = address!("0x000000000000000000000000000000000000c0e5"); +/// Charges a thousand times what `CHARGE` does, past any share here. +const SPENDER: Address = address!("0x000000000000000000000000000000000000c5e0"); +/// Clears its caller's slot 0 and stops, run by `DELEGATECALL` on the caller's storage. +const RESTORER: Address = address!("0x000000000000000000000000000000000000c0e0"); +/// Clears its caller's slot 0 and reverts. +const RESTORER_REVERTS: Address = address!("0x000000000000000000000000000000000000c0e1"); +/// The `ECRECOVER` precompile. +const ECRECOVER: Address = address!("0x0000000000000000000000000000000000000001"); + +/// The test's instruction, on an opcode the EVM does not assign. +const CHARGE: u8 = 0x0c; + +/// Charges [`CHARGED`] of state gas on the frame, reservoir first, as a write's state charge +/// does; a charge the frame cannot pay is its out-of-gas. +const fn charge( + context: InstructionContext<'_, TestContext, EthInterpreter>, +) -> InstructionExecResult { + if context.interpreter.gas.record_state_cost(CHARGED) { + Ok(()) + } else { + Err(InstructionResult::OutOfGas) + } +} + +/// A frame's figures as it returned, before its caller settled it: its result, its reservoir and +/// its net state gas. +type Returned = (InstructionResult, u64, i64); + +/// The mainnet context, with the start lifecycle's hooks of a consumer that keeps part of each +/// caller's reservoir for the caller, when told to ([`KeepingContext::percent`]). +/// +/// The frame-start hook takes `100 - percent` per cent of the caller's reservoir, rounded down, +/// for the caller, and names the rest as the child's reservoir; the settlement hook adds the +/// reservoir the caller held back to it once revm has settled a child into it. The transaction's +/// frame is given the whole reservoir, so nothing is added back to the transaction's gas. Each +/// settlement's depth and held reservoir is recorded, told to keep or not. +struct KeepingContext { + inner: MainnetContext<Db>, + /// The per cent of a caller's reservoir a child receives, if the consumer keeps the rest. + percent: Option<u64>, + /// Every settlement's depth and `held_reservoir`, in the order revm settled them. + held: Vec<(usize, u64)>, +} + +impl ContextTr for KeepingContext { + type Block = BlockEnv; + type Tx = TxEnv; + type Cfg = CfgEnv; + type Db = Db; + type Journal = Journal<Db>; + type Chain = (); + type Local = LocalContext; + + fn all( + &self, + ) -> ( + &Self::Block, + &Self::Tx, + &Self::Cfg, + &Self::Db, + &Self::Journal, + &Self::Chain, + &Self::Local, + ) { + self.inner.all() + } + + fn all_mut( + &mut self, + ) -> ( + &Self::Block, + &Self::Tx, + &Self::Cfg, + &mut Self::Journal, + &mut Self::Chain, + &mut Self::Local, + ) { + self.inner.all_mut() + } + + fn error(&mut self) -> &mut Result<(), ContextError<DbError>> { + self.inner.error() + } +} + +impl ContextSetters for KeepingContext { + fn set_tx(&mut self, tx: Self::Tx) { + self.inner.set_tx(tx); + } + + fn set_block(&mut self, block: Self::Block) { + self.inner.set_block(block); + } +} + +impl Host for KeepingContext { + fn frame_starting(&mut self, start: &mut FrameStart, gas: &mut GasTracker) -> bool { + if let Some(percent) = self.percent { + let reservoir = gas.reservoir(); + let kept = reservoir * (100 - percent) / 100; + start.reservoir = Some(reservoir - kept); + gas.set_reservoir(kept); + } + true + } + + fn frame_split(&mut self, split: &FrameSplit) { + self.inner.frame_split(split); + } + + fn frame_settle(&mut self, settle: &FrameSettle, gas: &mut GasTracker) { + self.held.push((settle.depth, settle.held_reservoir)); + if self.percent.is_some() && settle.depth > 0 { + gas.set_reservoir(gas.reservoir() + settle.held_reservoir); + } + self.inner.frame_settle(settle, gas); + } + + fn frame_lifecycle_end(&mut self, end: LifecycleEnd) { + self.inner.frame_lifecycle_end(end); + } + + fn state_gas_price(&mut self, id: GasId, site: StateGasSite) -> Option<u64> { + self.inner.state_gas_price(id, site) + } + + fn basefee(&self) -> U256 { + self.inner.basefee() + } + + fn blob_gasprice(&self) -> U256 { + self.inner.blob_gasprice() + } + + fn gas_limit(&self) -> U256 { + self.inner.gas_limit() + } + + fn difficulty(&self) -> U256 { + self.inner.difficulty() + } + + fn prevrandao(&self) -> Option<U256> { + self.inner.prevrandao() + } + + fn block_number(&self) -> U256 { + self.inner.block_number() + } + + fn timestamp(&self) -> U256 { + self.inner.timestamp() + } + + fn beneficiary(&self) -> Address { + self.inner.beneficiary() + } + + fn slot_num(&self) -> U256 { + self.inner.slot_num() + } + + fn chain_id(&self) -> U256 { + self.inner.chain_id() + } + + fn effective_gas_price(&self) -> U256 { + self.inner.effective_gas_price() + } + + fn caller(&self) -> Address { + self.inner.caller() + } + + fn blob_hash(&self, number: usize) -> Option<U256> { + self.inner.blob_hash(number) + } + + fn max_initcode_size(&self) -> usize { + self.inner.max_initcode_size() + } + + fn gas_params(&self) -> &GasParams { + self.inner.gas_params() + } + + fn is_amsterdam_eip8037_enabled(&self) -> bool { + self.inner.is_amsterdam_eip8037_enabled() + } + + fn block_hash(&mut self, number: u64) -> Option<B256> { + self.inner.block_hash(number) + } + + fn selfdestruct( + &mut self, + address: Address, + target: Address, + skip_cold_load: bool, + ) -> Result<StateLoad<SelfDestructResult>, LoadError> { + self.inner.selfdestruct(address, target, skip_cold_load) + } + + fn log(&mut self, log: Log) { + self.inner.log(log) + } + + fn sstore_skip_cold_load( + &mut self, + address: Address, + key: StorageKey, + value: StorageValue, + skip_cold_load: bool, + ) -> Result<StateLoad<SStoreResult>, LoadError> { + self.inner + .sstore_skip_cold_load(address, key, value, skip_cold_load) + } + + fn sload_skip_cold_load( + &mut self, + address: Address, + key: StorageKey, + skip_cold_load: bool, + ) -> Result<StateLoad<StorageValue>, LoadError> { + self.inner + .sload_skip_cold_load(address, key, skip_cold_load) + } + + fn tstore(&mut self, address: Address, key: StorageKey, value: StorageValue) { + self.inner.tstore(address, key, value) + } + + fn tload(&mut self, address: Address, key: StorageKey) -> StorageValue { + self.inner.tload(address, key) + } + + fn load_account_info_skip_cold_load( + &mut self, + address: Address, + load_code: bool, + skip_cold_load: bool, + ) -> Result<AccountInfoLoad<'_>, LoadError> { + self.inner + .load_account_info_skip_cold_load(address, load_code, skip_cold_load) + } +} + +const fn returned(result: &FrameResult) -> Returned { + let gas = result.gas(); + ( + result.instruction_result(), + gas.reservoir(), + gas.state_gas_spent(), + ) +} + +fn reservoir_of(input: &FrameInput) -> u64 { + match input { + FrameInput::Call(inputs) => inputs.reservoir, + FrameInput::Create(inputs) => inputs.reservoir(), + FrameInput::Empty => unreachable!(), + } +} + +/// The mainnet handler, recording every frame's reservoir as it starts and its figures as it +/// returns, and the transaction's gas once the first frame settled into it. +struct ShareHandler { + mainnet: Mainnet, + /// Whether every frame below the transaction's starts one past the call-stack limit, where a + /// 1,025th nested start would. + too_deep: bool, + /// A reservoir to give the transaction's gas, as a consumer that splits a system call's gas + /// does; mainnet gives a system call none. + system_reservoir: Option<u64>, + starts: Vec<u64>, + returned: Vec<Returned>, + /// The transaction's reservoir and net state gas after the first frame settled into it. + settled: Option<(u64, i64)>, + /// The reservoir of the last gas `tx_gas` built. + tx_reservoir: core::cell::Cell<Option<u64>>, + /// The transaction's reservoir once the first frame's input was built. + after_first_input: Option<u64>, + /// Every settlement's depth and held reservoir, once the transaction's start settled. + held: Vec<(usize, u64)>, +} + +impl ShareHandler { + fn new() -> Self { + Self { + mainnet: Mainnet::default(), + too_deep: false, + system_reservoir: None, + starts: Vec::new(), + returned: Vec::new(), + settled: None, + tx_reservoir: core::cell::Cell::new(None), + after_first_input: None, + held: Vec::new(), + } + } +} + +impl Handler for ShareHandler { + type Evm = TestEvm; + type Error = TestError; + type HaltReason = context::result::HaltReason; + + fn tx_gas(&self, evm: &mut TestEvm, init_and_floor_gas: &InitialAndFloorGas) -> GasTracker { + let mut gas = self.mainnet.tx_gas(evm, init_and_floor_gas); + if let Some(reservoir) = self.system_reservoir { + gas.set_remaining(gas.remaining() - reservoir); + gas.set_reservoir(reservoir); + } + self.tx_reservoir.set(Some(gas.reservoir())); + gas + } + + fn first_frame_input( + &mut self, + evm: &mut TestEvm, + gas: &mut GasTracker, + ) -> Result<Option<FrameInit>, TestError> { + let input = self.mainnet.first_frame_input(evm, gas)?; + self.after_first_input = Some(gas.reservoir()); + Ok(input) + } + + /// The default loop, recording each frame's reservoir as it starts and its figures as it + /// returns, and starting the frames below the transaction's past the call-stack limit if told + /// to. + fn run_exec_loop( + &mut self, + evm: &mut TestEvm, + first_frame_input: FrameInit, + ) -> Result<FrameResult, TestError> { + self.starts + .push(reservoir_of(&first_frame_input.frame_input)); + if let ItemOrResult::Result(result) = evm.frame_init(first_frame_input)? { + self.returned.push(returned(&result)); + return Ok(result); + } + loop { + let result = match evm.frame_run()? { + ItemOrResult::Item(mut init) => { + self.starts.push(reservoir_of(&init.frame_input)); + if self.too_deep { + init.depth = CALL_STACK_LIMIT as usize + 1; + } + match evm.frame_init(init)? { + ItemOrResult::Item(_) => continue, + ItemOrResult::Result(result) => result, + } + } + ItemOrResult::Result(mut result) => { + evm.frame_run_result(&mut result)?; + result + } + }; + self.returned.push(returned(&result)); + if let Some(result) = evm.frame_return_result(result)? { + return Ok(result); + } + } + } + + /// The default, recording the transaction's gas as the first frame left it. + fn last_frame_result( + &mut self, + evm: &mut TestEvm, + frame_result: &mut FrameResult, + gas: &mut GasTracker, + ) -> Result<(), TestError> { + self.mainnet.last_frame_result(evm, frame_result, gas)?; + self.settled = Some((gas.reservoir(), gas.state_gas_spent())); + self.held = evm.ctx().held.clone(); + Ok(()) + } +} + +/// `op(gas, to, value, 0, 0, 0, 0)` for `CALL`, `op(gas, to, 0, 0, 0, 0)` for `DELEGATECALL`, +/// dropping the success flag. +fn call_with(op: u8, to: Address, value: u8, gas: u32) -> Vec<u8> { + let mut code = vec![PUSH0, PUSH0, PUSH0, PUSH0]; + if op == CALL { + code.extend_from_slice(&[PUSH1, value]); + } + code.push(PUSH20); + code.extend_from_slice(to.as_slice()); + code.push(PUSH3); + code.extend_from_slice(&gas.to_be_bytes()[1..]); + code.extend_from_slice(&[op, POP]); + code +} + +/// `CALL(100_000, to, 0, 0, 0, 0, 0)`, dropping the success flag. +fn call(to: Address) -> Vec<u8> { + call_with(CALL, to, 0, 100_000) +} + +fn ends(mut code: Vec<u8>) -> Vec<u8> { + code.push(STOP); + code +} + +/// A transaction that calls [`PARENT`], which holds `parent`. +struct Run { + parent: Vec<u8>, + parent_balance: u64, + /// The per cent of the reservoir a child receives, if the consumer keeps the rest for the + /// caller ([`KeepingContext`]); by default it receives the whole reservoir. + percent: Option<u64>, + /// The transaction, if not a call to [`PARENT`] with [`GAS_LIMIT`]. + tx: Option<TxEnv>, + /// The regular cap, if not [`RESERVOIR`] below [`GAS_LIMIT`]. + cap: Option<u64>, + /// An account with code at [`PARENT`]'s first created address, where a `CREATE` collides. + occupied: bool, +} + +impl Run { + const fn new(parent: Vec<u8>) -> Self { + Self { + parent, + parent_balance: 10, + percent: None, + tx: None, + cap: None, + occupied: false, + } + } + + const fn percent(mut self, percent: u64) -> Self { + self.percent = Some(percent); + self + } + + /// A transaction that creates a contract from `initcode`. + fn creation(initcode: Vec<u8>) -> Self { + let mut run = Self::new(Vec::new()); + run.tx = Some( + TxEnv::builder_for_bench() + .kind(TxKind::Create) + .data(Bytes::from(initcode)) + .gas_price(0) + .gas_limit(GAS_LIMIT) + .build_fill(), + ); + run + } + + const fn occupied(mut self) -> Self { + self.occupied = true; + self + } + + const fn penniless(mut self) -> Self { + self.parent_balance = 0; + self + } + + fn db(&self) -> Db { + let mut db = Db::default(); + db.insert_account_info( + BENCH_CALLER, + AccountInfo::from_balance(U256::from(10u128.pow(21))), + ); + let mut nester = vec![CHARGE]; + nester.extend(call(OK)); + nester.extend_from_slice(&[PUSH0, PUSH0, REVERT]); + let accounts: [(Address, Vec<u8>, u64); 8] = [ + (PARENT, self.parent.clone(), self.parent_balance), + (OK, vec![CHARGE, STOP], 0), + (REVERTER, vec![CHARGE, PUSH0, PUSH0, REVERT], 0), + (HALTER, vec![CHARGE, INVALID], 0), + (NESTER, nester, 0), + ( + SPENDER, + [CHARGE; 1_000].into_iter().chain([STOP]).collect(), + 0, + ), + (RESTORER, vec![PUSH0, PUSH0, SSTORE, STOP], 0), + ( + RESTORER_REVERTS, + vec![PUSH0, PUSH0, SSTORE, PUSH0, PUSH0, REVERT], + 0, + ), + ]; + for (address, code, balance) in accounts { + let info = AccountInfo::from_balance(U256::from(balance)) + .with_nonce(1) + .with_code(Bytecode::new_raw(Bytes::from(code))); + db.insert_account_info(address, info); + } + if self.occupied { + db.insert_account_info( + PARENT.create(1), + AccountInfo::default() + .with_nonce(1) + .with_code(Bytecode::new_raw(Bytes::from_static(&[STOP]))), + ); + } + db + } + + fn evm(&self) -> TestEvm { + let percent = self.percent; + let cap = self.cap.unwrap_or(GAS_LIMIT - RESERVOIR); + let ctx = Context::mainnet() + .with_db(self.db()) + .modify_cfg_chained(|cfg| { + cfg.set_spec_and_mainnet_gas_params(SPEC); + cfg.tx_gas_limit_cap = Some(cap); + }); + let ctx = KeepingContext { + inner: ctx, + percent, + held: Vec::new(), + }; + let mut instructions = EthInstructions::new_mainnet_with_spec(SPEC); + instructions.insert_instruction(CHARGE, Instruction::new(charge), 0); + let mut evm: TestEvm = Evm::new(ctx, instructions, EthPrecompiles::new(SPEC)); + evm.ctx.set_tx(self.tx.clone().unwrap_or_else(|| { + TxEnv::builder_for_bench() + .kind(TxKind::Call(PARENT)) + .gas_price(0) + .gas_limit(GAS_LIMIT) + .build_fill() + })); + evm + } + + /// Runs the transaction with `handler` and returns its result and the handler, with what it + /// recorded. + fn with(&self, mut handler: ShareHandler) -> (ExecutionResult, ShareHandler) { + let result = handler.run(&mut self.evm()).expect("the transaction runs"); + (result, handler) + } + + fn run(&self) -> (ExecutionResult, ShareHandler) { + self.with(ShareHandler::new()) + } +} + +/// [`PARENT`] charges, then calls a child that stops, one that reverts, one that halts and one +/// that calls a child of its own and reverts, each after a charge of its own. +fn at_depth() -> Run { + let mut parent = vec![CHARGE]; + for child in [OK, REVERTER, HALTER, NESTER] { + parent.extend(call(child)); + } + Run::new(ends(parent)) +} + +/// The share at 98: `reservoir` less the caller's 2%, rounded down. +const fn share(reservoir: u64) -> u64 { + reservoir - reservoir * (100 - PERCENT) / 100 +} + +/// A consumer that keeps 2% of each caller's reservoir, rounded down, gives each start the rest; +/// revm's settlement replaces the caller's reservoir with what the child hands back, and the +/// consumer adds what the caller held, the part it kept: what the child left when it succeeded, +/// the whole share when it reverted or halted, a successful grandchild's charge included, joins +/// the kept part. The transaction's frame is given the whole reservoir, which the transaction's gas +/// holds as its copy, so nothing is added back to it. No frame here spends past its share, so the +/// transaction ends with the figures the whole forward gives, and the same result. +#[test] +fn test_a_consumer_that_keeps_part_of_the_reservoir_adds_back_what_the_caller_held() { + let (result, handler) = at_depth().percent(PERCENT).run(); + + assert!(result.is_success(), "{result:?}"); + // PARENT charged 1,000 of its 1,000,000 before each start below. + let after_parent = RESERVOIR - CHARGED; + assert_eq!(share(after_parent), 979_020); + // OK returns 978,020, so PARENT holds 19,980 + 978,020 = 998,000 for each later start. + let before_each = after_parent - CHARGED; + assert_eq!(share(before_each), 978_040); + // NESTER charged 1,000 of its 978,040 before calling OK: it keeps 2% of 977,040 rounded + // down, 19,540, where 98% rounded down would have forwarded 957,499. + let nester_after = share(before_each) - CHARGED; + assert_eq!(share(nester_after), 957_500); + assert_eq!( + handler.starts, + [ + RESERVOIR, + share(after_parent), + share(before_each), + share(before_each), + share(before_each), + share(nester_after), + ] + ); + let charged = CHARGED as i64; + assert_eq!( + handler.returned, + [ + ( + InstructionResult::Stop, + share(after_parent) - CHARGED, + charged + ), + ( + InstructionResult::Revert, + share(before_each) - CHARGED, + charged + ), + ( + InstructionResult::InvalidFEOpcode, + share(before_each) - CHARGED, + charged + ), + // OK under NESTER: 957,500 less its charge. + ( + InstructionResult::Stop, + share(nester_after) - CHARGED, + charged + ), + // NESTER kept 19,540 and got back 956,500: 976,040, two charges net. + (InstructionResult::Revert, 976_040, 2 * charged), + ( + InstructionResult::Stop, + RESERVOIR - 2 * CHARGED, + 2 * charged + ), + ] + ); + assert_eq!( + handler.settled, + Some((RESERVOIR - 2 * CHARGED, 2 * charged)) + ); + // What each caller held when revm settled its child: the 2% it kept, of 999,000, 998,000 and + // 977,040; the transaction's gas held the copy of the whole reservoir it gave its frame. + assert_eq!( + handler.held, + [ + (1, 19_980), + (1, 19_960), + (1, 19_960), + (2, 19_540), + (1, 19_960), + (0, RESERVOIR), + ] + ); + + let (whole, whole_handler) = at_depth().run(); + assert_eq!(result, whole, "the shares change no result here"); + assert_eq!(whole_handler.settled, handler.settled); +} + +/// The default forward is upstream's: every start copies all its caller has into the child's +/// input, the caller keeps its reservoir while the child runs, and the child's return replaces it. +/// The transaction's gas keeps the reservoir it gives its frame, which its frame's return replaces. +#[test] +fn test_every_start_copies_the_whole_reservoir_by_default() { + let (result, handler) = at_depth().run(); + + assert!(result.is_success(), "{result:?}"); + assert_eq!( + handler.after_first_input, + Some(RESERVOIR), + "the transaction's gas keeps its reservoir" + ); + let before_each = RESERVOIR - 2 * CHARGED; + assert_eq!( + handler.starts, + [ + RESERVOIR, + RESERVOIR - CHARGED, + before_each, + before_each, + before_each, + before_each - CHARGED, + ] + ); + let charged = CHARGED as i64; + // NESTER and its OK each charged once on what NESTER started with. + assert_eq!( + handler.returned[4], + ( + InstructionResult::Revert, + before_each - 2 * CHARGED, + 2 * charged + ) + ); + assert_eq!(handler.settled, Some((before_each, 2 * charged))); + // Each caller held the reservoir it copied to its child: PARENT 999,000 at its first call and + // 998,000, OK's return, at the others; NESTER 997,000; the transaction's gas the whole. + assert_eq!( + handler.held, + [ + (1, RESERVOIR - CHARGED), + (1, before_each), + (1, before_each), + (2, before_each - CHARGED), + (1, before_each), + (0, RESERVOIR), + ] + ); +} + +/// A child whose charges pass its share spills onto its regular gas, as a frame whose reservoir +/// is empty does, though its caller holds the 2% the consumer kept: the share is all the child +/// has. On +/// return the caller holds what it kept beside the child's spill; when the caller's own frame +/// returns, its reservoir unwinds that spill first, as any returned reservoir does (last in, first +/// out), so the transaction ends as the whole forward ends it. +#[test] +fn test_a_child_spends_past_its_share_onto_its_regular_gas() { + let parent = ends(call(SPENDER)); + let (result, handler) = Run::new(parent.clone()).percent(PERCENT).run(); + let (whole, whole_handler) = Run::new(parent).run(); + + assert!( + result.is_success() && whole.is_success(), + "{result:?} {whole:?}" + ); + let spent = (1_000 * CHARGED) as i64; + // The share is 980,000 of 1,000,000: 20,000 of the million charged spill. + assert_eq!(handler.starts, [RESERVOIR, share(RESERVOIR)]); + assert_eq!( + handler.returned, + [ + (InstructionResult::Stop, 0, spent), + (InstructionResult::Stop, RESERVOIR - share(RESERVOIR), spent), + ], + "the share is spent and the rest spilled; PARENT holds what it kept" + ); + // With the whole reservoir forwarded, the million fits it exactly and nothing spills. + assert_eq!( + whole_handler.returned, + [ + (InstructionResult::Stop, 0, spent), + (InstructionResult::Stop, 0, spent) + ] + ); + assert_eq!(handler.settled, Some((0, spent))); + assert_eq!(whole_handler.settled, handler.settled); + assert_eq!(result, whole); +} + +/// The share is what the child may draw from the reservoir while it runs: a child that needs the +/// whole reservoir and has too little regular gas to pay past its share runs out of gas at 98%, +/// and its failure gives the share back, where the whole forward lets it finish. +#[test] +fn test_a_child_that_cannot_pay_past_its_share_runs_out_of_gas() { + let parent = ends(call_with(CALL, SPENDER, 0, 10_000)); + let (result, handler) = Run::new(parent.clone()).percent(PERCENT).run(); + let (whole, whole_handler) = Run::new(parent).run(); + + assert!( + result.is_success() && whole.is_success(), + "{result:?} {whole:?}" + ); + // 980 charges spend the share, ten more spill its 10,000 of regular gas, the 991st fails. + assert_eq!( + handler.returned[0], + ( + InstructionResult::OutOfGas, + 0, + (991 * CHARGED - CHARGED) as i64 + ) + ); + assert_eq!( + handler.settled, + Some((RESERVOIR, 0)), + "nothing charged in the end" + ); + let spent = (1_000 * CHARGED) as i64; + assert_eq!( + whole_handler.returned[0], + (InstructionResult::Stop, 0, spent) + ); + assert_eq!(whole_handler.settled, Some((0, spent))); +} + +/// A child that clears a slot its caller created gets the slot's state gas back as an EIP-8037 +/// restoration, into its own reservoir; when it succeeds, the caller gets it back with the rest of +/// the share and the part the consumer kept, and is back where it was before it created the slot. +/// When it reverts, the restoration is undone with the rest of its frame and the caller gets the +/// share back. +#[test] +fn test_a_restoration_in_the_child_comes_back_to_its_caller() { + for (restorer, kept) in [(RESTORER, true), (RESTORER_REVERTS, false)] { + let mut parent = vec![PUSH1, 1, PUSH0, SSTORE]; + parent.extend(call_with(DELEGATECALL, restorer, 0, 100_000)); + let (result, handler) = Run::new(ends(parent)).percent(PERCENT).run(); + + assert!(result.is_success(), "{restorer}: {result:?}"); + let created = RESERVOIR - SLOT; + assert_eq!(handler.starts, [RESERVOIR, share(created)], "{restorer}"); + if kept { + assert_eq!( + handler.returned[0], + ( + InstructionResult::Stop, + share(created) + SLOT, + -(SLOT as i64) + ), + "the restoration lands in the child's reservoir" + ); + assert_eq!( + handler.settled, + Some((RESERVOIR, 0)), + "nothing charged in all" + ); + } else { + assert_eq!( + handler.returned[0], + ( + InstructionResult::Revert, + share(created) + SLOT, + -(SLOT as i64) + ), + ); + assert_eq!( + handler.settled, + Some((created, SLOT as i64)), + "the slot stays, and its charge" + ); + } + } +} + +/// A precompile's answer carries the share it was given, which comes back whole; so does a start +/// the handler refuses before any frame: a transfer the caller cannot pay, and a start one past +/// the call-stack limit. +#[test] +fn test_an_answer_without_a_frame_hands_the_share_back() { + let mut precompile = vec![CHARGE]; + precompile.extend(call(ECRECOVER)); + let mut transfer = vec![CHARGE]; + transfer.extend(call_with(CALL, OK, 1, 100_000)); + let mut deep = vec![CHARGE]; + deep.extend(call(OK)); + for (name, run, too_deep, answer) in [ + ( + "a precompile", + Run::new(ends(precompile)), + false, + InstructionResult::Return, + ), + ( + "an unpaid transfer", + Run::new(ends(transfer)).penniless(), + false, + InstructionResult::OutOfFunds, + ), + ( + "too deep", + Run::new(ends(deep)), + true, + InstructionResult::CallTooDeep, + ), + ] { + let mut handler = ShareHandler::new(); + handler.too_deep = too_deep; + let (result, handler) = run.percent(PERCENT).with(handler); + + assert!(result.is_success(), "{name}: {result:?}"); + let before = RESERVOIR - CHARGED; + assert_eq!(handler.starts, [RESERVOIR, share(before)], "{name}"); + assert_eq!( + handler.returned[0], + (answer, share(before), 0), + "{name}: the answer carries the share" + ); + assert_eq!( + handler.settled, + Some((before, CHARGED as i64)), + "{name}: PARENT's reservoir whole again" + ); + } +} + +/// A system call's frame takes the whole reservoir its gas holds, a consumer's split of the +/// system call's gas, and its children their shares, as a transaction's do. +#[test] +fn test_a_system_call_forwards_and_settles_its_reservoir() { + for percent in [None, Some(PERCENT)] { + let mut run = Run::new(ends(call(OK))); + run.percent = percent; + let mut evm = run.evm(); + evm.ctx.set_tx(TxEnv::new_system_tx(PARENT, Bytes::new())); + let mut handler = ShareHandler::new(); + handler.system_reservoir = Some(RESERVOIR); + + let result = handler + .run_system_call(&mut evm) + .expect("the system call runs"); + + assert!(result.is_success(), "{percent:?}: {result:?}"); + let child = if percent.is_some() { + share(RESERVOIR) + } else { + RESERVOIR + }; + assert_eq!(handler.starts, [RESERVOIR, child], "{percent:?}"); + assert_eq!( + handler.returned[0], + (InstructionResult::Stop, child - CHARGED, CHARGED as i64), + "{percent:?}" + ); + assert_eq!( + handler.settled, + Some((RESERVOIR - CHARGED, CHARGED as i64)), + "{percent:?}" + ); + } +} + +/// `CREATE` of the two bytes `CHARGE STOP`, endowed with nothing, dropping the address. +fn create_charging() -> Vec<u8> { + vec![ + PUSH2, CHARGE, STOP, PUSH0, MSTORE, PUSH1, 2, PUSH1, 30, PUSH0, CREATE, POP, + ] +} + +/// A creation's frame gets its share like a call's, after the creation instruction's own state +/// charge for the account it creates, and settles it back; a creation that lands on an occupied +/// address fails before any frame and hands the share back whole. +#[test] +fn test_a_creation_forwards_its_share_and_a_collision_hands_it_back() { + let account = Run::new(Vec::new()) + .evm() + .ctx + .cfg() + .gas_params() + .get(GasId::create_state_gas()); + let mut parent = vec![CHARGE]; + parent.extend(create_charging()); + let after_parent = RESERVOIR - CHARGED; + + let (result, handler) = Run::new(ends(parent.clone())).percent(PERCENT).run(); + assert!(result.is_success(), "{result:?}"); + let before = after_parent - account; + assert_eq!(handler.starts, [RESERVOIR, share(before)]); + assert_eq!( + handler.returned[0], + ( + InstructionResult::Return, + share(before) - CHARGED, + CHARGED as i64 + ), + "the creation's own charge is on its frame" + ); + assert_eq!( + handler.settled, + Some((before - CHARGED, (2 * CHARGED + account) as i64)) + ); + + let (result, handler) = Run::new(ends(parent)).percent(PERCENT).occupied().run(); + assert!(result.is_success(), "{result:?}"); + assert_eq!( + handler.starts, + [RESERVOIR, share(after_parent)], + "no charge for an occupied address" + ); + assert_eq!( + handler.returned[0], + (InstructionResult::CreateCollision, share(after_parent), 0) + ); + assert_eq!(handler.settled, Some((after_parent, CHARGED as i64))); +} + +/// A creation transaction's frame is given the whole reservoir the transaction has left, which the +/// transaction's gas keeps as its copy, whether the consumer keeps part of a caller's reservoir or +/// not; the frame's return replaces it. +#[test] +fn test_a_creation_transaction_is_given_the_whole_reservoir() { + for percent in [None, Some(PERCENT)] { + let mut run = Run::creation(vec![CHARGE, STOP]); + run.percent = percent; + let (result, handler) = run.run(); + + assert!(result.is_success(), "{percent:?}: {result:?}"); + let first = handler.starts[0]; + assert!(first > 0, "{percent:?}"); + assert_eq!( + handler.after_first_input, + Some(first), + "{percent:?}: the transaction's gas keeps its copy" + ); + assert_eq!( + handler.settled.map(|(reservoir, _)| reservoir), + Some(first - CHARGED) + ); + } +} + +/// A transaction whose EIP-2780 runtime phase runs out of gas skips execution and is settled +/// from a stand-in for its first frame: all regular gas consumed and the reservoir returned once, +/// the stand-in's replacing the copy the transaction's gas kept. +#[test] +fn test_a_runtime_out_of_gas_returns_the_reservoir_once() { + const LIMIT: u64 = 130_000; + const CAP: u64 = 30_000; + for percent in [None, Some(PERCENT)] { + // A value transfer to an account that does not exist, whose new-account state gas the + // reservoir and the regular gas left together cannot pay. + let mut run = Run::new(Vec::new()); + run.percent = percent; + run.cap = Some(CAP); + run.tx = Some( + TxEnv::builder_for_bench() + .kind(TxKind::Call(address!( + "0x00000000000000000000000000000000000e3970" + ))) + .value(U256::from(1)) + .gas_price(0) + .gas_limit(LIMIT) + .build_fill(), + ); + let (result, handler) = run.run(); + + assert!( + matches!(result, ExecutionResult::Halt { .. }), + "{percent:?}: {result:?}" + ); + let reservoir = handler.tx_reservoir.get().expect("tx_gas ran"); + assert!(reservoir > 0, "{percent:?}"); + assert_eq!(handler.settled, Some((reservoir, 0)), "{percent:?}"); + assert_eq!( + result.gas().total_gas_spent(), + LIMIT - reservoir, + "{percent:?}: every regular gas spent, the reservoir returned" + ); + } +} + +/// The same for a creation transaction, whose runtime phase charges the account it would create: +/// the stand-in carries the whole reservoir, which settles back once. +#[test] +fn test_a_creation_transactions_runtime_out_of_gas_returns_the_reservoir_once() { + const LIMIT: u64 = 160_000; + const CAP: u64 = 60_000; + for percent in [None, Some(PERCENT)] { + // A creation whose account's state gas the reservoir and the regular gas left together + // cannot pay. + let mut run = Run::new(Vec::new()); + run.percent = percent; + run.cap = Some(CAP); + run.tx = Some( + TxEnv::builder_for_bench() + .kind(TxKind::Create) + .gas_price(0) + .gas_limit(LIMIT) + .build_fill(), + ); + let (result, handler) = run.with(ShareHandler::new()); + + assert!( + matches!(result, ExecutionResult::Halt { .. }), + "{percent:?}: {result:?}" + ); + let reservoir = handler.tx_reservoir.get().expect("tx_gas ran"); + assert!(reservoir > 0, "{percent:?}"); + assert_eq!(handler.settled, Some((reservoir, 0)), "{percent:?}"); + assert_eq!( + result.gas().total_gas_spent(), + LIMIT - reservoir, + "{percent:?}: every regular gas spent, the reservoir returned" + ); + } +} + +/// A runner that settles a first frame into gas that still holds the reservoir the frame was given, +/// as the transaction's gas does, gets the frame's reservoir in its place, counted once. +#[test] +fn test_a_first_frame_settled_into_gas_that_kept_its_reservoir_counts_it_once() { + let mut evm = Run::new(ends(Vec::new())).evm(); + let mut result = FrameResult::new_call_oog(GAS_LIMIT, 0..0, RESERVOIR); + let mut gas = GasTracker::new(GAS_LIMIT, 0, RESERVOIR); + // A runner that settles a first frame it built itself opens the transaction's start first. + revm_handler::lifecycle::open_transaction_start(&mut evm).expect("the start opens"); + + Mainnet::default() + .last_frame_result(&mut evm, &mut result, &mut gas) + .expect("the frame settles"); + + assert_eq!(gas.reservoir(), RESERVOIR); + assert_eq!(evm.ctx.held, [(0, RESERVOIR)]); +} + +/// A runner that builds the gas with `GasTracker::new`, with no reservoir, settles as before. +#[test] +fn test_a_first_frame_settled_into_gas_with_no_reservoir_settles() { + let mut evm = Run::new(ends(Vec::new())).evm(); + let mut result = FrameResult::new_call_oog(GAS_LIMIT, 0..0, 0); + let mut gas = GasTracker::new(GAS_LIMIT, 0, 0); + // A runner that settles a first frame it built itself opens the transaction's start first. + revm_handler::lifecycle::open_transaction_start(&mut evm).expect("the start opens"); + + Mainnet::default() + .last_frame_result(&mut evm, &mut result, &mut gas) + .expect("the frame settles"); + + assert_eq!(gas.reservoir(), 0); +} diff --git a/crates/handler/tests/withheld_gas.rs b/crates/handler/tests/withheld_gas.rs index 6b6a3a7f85..131a31adc0 100644 --- a/crates/handler/tests/withheld_gas.rs +++ b/crates/handler/tests/withheld_gas.rs @@ -143,7 +143,10 @@ impl Handler for Observer { ItemOrResult::Item(_) => continue, ItemOrResult::Result(result) => result, }, - ItemOrResult::Result(result) => result, + ItemOrResult::Result(mut result) => { + evm.frame_run_result(&mut result)?; + result + } }; record(&result); if let Some(result) = evm.frame_return_result(result)? { diff --git a/crates/inspector/src/handler.rs b/crates/inspector/src/handler.rs index 71337c388f..154622c554 100644 --- a/crates/inspector/src/handler.rs +++ b/crates/inspector/src/handler.rs @@ -100,6 +100,8 @@ where }; // The runtime gas phase is complete: commit its state changes. evm.ctx().journal_mut().checkpoint_commit(); + // The transaction's start opens with the frame init revm made for it. + handler::lifecycle::open_frame_start(evm, &first_frame_input)?; // Run execution loop let mut frame_result = self.inspect_run_exec_loop(evm, first_frame_input)?; @@ -247,6 +249,9 @@ pub fn frame_end<CTX, INTR: InterpreterTypes>( /// This function is used to inspect the Interpreter loop. /// It will call [`Inspector::step`] and [`Inspector::step_end`] after each instruction. /// And [`Inspector::log`],[`Inspector::selfdestruct`] for each log and selfdestruct instruction. +/// +/// An action set before the run ([`LoopControl::set_action`]) is returned before any +/// instruction runs and before any [`Inspector::step`], as [`Interpreter::run_plain`] returns it. pub fn inspect_instructions<CTX, IT>( context: &mut CTX, interpreter: &mut Interpreter<IT>, @@ -258,6 +263,10 @@ where CTX: ContextTr<Journal: JournalExt> + Host, IT: InterpreterTypes, { + if interpreter.bytecode.is_end() { + cold_path(); + return interpreter.take_next_action(); + } let mut instruction_journal_i = None; loop { inspector.step(interpreter, context); diff --git a/crates/inspector/src/inspector.rs b/crates/inspector/src/inspector.rs index 26840c49e9..affc763c0a 100644 --- a/crates/inspector/src/inspector.rs +++ b/crates/inspector/src/inspector.rs @@ -20,6 +20,11 @@ pub trait Inspector<CTX, INTR: InterpreterTypes = EthInterpreter, FI = FrameInpu /// Called before the interpreter is initialized. /// /// If `interp.bytecode.set_action` is set the execution of the interpreter is skipped. + /// The frame's run returns that action before its first [`Inspector::step`], so no `step` of + /// that run sees or edits it. + /// + /// Not called for a frame whose next action the EVM set when it built the frame: the frame's + /// first run returns that action before any instruction. #[inline] fn initialize_interp(&mut self, interp: &mut Interpreter<INTR>, context: &mut CTX) { let _ = interp; diff --git a/crates/inspector/src/traits.rs b/crates/inspector/src/traits.rs index e72b827855..026be03137 100644 --- a/crates/inspector/src/traits.rs +++ b/crates/inspector/src/traits.rs @@ -2,11 +2,11 @@ use context::{ContextTr, FrameStack, JournalTr}; use handler::{ evm::{ContextDbError, FrameInitResult, FrameTr}, instructions::InstructionProvider, - EthFrame, EvmTr, FrameInitOrResult, FrameResult, ItemOrResult, + lifecycle, EthFrame, EvmTr, FrameInitOrResult, FrameResult, ItemOrResult, }; use interpreter::{ - interpreter::EthInterpreter, interpreter_action::FrameInit, CallOutcome, FrameInput, - InterpreterTypes, + interpreter::EthInterpreter, interpreter_action::FrameInit, interpreter_types::LoopControl, + CallOutcome, FrameInput, InterpreterTypes, }; use crate::{ @@ -95,14 +95,27 @@ pub trait InspectorEvmTr: } /// Initializes the frame for the given frame input. Frame is pushed to the frame stack. + /// + /// A new frame is handed to [`Inspector::initialize_interp`] unless its next action is + /// already set ([`EvmTr::frame_init`] set it): its first run returns that action before any + /// instruction, and the inspector may not replace it. #[inline] fn inspect_frame_init( &mut self, mut frame_init: <Self::Frame as FrameTr>::FrameInit, ) -> Result<FrameInitResult<'_, Self::Frame>, ContextDbError<Self::Context>> { - let (ctx, inspector) = self.ctx_inspector(); + let (ctx, _, _, frame_stack, inspector) = self.all_mut_inspector(); if let Some(mut output) = frame_start(ctx, inspector, &mut frame_init.frame_input) { + // The inspector answered the start revm opened for this init. + let start = frame_stack.pending_start(); + if let Some(start) = &start { + lifecycle::mark_for_end_callbacks(&mut output, start); + } frame_end(ctx, inspector, &frame_init.frame_input, &mut output); + if let Some(start) = start { + start.set_inspector_answer(); + lifecycle::check_end_callbacks(&output, start); + } return Ok(ItemOrResult::Result(output)); } @@ -126,7 +139,14 @@ pub trait InspectorEvmTr: inspector.log(ctx, log); } } + if let Some(start) = self.frame_stack().pending_start() { + lifecycle::mark_for_end_callbacks(&mut output, start); + } + let (ctx, inspector) = self.ctx_inspector(); frame_end(ctx, inspector, &frame_input, &mut output); + if let Some(start) = self.frame_stack().pending_start() { + lifecycle::check_end_callbacks(&output, start); + } return Ok(ItemOrResult::Result(output)); } @@ -137,14 +157,21 @@ pub trait InspectorEvmTr: } if let Some(frame) = frame.eth_frame() { let interp = &mut frame.interpreter; - inspector.initialize_interp(interp, ctx); + if interp.bytecode.is_not_end() { + inspector.initialize_interp(interp, ctx); + } }; Ok(ItemOrResult::Item(frame)) } /// Run the frame from the top of the stack. Returns the frame init or result. /// - /// If frame has returned result it would mark it as finished. + /// If frame has returned result it would hand it to [`EvmTr::frame_run_result`], then to the + /// inspector's `frame_end`, and mark the frame as finished. A frame without an `EthFrame` is + /// run by [`EvmTr::frame_run`], and its result handed to [`EvmTr::frame_run_result`] only. + /// + /// A frame init it returns opens the child's start, as [`EvmTr::frame_run`] does + /// ([`lifecycle::open_frame_start`]). #[inline] fn inspect_frame_run( &mut self, @@ -152,7 +179,11 @@ pub trait InspectorEvmTr: let (ctx, inspector, frame, instructions) = self.ctx_inspector_frame_instructions(); let Some(frame) = frame.eth_frame() else { - return self.frame_run(); + let mut result = self.frame_run()?; + if let ItemOrResult::Result(frame_result) = &mut result { + self.frame_run_result(frame_result)?; + } + return Ok(result); }; let next_action = inspect_instructions( @@ -163,14 +194,26 @@ pub trait InspectorEvmTr: instructions.gas_table(), ); let mut result = frame.process_next_action(ctx, next_action); + // revm consumed the frame's `NewFrame` action: the child's start opens. + if let Ok(ItemOrResult::Item(init)) = &result { + lifecycle::open_frame_start(self, init)?; + } if let Ok(ItemOrResult::Result(frame_result)) = &mut result { + self.frame_run_result(frame_result)?; + // The result settles the start the frame runs for. + if let Some(start) = self.frame_stack().running_start() { + lifecycle::mark_for_end_callbacks(frame_result, start); + } let (ctx, inspector, frame) = self.ctx_inspector_frame(); // TODO When all_mut fn is added we can fetch inspector at the top of the function.s if let Some(frame) = frame.eth_frame() { frame_end(ctx, inspector, &frame.input, frame_result); frame.set_finished(true); } + if let Some(start) = self.frame_stack().running_start() { + lifecycle::check_end_callbacks(frame_result, start); + } }; result } diff --git a/crates/inspector/tests/custom_frame.rs b/crates/inspector/tests/custom_frame.rs new file mode 100644 index 0000000000..d3c79de9af --- /dev/null +++ b/crates/inspector/tests/custom_frame.rs @@ -0,0 +1,353 @@ +//! The inspected run of a consumer's own frame type, which wraps revm's [`EthFrame`] and gives the +//! inspector that frame ([`InspectorFrame::eth_frame`]) only while it has not finished. Nothing +//! asks the accessor to ignore the frame's state, so the run looks the frame up for the inspector's +//! end callbacks before it marks the frame finished, as upstream's does: the inspector sees each +//! frame's `call_end` and `frame_end`. +//! +//! [`PARENT`] calls [`CHILD`], and both stop. The consumer sets no action and keeps +//! [`EvmTr::frame_run_result`]'s default; its EVM runs its frames as revm's own does. + +use context::{ + result::{EVMError, ExecutionResult, HaltReason}, + Context, ContextSetters, Evm, FrameStack, OutFrame, TxEnv, +}; +use database::{CacheDB, EmptyDB, BENCH_CALLER}; +use handler::{ + evm::{ContextDbError, FrameInitResult, FrameTr}, + instructions::{EthInstructions, InstructionProvider}, + lifecycle, EthFrame, EthPrecompiles, EvmTr, FrameInitOrResult, FrameResult, Handler, + ItemOrResult, MainContext, MainnetContext, +}; +use interpreter::{ + interpreter::EthInterpreter, interpreter_action::FrameInit, CallInputs, CallOutcome, FrameInput, +}; +use primitives::{address, hardfork::SpecId, Address, Bytes, TxKind, U256}; +use revm_inspector::{Inspector, InspectorEvmTr, InspectorFrame, InspectorHandler}; +use state::{ + bytecode::opcode::{CALL, GAS, PUSH0, PUSH20, STOP}, + AccountInfo, Bytecode, +}; +use std::convert::Infallible; + +type Db = CacheDB<EmptyDB>; +type Ctx = MainnetContext<Db>; +type Instructions = EthInstructions<EthInterpreter, Ctx>; +type Inner = Evm<Ctx, Recorder, Instructions, EthPrecompiles, HiddenOnceFinished>; +type Error = EVMError<Infallible>; + +const SPEC: SpecId = SpecId::OSAKA; +const GAS_LIMIT: u64 = 1_000_000; + +/// Calls [`CHILD`] with all its gas, and stops. +const PARENT: Address = address!("0x00000000000000000000000000000000000c0de0"); +/// Stops. +const CHILD: Address = address!("0x00000000000000000000000000000000000c0de1"); + +/// revm's frame, which the inspector is given only while it has not finished. +#[derive(Debug, Default)] +struct HiddenOnceFinished(EthFrame); + +impl FrameTr for HiddenOnceFinished { + type FrameInit = FrameInit; + type FrameResult = FrameResult; +} + +impl InspectorFrame for HiddenOnceFinished { + type IT = EthInterpreter; + + fn eth_frame(&mut self) -> Option<&mut EthFrame> { + if self.0.is_finished() { + None + } else { + Some(&mut self.0) + } + } +} + +/// The frames' starts and ends, one line per callback, by the account the frame runs as. +#[derive(Debug, Default)] +struct Recorder { + events: Vec<String>, +} + +const fn name(address: Address) -> &'static str { + match address { + PARENT => "PARENT", + CHILD => "CHILD", + _ => "other", + } +} + +impl Inspector<Ctx> for Recorder { + fn call(&mut self, _: &mut Ctx, inputs: &mut CallInputs) -> Option<CallOutcome> { + let account = name(inputs.target_address); + self.events.push(format!("call {account}")); + None + } + + fn call_end(&mut self, _: &mut Ctx, inputs: &CallInputs, outcome: &mut CallOutcome) { + let (account, result) = (name(inputs.target_address), outcome.result.result); + self.events.push(format!("call_end {account} {result:?}")); + } + + fn frame_end(&mut self, _: &mut Ctx, input: &FrameInput, result: &mut FrameResult) { + let account = match input { + FrameInput::Call(inputs) => name(inputs.target_address), + _ => "other", + }; + let result = result.instruction_result(); + self.events.push(format!("frame_end {account} {result:?}")); + } +} + +/// revm's EVM on [`HiddenOnceFinished`]: its frame start, run and return are revm's own, on the +/// [`EthFrame`] inside. +struct Consumer { + evm: Inner, +} + +impl EvmTr for Consumer { + type Context = Ctx; + type Instructions = Instructions; + type Precompiles = EthPrecompiles; + type Frame = HiddenOnceFinished; + + fn all( + &self, + ) -> ( + &Ctx, + &Instructions, + &EthPrecompiles, + &FrameStack<HiddenOnceFinished>, + ) { + let evm = &self.evm; + ( + &evm.ctx, + &evm.instruction, + &evm.precompiles, + &evm.frame_stack, + ) + } + + fn all_mut( + &mut self, + ) -> ( + &mut Ctx, + &mut Instructions, + &mut EthPrecompiles, + &mut FrameStack<HiddenOnceFinished>, + ) { + let evm = &mut self.evm; + ( + &mut evm.ctx, + &mut evm.instruction, + &mut evm.precompiles, + &mut evm.frame_stack, + ) + } + + fn frame_init( + &mut self, + frame_input: FrameInit, + ) -> Result<FrameInitResult<'_, HiddenOnceFinished>, ContextDbError<Ctx>> { + let Evm { + ctx, + precompiles, + frame_stack, + .. + } = &mut self.evm; + let is_first_init = frame_stack.index().is_none(); + let mut slot = if is_first_init { + frame_stack.start_init() + } else { + frame_stack.get_next() + }; + let frame = &mut slot.get(HiddenOnceFinished::default).0; + let out = OutFrame::new_init(frame); + if let ItemOrResult::Result(result) = + EthFrame::init_with_context(out, ctx, precompiles, frame_input)? + { + return Ok(ItemOrResult::Result(result)); + } + let token = slot.consume(); + // SAFETY: the token is the slot's this stack just gave, which `slot.get` initialized. + unsafe { + if is_first_init { + frame_stack.end_init(token); + } else { + frame_stack.push(token); + } + } + Ok(ItemOrResult::Item(frame_stack.get())) + } + + fn frame_run(&mut self) -> Result<FrameInitOrResult<HiddenOnceFinished>, ContextDbError<Ctx>> { + let Evm { + ctx, + instruction, + frame_stack, + .. + } = &mut self.evm; + let frame = &mut frame_stack.get().0; + let action = frame.interpreter.run_plain( + instruction.instruction_table(), + instruction.gas_table(), + ctx, + ); + let result = frame.process_next_action(ctx, action); + if let Ok(ItemOrResult::Result(_)) = &result { + frame.set_finished(true); + } + // An EVM that runs its frames itself opens the start of the child init it consumed. + if let Ok(ItemOrResult::Item(init)) = &result { + lifecycle::open_frame_start(self, init)?; + } + result + } + + fn frame_return_result( + &mut self, + result: FrameResult, + ) -> Result<Option<FrameResult>, ContextDbError<Ctx>> { + let Evm { + ctx, frame_stack, .. + } = &mut self.evm; + if frame_stack.get().0.is_finished() { + frame_stack.pop(); + } + if frame_stack.index().is_none() { + return Ok(Some(result)); + } + // An EVM that returns results itself settles the caller's open start after the return. + let caller = &mut frame_stack.get().0; + let returning = lifecycle::Returning::new(&result, caller); + caller.return_result::<_, ContextDbError<Ctx>>(ctx, result)?; + lifecycle::close_frame_start(ctx, frame_stack, returning, |frame| &mut frame.0)?; + Ok(None) + } +} + +impl InspectorEvmTr for Consumer { + type Inspector = Recorder; + + fn all_inspector( + &self, + ) -> ( + &Ctx, + &Instructions, + &EthPrecompiles, + &FrameStack<HiddenOnceFinished>, + &Recorder, + ) { + let evm = &self.evm; + ( + &evm.ctx, + &evm.instruction, + &evm.precompiles, + &evm.frame_stack, + &evm.inspector, + ) + } + + fn all_mut_inspector( + &mut self, + ) -> ( + &mut Ctx, + &mut Instructions, + &mut EthPrecompiles, + &mut FrameStack<HiddenOnceFinished>, + &mut Recorder, + ) { + let evm = &mut self.evm; + ( + &mut evm.ctx, + &mut evm.instruction, + &mut evm.precompiles, + &mut evm.frame_stack, + &mut evm.inspector, + ) + } +} + +/// The mainnet handler, on [`Consumer`]. +struct Mainnet; + +impl Handler for Mainnet { + type Evm = Consumer; + type Error = Error; + type HaltReason = HaltReason; +} + +impl InspectorHandler for Mainnet { + type IT = EthInterpreter; +} + +/// A [`Consumer`] holding [`PARENT`] and [`CHILD`], with a transaction to [`PARENT`]. +fn consumer() -> Consumer { + let mut db = Db::default(); + db.insert_account_info( + BENCH_CALLER, + AccountInfo::from_balance(U256::from(10u128.pow(21))), + ); + let mut parent = vec![PUSH0, PUSH0, PUSH0, PUSH0, PUSH0, PUSH20]; + parent.extend_from_slice(CHILD.as_slice()); + parent.extend_from_slice(&[GAS, CALL, STOP]); + let codes = [ + (PARENT, parent.into()), + (CHILD, Bytes::from_static(&[STOP])), + ]; + for (address, code) in codes { + let code = Bytecode::new_raw(code); + db.insert_account_info( + address, + AccountInfo::new(U256::ZERO, 1, code.hash_slow(), code), + ); + } + let mut ctx = Context::mainnet() + .with_db(db) + .modify_cfg_chained(|cfg| cfg.set_spec_and_mainnet_gas_params(SPEC)); + ctx.set_tx( + TxEnv::builder_for_bench() + .kind(TxKind::Call(PARENT)) + .gas_price(0) + .gas_limit(GAS_LIMIT) + .build_fill(), + ); + Consumer { + evm: Evm { + ctx, + inspector: Recorder::default(), + instruction: Instructions::new_mainnet_with_spec(SPEC), + precompiles: EthPrecompiles::new(SPEC), + frame_stack: FrameStack::new(), + }, + } +} + +/// The inspector sees each frame's end, though the frame's accessor gives it no finished frame, +/// and the transaction's result is the plain run's. +#[test] +fn test_a_frame_hidden_once_finished_gets_its_end_callbacks() { + let mut inspected = consumer(); + let result = Mainnet + .inspect_run(&mut inspected) + .expect("the transaction runs"); + + assert_eq!( + inspected.evm.inspector.events, + [ + "call PARENT", + "call CHILD", + "call_end CHILD Stop", + "frame_end CHILD Stop", + "call_end PARENT Stop", + "frame_end PARENT Stop", + ] + ); + assert!( + matches!(result, ExecutionResult::Success { .. }), + "{result:?}" + ); + let plain = Mainnet.run(&mut consumer()).expect("the transaction runs"); + assert_eq!(result, plain); +} diff --git a/crates/inspector/tests/default_hook_figures.rs b/crates/inspector/tests/default_hook_figures.rs new file mode 100644 index 0000000000..74b159526c --- /dev/null +++ b/crates/inspector/tests/default_hook_figures.rs @@ -0,0 +1,972 @@ +//! With the default hooks, the start lifecycle changes no figure revm's settlement computes. +//! +//! Each case answers or rewrites a start's result the way an inspector or a consumer's +//! `frame_init` can, on the transaction's frame or on a child, and the transaction's figures must +//! be the ones revm computed before the lifecycle existed. The expected figures were recorded on +//! that revision (`b370b538`), so a lifecycle helper that moves a figure fails here. +//! +//! The transaction runs on Amsterdam with every gas regular (the cap is lifted), so the +//! transaction's frame starts with no reservoir and every state charge spills into regular gas: +//! a result that hands a reservoir back then unwinds the spill into regular gas, and a halt keeps +//! that gas. [`EMPTY`] is an account with no code; a value transfer to it pays for its leaf, as +//! a creation pays for the account it creates. + +use context::{ + result::{EVMError, ExecutionResult}, + Context, ContextSetters, Evm, FrameStack, TxEnv, +}; +use database::{CacheDB, EmptyDB, BENCH_CALLER}; +use handler::{ + evm::{ContextDbError, FrameInitResult}, + instructions::EthInstructions, + EthFrame, EthPrecompiles, EvmTr, ExecuteEvm, FrameInitOrResult, FrameResult, Handler, + ItemOrResult, MainBuilder, MainContext, MainnetContext, MainnetHandler, +}; +use interpreter::{ + interpreter::EthInterpreter, interpreter_action::FrameInit, CallInputs, CallOutcome, + CreateInputs, CreateOutcome, FrameInput, Gas, InstructionResult, InterpreterResult, +}; +use primitives::{address, hardfork::SpecId, Address, Bytes, TxKind, U256}; +use revm_inspector::{InspectEvm, Inspector}; +use state::{ + bytecode::opcode::{CALL, CREATE, PUSH0, PUSH1, PUSH20, PUSH3, STOP}, + AccountInfo, Bytecode, +}; +use std::convert::Infallible; + +type Db = CacheDB<EmptyDB>; +type Ctx = MainnetContext<Db>; +type MainEvm<I> = Evm<Ctx, I, EthInstructions<EthInterpreter, Ctx>, EthPrecompiles, EthFrame>; +type Error = EVMError<Infallible>; + +/// Calls [`EMPTY`] with a value of 1 and stops. +const PARENT: Address = address!("0x00000000000000000000000000000000000c0de0"); +/// Creates an empty contract and stops. +const CREATOR: Address = address!("0x00000000000000000000000000000000000c0de2"); +/// No code, no balance, no nonce. +const EMPTY: Address = address!("0x00000000000000000000000000000000000000ab"); +const GAS_LIMIT: u64 = 1_000_000; + +/// The frame a case acts on. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Target { + /// The transaction's frame: a value transfer to [`EMPTY`]. + Root, + /// [`PARENT`]'s call to [`EMPTY`], at depth 1. + Child, + /// The transaction's frame: a creation with no init code. + RootCreation, + /// [`CREATOR`]'s creation, at depth 1. + ChildCreation, +} + +impl Target { + /// The caller of the target's start. + const fn caller(self) -> Address { + match self { + Self::Root | Self::RootCreation => BENCH_CALLER, + Self::Child => PARENT, + Self::ChildCreation => CREATOR, + } + } + + const fn is_creation(self) -> bool { + matches!(self, Self::RootCreation | Self::ChildCreation) + } +} + +/// How much of the start's gas limit an answer's tracker has left. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Left { + All, + Half, +} + +/// What is done to the start's result. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Shape { + /// The start is answered with a constructor-built outcome: `status`, a tracker with `left` of + /// the gas limit and a reservoir of the given amount. + Answer(InstructionResult, Left, u64), + /// The end callback puts a constructor-built tracker in the result, with `left` of the gas + /// limit and a reservoir of the given amount. + ReplaceGas(Left, u64), + /// The end callback builds a new outcome around the same result. + RebuildOutcome, + /// The end callback rewrites the status only. + RewriteStatus(InstructionResult), + /// The end callback rewrites the status and puts a constructor-built tracker with the whole + /// gas limit and a reservoir of the given amount in the result. + RewriteAndReplace(InstructionResult, u64), +} + +/// A tracker built as an answer builds one: `left` of `gas_limit` and `reservoir`. +fn built_gas(gas_limit: u64, left: Left, reservoir: u64) -> Gas { + let mut gas = Gas::new(gas_limit); + if left == Left::Half { + gas.tracker_mut().set_remaining(gas_limit / 2); + } + gas.tracker_mut().set_reservoir(reservoir); + gas +} + +/// Whether the start of `caller` is the target's. +fn targeted(target: Target, caller: Address, creation: bool) -> bool { + caller == target.caller() && creation == target.is_creation() +} + +/// `shape`'s end-callback edit of a result whose start had `gas_limit`. +fn edit(shape: Shape, gas_limit: u64, result: &mut InterpreterResult) { + match shape { + Shape::Answer(..) | Shape::RebuildOutcome => {} + Shape::ReplaceGas(left, reservoir) => result.gas = built_gas(gas_limit, left, reservoir), + Shape::RewriteStatus(status) => result.result = status, + Shape::RewriteAndReplace(status, reservoir) => { + result.result = status; + result.gas = built_gas(gas_limit, Left::All, reservoir); + } + } +} + +/// Acts on the target's start as an inspector. +struct Rewrites(Target, Shape); + +/// The answer `shape` makes to a start with `gas_limit`, if it answers. +fn answer(shape: Shape, gas_limit: u64) -> Option<InterpreterResult> { + let Shape::Answer(status, left, reservoir) = shape else { + return None; + }; + let gas = built_gas(gas_limit, left, reservoir); + Some(InterpreterResult::new(status, Bytes::new(), gas)) +} + +impl Inspector<Ctx> for Rewrites { + fn call(&mut self, _: &mut Ctx, inputs: &mut CallInputs) -> Option<CallOutcome> { + if !targeted(self.0, inputs.caller, false) { + return None; + } + let result = answer(self.1, inputs.gas_limit)?; + Some(CallOutcome::new( + result, + inputs.return_memory_offset.clone(), + )) + } + + fn call_end(&mut self, _: &mut Ctx, inputs: &CallInputs, outcome: &mut CallOutcome) { + if !targeted(self.0, inputs.caller, false) { + return; + } + if self.1 == Shape::RebuildOutcome { + *outcome = CallOutcome::new(outcome.result.clone(), outcome.memory_offset.clone()); + } + edit(self.1, inputs.gas_limit, &mut outcome.result); + } + + fn create(&mut self, _: &mut Ctx, inputs: &mut CreateInputs) -> Option<CreateOutcome> { + if !targeted(self.0, inputs.caller(), true) { + return None; + } + Some(CreateOutcome::new( + answer(self.1, inputs.gas_limit())?, + None, + )) + } + + fn create_end(&mut self, _: &mut Ctx, inputs: &CreateInputs, outcome: &mut CreateOutcome) { + if !targeted(self.0, inputs.caller(), true) { + return; + } + if self.1 == Shape::RebuildOutcome { + *outcome = CreateOutcome::new(outcome.result.clone(), outcome.address); + } + edit(self.1, inputs.gas_limit(), &mut outcome.result); + } +} + +/// revm's mainnet EVM whose `frame_init` answers the target's start, as a consumer's +/// `frame_init` answers a start it intercepts. +struct Answers { + evm: MainEvm<()>, + target: Target, + answer: (InstructionResult, Left, u64), +} + +impl EvmTr for Answers { + type Context = Ctx; + type Instructions = EthInstructions<EthInterpreter, Ctx>; + type Precompiles = EthPrecompiles; + type Frame = EthFrame; + + fn all( + &self, + ) -> ( + &Self::Context, + &Self::Instructions, + &Self::Precompiles, + &FrameStack<Self::Frame>, + ) { + self.evm.all() + } + + fn all_mut( + &mut self, + ) -> ( + &mut Self::Context, + &mut Self::Instructions, + &mut Self::Precompiles, + &mut FrameStack<Self::Frame>, + ) { + self.evm.all_mut() + } + + fn frame_init( + &mut self, + frame_init: FrameInit, + ) -> Result<FrameInitResult<'_, EthFrame>, ContextDbError<Ctx>> { + let (status, left, reservoir) = self.answer; + let shape = Shape::Answer(status, left, reservoir); + match &frame_init.frame_input { + FrameInput::Call(inputs) if targeted(self.target, inputs.caller, false) => { + let result = answer(shape, inputs.gas_limit).expect("an answer"); + let offset = inputs.return_memory_offset.clone(); + Ok(ItemOrResult::Result(FrameResult::Call(CallOutcome::new( + result, offset, + )))) + } + FrameInput::Create(inputs) if targeted(self.target, inputs.caller(), true) => { + let result = answer(shape, inputs.gas_limit()).expect("an answer"); + Ok(ItemOrResult::Result(FrameResult::Create( + CreateOutcome::new(result, None), + ))) + } + _ => self.evm.frame_init(frame_init), + } + } + + fn frame_run(&mut self) -> Result<FrameInitOrResult<EthFrame>, ContextDbError<Ctx>> { + self.evm.frame_run() + } + + fn frame_return_result( + &mut self, + result: FrameResult, + ) -> Result<Option<FrameResult>, ContextDbError<Ctx>> { + self.evm.frame_return_result(result) + } +} + +fn account(code: Vec<u8>, balance: u64) -> AccountInfo { + let code = Bytecode::new_raw(code.into()); + AccountInfo::new(U256::from(balance), 1, code.hash_slow(), code) +} + +fn context() -> Ctx { + let mut db = Db::default(); + db.insert_account_info( + BENCH_CALLER, + AccountInfo::from_balance(U256::from(10u128.pow(21))), + ); + // PUSH0 PUSH0 PUSH0 PUSH0 (no data in or out), PUSH1 1 (the value), PUSH20 EMPTY, + // PUSH3 0x010000 (the gas), CALL, STOP. + let mut parent = vec![PUSH0, PUSH0, PUSH0, PUSH0, PUSH1, 1, PUSH20]; + parent.extend_from_slice(EMPTY.as_slice()); + parent.extend_from_slice(&[PUSH3, 0x01, 0x00, 0x00, CALL, STOP]); + db.insert_account_info(PARENT, account(parent, 1)); + db.insert_account_info(CREATOR, account(vec![PUSH0, PUSH0, PUSH0, CREATE, STOP], 0)); + Context::mainnet().with_db(db).modify_cfg_chained(|cfg| { + cfg.set_spec_and_mainnet_gas_params(SpecId::AMSTERDAM); + cfg.tx_gas_limit_cap = Some(u64::MAX); + }) +} + +fn tx(target: Target) -> TxEnv { + let (kind, value) = match target { + Target::Root => (TxKind::Call(EMPTY), 1), + Target::Child => (TxKind::Call(PARENT), 0), + Target::RootCreation => (TxKind::Create, 0), + Target::ChildCreation => (TxKind::Call(CREATOR), 0), + }; + TxEnv::builder_for_bench() + .kind(kind) + .value(U256::from(value)) + .gas_price(0) + .gas_limit(GAS_LIMIT) + .build_fill() +} + +/// The figures a transaction's result carries: its kind, its gas and its output. +fn figures(result: &ExecutionResult) -> String { + let kind = match result { + ExecutionResult::Success { reason, .. } => format!("Success({reason:?})"), + ExecutionResult::Revert { .. } => "Revert".to_string(), + ExecutionResult::Halt { reason, .. } => format!("Halt({reason:?})"), + }; + let gas = result.gas(); + format!( + "{kind} spent {} state {} refunded {} floor {} output {}", + gas.total_gas_spent(), + gas.state_gas_spent_final(), + gas.inner_refunded(), + gas.floor_gas(), + result.output().cloned().unwrap_or_default(), + ) +} + +/// The transaction of `target`, run plain. +fn plain(target: Target) -> String { + let result = context() + .build_mainnet() + .transact(tx(target)) + .expect("runs"); + figures(&result.result) +} + +/// The transaction of `target`, inspected under `shape`. +fn inspected(target: Target, shape: Shape) -> String { + let mut evm = context().build_mainnet_with_inspector(Rewrites(target, shape)); + let result = evm.inspect_tx(tx(target)).expect("runs"); + figures(&result.result) +} + +/// The transaction of `target`, its start answered by the consumer's `frame_init`. +fn answered(target: Target, answer: (InstructionResult, Left, u64)) -> String { + let mut evm = Answers { + evm: context().build_mainnet(), + target, + answer, + }; + evm.evm.ctx.set_tx(tx(target)); + let result = MainnetHandler::<_, Error, EthFrame>::default() + .run(&mut evm) + .expect("runs"); + figures(&result) +} + +/// Every case, named. +fn cases() -> Vec<(String, String)> { + use InstructionResult::{OutOfGas, Revert, Stop}; + let mut shapes = Vec::new(); + for status in [Stop, Revert, OutOfGas] { + for left in [Left::All, Left::Half] { + for reservoir in [0, 1] { + shapes.push(Shape::Answer(status, left, reservoir)); + } + } + } + for left in [Left::All, Left::Half] { + for reservoir in [0, 1] { + shapes.push(Shape::ReplaceGas(left, reservoir)); + } + } + shapes.push(Shape::RebuildOutcome); + shapes.push(Shape::RewriteStatus(Revert)); + shapes.push(Shape::RewriteStatus(OutOfGas)); + shapes.push(Shape::RewriteAndReplace(OutOfGas, 1)); + shapes.push(Shape::RewriteAndReplace(Revert, 1)); + + let mut cases = Vec::new(); + for target in [ + Target::Root, + Target::Child, + Target::RootCreation, + Target::ChildCreation, + ] { + cases.push((format!("{target:?} plain"), plain(target))); + for shape in &shapes { + cases.push(( + format!("{target:?} inspected {shape:?}"), + inspected(target, *shape), + )); + if let Shape::Answer(status, left, reservoir) = *shape { + cases.push(( + format!("{target:?} frame_init {shape:?}"), + answered(target, (status, left, reservoir)), + )); + } + } + } + cases +} + +/// The figures revm computed for each case before the lifecycle existed (`b370b538`). +const EXPECTED: &[(&str, &str)] = &[ + ( + "Root plain", + "Success(Stop) spent 204600 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected Answer(Stop, All, 0)", + "Success(Stop) spent 204600 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root frame_init Answer(Stop, All, 0)", + "Success(Stop) spent 204600 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected Answer(Stop, All, 1)", + "Success(Stop) spent 204599 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root frame_init Answer(Stop, All, 1)", + "Success(Stop) spent 204599 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected Answer(Stop, Half, 0)", + "Success(Stop) spent 602300 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root frame_init Answer(Stop, Half, 0)", + "Success(Stop) spent 602300 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected Answer(Stop, Half, 1)", + "Success(Stop) spent 602299 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root frame_init Answer(Stop, Half, 1)", + "Success(Stop) spent 602299 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected Answer(Revert, All, 0)", + "Revert spent 204600 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root frame_init Answer(Revert, All, 0)", + "Revert spent 204600 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected Answer(Revert, All, 1)", + "Revert spent 204599 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root frame_init Answer(Revert, All, 1)", + "Revert spent 204599 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected Answer(Revert, Half, 0)", + "Revert spent 602300 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root frame_init Answer(Revert, Half, 0)", + "Revert spent 602300 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected Answer(Revert, Half, 1)", + "Revert spent 602299 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root frame_init Answer(Revert, Half, 1)", + "Revert spent 602299 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected Answer(OutOfGas, All, 0)", + "Halt(OutOfGas(Basic)) spent 1000000 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root frame_init Answer(OutOfGas, All, 0)", + "Halt(OutOfGas(Basic)) spent 1000000 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected Answer(OutOfGas, All, 1)", + "Halt(OutOfGas(Basic)) spent 999999 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root frame_init Answer(OutOfGas, All, 1)", + "Halt(OutOfGas(Basic)) spent 999999 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected Answer(OutOfGas, Half, 0)", + "Halt(OutOfGas(Basic)) spent 1000000 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root frame_init Answer(OutOfGas, Half, 0)", + "Halt(OutOfGas(Basic)) spent 1000000 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected Answer(OutOfGas, Half, 1)", + "Halt(OutOfGas(Basic)) spent 999999 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root frame_init Answer(OutOfGas, Half, 1)", + "Halt(OutOfGas(Basic)) spent 999999 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected ReplaceGas(All, 0)", + "Success(Stop) spent 204600 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected ReplaceGas(All, 1)", + "Success(Stop) spent 204599 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected ReplaceGas(Half, 0)", + "Success(Stop) spent 602300 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected ReplaceGas(Half, 1)", + "Success(Stop) spent 602299 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected RebuildOutcome", + "Success(Stop) spent 204600 state 183600 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected RewriteStatus(Revert)", + "Revert spent 21000 state 0 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected RewriteStatus(OutOfGas)", + "Halt(OutOfGas(Basic)) spent 1000000 state 0 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected RewriteAndReplace(OutOfGas, 1)", + "Halt(OutOfGas(Basic)) spent 999999 state 0 refunded 0 floor 21000 output 0x", + ), + ( + "Root inspected RewriteAndReplace(Revert, 1)", + "Revert spent 20999 state 0 refunded 0 floor 21000 output 0x", + ), + ( + "Child plain", + "Success(Stop) spent 210617 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected Answer(Stop, All, 0)", + "Success(Stop) spent 210617 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child frame_init Answer(Stop, All, 0)", + "Success(Stop) spent 210617 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected Answer(Stop, All, 1)", + "Success(Stop) spent 210616 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child frame_init Answer(Stop, All, 1)", + "Success(Stop) spent 210616 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected Answer(Stop, Half, 0)", + "Success(Stop) spent 244535 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child frame_init Answer(Stop, Half, 0)", + "Success(Stop) spent 244535 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected Answer(Stop, Half, 1)", + "Success(Stop) spent 244534 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child frame_init Answer(Stop, Half, 1)", + "Success(Stop) spent 244534 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected Answer(Revert, All, 0)", + "Success(Stop) spent 210617 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child frame_init Answer(Revert, All, 0)", + "Success(Stop) spent 210617 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected Answer(Revert, All, 1)", + "Success(Stop) spent 210616 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child frame_init Answer(Revert, All, 1)", + "Success(Stop) spent 210616 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected Answer(Revert, Half, 0)", + "Success(Stop) spent 244535 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child frame_init Answer(Revert, Half, 0)", + "Success(Stop) spent 244535 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected Answer(Revert, Half, 1)", + "Success(Stop) spent 244534 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child frame_init Answer(Revert, Half, 1)", + "Success(Stop) spent 244534 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected Answer(OutOfGas, All, 0)", + "Success(Stop) spent 278453 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child frame_init Answer(OutOfGas, All, 0)", + "Success(Stop) spent 278453 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected Answer(OutOfGas, All, 1)", + "Success(Stop) spent 278452 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child frame_init Answer(OutOfGas, All, 1)", + "Success(Stop) spent 278452 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected Answer(OutOfGas, Half, 0)", + "Success(Stop) spent 278453 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child frame_init Answer(OutOfGas, Half, 0)", + "Success(Stop) spent 278453 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected Answer(OutOfGas, Half, 1)", + "Success(Stop) spent 278452 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child frame_init Answer(OutOfGas, Half, 1)", + "Success(Stop) spent 278452 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected ReplaceGas(All, 0)", + "Success(Stop) spent 210617 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected ReplaceGas(All, 1)", + "Success(Stop) spent 210616 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected ReplaceGas(Half, 0)", + "Success(Stop) spent 244535 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected ReplaceGas(Half, 1)", + "Success(Stop) spent 244534 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected RebuildOutcome", + "Success(Stop) spent 210617 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected RewriteStatus(Revert)", + "Success(Stop) spent 27017 state 0 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected RewriteStatus(OutOfGas)", + "Success(Stop) spent 94853 state 0 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected RewriteAndReplace(OutOfGas, 1)", + "Success(Stop) spent 94852 state 0 refunded 0 floor 15000 output 0x", + ), + ( + "Child inspected RewriteAndReplace(Revert, 1)", + "Success(Stop) spent 27016 state 0 refunded 0 floor 15000 output 0x", + ), + ( + "RootCreation plain", + "Success(Return) spent 207600 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected Answer(Stop, All, 0)", + "Success(Stop) spent 207600 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation frame_init Answer(Stop, All, 0)", + "Success(Stop) spent 207600 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected Answer(Stop, All, 1)", + "Success(Stop) spent 207599 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation frame_init Answer(Stop, All, 1)", + "Success(Stop) spent 207599 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected Answer(Stop, Half, 0)", + "Success(Stop) spent 603800 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation frame_init Answer(Stop, Half, 0)", + "Success(Stop) spent 603800 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected Answer(Stop, Half, 1)", + "Success(Stop) spent 603799 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation frame_init Answer(Stop, Half, 1)", + "Success(Stop) spent 603799 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected Answer(Revert, All, 0)", + "Revert spent 207600 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation frame_init Answer(Revert, All, 0)", + "Revert spent 207600 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected Answer(Revert, All, 1)", + "Revert spent 207599 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation frame_init Answer(Revert, All, 1)", + "Revert spent 207599 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected Answer(Revert, Half, 0)", + "Revert spent 603800 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation frame_init Answer(Revert, Half, 0)", + "Revert spent 603800 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected Answer(Revert, Half, 1)", + "Revert spent 603799 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation frame_init Answer(Revert, Half, 1)", + "Revert spent 603799 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected Answer(OutOfGas, All, 0)", + "Halt(OutOfGas(Basic)) spent 1000000 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation frame_init Answer(OutOfGas, All, 0)", + "Halt(OutOfGas(Basic)) spent 1000000 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected Answer(OutOfGas, All, 1)", + "Halt(OutOfGas(Basic)) spent 999999 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation frame_init Answer(OutOfGas, All, 1)", + "Halt(OutOfGas(Basic)) spent 999999 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected Answer(OutOfGas, Half, 0)", + "Halt(OutOfGas(Basic)) spent 1000000 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation frame_init Answer(OutOfGas, Half, 0)", + "Halt(OutOfGas(Basic)) spent 1000000 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected Answer(OutOfGas, Half, 1)", + "Halt(OutOfGas(Basic)) spent 999999 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation frame_init Answer(OutOfGas, Half, 1)", + "Halt(OutOfGas(Basic)) spent 999999 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected ReplaceGas(All, 0)", + "Success(Return) spent 207600 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected ReplaceGas(All, 1)", + "Success(Return) spent 207599 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected ReplaceGas(Half, 0)", + "Success(Return) spent 603800 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected ReplaceGas(Half, 1)", + "Success(Return) spent 603799 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected RebuildOutcome", + "Success(Return) spent 207600 state 183600 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected RewriteStatus(Revert)", + "Revert spent 24000 state 0 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected RewriteStatus(OutOfGas)", + "Halt(OutOfGas(Basic)) spent 1000000 state 0 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected RewriteAndReplace(OutOfGas, 1)", + "Halt(OutOfGas(Basic)) spent 999999 state 0 refunded 0 floor 24000 output 0x", + ), + ( + "RootCreation inspected RewriteAndReplace(Revert, 1)", + "Revert spent 23999 state 0 refunded 0 floor 24000 output 0x", + ), + ( + "ChildCreation plain", + "Success(Stop) spent 210606 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected Answer(Stop, All, 0)", + "Success(Stop) spent 210606 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation frame_init Answer(Stop, All, 0)", + "Success(Stop) spent 210606 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected Answer(Stop, All, 1)", + "Success(Stop) spent 210605 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation frame_init Answer(Stop, All, 1)", + "Success(Stop) spent 210605 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected Answer(Stop, Half, 0)", + "Success(Stop) spent 599136 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation frame_init Answer(Stop, Half, 0)", + "Success(Stop) spent 599136 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected Answer(Stop, Half, 1)", + "Success(Stop) spent 599135 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation frame_init Answer(Stop, Half, 1)", + "Success(Stop) spent 599135 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected Answer(Revert, All, 0)", + "Success(Stop) spent 210606 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation frame_init Answer(Revert, All, 0)", + "Success(Stop) spent 210606 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected Answer(Revert, All, 1)", + "Success(Stop) spent 210605 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation frame_init Answer(Revert, All, 1)", + "Success(Stop) spent 210605 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected Answer(Revert, Half, 0)", + "Success(Stop) spent 599136 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation frame_init Answer(Revert, Half, 0)", + "Success(Stop) spent 599136 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected Answer(Revert, Half, 1)", + "Success(Stop) spent 599135 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation frame_init Answer(Revert, Half, 1)", + "Success(Stop) spent 599135 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected Answer(OutOfGas, All, 0)", + "Success(Stop) spent 987666 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation frame_init Answer(OutOfGas, All, 0)", + "Success(Stop) spent 987666 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected Answer(OutOfGas, All, 1)", + "Success(Stop) spent 987665 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation frame_init Answer(OutOfGas, All, 1)", + "Success(Stop) spent 987665 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected Answer(OutOfGas, Half, 0)", + "Success(Stop) spent 987666 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation frame_init Answer(OutOfGas, Half, 0)", + "Success(Stop) spent 987666 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected Answer(OutOfGas, Half, 1)", + "Success(Stop) spent 987665 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation frame_init Answer(OutOfGas, Half, 1)", + "Success(Stop) spent 987665 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected ReplaceGas(All, 0)", + "Success(Stop) spent 210606 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected ReplaceGas(All, 1)", + "Success(Stop) spent 210605 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected ReplaceGas(Half, 0)", + "Success(Stop) spent 599136 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected ReplaceGas(Half, 1)", + "Success(Stop) spent 599135 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected RebuildOutcome", + "Success(Stop) spent 210606 state 183600 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected RewriteStatus(Revert)", + "Success(Stop) spent 27006 state 0 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected RewriteStatus(OutOfGas)", + "Success(Stop) spent 804066 state 0 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected RewriteAndReplace(OutOfGas, 1)", + "Success(Stop) spent 804065 state 0 refunded 0 floor 15000 output 0x", + ), + ( + "ChildCreation inspected RewriteAndReplace(Revert, 1)", + "Success(Stop) spent 27005 state 0 refunded 0 floor 15000 output 0x", + ), +]; + +#[test] +fn test_default_hooks_change_no_figure_the_settlement_computes() { + let actual = cases(); + let table: String = actual + .iter() + .map(|(name, figures)| format!(" ({name:?}, {figures:?}),\n")) + .collect(); + let expected: Vec<(String, String)> = EXPECTED + .iter() + .map(|(name, figures)| (name.to_string(), figures.to_string())) + .collect(); + assert!( + actual == expected, + "the figures moved; this revision's table:\n{table}" + ); +} + +/// The transaction's frame answered with an out-of-gas outcome whose tracker hands back a +/// reservoir of 1, which unwinds 1 of the transaction's spill into regular gas. The halt keeps that +/// gas, as revm's settlement left it, whether an inspector or the consumer's `frame_init` answers: +/// 999,999 of the 1,000,000 gas limit is spent. +#[test] +fn test_a_halted_answer_to_the_transactions_frame_keeps_the_gas_its_settlement_returned() { + let answer = (InstructionResult::OutOfGas, Left::All, 1); + for figures in [ + inspected(Target::Root, Shape::Answer(answer.0, answer.1, answer.2)), + answered(Target::Root, answer), + ] { + assert!( + figures.starts_with("Halt(OutOfGas(Basic)) spent 999999 "), + "{figures}" + ); + } +} diff --git a/crates/inspector/tests/instruction_hooks.rs b/crates/inspector/tests/instruction_hooks.rs new file mode 100644 index 0000000000..588daeb6dd --- /dev/null +++ b/crates/inspector/tests/instruction_hooks.rs @@ -0,0 +1,1568 @@ +//! The instruction hooks on the plain and the inspected path. +//! +//! `transact` runs a frame's instructions in the interpreter's loop and `inspect_tx` in the +//! inspector's; both run the same instructions, which call [`Host::write_completed`] and +//! [`Host::frame_starting`]. Each test runs a transaction both ways on [`HookContext`], which +//! delegates everything to the mainnet [`Context`] but the two hooks, and checks that the hooks are +//! reached at the same points with the same gas and that their answers end the transaction the same +//! way. + +use context::{ + context_interface::{ + cfg::{GasId, GasParams, StateGasSite}, + host::{CompletedWrite, FrameStart, FrameStartKind, LoadError, WriteVerdict}, + journaled_state::AccountInfoLoad, + result::{ExecutionResult, HaltReason, OutOfGasError, ResultAndState, ResultGas}, + }, + BlockEnv, CfgEnv, Context, ContextError, ContextSetters, ContextTr, Evm, Host, Journal, + LocalContext, TxEnv, +}; +use database::{CacheDB, EmptyDB, BENCH_CALLER}; +use handler::{ + instructions::EthInstructions, EthFrame, EthPrecompiles, ExecuteEvm, MainBuilder, MainContext, + MainnetContext, +}; +use interpreter::{ + interpreter::EthInterpreter, CallInputs, CallOutcome, CreateInputs, CreateOutcome, GasTracker, + SStoreResult, SelfDestructResult, StateLoad, +}; +use primitives::{ + address, hardfork::SpecId, Address, Bytes, Log, StorageKey, StorageValue, TxKind, B256, + KECCAK_EMPTY, U256, +}; +use revm_inspector::{InspectEvm, Inspector, NoOpInspector}; +use state::{ + bytecode::opcode::{ + ADDRESS, CALL, CALLCODE, CALLVALUE, CREATE, CREATE2, DELEGATECALL, DUP6, JUMPDEST, JUMPI, + LOG0, LOG1, MSTORE, POP, PUSH0, PUSH1, PUSH32, PUSH4, RETURN, SELFDESTRUCT, SSTORE, + STATICCALL, STOP, + }, + AccountInfo, Bytecode, +}; + +type Db = CacheDB<EmptyDB>; +type DbError = <Db as context::Database>::Error; + +/// The account the transaction calls. +const PARENT: Address = address!("0x00000000000000000000000000000000000c0de0"); +/// The account [`PARENT`] starts frames on. +const CHILD: Address = address!("0x00000000000000000000000000000000000c41d0"); +/// An account that does not exist, which `SELFDESTRUCT` pays. +const BENEFICIARY: Address = address!("0x00000000000000000000000000000000000be4e0"); +/// An account that does not exist, which a call sends value to. +const EMPTY: Address = address!("0x00000000000000000000000000000000000e3970"); +/// The identity precompile, a start the handler answers without a frame. +const IDENTITY: Address = address!("0x0000000000000000000000000000000000000004"); +/// The transaction's gas limit. +const GAS_LIMIT: u64 = 5_000_000; +/// What a reverting hook returns. +const STOP_OUTPUT: &[u8] = b"stop"; + +/// A write the hook saw, owned. +#[derive(Clone, Debug, PartialEq, Eq)] +enum Write { + Sstore(Address, StorageKey, SStoreResult), + Log(Address, u8, u64), + SelfDestruct(Address, Address, U256, SelfDestructResult), +} + +impl Write { + fn of(write: CompletedWrite<'_>) -> Self { + match write { + CompletedWrite::Sstore { + address, + key, + result, + } => Self::Sstore(address, key, result.clone()), + CompletedWrite::Log { + address, + topics, + data_len, + } => Self::Log(address, topics, data_len), + CompletedWrite::SelfDestruct { + address, + target, + balance, + result, + } => Self::SelfDestruct(address, target, balance, result.clone()), + } + } + + const fn address(&self) -> Address { + match self { + Self::Sstore(address, ..) + | Self::Log(address, ..) + | Self::SelfDestruct(address, ..) => *address, + } + } +} + +/// What the hooks answer, and what they saw. +#[derive(Clone, Debug, PartialEq, Eq)] +struct Hooks { + verdict: WriteVerdict, + admit: bool, + /// History gas the first write hook charges on the gas it is handed. + first_write_charge: u64, + /// History gas the first start hook charges on the gas it is handed. + first_start_charge: u64, + /// Every write, with the gas as the hook found it. + writes: Vec<(Write, GasTracker)>, + /// Every start, with the gas as the hook found it. + starts: Vec<(FrameStart, GasTracker)>, + /// Every start's target as the journal held it when the hook saw the start. + targets: Vec<View>, + /// Every destruction's account and beneficiary as the journal held them before the write. + destructions_before: Vec<[View; 2]>, + /// Every destruction's account and beneficiary as the journal held them at the hook. + destructions_at_hook: Vec<[View; 2]>, +} + +/// An account as the journal holds it: its info and the info the transaction loaded it with, or +/// `None` for an account the transaction has not loaded. +type View = Option<(AccountInfo, AccountInfo)>; + +/// Whether the transaction has changed the account `view` shows: its nonce, balance or code differs +/// from what the transaction loaded. An account it has not loaded is unchanged. +fn changed(view: &View) -> bool { + view.as_ref().is_some_and(|(info, original)| { + info.nonce != original.nonce + || info.balance != original.balance + || info.code_hash != original.code_hash + }) +} + +impl Hooks { + const fn observing() -> Self { + Self { + verdict: WriteVerdict::Continue, + admit: true, + first_write_charge: 0, + first_start_charge: 0, + writes: Vec::new(), + starts: Vec::new(), + targets: Vec::new(), + destructions_before: Vec::new(), + destructions_at_hook: Vec::new(), + } + } +} + +/// The mainnet [`Context`] with [`Hooks`]. +struct HookContext { + inner: MainnetContext<Db>, + hooks: Hooks, +} + +impl HookContext { + /// The account at `address` as the journal holds it. + fn view(&self, address: Address) -> View { + self.inner + .journal_ref() + .state + .get(&address) + .map(|account| (account.info.clone(), account.original_info())) + } +} + +impl ContextTr for HookContext { + type Block = BlockEnv; + type Tx = TxEnv; + type Cfg = CfgEnv; + type Db = Db; + type Journal = Journal<Db>; + type Chain = (); + type Local = LocalContext; + + fn all( + &self, + ) -> ( + &Self::Block, + &Self::Tx, + &Self::Cfg, + &Self::Db, + &Self::Journal, + &Self::Chain, + &Self::Local, + ) { + self.inner.all() + } + + fn all_mut( + &mut self, + ) -> ( + &Self::Block, + &Self::Tx, + &Self::Cfg, + &mut Self::Journal, + &mut Self::Chain, + &mut Self::Local, + ) { + self.inner.all_mut() + } + + fn error(&mut self) -> &mut Result<(), ContextError<DbError>> { + self.inner.error() + } +} + +impl ContextSetters for HookContext { + fn set_tx(&mut self, tx: Self::Tx) { + self.inner.set_tx(tx); + } + + fn set_block(&mut self, block: Self::Block) { + self.inner.set_block(block); + } +} + +impl Host for HookContext { + fn write_completed(&mut self, write: CompletedWrite<'_>, gas: &mut GasTracker) -> WriteVerdict { + self.hooks.writes.push((Write::of(write), *gas)); + if let CompletedWrite::SelfDestruct { + address, target, .. + } = write + { + let accounts = [self.view(address), self.view(target)]; + self.hooks.destructions_at_hook.push(accounts); + } + if self.hooks.writes.len() == 1 && self.hooks.first_write_charge > 0 { + assert!(gas.record_history_cost(self.hooks.first_write_charge)); + } + self.hooks.verdict.clone() + } + + fn frame_starting(&mut self, start: &mut FrameStart, gas: &mut GasTracker) -> bool { + self.hooks.starts.push((*start, *gas)); + let target = start.target.and_then(|target| self.view(target)); + self.hooks.targets.push(target); + if self.hooks.starts.len() == 1 && self.hooks.first_start_charge > 0 { + assert!(gas.record_history_cost(self.hooks.first_start_charge)); + } + self.hooks.admit + } + + fn state_gas_price(&mut self, id: GasId, site: StateGasSite) -> Option<u64> { + self.inner.state_gas_price(id, site) + } + + fn basefee(&self) -> U256 { + self.inner.basefee() + } + + fn blob_gasprice(&self) -> U256 { + self.inner.blob_gasprice() + } + + fn gas_limit(&self) -> U256 { + self.inner.gas_limit() + } + + fn difficulty(&self) -> U256 { + self.inner.difficulty() + } + + fn prevrandao(&self) -> Option<U256> { + self.inner.prevrandao() + } + + fn block_number(&self) -> U256 { + self.inner.block_number() + } + + fn timestamp(&self) -> U256 { + self.inner.timestamp() + } + + fn beneficiary(&self) -> Address { + self.inner.beneficiary() + } + + fn slot_num(&self) -> U256 { + self.inner.slot_num() + } + + fn chain_id(&self) -> U256 { + self.inner.chain_id() + } + + fn effective_gas_price(&self) -> U256 { + self.inner.effective_gas_price() + } + + fn caller(&self) -> Address { + self.inner.caller() + } + + fn blob_hash(&self, number: usize) -> Option<U256> { + self.inner.blob_hash(number) + } + + fn max_initcode_size(&self) -> usize { + self.inner.max_initcode_size() + } + + fn gas_params(&self) -> &GasParams { + self.inner.gas_params() + } + + fn is_amsterdam_eip8037_enabled(&self) -> bool { + self.inner.is_amsterdam_eip8037_enabled() + } + + fn block_hash(&mut self, number: u64) -> Option<B256> { + self.inner.block_hash(number) + } + + fn selfdestruct( + &mut self, + address: Address, + target: Address, + skip_cold_load: bool, + ) -> Result<StateLoad<SelfDestructResult>, LoadError> { + let before = [self.view(address), self.view(target)]; + let result = self.inner.selfdestruct(address, target, skip_cold_load); + if result.is_ok() { + self.hooks.destructions_before.push(before); + } + result + } + + fn log(&mut self, log: Log) { + self.inner.log(log) + } + + fn sstore_skip_cold_load( + &mut self, + address: Address, + key: StorageKey, + value: StorageValue, + skip_cold_load: bool, + ) -> Result<StateLoad<SStoreResult>, LoadError> { + self.inner + .sstore_skip_cold_load(address, key, value, skip_cold_load) + } + + fn sload_skip_cold_load( + &mut self, + address: Address, + key: StorageKey, + skip_cold_load: bool, + ) -> Result<StateLoad<StorageValue>, LoadError> { + self.inner + .sload_skip_cold_load(address, key, skip_cold_load) + } + + fn tstore(&mut self, address: Address, key: StorageKey, value: StorageValue) { + self.inner.tstore(address, key, value) + } + + fn tload(&mut self, address: Address, key: StorageKey) -> StorageValue { + self.inner.tload(address, key) + } + + fn load_account_info_skip_cold_load( + &mut self, + address: Address, + load_code: bool, + skip_cold_load: bool, + ) -> Result<AccountInfoLoad<'_>, LoadError> { + self.inner + .load_account_info_skip_cold_load(address, load_code, skip_cold_load) + } +} + +/// What the inspector saw of the frames that started. +#[derive(Default)] +struct Frames { + /// The gas limit and reservoir of every frame, the transaction's first. + gas: Vec<(u64, u64)>, + /// The address each creation's frame took, in the order the creations started. + created: Vec<Option<Address>>, + /// The place in `created` of each creation that has not returned yet. + open: Vec<usize>, +} + +impl Inspector<HookContext, EthInterpreter> for Frames { + fn call(&mut self, _context: &mut HookContext, inputs: &mut CallInputs) -> Option<CallOutcome> { + self.gas.push((inputs.gas_limit, inputs.reservoir)); + None + } + + fn create( + &mut self, + _context: &mut HookContext, + inputs: &mut CreateInputs, + ) -> Option<CreateOutcome> { + self.gas.push((inputs.gas_limit(), inputs.reservoir())); + self.open.push(self.created.len()); + self.created.push(None); + None + } + + fn create_end( + &mut self, + _context: &mut HookContext, + _inputs: &CreateInputs, + outcome: &mut CreateOutcome, + ) { + let started = self.open.pop().expect("a creation returns once it started"); + self.created[started] = outcome.address; + } +} + +type HookEvm = Evm< + HookContext, + Frames, + EthInstructions<EthInterpreter, HookContext>, + EthPrecompiles, + EthFrame<EthInterpreter>, +>; + +/// A transaction to [`PARENT`] and the accounts it runs on. +struct Run { + spec: SpecId, + /// The transaction's reservoir: its cap is set this far below [`GAS_LIMIT`] on Amsterdam. + reservoir: u64, + /// `(address, code, balance)`. + accounts: Vec<(Address, Vec<u8>, u64)>, + hooks: Hooks, +} + +impl Run { + fn new(spec: SpecId, parent: Vec<u8>) -> Self { + Self { + spec, + reservoir: 0, + accounts: vec![(PARENT, parent, 10)], + hooks: Hooks::observing(), + } + } + + fn with(mut self, address: Address, code: Vec<u8>, balance: u64) -> Self { + self.accounts.push((address, code, balance)); + self + } + + const fn reservoir(mut self, reservoir: u64) -> Self { + self.reservoir = reservoir; + self + } + + fn hooks(mut self, hooks: Hooks) -> Self { + self.hooks = hooks; + self + } + + fn context(&self) -> MainnetContext<Db> { + let mut db = Db::default(); + db.insert_account_info( + BENCH_CALLER, + AccountInfo::from_balance(U256::from(10u128.pow(21))), + ); + for (address, code, balance) in &self.accounts { + let info = AccountInfo::from_balance(U256::from(*balance)) + .with_nonce(1) + .with_code(Bytecode::new_raw(Bytes::copy_from_slice(code))); + db.insert_account_info(*address, info); + } + let (spec, reservoir) = (self.spec, self.reservoir); + Context::mainnet().with_db(db).modify_cfg_chained(|cfg| { + cfg.set_spec_and_mainnet_gas_params(spec); + if spec.is_enabled_in(SpecId::AMSTERDAM) { + cfg.tx_gas_limit_cap = Some(GAS_LIMIT - reservoir); + } + }) + } + + fn evm(&self) -> HookEvm { + let ctx = HookContext { + inner: self.context(), + hooks: self.hooks.clone(), + }; + Evm::new_with_inspector( + ctx, + Frames::default(), + EthInstructions::new_mainnet_with_spec(self.spec), + EthPrecompiles::new(self.spec), + ) + } + + fn tx() -> TxEnv { + TxEnv::builder() + .caller(BENCH_CALLER) + .kind(TxKind::Call(PARENT)) + .gas_price(0) + .gas_limit(GAS_LIMIT) + .build() + .unwrap() + } + + /// The transaction on the mainnet context, with the default hooks, with `transact` and with + /// `inspect_tx`, which must end the same way. + fn on_defaults(&self) -> ResultAndState { + let transacted = self + .context() + .build_mainnet() + .transact(Self::tx()) + .expect("the transaction runs"); + let inspected = self + .context() + .build_mainnet_with_inspector(NoOpInspector) + .inspect_tx(Self::tx()) + .expect("the transaction runs"); + assert_eq!(inspected, transacted, "both paths end the same way"); + transacted + } + + /// The transaction with `transact` and with `inspect_tx`, which must end the same way and + /// reach the hooks at the same points with the same gas. Returns the outcome, what the hooks + /// saw, and the gas of the frames the inspector saw start. + fn on_both_paths(&self) -> (ResultAndState, Hooks, Vec<(u64, u64)>) { + let (outcome, hooks, frames) = self.on_both_paths_with_frames(); + (outcome, hooks, frames.gas) + } + + /// [`on_both_paths`](Self::on_both_paths), with all the inspector saw of the frames. + fn on_both_paths_with_frames(&self) -> (ResultAndState, Hooks, Frames) { + let mut plain = self.evm(); + let transacted = plain.transact(Self::tx()).expect("the transaction runs"); + let mut inspected = self.evm(); + let inspected_outcome = inspected + .inspect_tx(Self::tx()) + .expect("the transaction runs"); + + assert_eq!(inspected_outcome, transacted, "both paths end the same way"); + assert_eq!( + inspected.ctx.hooks, plain.ctx.hooks, + "both paths reach the hooks at the same points with the same gas" + ); + (transacted, plain.ctx.hooks, inspected.inspector) + } +} + +/// `PUSHn` of `bytes`. +fn push(bytes: &[u8]) -> Vec<u8> { + let mut code = vec![PUSH0 + bytes.len() as u8]; + code.extend_from_slice(bytes); + code +} + +/// The shortest push of `address`. +fn push_address(address: Address) -> Vec<u8> { + let bytes = address.as_slice(); + let first = bytes.iter().position(|byte| *byte != 0).unwrap_or(19); + push(&bytes[first..]) +} + +/// `SSTORE(0, 1)`. +fn sstore() -> Vec<u8> { + vec![PUSH1, 1, PUSH0, SSTORE] +} + +/// `LOG1` of 32 bytes of memory at offset 0. +fn log1() -> Vec<u8> { + vec![PUSH1, 0xaa, PUSH1, 32, PUSH0, LOG1] +} + +/// `SELFDESTRUCT` in favour of `target`. +fn selfdestruct(target: Address) -> Vec<u8> { + let mut code = push_address(target); + code.push(SELFDESTRUCT); + code +} + +/// `op` (a call) to `to` with `gas` and `value` (for `CALL` and `CALLCODE`), no input and no +/// output, dropping the success flag. +fn call(op: u8, to: Address, gas: u32, value: u8) -> Vec<u8> { + let mut code = vec![PUSH0, PUSH0, PUSH0, PUSH0]; + if matches!(op, CALL | CALLCODE) { + code.extend_from_slice(&[PUSH1, value]); + } + code.extend(push_address(to)); + code.push(PUSH4); + code.extend_from_slice(&gas.to_be_bytes()); + code.extend_from_slice(&[op, POP]); + code +} + +/// `op` (`CREATE` or `CREATE2`) of `initcode`, at most 32 bytes, endowed with nothing, dropping +/// the address. +fn create(op: u8, initcode: &[u8]) -> Vec<u8> { + let len = initcode.len() as u8; + let mut code = push(initcode); + code.extend_from_slice(&[PUSH0, MSTORE]); + if op == CREATE2 { + code.extend_from_slice(&[PUSH1, 0x5a]); + } + code.extend_from_slice(&[PUSH1, len, PUSH1, 32 - len, PUSH0, op, POP]); + code +} + +/// Code that starts a frame of its own: a `STATICCALL` of [`IDENTITY`], which a static frame may +/// make too. +fn nested_start() -> Vec<u8> { + let mut code = call(STATICCALL, IDENTITY, 0, 0); + code.push(STOP); + code +} + +fn ends(mut code: Vec<u8>) -> Vec<u8> { + code.push(STOP); + code +} + +/// A frame of each kind [`PARENT`] starts: on [`CHILD`], whose code starts a frame of its own, or +/// with that code as init code. +fn start_cases() -> Vec<(FrameStartKind, Vec<u8>)> { + vec![ + (FrameStartKind::Call, ends(call(CALL, CHILD, 100_000, 1))), + ( + FrameStartKind::CallCode, + ends(call(CALLCODE, CHILD, 100_000, 1)), + ), + ( + FrameStartKind::DelegateCall, + ends(call(DELEGATECALL, CHILD, 100_000, 0)), + ), + ( + FrameStartKind::StaticCall, + ends(call(STATICCALL, CHILD, 100_000, 0)), + ), + ( + FrameStartKind::Create, + ends(create(CREATE, &nested_start())), + ), + ( + FrameStartKind::Create2, + ends(create(CREATE2, &nested_start())), + ), + ] +} + +/// [`PARENT`] writes, logs, starts a frame of each kind and self-destructs; [`CHILD`] logs. +fn every_site() -> Run { + let mut parent = sstore(); + parent.extend(log1()); + parent.extend(call(CALL, CHILD, 50_000, 1)); + parent.extend(call(CALLCODE, CHILD, 50_000, 1)); + parent.extend(call(DELEGATECALL, CHILD, 50_000, 0)); + parent.extend(call(STATICCALL, CHILD, 50_000, 0)); + parent.extend(create(CREATE, &[])); + parent.extend(create(CREATE2, &[])); + parent.extend(selfdestruct(BENEFICIARY)); + Run::new(SpecId::PRAGUE, parent).with(CHILD, vec![PUSH0, PUSH0, LOG0, STOP], 0) +} + +/// [`every_site`]'s gas and number of logs as the fork reported them before the hooks, on a spec +/// before EIP-8037 and on one with it. +const EVERY_SITE: [(SpecId, ResultGas, usize); 2] = [ + ( + SpecId::PRAGUE, + ResultGas::new_with_state_gas(208_269, 0, 21_000, 0), + 4, + ), + // Two more logs: EIP-7708's transfer logs for the value `CALL` and the `SELFDESTRUCT`. + ( + SpecId::AMSTERDAM, + ResultGas::new_with_state_gas(790_389, 0, 15_000, 648_720), + 6, + ), +]; + +/// The default hooks change nothing: on a spec before EIP-8037 and on one with it, a transaction +/// that reaches every site reports what it reported before the hooks, and hooks that only observe +/// change nothing on either path. The observing hooks see every site. +#[test] +fn test_hooks_that_only_observe_change_nothing() { + for (spec, gas, logs) in EVERY_SITE { + let run = Run { + spec, + ..every_site() + }; + let defaults = run.on_defaults(); + let (outcome, hooks, _) = run.on_both_paths(); + + assert_eq!(outcome, defaults, "{spec:?}"); + assert!( + outcome.result.is_success(), + "{spec:?}: {:?}", + outcome.result + ); + assert_eq!(*outcome.result.gas(), gas, "{spec:?}"); + assert_eq!(outcome.result.logs().len(), logs, "{spec:?}"); + + let writes: Vec<Write> = hooks.writes.into_iter().map(|(write, _)| write).collect(); + let set = SStoreResult { + original_value: StorageValue::ZERO, + present_value: StorageValue::ZERO, + new_value: StorageValue::from(1), + }; + let destructed = SelfDestructResult { + had_value: true, + target_exists: false, + previously_destroyed: false, + }; + assert_eq!( + writes, + vec![ + Write::Sstore(PARENT, StorageKey::ZERO, set), + Write::Log(PARENT, 1, 32), + Write::Log(CHILD, 0, 0), + Write::Log(PARENT, 0, 0), + Write::Log(PARENT, 0, 0), + Write::SelfDestruct(PARENT, BENEFICIARY, U256::from(9), destructed), + ], + "{spec:?}: the static call's log fails before the hook" + ); + let kinds: Vec<FrameStartKind> = hooks.starts.iter().map(|(start, _)| start.kind).collect(); + assert_eq!( + kinds, + [ + FrameStartKind::Call, + FrameStartKind::CallCode, + FrameStartKind::DelegateCall, + FrameStartKind::StaticCall, + FrameStartKind::Create, + FrameStartKind::Create2, + ], + "{spec:?}" + ); + } +} + +/// A creation's start carries the address its frame takes, with EIP-8037 and without it: a `CREATE` +/// from the transaction's frame, one from the frame it created, whose nonce starts at 1, and a +/// `CREATE2`. +#[test] +fn test_a_creation_start_carries_the_address_its_frame_takes() { + let mut parent = create(CREATE, &ends(create(CREATE, &[]))); + parent.extend(ends(create(CREATE2, &[]))); + let first = PARENT.create(1); + let expected = vec![ + Some(first), + Some(first.create(1)), + Some(PARENT.create2(B256::from(U256::from(0x5a)), KECCAK_EMPTY)), + ]; + for spec in [SpecId::PRAGUE, SpecId::AMSTERDAM] { + let (outcome, hooks, frames) = Run::new(spec, parent.clone()).on_both_paths_with_frames(); + let targets: Vec<Option<Address>> = + hooks.starts.iter().map(|(start, _)| start.target).collect(); + + assert!(outcome.result.is_success(), "{spec:?}"); + assert_eq!(frames.created, expected, "{spec:?}: the frames' addresses"); + assert_eq!( + targets, frames.created, + "{spec:?}: each start carries its frame's address" + ); + } +} + +/// At a creation's start, a consumer can tell whether the transaction has changed the account the +/// creation takes: one the transaction funded first is changed, one it has not touched is not. With +/// EIP-8037 the instruction has loaded the account before the hook; without it the account is not +/// loaded until the frame starts, and an account the transaction has not loaded is unchanged. +#[test] +fn test_a_creation_start_shows_whether_its_account_was_changed() { + let salt = B256::from(U256::from(0x5a)); + for (op, address) in [ + (CREATE, PARENT.create(1)), + (CREATE2, PARENT.create2(salt, KECCAK_EMPTY)), + ] { + for spec in [SpecId::PRAGUE, SpecId::AMSTERDAM] { + for funded in [false, true] { + let mut parent = if funded { + call(CALL, address, 0, 1) + } else { + Vec::new() + }; + parent.extend(ends(create(op, &[]))); + let (outcome, hooks, _) = Run::new(spec, parent).on_both_paths(); + let creation = hooks + .starts + .iter() + .position(|(start, _)| start.kind != FrameStartKind::Call) + .expect("the creation starts"); + let created = &outcome.state[&address].info; + + assert!(outcome.result.is_success(), "{op:#x} {spec:?} {funded}"); + assert_eq!(hooks.starts[creation].0.target, Some(address)); + assert_eq!( + changed(&hooks.targets[creation]), + funded, + "{op:#x} {spec:?}: the account was funded first: {funded}" + ); + assert_eq!( + (created.nonce, created.balance), + (1, U256::from(funded as u8)), + "{op:#x} {spec:?} {funded}: the frame took the account" + ); + } + } + } +} + +/// An account that destructs itself: its code stops when called with value, which funds it, and +/// self-destructs otherwise. +const DESTRUCTOR: Address = address!("0x00000000000000000000000000000000000de57e"); +/// An account with a balance of 4 that a destruction pays. +const PAYEE: Address = address!("0x00000000000000000000000000000000000ba1ee"); +/// An account with a balance of 5 whose code self-destructs in favour of [`PARENT`], which a +/// destruction then pays. +const DRAINED: Address = address!("0x00000000000000000000000000000000000d4a1d"); + +/// The account a destruction destructs. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Source { + /// [`DESTRUCTOR`], which the transaction has not changed before. + Untouched, + /// [`DESTRUCTOR`], funded with 2 by the transaction first. + Funded, + /// An account the transaction creates with a [`DESTRUCTOR`]'s code (EIP-6780). + Created, +} + +/// The account a destruction pays. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Payee { + /// [`PAYEE`], which the transaction has not changed before. + Untouched, + /// [`PAYEE`], funded with 1 by the transaction first. + Funded, + /// [`BENEFICIARY`], which does not exist. + New, + /// [`DRAINED`], which the transaction drained first by calling it, so a destruction that pays + /// it 5 puts it back as it was loaded. + Drained, + /// The destructed account itself. + Itself, +} + +/// A destruction: the source and the beneficiary as the journal held them before the write and at +/// the hook, with what the hook was handed. +#[derive(Debug)] +struct Destruct { + address: Address, + target: Address, + balance: U256, + result: SelfDestructResult, + before: [View; 2], + after: [View; 2], +} + +/// An account's nonce, balance and code hash, and those it was loaded with. +type Facts = ((u64, U256, B256), (u64, U256, B256)); + +fn facts(view: &View) -> Option<Facts> { + view.as_ref().map(|(info, original)| { + ( + (info.nonce, info.balance, info.code_hash), + (original.nonce, original.balance, original.code_hash), + ) + }) +} + +impl Destruct { + /// The source and the beneficiary before the write, as a consumer rebuilds them from the + /// journal at the hook and the hook's facts: the write changed no nonce and no code, the + /// source held `balance`, and a beneficiary that is another account got all of it. + fn rebuilt(&self) -> [View; 2] { + let with_balance = |view: &View, balance: U256| { + view.clone().map(|(mut info, original)| { + info.balance = balance; + (info, original) + }) + }; + let source = with_balance(&self.after[0], self.balance); + let target = if self.target == self.address { + source.clone() + } else { + let paid = self.after[1] + .as_ref() + .expect("the write loaded it") + .0 + .balance; + with_balance(&self.after[1], paid - self.balance) + }; + [source, target] + } +} + +/// `PUSH32 word`, where `bytes` fill the word from the left. +fn push_word(bytes: &[u8]) -> Vec<u8> { + let mut word = [0u8; 32]; + word[..bytes.len()].copy_from_slice(bytes); + let mut code = vec![PUSH32]; + code.extend_from_slice(&word); + code +} + +/// `bytes` stored in memory from offset 0. +fn mstore_bytes(bytes: &[u8]) -> Vec<u8> { + let mut code = Vec::new(); + for (word, chunk) in bytes.chunks(32).enumerate() { + code.extend(push_word(chunk)); + code.extend_from_slice(&[PUSH1, (word * 32) as u8, MSTORE]); + } + code +} + +/// A [`DESTRUCTOR`]'s code, paying `payee`, or the account itself when `None`. +fn destructor(payee: Option<Address>) -> Vec<u8> { + let pay = payee.map_or(vec![ADDRESS], push_address); + let stop = 5 + pay.len() as u8; + let mut code = vec![CALLVALUE, PUSH1, stop, JUMPI]; + code.extend(pay); + code.extend_from_slice(&[SELFDESTRUCT, JUMPDEST, STOP]); + code +} + +/// Init code that deploys `runtime`. +fn deploying(runtime: &[u8]) -> Vec<u8> { + let mut code = mstore_bytes(runtime); + code.extend_from_slice(&[PUSH1, runtime.len() as u8, PUSH0, RETURN]); + code +} + +/// `CREATE` of `initcode` endowed with `value`, leaving the address on the stack. +fn create_keeping(initcode: &[u8], value: u8) -> Vec<u8> { + let mut code = mstore_bytes(initcode); + code.extend_from_slice(&[PUSH1, initcode.len() as u8, PUSH0, PUSH1, value, CREATE]); + code +} + +/// A `CALL` with `value` and all the gas the cap allows to the address on top of the stack, which +/// stays there. +fn call_top(value: u8) -> Vec<u8> { + vec![ + PUSH0, PUSH0, PUSH0, PUSH0, PUSH1, value, DUP6, PUSH4, 0xff, 0xff, 0xff, 0xff, CALL, POP, + ] +} + +/// The transaction [`PARENT`] runs for a destruction of `source` holding `held` that pays +/// `payee`, done once or twice: the second time after the transaction funded the source with 3. +/// Returns each destruction. +fn destructions( + spec: SpecId, + source: Source, + held: u8, + payee: Payee, + twice: bool, +) -> Vec<Destruct> { + let pays = match payee { + Payee::Untouched | Payee::Funded => Some(PAYEE), + Payee::New => Some(BENEFICIARY), + Payee::Drained => Some(DRAINED), + Payee::Itself => None, + }; + let code = destructor(pays); + let call_source = |value: u8| match source { + Source::Created => call_top(value), + Source::Untouched | Source::Funded => call(CALL, DESTRUCTOR, u32::MAX, value), + }; + let mut parent = Vec::new(); + if source == Source::Created { + parent.extend(create_keeping(&deploying(&code), held)); + } + if payee == Payee::Funded { + parent.extend(call(CALL, PAYEE, 0, 1)); + } + if payee == Payee::Drained { + parent.extend(call(CALL, DRAINED, u32::MAX, 0)); + } + if source == Source::Funded { + parent.extend(call_source(2)); + } + parent.extend(call_source(0)); + if twice { + parent.extend(call_source(3)); + parent.extend(call_source(0)); + } + parent.push(STOP); + + let mut run = + Run::new(spec, parent) + .with(PAYEE, Vec::new(), 4) + .with(DRAINED, selfdestruct(PARENT), 5); + run.accounts[0].2 = 100; + if source != Source::Created { + run = run.with(DESTRUCTOR, code, u64::from(held)); + } + let (outcome, hooks, _) = run.on_both_paths(); + let case = format!("{spec:?} {source:?} {held} {payee:?} {twice}"); + assert!(outcome.result.is_success(), "{case}: {:?}", outcome.result); + assert_eq!( + hooks.destructions_before.len(), + hooks.destructions_at_hook.len(), + "{case}: every destruction reaches the hook" + ); + let writes = hooks + .writes + .into_iter() + .filter_map(|(write, _)| match write { + Write::SelfDestruct(address, target, balance, result) => { + Some((address, target, balance, result)) + } + _ => None, + }); + writes + .zip( + hooks + .destructions_before + .into_iter() + .zip(hooks.destructions_at_hook), + ) + .map( + |((address, target, balance, result), (before, after))| Destruct { + address, + target, + balance, + result, + before, + after, + }, + ) + .collect() +} + +/// For every destruction, the facts the completed-write hook is handed and the journal at the +/// hook are enough to rebuild both accounts as they were before the write, so a consumer can tell +/// whether each was changed from what the transaction loaded before the write and after it: the +/// source's balance before the write is what the hook sees, and rebuilding from it agrees with the +/// journal before the write. Over a source equal +/// to its beneficiary or not, created in the transaction or not (EIP-6780) and changed before or +/// not; its balance zero or not; a beneficiary unchanged, changed or new; a first destruction and +/// a second (destroyed before); on a spec before EIP-6780, one with it, and one with EIP-8246. +#[test] +fn test_a_destruction_hands_the_hook_what_rebuilds_both_accounts() { + let mut seen = 0; + for spec in [SpecId::SHANGHAI, SpecId::PRAGUE, SpecId::AMSTERDAM] { + for source in [Source::Untouched, Source::Funded, Source::Created] { + for held in [0, 5] { + for payee in [ + Payee::Untouched, + Payee::Funded, + Payee::New, + Payee::Drained, + Payee::Itself, + ] { + for twice in [false, true] { + let case = format!("{spec:?} {source:?} {held} {payee:?} {twice}"); + let destructs = destructions(spec, source, held, payee, twice); + let drains = (payee == Payee::Drained) as usize; + assert_eq!(destructs.len(), drains + 1 + twice as usize, "{case}"); + for (n, destruct) in destructs.iter().enumerate() { + let rebuilt = destruct.rebuilt(); + let held_before = facts(&destruct.before[0]).map(|(info, _)| info.1); + + assert_eq!( + Some(destruct.balance), + held_before, + "{case} #{n}: the hook sees the source's balance" + ); + assert_eq!( + facts(&rebuilt[0]), + facts(&destruct.before[0]), + "{case} #{n}" + ); + if destruct.before[1].is_some() { + assert_eq!( + facts(&rebuilt[1]), + facts(&destruct.before[1]), + "{case} #{n}" + ); + } else { + assert!(!changed(&rebuilt[1]), "{case} #{n}: loaded unchanged"); + } + seen += 1; + } + } + } + } + } + } + // Per spec, source and balance: three destructions for each of five beneficiaries, and the + // drained one's own two. + assert_eq!(seen, 3 * 3 * 2 * (5 * 3 + 2)); +} + +/// Worked examples of the balances a consumer rebuilds from a destruction's facts: each row is +/// `(spec, source, held, payee, twice)` and, for each destruction in turn, the source's balance and +/// the beneficiary's (none when it is the source) before the write. The first two rows leave the +/// source the same after the write (loaded with 5, now 0) and report the same result, but one +/// destructed it from 5, as loaded, and the other from 7, after the transaction funded it: only the +/// balance before the write tells them apart. A drained beneficiary the write pays rebuilds to the +/// nothing it held. +#[test] +fn test_a_destruction_rebuilds_to_the_balances_before_it() { + type Row = ( + SpecId, + Source, + u8, + Payee, + bool, + &'static [(u64, Option<u64>)], + ); + let rows: [Row; 13] = [ + ( + SpecId::PRAGUE, + Source::Untouched, + 5, + Payee::New, + false, + &[(5, Some(0))], + ), + ( + SpecId::PRAGUE, + Source::Funded, + 5, + Payee::New, + false, + &[(7, Some(0))], + ), + ( + SpecId::PRAGUE, + Source::Funded, + 0, + Payee::New, + false, + &[(2, Some(0))], + ), + ( + SpecId::PRAGUE, + Source::Untouched, + 0, + Payee::New, + false, + &[(0, Some(0))], + ), + ( + SpecId::PRAGUE, + Source::Untouched, + 5, + Payee::Funded, + false, + &[(5, Some(5))], + ), + ( + SpecId::PRAGUE, + Source::Untouched, + 5, + Payee::Untouched, + false, + &[(5, Some(4))], + ), + ( + SpecId::PRAGUE, + Source::Untouched, + 5, + Payee::Itself, + false, + &[(5, None)], + ), + ( + SpecId::SHANGHAI, + Source::Untouched, + 5, + Payee::Itself, + false, + &[(5, None)], + ), + ( + SpecId::AMSTERDAM, + Source::Created, + 5, + Payee::Itself, + false, + &[(5, None)], + ), + ( + SpecId::PRAGUE, + Source::Created, + 5, + Payee::New, + false, + &[(5, Some(0))], + ), + ( + SpecId::PRAGUE, + Source::Created, + 5, + Payee::New, + true, + &[(5, Some(0)), (3, Some(5))], + ), + // The drained account's own destruction in favour of `PARENT` comes first. + ( + SpecId::PRAGUE, + Source::Untouched, + 5, + Payee::Drained, + false, + &[(5, Some(100)), (5, Some(0))], + ), + ( + SpecId::PRAGUE, + Source::Untouched, + 0, + Payee::Drained, + false, + &[(5, Some(100)), (0, Some(0))], + ), + ]; + let balance = |view: &View| view.as_ref().expect("loaded").0.balance.to::<u64>(); + let mut afters = Vec::new(); + for (spec, source, held, payee, twice, balances) in rows { + let case = format!("{spec:?} {source:?} {held} {payee:?} {twice}"); + let destructs = destructions(spec, source, held, payee, twice); + let seen: Vec<(u64, Option<u64>)> = destructs + .iter() + .map(|destruct| { + let rebuilt = destruct.rebuilt(); + let paid = (destruct.target != destruct.address).then(|| balance(&rebuilt[1])); + (balance(&rebuilt[0]), paid) + }) + .collect(); + + assert_eq!(seen, balances, "{case}"); + afters.push((facts(&destructs[0].after[0]), destructs[0].result.clone())); + } + assert_eq!(afters[0], afters[1], "the same after the write"); + let second = destructions(SpecId::PRAGUE, Source::Created, 5, Payee::New, true); + assert!(second[1].result.previously_destroyed); +} + +/// `code` with its last instruction, which drops a result, replaced by `STOP`. +fn stops_after(mut code: Vec<u8>) -> Vec<u8> { + assert_eq!(code.pop(), Some(POP)); + ends(code) +} + +/// The instruction under test, on [`CHILD`], which [`PARENT`] calls with `gas`: the first is its +/// name, the second its code, which ends with the instruction. `CHILD` has a balance of 1, to send +/// or pay out; the calls go to an account that does not exist, so it is cold. +fn charge_cases() -> Vec<(&'static str, Vec<u8>)> { + vec![ + ("SSTORE", ends(sstore())), + ("LOG1", ends(log1())), + ("SELFDESTRUCT", selfdestruct(BENEFICIARY)), + ("CALL", stops_after(call(CALL, EMPTY, 0, 1))), + ("CALLCODE", stops_after(call(CALLCODE, EMPTY, 0, 1))), + ("DELEGATECALL", stops_after(call(DELEGATECALL, EMPTY, 0, 0))), + ("STATICCALL", stops_after(call(STATICCALL, EMPTY, 0, 0))), + ("CREATE", stops_after(create(CREATE, &[]))), + ("CREATE2", stops_after(create(CREATE2, &[]))), + ] +} + +/// On each path, an instruction one gas short of what it charges before its hook fails without +/// reaching it, and with exactly that gas reaches it with nothing left and nothing is charged +/// after it: the frame, which ends with the instruction, succeeds. On Amsterdam with no reservoir, +/// so the last charge is the state-gas charge where there is one. +#[test] +fn test_a_charge_that_fails_before_the_hook_never_reaches_it() { + // The parent stores whether the child succeeded in its slot 0. + let mut parent = stops_after(call(CALL, CHILD, 0, 0)); + parent.pop(); + parent.extend_from_slice(&[PUSH0, SSTORE, STOP]); + // The named gas: the four bytes before `CALL PUSH0 SSTORE STOP`. + let gas_at = parent.len() - 8; + let child_run = |code: &[u8], gas: u32| { + let mut parent = parent.clone(); + parent[gas_at..gas_at + 4].copy_from_slice(&gas.to_be_bytes()); + let (outcome, hooks, _) = Run::new(SpecId::AMSTERDAM, parent) + .with(CHILD, code.to_vec(), 1) + .on_both_paths(); + let succeeded = outcome.state[&PARENT].storage[&StorageKey::ZERO].present_value; + (hooks, succeeded == U256::from(1)) + }; + // The child's own hook call: its write, or the start it makes after the parent's. + let childs = |hooks: &Hooks| -> Option<(u64, u64)> { + if let Some((_, gas)) = hooks + .writes + .iter() + .find(|(write, _)| write.address() == CHILD) + { + return Some((gas.remaining(), 0)); + } + hooks + .starts + .get(1) + .map(|(start, gas)| (gas.remaining(), start.forward)) + }; + for (name, code) in charge_cases() { + let ample: u32 = 1_000_000; + let (hooks, succeeded) = child_run(&code, ample); + let (left, forward) = childs(&hooks).expect("the hook is reached"); + let needed = u64::from(ample) - left - forward; + assert!(succeeded, "{name}"); + + let (hooks, succeeded) = child_run(&code, needed as u32); + assert_eq!( + childs(&hooks), + Some((0, 0)), + "{name}: reached with nothing left" + ); + assert!(succeeded, "{name}: nothing is charged after the hook"); + + let (hooks, succeeded) = child_run(&code, needed as u32 - 1); + assert_eq!(childs(&hooks), None, "{name}: one gas short is not reached"); + assert!(!succeeded, "{name}"); + } +} + +/// [`PARENT`] runs `code` and stops, with what it changes: slot 0, a log, or [`BENEFICIARY`]'s +/// balance. +fn verdict_cases() -> Vec<(&'static str, Vec<u8>)> { + vec![ + ("SSTORE", ends(sstore())), + ("LOG1", ends(log1())), + ("SELFDESTRUCT", selfdestruct(BENEFICIARY)), + ] +} + +/// What the transaction left of the write: slot 0's value, the logs, and what [`BENEFICIARY`] got. +fn written(outcome: &ResultAndState) -> (U256, usize, U256) { + let slot = outcome + .state + .get(&PARENT) + .and_then(|account| account.storage.get(&StorageKey::ZERO)) + .map_or(U256::ZERO, |slot| slot.present_value); + let paid = outcome + .state + .get(&BENEFICIARY) + .map_or(U256::ZERO, |account| account.info.balance); + (slot, outcome.result.logs().len(), paid) +} + +/// Each verdict ends the transaction the same way on both paths: `Continue` keeps the write, +/// `OutOfGas` halts and `Revert` reverts with the verdict's output, on the gas the hook left, and +/// both undo it; a `SELFDESTRUCT` so stopped pays nothing. +#[test] +fn test_each_verdict_ends_the_write_the_same_way_on_both_paths() { + let kept = [ + (U256::from(1), 0, U256::ZERO), + (U256::ZERO, 1, U256::ZERO), + (U256::ZERO, 0, U256::from(10)), + ]; + for ((name, code), kept) in verdict_cases().into_iter().zip(kept) { + let run = |verdict| { + Run::new(SpecId::OSAKA, code.clone()) + .hooks(Hooks { + verdict, + ..Hooks::observing() + }) + .on_both_paths() + }; + + let (outcome, _, _) = run(WriteVerdict::Continue); + assert!(outcome.result.is_success(), "{name}: {:?}", outcome.result); + assert_eq!(written(&outcome), kept, "{name}: the write is kept"); + + let (outcome, _, _) = run(WriteVerdict::OutOfGas); + let ExecutionResult::Halt { reason, gas, .. } = &outcome.result else { + panic!("{name}: {:?}", outcome.result); + }; + assert_eq!(*reason, HaltReason::OutOfGas(OutOfGasError::Basic)); + assert_eq!(gas.total_gas_spent(), GAS_LIMIT, "{name}"); + assert_eq!(written(&outcome), (U256::ZERO, 0, U256::ZERO), "{name}"); + + let (outcome, hooks, _) = run(WriteVerdict::Revert(Bytes::from_static(STOP_OUTPUT))); + let ExecutionResult::Revert { output, gas, .. } = &outcome.result else { + panic!("{name}: {:?}", outcome.result); + }; + assert_eq!(*output, Bytes::from_static(STOP_OUTPUT), "{name}"); + assert_eq!( + gas.total_gas_spent(), + GAS_LIMIT - hooks.writes[0].1.remaining(), + "{name}: the frame ends on the gas the hook left" + ); + assert_eq!(written(&outcome), (U256::ZERO, 0, U256::ZERO), "{name}"); + } +} + +/// `false` fails the starting instruction out of gas and starts no frame, on both paths: the +/// frame's code never runs, so its own start never reaches the hook, and the inspector sees no +/// frame start. +#[test] +fn test_a_refused_start_starts_no_frame_on_both_paths() { + for (kind, parent) in start_cases() { + let run = Run::new(SpecId::OSAKA, parent).with(CHILD, nested_start(), 10); + + let (admitted, hooks, frames) = run.on_both_paths(); + assert!(admitted.result.is_success(), "{kind:?}"); + assert_eq!(hooks.starts.len(), 2, "{kind:?}: the frame ran"); + assert_eq!(frames.len(), 3, "{kind:?}"); + + let (refused, hooks, frames) = run + .hooks(Hooks { + admit: false, + ..Hooks::observing() + }) + .on_both_paths(); + let ExecutionResult::Halt { reason, .. } = &refused.result else { + panic!("{kind:?}: {:?}", refused.result); + }; + assert_eq!( + *reason, + HaltReason::OutOfGas(OutOfGasError::Basic), + "{kind:?}" + ); + assert_eq!(hooks.starts.len(), 1, "{kind:?}: the frame never ran"); + assert_eq!(hooks.starts[0].0.kind, kind); + assert_eq!(frames.len(), 1, "{kind:?}: no frame started but the first"); + } +} + +/// A started frame inherits the reservoir as the hook left it, on both paths: the parent's hook +/// charges history gas the reservoir covers, and the frame finds the rest, whether it runs its own +/// code or is answered without a frame, as a precompile is. +#[test] +fn test_a_started_frame_inherits_the_reservoir_the_hook_left() { + const CHARGE: u64 = 4_000; + let hooks = Hooks { + first_start_charge: CHARGE, + ..Hooks::observing() + }; + for (kind, parent) in start_cases() { + let (_, hooks, frames) = Run::new(SpecId::AMSTERDAM, parent) + .with(CHILD, nested_start(), 10) + .reservoir(1_000_000) + .hooks(hooks.clone()) + .on_both_paths(); + let handed = hooks.starts[0].1.reservoir(); + let inherited = hooks.starts[1].1.reservoir(); + + assert!(handed > CHARGE, "{kind:?}: the reservoir covers the charge"); + assert_eq!(inherited, handed - CHARGE, "{kind:?}"); + assert_eq!(frames[1].1, handed - CHARGE, "{kind:?}: the frame's input"); + } + + // The parent calls the identity precompile, then logs: the reservoir the answered call returns + // is the one its input carried. + let mut parent = call(STATICCALL, IDENTITY, 100_000, 0); + parent.extend_from_slice(&[PUSH0, PUSH0, LOG0, STOP]); + let (_, hooks, frames) = Run::new(SpecId::AMSTERDAM, parent) + .reservoir(1_000_000) + .hooks(hooks) + .on_both_paths(); + let handed = hooks.starts[0].1.reservoir(); + + assert_eq!(hooks.writes[0].1.reservoir(), handed - CHARGE); + assert_eq!(frames[1].1, handed - CHARGE); +} + +/// On both paths, a call's forward is the gas it names, or 63/64 of what the caller has left when it +/// names more, and a creation's is always the cap; the hook sees it already taken; and the frame's +/// gas limit is the forward with a value call's stipend on top. +#[test] +fn test_the_forward_on_both_paths() { + let stipend = GasParams::new_spec(SpecId::OSAKA).call_stipend(); + let run = |parent: Vec<u8>| { + let (_, hooks, frames) = Run::new(SpecId::OSAKA, parent) + .with(CHILD, vec![STOP], 0) + .on_both_paths(); + (hooks.starts[0], frames[1].0) + }; + for (op, value) in [(CALL, 1), (CALLCODE, 1), (DELEGATECALL, 0), (STATICCALL, 0)] { + let ((named, named_gas), named_limit) = run(ends(call(op, CHILD, 30_000, value))); + let ((capped, capped_gas), capped_limit) = run(ends(call(op, CHILD, u32::MAX, value))); + // Both runs had the same gas before the forward. + let left = capped_gas.remaining() + capped.forward; + let stipend = if value > 0 { stipend } else { 0 }; + + assert_eq!(named.forward, 30_000, "{op:#x}"); + assert_eq!(capped.forward, left - left / 64, "{op:#x}: the 63/64 cap"); + assert_eq!( + named_gas.remaining() + named.forward, + left, + "{op:#x}: the hook sees the forward taken" + ); + assert_eq!(named_limit, named.forward + stipend, "{op:#x}"); + assert_eq!(capped_limit, capped.forward + stipend, "{op:#x}"); + } + for op in [CREATE, CREATE2] { + let ((start, gas), limit) = run(ends(create(op, &[]))); + let left = gas.remaining() + start.forward; + + assert_eq!( + start.forward, + left - left / 64, + "{op:#x}: taken, and the 63/64 cap" + ); + assert_eq!(limit, start.forward, "{op:#x}"); + } +} + +/// On both paths, what a hook charges stands and the instruction goes on with the gas as the hook +/// left it: a charge the reservoir covers comes out of the reservoir, and one that spills empties +/// it and takes the rest from regular gas. A start's forward is what was taken before the charge. +#[test] +fn test_a_hook_charge_stands_on_both_paths() { + const RESERVOIR: u64 = 100_000; + + // The first `LOG1`'s hook charges; the second sees what it left. + let mut parent = log1(); + parent.extend(log1()); + let run = |charge| { + Run::new(SpecId::AMSTERDAM, ends(parent.clone())) + .reservoir(RESERVOIR) + .hooks(Hooks { + first_write_charge: charge, + ..Hooks::observing() + }) + .on_both_paths() + .1 + }; + let quiet = run(0).writes[1].1; + let handed = quiet.reservoir(); + for (charge, reservoir, spilled) in [(4_000, handed - 4_000, 0), (handed + 500, 0, 500)] { + let second = run(charge).writes[1].1; + + assert_eq!(second.reservoir(), reservoir, "charge {charge}"); + assert_eq!( + second.remaining(), + quiet.remaining() - spilled, + "charge {charge}" + ); + assert_eq!(second.history_gas_spent(), charge as i64, "charge {charge}"); + } + + // The `CALL`'s hook charges; the frame inherits the reservoir it left, with the gas limit it + // would have had, and the parent logs once the frame returns. + let mut parent = call(CALL, CHILD, 100_000, 1); + parent.extend_from_slice(&[PUSH0, PUSH0, LOG0, STOP]); + let run = |charge| { + Run::new(SpecId::AMSTERDAM, parent.clone()) + .with(CHILD, nested_start(), 0) + .reservoir(RESERVOIR) + .hooks(Hooks { + first_start_charge: charge, + ..Hooks::observing() + }) + .on_both_paths() + }; + let (_, quiet, quiet_frames) = run(0); + let handed = quiet.starts[0].1.reservoir(); + for (charge, reservoir, spilled) in [(4_000, handed - 4_000, 0), (handed + 500, 0, 500)] { + let (_, hooks, frames) = run(charge); + + assert_eq!( + hooks.starts[1].1.reservoir(), + reservoir, + "charge {charge}: inherited" + ); + assert_eq!( + frames[1], + (quiet_frames[1].0, reservoir), + "charge {charge}: the input" + ); + let (after, quiet_after) = (hooks.writes[0].1, quiet.writes[0].1); + assert_eq!(after.reservoir(), reservoir, "charge {charge}: returned"); + assert_eq!( + after.remaining(), + quiet_after.remaining() - spilled, + "charge {charge}" + ); + } +} diff --git a/crates/inspector/tests/loop_callbacks.rs b/crates/inspector/tests/loop_callbacks.rs new file mode 100644 index 0000000000..66f3277eac --- /dev/null +++ b/crates/inspector/tests/loop_callbacks.rs @@ -0,0 +1,476 @@ +//! What revm's own EVM, which uses neither loop hook, gives an inspector and a caller: every +//! callback with what it is handed, and the transaction's result on the plain and the inspected +//! path. [`EXPECTED`] was recorded on the loops before they had the hooks (a pending action +//! returned before the first step; a frame's run result handed to the EVM before `frame_end`), so +//! the hooks' defaults change nothing a consumer that does not use them sees. +//! +//! [`PARENT`] calls a child that writes, logs and reverts, one that halts, a precompile, and a +//! contract that self-destructs; creates a contract; logs; and returns. Each frame ends a +//! different way. A change that moves gas or callbacks, such as an upstream pick, moves these +//! lines too: they are then recorded again on the loops of the change's base. + +use context::{result::ExecutionResult, Context, TxEnv}; +use database::{CacheDB, EmptyDB, BENCH_CALLER}; +use handler::{ExecuteEvm, FrameResult, MainBuilder, MainContext, MainnetContext, MainnetEvm}; +use interpreter::{ + interpreter_types::Jumps, CallInputs, CallOutcome, CreateInputs, CreateOutcome, FrameInput, + Interpreter, +}; +use primitives::{address, hardfork::SpecId, Address, Log, TxKind, U256}; +use revm_inspector::{InspectEvm, Inspector}; +use state::{ + bytecode::opcode::{ + OpCode, CALL, CREATE, INVALID, LOG0, LOG1, MSTORE, POP, PUSH0, PUSH1, PUSH20, PUSH3, + RETURN, REVERT, SELFDESTRUCT, SSTORE, + }, + AccountInfo, Bytecode, EvmState, +}; + +type Db = CacheDB<EmptyDB>; +type Ctx = MainnetContext<Db>; + +const SPEC: SpecId = SpecId::OSAKA; +const GAS_LIMIT: u64 = 1_000_000; + +/// Calls [`CHILD`], [`HALTS`], [`IDENTITY`] and [`DESTRUCT`], creates a contract, logs and +/// returns. +const PARENT: Address = address!("0x00000000000000000000000000000000000c0de0"); +/// Writes its slot 0, logs, and reverts with no output. +const CHILD: Address = address!("0x00000000000000000000000000000000000c0de1"); +/// Halts on `INVALID`. +const HALTS: Address = address!("0x00000000000000000000000000000000000c0de3"); +/// Self-destructs to the transaction's caller. +const DESTRUCT: Address = address!("0x00000000000000000000000000000000000c0de2"); +/// The identity precompile. +const IDENTITY: Address = address!("0x0000000000000000000000000000000000000004"); +/// The gas [`PARENT`] forwards to each call: 0x0186a0. +const CALL_GAS: [u8; 3] = [0x01, 0x86, 0xa0]; +/// The creation's init code, which returns one `INVALID` byte as the contract's code. +const INIT_CODE: [u8; 9] = [PUSH1, INVALID, PUSH0, MSTORE, PUSH1, 1, PUSH1, 31, RETURN]; + +/// Every callback, one line each, with what it is handed. +#[derive(Debug, Default)] +struct Recorder { + events: Vec<String>, +} + +/// The name the lines give `address`. +fn name(address: Address) -> String { + match address { + PARENT => "PARENT".into(), + CHILD => "CHILD".into(), + HALTS => "HALTS".into(), + DESTRUCT => "DESTRUCT".into(), + IDENTITY => "IDENTITY".into(), + BENCH_CALLER => "CALLER".into(), + other => other.to_string(), + } +} + +/// The frame `input` starts. +fn frame(input: &FrameInput) -> String { + match input { + FrameInput::Call(inputs) => format!("call {}", name(inputs.target_address)), + FrameInput::Create(inputs) => format!("create by {}", name(inputs.caller())), + FrameInput::Empty => "empty".into(), + } +} + +/// How a frame ended: its result, output and gas. +fn ended(result: &FrameResult) -> String { + let (interpreter_result, gas) = (result.interpreter_result(), result.gas()); + format!( + "{:?} {} remaining={} refunded={} reservoir={}", + interpreter_result.result, + interpreter_result.output, + gas.remaining(), + gas.refunded(), + gas.reservoir() + ) +} + +/// Where `interp` is: its account, program counter, opcode, gas and stack depth. +fn at(interp: &Interpreter) -> String { + let pc = interp.bytecode.pc(); + let opcode = OpCode::new(interp.bytecode.opcode()).map_or("?", OpCode::as_str); + format!( + "{} {pc} {opcode} gas={} stack={}", + name(interp.input.target_address), + interp.gas.remaining(), + interp.stack.len() + ) +} + +impl Inspector<Ctx> for Recorder { + fn initialize_interp(&mut self, interp: &mut Interpreter, _: &mut Ctx) { + self.events + .push(format!("initialize_interp {}", at(interp))); + } + + fn step(&mut self, interp: &mut Interpreter, _: &mut Ctx) { + self.events.push(format!("step {}", at(interp))); + } + + fn step_end(&mut self, interp: &mut Interpreter, _: &mut Ctx) { + self.events.push(format!("step_end {}", at(interp))); + } + + fn log(&mut self, _: &mut Ctx, log: Log) { + self.events.push(format!("log {log:?}")); + } + + fn log_full(&mut self, interp: &mut Interpreter, _: &mut Ctx, log: Log) { + self.events.push(format!("log_full {} {log:?}", at(interp))); + } + + fn frame_start(&mut self, _: &mut Ctx, input: &mut FrameInput) -> Option<FrameResult> { + self.events.push(format!("frame_start {}", frame(input))); + None + } + + fn frame_end(&mut self, _: &mut Ctx, input: &FrameInput, result: &mut FrameResult) { + let line = format!("frame_end {} {}", frame(input), ended(result)); + self.events.push(line); + } + + fn call(&mut self, _: &mut Ctx, inputs: &mut CallInputs) -> Option<CallOutcome> { + let (target, gas) = (name(inputs.target_address), inputs.gas_limit); + self.events.push(format!("call {target} gas={gas}")); + None + } + + fn call_end(&mut self, _: &mut Ctx, inputs: &CallInputs, outcome: &mut CallOutcome) { + let result = ended(&FrameResult::Call(outcome.clone())); + let target = name(inputs.target_address); + self.events.push(format!("call_end {target} {result}")); + } + + fn create(&mut self, _: &mut Ctx, inputs: &mut CreateInputs) -> Option<CreateOutcome> { + let (caller, gas) = (name(inputs.caller()), inputs.gas_limit()); + self.events.push(format!("create by {caller} gas={gas}")); + None + } + + fn create_end(&mut self, _: &mut Ctx, _: &CreateInputs, outcome: &mut CreateOutcome) { + let address = outcome.address.map(name); + let result = ended(&FrameResult::Create(outcome.clone())); + self.events.push(format!("create_end {address:?} {result}")); + } + + fn selfdestruct(&mut self, contract: Address, target: Address, value: U256) { + let (contract, target) = (name(contract), name(target)); + self.events + .push(format!("selfdestruct {contract} to {target} value={value}")); + } +} + +/// Appends a call to `target` with [`CALL_GAS`] and no input, whose status it pops. +fn call(code: &mut Vec<u8>, target: Address) { + code.extend_from_slice(&[PUSH0, PUSH0, PUSH0, PUSH0, PUSH0, PUSH20]); + code.extend_from_slice(target.as_slice()); + code.push(PUSH3); + code.extend_from_slice(&CALL_GAS); + code.extend_from_slice(&[CALL, POP]); +} + +/// [`PARENT`]'s code. +fn parent_code() -> Bytecode { + let mut code = Vec::new(); + call(&mut code, CHILD); + call(&mut code, HALTS); + call(&mut code, IDENTITY); + call(&mut code, DESTRUCT); + // The init code at the end of the first word, then CREATE(0, 32 - len, len). + code.push(PUSH1 + INIT_CODE.len() as u8 - 1); + code.extend_from_slice(&INIT_CODE); + code.extend_from_slice(&[PUSH0, MSTORE]); + code.extend_from_slice(&[ + PUSH1, + INIT_CODE.len() as u8, + PUSH1, + 32 - INIT_CODE.len() as u8, + PUSH0, + CREATE, + POP, + ]); + code.extend_from_slice(&[PUSH1, 7, PUSH0, PUSH0, LOG1]); + code.extend_from_slice(&[PUSH1, 32, PUSH0, RETURN]); + Bytecode::new_raw(code.into()) +} + +/// [`CHILD`]'s code. +fn child_code() -> Bytecode { + Bytecode::new_raw( + vec![ + PUSH1, 1, PUSH0, SSTORE, PUSH0, PUSH0, LOG0, PUSH0, PUSH0, REVERT, + ] + .into(), + ) +} + +/// [`DESTRUCT`]'s code. +fn destruct_code() -> Bytecode { + let mut code = vec![PUSH20]; + code.extend_from_slice(BENCH_CALLER.as_slice()); + code.push(SELFDESTRUCT); + Bytecode::new_raw(code.into()) +} + +/// revm's mainnet EVM, with the accounts and a [`Recorder`]. +fn evm() -> MainnetEvm<Ctx, Recorder> { + let mut db = Db::default(); + db.insert_account_info( + BENCH_CALLER, + AccountInfo::from_balance(U256::from(10u128.pow(21))), + ); + for (address, code, balance) in [ + (PARENT, parent_code(), 0), + (CHILD, child_code(), 0), + (HALTS, Bytecode::new_raw(vec![PUSH0, INVALID].into()), 0), + (DESTRUCT, destruct_code(), 5), + ] { + let info = AccountInfo::new(U256::from(balance), 1, code.hash_slow(), code); + db.insert_account_info(address, info); + } + Context::mainnet() + .with_db(db) + .modify_cfg_chained(|cfg| cfg.set_spec_and_mainnet_gas_params(SPEC)) + .build_mainnet_with_inspector(Recorder::default()) +} + +/// The transaction to [`PARENT`]. +fn tx() -> TxEnv { + TxEnv::builder_for_bench() + .kind(TxKind::Call(PARENT)) + .gas_price(0) + .gas_limit(GAS_LIMIT) + .build_fill() +} + +/// The result, and the state the transaction left, one line per account. +fn summary(result: &ExecutionResult, state: EvmState) -> Vec<String> { + let mut lines = vec![format!("result {result:?}")]; + let mut accounts: Vec<_> = state.into_iter().collect(); + accounts.sort_by_key(|(address, _)| *address); + for (address, account) in accounts { + let mut slots: Vec<_> = account + .storage + .iter() + .map(|(slot, value)| (*slot, value.present_value)) + .collect(); + slots.sort(); + lines.push(format!( + "account {} balance={} nonce={} code={} slots={slots:?}", + name(address), + account.info.balance, + account.info.nonce, + account.info.code_hash + )); + } + lines +} + +/// The inspector's lines, then the result and state lines, as recorded on the loops without the +/// hooks. +const EXPECTED: &[&str] = &[ + "frame_start call PARENT", + "call PARENT gas=979000", + "initialize_interp PARENT 0 PUSH0 gas=979000 stack=0", + "step PARENT 0 PUSH0 gas=979000 stack=0", + "step_end PARENT 1 PUSH0 gas=978998 stack=1", + "step PARENT 1 PUSH0 gas=978998 stack=1", + "step_end PARENT 2 PUSH0 gas=978996 stack=2", + "step PARENT 2 PUSH0 gas=978996 stack=2", + "step_end PARENT 3 PUSH0 gas=978994 stack=3", + "step PARENT 3 PUSH0 gas=978994 stack=3", + "step_end PARENT 4 PUSH0 gas=978992 stack=4", + "step PARENT 4 PUSH0 gas=978992 stack=4", + "step_end PARENT 5 PUSH20 gas=978990 stack=5", + "step PARENT 5 PUSH20 gas=978990 stack=5", + "step_end PARENT 26 PUSH3 gas=978987 stack=6", + "step PARENT 26 PUSH3 gas=978987 stack=6", + "step_end PARENT 30 CALL gas=978984 stack=7", + "step PARENT 30 CALL gas=978984 stack=7", + "step_end PARENT 31 POP gas=876384 stack=0", + "frame_start call CHILD", + "call CHILD gas=100000", + "initialize_interp CHILD 0 PUSH1 gas=100000 stack=0", + "step CHILD 0 PUSH1 gas=100000 stack=0", + "step_end CHILD 2 PUSH0 gas=99997 stack=1", + "step CHILD 2 PUSH0 gas=99997 stack=1", + "step_end CHILD 3 SSTORE gas=99995 stack=2", + "step CHILD 3 SSTORE gas=99995 stack=2", + "step_end CHILD 4 PUSH0 gas=77895 stack=0", + "step CHILD 4 PUSH0 gas=77895 stack=0", + "step_end CHILD 5 PUSH0 gas=77893 stack=1", + "step CHILD 5 PUSH0 gas=77893 stack=1", + "step_end CHILD 6 LOG0 gas=77891 stack=2", + "step CHILD 6 LOG0 gas=77891 stack=2", + "log_full CHILD 7 PUSH0 gas=77516 stack=0 Log { address: 0x00000000000000000000000000000000000c0de1, data: LogData { topics: [], data: 0x } }", + "step_end CHILD 7 PUSH0 gas=77516 stack=0", + "step CHILD 7 PUSH0 gas=77516 stack=0", + "step_end CHILD 8 PUSH0 gas=77514 stack=1", + "step CHILD 8 PUSH0 gas=77514 stack=1", + "step_end CHILD 9 REVERT gas=77512 stack=2", + "step CHILD 9 REVERT gas=77512 stack=2", + "step_end CHILD 10 STOP gas=77512 stack=0", + "call_end CHILD Revert 0x remaining=77512 refunded=0 reservoir=0", + "frame_end call CHILD Revert 0x remaining=77512 refunded=0 reservoir=0", + "step PARENT 31 POP gas=953896 stack=1", + "step_end PARENT 32 PUSH0 gas=953894 stack=0", + "step PARENT 32 PUSH0 gas=953894 stack=0", + "step_end PARENT 33 PUSH0 gas=953892 stack=1", + "step PARENT 33 PUSH0 gas=953892 stack=1", + "step_end PARENT 34 PUSH0 gas=953890 stack=2", + "step PARENT 34 PUSH0 gas=953890 stack=2", + "step_end PARENT 35 PUSH0 gas=953888 stack=3", + "step PARENT 35 PUSH0 gas=953888 stack=3", + "step_end PARENT 36 PUSH0 gas=953886 stack=4", + "step PARENT 36 PUSH0 gas=953886 stack=4", + "step_end PARENT 37 PUSH20 gas=953884 stack=5", + "step PARENT 37 PUSH20 gas=953884 stack=5", + "step_end PARENT 58 PUSH3 gas=953881 stack=6", + "step PARENT 58 PUSH3 gas=953881 stack=6", + "step_end PARENT 62 CALL gas=953878 stack=7", + "step PARENT 62 CALL gas=953878 stack=7", + "step_end PARENT 63 POP gas=851278 stack=0", + "frame_start call HALTS", + "call HALTS gas=100000", + "initialize_interp HALTS 0 PUSH0 gas=100000 stack=0", + "step HALTS 0 PUSH0 gas=100000 stack=0", + "step_end HALTS 1 INVALID gas=99998 stack=1", + "step HALTS 1 INVALID gas=99998 stack=1", + "step_end HALTS 2 STOP gas=99998 stack=1", + "call_end HALTS InvalidFEOpcode 0x remaining=99998 refunded=0 reservoir=0", + "frame_end call HALTS InvalidFEOpcode 0x remaining=99998 refunded=0 reservoir=0", + "step PARENT 63 POP gas=851278 stack=1", + "step_end PARENT 64 PUSH0 gas=851276 stack=0", + "step PARENT 64 PUSH0 gas=851276 stack=0", + "step_end PARENT 65 PUSH0 gas=851274 stack=1", + "step PARENT 65 PUSH0 gas=851274 stack=1", + "step_end PARENT 66 PUSH0 gas=851272 stack=2", + "step PARENT 66 PUSH0 gas=851272 stack=2", + "step_end PARENT 67 PUSH0 gas=851270 stack=3", + "step PARENT 67 PUSH0 gas=851270 stack=3", + "step_end PARENT 68 PUSH0 gas=851268 stack=4", + "step PARENT 68 PUSH0 gas=851268 stack=4", + "step_end PARENT 69 PUSH20 gas=851266 stack=5", + "step PARENT 69 PUSH20 gas=851266 stack=5", + "step_end PARENT 90 PUSH3 gas=851263 stack=6", + "step PARENT 90 PUSH3 gas=851263 stack=6", + "step_end PARENT 94 CALL gas=851260 stack=7", + "step PARENT 94 CALL gas=851260 stack=7", + "step_end PARENT 95 POP gas=751160 stack=0", + "frame_start call IDENTITY", + "call IDENTITY gas=100000", + "call_end IDENTITY Return 0x remaining=99985 refunded=0 reservoir=0", + "frame_end call IDENTITY Return 0x remaining=99985 refunded=0 reservoir=0", + "step PARENT 95 POP gas=851145 stack=1", + "step_end PARENT 96 PUSH0 gas=851143 stack=0", + "step PARENT 96 PUSH0 gas=851143 stack=0", + "step_end PARENT 97 PUSH0 gas=851141 stack=1", + "step PARENT 97 PUSH0 gas=851141 stack=1", + "step_end PARENT 98 PUSH0 gas=851139 stack=2", + "step PARENT 98 PUSH0 gas=851139 stack=2", + "step_end PARENT 99 PUSH0 gas=851137 stack=3", + "step PARENT 99 PUSH0 gas=851137 stack=3", + "step_end PARENT 100 PUSH0 gas=851135 stack=4", + "step PARENT 100 PUSH0 gas=851135 stack=4", + "step_end PARENT 101 PUSH20 gas=851133 stack=5", + "step PARENT 101 PUSH20 gas=851133 stack=5", + "step_end PARENT 122 PUSH3 gas=851130 stack=6", + "step PARENT 122 PUSH3 gas=851130 stack=6", + "step_end PARENT 126 CALL gas=851127 stack=7", + "step PARENT 126 CALL gas=851127 stack=7", + "step_end PARENT 127 POP gas=748527 stack=0", + "frame_start call DESTRUCT", + "call DESTRUCT gas=100000", + "initialize_interp DESTRUCT 0 PUSH20 gas=100000 stack=0", + "step DESTRUCT 0 PUSH20 gas=100000 stack=0", + "step_end DESTRUCT 21 SELFDESTRUCT gas=99997 stack=1", + "step DESTRUCT 21 SELFDESTRUCT gas=99997 stack=1", + "step_end DESTRUCT 22 STOP gas=94997 stack=0", + "selfdestruct DESTRUCT to CALLER value=5", + "call_end DESTRUCT SelfDestruct 0x remaining=94997 refunded=0 reservoir=0", + "frame_end call DESTRUCT SelfDestruct 0x remaining=94997 refunded=0 reservoir=0", + "step PARENT 127 POP gas=843524 stack=1", + "step_end PARENT 128 PUSH9 gas=843522 stack=0", + "step PARENT 128 PUSH9 gas=843522 stack=0", + "step_end PARENT 138 PUSH0 gas=843519 stack=1", + "step PARENT 138 PUSH0 gas=843519 stack=1", + "step_end PARENT 139 MSTORE gas=843517 stack=2", + "step PARENT 139 MSTORE gas=843517 stack=2", + "step_end PARENT 140 PUSH1 gas=843511 stack=0", + "step PARENT 140 PUSH1 gas=843511 stack=0", + "step_end PARENT 142 PUSH1 gas=843508 stack=1", + "step PARENT 142 PUSH1 gas=843508 stack=1", + "step_end PARENT 144 PUSH0 gas=843505 stack=2", + "step PARENT 144 PUSH0 gas=843505 stack=2", + "step_end PARENT 145 CREATE gas=843503 stack=3", + "step PARENT 145 CREATE gas=843503 stack=3", + "step_end PARENT 146 POP gas=12679 stack=0", + "frame_start create by PARENT", + "create by PARENT gas=798822", + "initialize_interp 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 0 PUSH1 gas=798822 stack=0", + "step 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 0 PUSH1 gas=798822 stack=0", + "step_end 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 2 PUSH0 gas=798819 stack=1", + "step 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 2 PUSH0 gas=798819 stack=1", + "step_end 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 3 MSTORE gas=798817 stack=2", + "step 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 3 MSTORE gas=798817 stack=2", + "step_end 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 4 PUSH1 gas=798811 stack=0", + "step 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 4 PUSH1 gas=798811 stack=0", + "step_end 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 6 PUSH1 gas=798808 stack=1", + "step 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 6 PUSH1 gas=798808 stack=1", + "step_end 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 8 RETURN gas=798805 stack=2", + "step 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 8 RETURN gas=798805 stack=2", + "step_end 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 9 STOP gas=798805 stack=0", + "create_end Some(\"0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18\") Return 0xfe remaining=798605 refunded=0 reservoir=0", + "frame_end create by PARENT Return 0xfe remaining=798605 refunded=0 reservoir=0", + "step PARENT 146 POP gas=811284 stack=1", + "step_end PARENT 147 PUSH1 gas=811282 stack=0", + "step PARENT 147 PUSH1 gas=811282 stack=0", + "step_end PARENT 149 PUSH0 gas=811279 stack=1", + "step PARENT 149 PUSH0 gas=811279 stack=1", + "step_end PARENT 150 PUSH0 gas=811277 stack=2", + "step PARENT 150 PUSH0 gas=811277 stack=2", + "step_end PARENT 151 LOG1 gas=811275 stack=3", + "step PARENT 151 LOG1 gas=811275 stack=3", + "log_full PARENT 152 PUSH1 gas=810525 stack=0 Log { address: 0x00000000000000000000000000000000000c0de0, data: LogData { topics: [0x0000000000000000000000000000000000000000000000000000000000000007], data: 0x } }", + "step_end PARENT 152 PUSH1 gas=810525 stack=0", + "step PARENT 152 PUSH1 gas=810525 stack=0", + "step_end PARENT 154 PUSH0 gas=810522 stack=1", + "step PARENT 154 PUSH0 gas=810522 stack=1", + "step_end PARENT 155 RETURN gas=810520 stack=2", + "step PARENT 155 RETURN gas=810520 stack=2", + "step_end PARENT 156 STOP gas=810520 stack=0", + "call_end PARENT Return 0x000000000000000000000000000000000000000000000060fe5f526001601ff3 remaining=810520 refunded=0 reservoir=0", + "frame_end call PARENT Return 0x000000000000000000000000000000000000000000000060fe5f526001601ff3 remaining=810520 refunded=0 reservoir=0", + "result Success { reason: Return, gas: ResultGas { total_gas_spent: 189480, state_gas_spent: 0, refunded: 0, floor_gas: 21000 }, logs: [Log { address: 0x00000000000000000000000000000000000c0de0, data: LogData { topics: [0x0000000000000000000000000000000000000000000000000000000000000007], data: 0x } }], output: Call(0x000000000000000000000000000000000000000000000060fe5f526001601ff3) }", + "account 0x0000000000000000000000000000000000000000 balance=0 nonce=0 code=0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470 slots=[]", + "account IDENTITY balance=0 nonce=0 code=0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470 slots=[]", + "account PARENT balance=0 nonce=2 code=0x768dfcacf8bd182319a6177b16b326be856c90ddb3e3ece4f54c6884fd242918 slots=[]", + "account CHILD balance=0 nonce=1 code=0x67fda313dc72b1739f04ae407f6386f7db6466b9ee221a1c91ca0e0dbf9f648a slots=[(0, 0)]", + "account DESTRUCT balance=0 nonce=1 code=0x7ff285cf123c2738db918e966277ec00263c11d3942a177731207a462269db36 slots=[]", + "account HALTS balance=0 nonce=1 code=0xf8e33f1c6e1a51f3b5f0cf6136a5ffe74392bd9bcca9d6a96614fe629ef3cf6d slots=[]", + "account 0xed591dC4375A9E8c959dA1AAa3712ac1063fCC18 balance=0 nonce=1 code=0xbcc90f2d6dada5b18e155c17a1c0a55920aae94f39857d39d0d8ed07ae8f228b slots=[]", + "account CALLER balance=1000000000000000000005 nonce=1 code=0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470 slots=[]", +]; + +/// The inspector's callbacks, and the result and state of both paths, are as recorded. +#[test] +fn test_an_evm_without_the_loop_hooks_gives_the_recorded_callbacks_and_results() { + let mut inspected = evm(); + let result = inspected + .inspect_one_tx(tx()) + .expect("the transaction runs"); + let state = inspected.finalize(); + let mut seen = core::mem::take(&mut inspected.inspector.events); + seen.extend(summary(&result, state)); + + let mut plain = evm(); + let result = plain.transact_one(tx()).expect("the transaction runs"); + let plain = summary(&result, plain.finalize()); + + assert_eq!(seen[seen.len() - plain.len()..], plain, "the plain path"); + assert_eq!(seen, EXPECTED); +} diff --git a/crates/inspector/tests/loop_hooks.rs b/crates/inspector/tests/loop_hooks.rs new file mode 100644 index 0000000000..964c02f3bf --- /dev/null +++ b/crates/inspector/tests/loop_hooks.rs @@ -0,0 +1,914 @@ +//! The two points the handler loops give a consumer's EVM, on the plain and the inspected path. +//! +//! A pending action: a consumer sets a frame's next action on its interpreter before the frame +//! runs, at its start or when a child returned into it, and the frame's run returns that action +//! before any instruction runs, without an inspector `step`. A return ends the frame; a new frame +//! starts a child, and the frame resumes on its result. A frame whose action is set at its start +//! is not handed to the inspector's `initialize_interp`, so the inspector cannot replace it. +//! +//! A frame's run result: the result of a frame that ran reaches the consumer's +//! [`EvmTr::frame_run_result`] once, as it leaves the frame's run, before the inspector's +//! `call_end` and `frame_end` and before its caller; what the consumer leaves in it is what they +//! see. A result given without a run (a precompile's, an inspector's answer) does not reach it. +//! +//! The consumer here wraps revm's EVM and changes nothing else: [`PARENT`] calls [`CHILD`], then +//! marks a slot of its own, and returns the call's status and return data; [`CHILD`] marks a slot +//! of its own and halts. A transaction goes to [`PARENT`] unless a test sends it to [`CHILD`]. A +//! slot left unmarked is an instruction that did not run. The consumer's hook writes its line into +//! the inspector's, so one list orders both. + +use context::{ + result::{EVMError, ExecutionResult, Output}, + Context, ContextSetters, ContextTr, Evm, FrameStack, JournalTr, TxEnv, +}; +use database::{CacheDB, EmptyDB, BENCH_CALLER}; +use handler::{ + evm::{ContextDbError, FrameInitResult}, + instructions::EthInstructions, + EthFrame, EthPrecompiles, EvmTr, FrameInitOrResult, FrameResult, Handler, ItemOrResult, + MainBuilder, MainContext, MainnetContext, MainnetHandler, +}; +use interpreter::{ + interpreter::{EthInterpreter, ExtBytecode}, + interpreter_action::FrameInit, + interpreter_types::{Jumps, LoopControl}, + CallInputs, CallOutcome, CreateInputs, CreateScheme, FrameInput, Gas, InputsImpl, + InstructionResult, Interpreter, InterpreterAction, InterpreterResult, SharedMemory, +}; +use primitives::{address, hardfork::SpecId, Address, Bytes, TxKind, U256}; +use revm_inspector::{inspect_instructions, Inspector, InspectorEvmTr, InspectorHandler}; +use state::{ + bytecode::opcode::{ + ADD, CALL, INVALID, MSTORE, PUSH0, PUSH1, PUSH20, PUSH3, RETURN, RETURNDATACOPY, + RETURNDATASIZE, SSTORE, + }, + AccountInfo, Bytecode, +}; +use std::convert::Infallible; + +type Db = CacheDB<EmptyDB>; +type Ctx = MainnetContext<Db>; +type Inner = Evm<Ctx, Recorder, EthInstructions<EthInterpreter, Ctx>, EthPrecompiles, EthFrame>; +type Error = EVMError<Infallible>; + +const SPEC: SpecId = SpecId::OSAKA; +const GAS_LIMIT: u64 = 1_000_000; + +/// Calls [`CHILD`] (or the [`Callee`] a test names) with [`CHILD_GAS`], marks its slot 0, and +/// returns the call's status as a word followed by the call's return data. +const PARENT: Address = address!("0x00000000000000000000000000000000000c0de0"); +/// Marks its slot 0 and halts on `INVALID`. +const CHILD: Address = address!("0x00000000000000000000000000000000000c0de1"); +/// The gas [`PARENT`] forwards to [`CHILD`], whose halt spends it: 0x0186a0. +const CHILD_GAS: [u8; 3] = [0x01, 0x86, 0xa0]; +/// The identity precompile, which revm answers without running a frame. +const IDENTITY: Address = address!("0x0000000000000000000000000000000000000004"); +/// The gas the consumer takes from [`CHILD`] for the creation it starts there. +const CREATION_GAS: u64 = 50_000; + +/// The output of the action the consumer sets on [`CHILD`] at its start. +const AT_START: &[u8] = b"set at its start"; +/// The output of the action the consumer sets on [`PARENT`] when [`CHILD`] returns into it. +const ON_RESUME: &[u8] = b"set on its resume"; +/// The output of the action the consumer sets on [`CHILD`] when the creation it started there +/// returns into it. +const AFTER_ITS_CHILD: &[u8] = b"set once its child returned"; +/// The output of the revert the consumer's hook makes of [`CHILD`]'s halt. +const REWRITTEN: &[u8] = b"rewritten as it leaves its run"; +/// The output of the revert the inspector answers the call to [`CHILD`] with. +const ANSWERED: &[u8] = b"answered by the inspector"; +/// The output of the return the inspector sets on [`CHILD`]'s frame in `initialize_interp`. +const AT_INIT: &[u8] = b"set in initialize_interp"; +/// The output the inspector's `step` writes into a return pending on the frame it steps. +const IN_STEP: &[u8] = b"edited in step"; + +/// What the consumer does at the loops' points. +#[derive(Clone, Copy, Debug, Default)] +struct Plan { + /// What the consumer sets on [`CHILD`]'s frame, once revm built it. + at_start: Option<AtStart>, + /// A return carrying [`ON_RESUME`] on [`PARENT`]'s frame, once [`CHILD`]'s result is in it. + on_resume: bool, + /// [`CHILD`]'s halt made a revert carrying [`REWRITTEN`] as it leaves its run. + rewrite: bool, +} + +/// The action the consumer sets on [`CHILD`]'s frame before it runs. +#[derive(Clone, Copy, Debug)] +enum AtStart { + /// A return carrying [`AT_START`]. + Return, + /// A creation with no init code on [`CREATION_GAS`] and the frame's reservoir; once it + /// returned into [`CHILD`], a return carrying [`AFTER_ITS_CHILD`]. + Create, + /// The creation of [`AtStart::Create`]; once it returned into [`CHILD`], nothing, so + /// [`CHILD`] runs its code. + CreateThenRun, +} + +/// What [`PARENT`] calls, and whether the call runs. +#[derive(Clone, Copy, Debug)] +enum Callee { + /// [`CHILD`], which runs. + Child, + /// [`IDENTITY`], which revm answers. + Precompile, + /// [`CHILD`], which the inspector answers with a revert carrying [`ANSWERED`]. + Answered, + /// [`CHILD`], which the inspector halts out of gas in `initialize_interp`. + HaltedAtInit, + /// [`CHILD`], which the inspector returns with [`AT_INIT`] in `initialize_interp`, and whose + /// pending return its `step` edits to carry [`IN_STEP`]. + ReturnedAtInit, +} + +/// What the inspector saw, one line per callback, by the account the frame runs as. +#[derive(Debug, Default)] +struct Recorder { + events: Vec<String>, + /// Answers the call to [`CHILD`]. + answer: bool, + /// Halts [`CHILD`]'s frame out of gas in `initialize_interp`. + halt_at_init: bool, + /// Returns [`CHILD`]'s frame with [`AT_INIT`] in `initialize_interp`, and edits a return + /// pending on a frame it steps to carry [`IN_STEP`]. + return_at_init: bool, +} + +const fn name(address: Address) -> &'static str { + match address { + PARENT => "PARENT", + CHILD => "CHILD", + IDENTITY => "IDENTITY", + _ => "other", + } +} + +fn target(input: &FrameInput) -> &'static str { + match input { + FrameInput::Call(inputs) => name(inputs.target_address), + FrameInput::Create(_) => "CREATION", + FrameInput::Empty => "other", + } +} + +fn is_call_to(input: &FrameInput, address: Address) -> bool { + matches!(input, FrameInput::Call(inputs) if inputs.target_address == address) +} + +/// A return of `frame` carrying `output`, on the gas it holds. +const fn returning(frame: &EthFrame, output: &'static [u8]) -> InterpreterAction { + InterpreterAction::new_return( + InstructionResult::Return, + Bytes::from_static(output), + frame.interpreter.gas, + ) +} + +impl Inspector<Ctx> for Recorder { + fn initialize_interp(&mut self, interp: &mut Interpreter, _: &mut Ctx) { + let account = name(interp.input.target_address); + self.events.push(format!("initialize_interp {account}")); + if self.halt_at_init && interp.input.target_address == CHILD { + interp.halt(InstructionResult::OutOfGas); + } + if self.return_at_init && interp.input.target_address == CHILD { + interp.return_with_output(Bytes::from_static(AT_INIT)); + } + } + + fn step(&mut self, interp: &mut Interpreter, _: &mut Ctx) { + let (account, pc) = (name(interp.input.target_address), interp.bytecode.pc()); + self.events.push(format!("step {account} {pc}")); + if self.return_at_init { + if let Some(InterpreterAction::Return(result)) = interp.bytecode.action() { + result.output = Bytes::from_static(IN_STEP); + } + } + } + + fn step_end(&mut self, interp: &mut Interpreter, _: &mut Ctx) { + let (account, pc) = (name(interp.input.target_address), interp.bytecode.pc()); + self.events.push(format!("step_end {account} {pc}")); + } + + fn call(&mut self, _: &mut Ctx, inputs: &mut CallInputs) -> Option<CallOutcome> { + if !self.answer || inputs.target_address != CHILD { + return None; + } + let result = InterpreterResult::new( + InstructionResult::Revert, + Bytes::from_static(ANSWERED), + Gas::new(inputs.gas_limit), + ); + Some(CallOutcome::new( + result, + inputs.return_memory_offset.clone(), + )) + } + + fn call_end(&mut self, _: &mut Ctx, inputs: &CallInputs, outcome: &mut CallOutcome) { + let (result, output) = (outcome.result.result, &outcome.result.output); + let account = name(inputs.target_address); + self.events + .push(format!("call_end {account} {result:?} {output}")); + } + + fn frame_end(&mut self, _: &mut Ctx, input: &FrameInput, result: &mut FrameResult) { + let (account, result) = (target(input), result.instruction_result()); + self.events.push(format!("frame_end {account} {result:?}")); + } +} + +/// revm's EVM, with a consumer's actions set as [`Plan`] says. +struct Consumer { + evm: Inner, + plan: Plan, +} + +impl EvmTr for Consumer { + type Context = Ctx; + type Instructions = EthInstructions<EthInterpreter, Ctx>; + type Precompiles = EthPrecompiles; + type Frame = EthFrame; + + fn all( + &self, + ) -> ( + &Self::Context, + &Self::Instructions, + &Self::Precompiles, + &FrameStack<Self::Frame>, + ) { + self.evm.all() + } + + fn all_mut( + &mut self, + ) -> ( + &mut Self::Context, + &mut Self::Instructions, + &mut Self::Precompiles, + &mut FrameStack<Self::Frame>, + ) { + self.evm.all_mut() + } + + fn frame_init( + &mut self, + frame_input: FrameInit, + ) -> Result<FrameInitResult<'_, EthFrame>, ContextDbError<Ctx>> { + let at_start = self + .plan + .at_start + .filter(|_| is_call_to(&frame_input.frame_input, CHILD)); + let mut started = self.evm.frame_init(frame_input)?; + if let (Some(at_start), ItemOrResult::Item(frame)) = (at_start, &mut started) { + let action = match at_start { + AtStart::Return => returning(frame, AT_START), + AtStart::Create | AtStart::CreateThenRun => { + let gas = &mut frame.interpreter.gas; + assert!( + gas.record_regular_cost(CREATION_GAS), + "the frame pays the creation" + ); + let inputs = CreateInputs::new( + CHILD, + CreateScheme::Create, + U256::ZERO, + Bytes::new(), + CREATION_GAS, + gas.reservoir(), + ); + InterpreterAction::NewFrame(FrameInput::Create(Box::new(inputs))) + } + }; + frame.interpreter.bytecode.set_action(action); + } + Ok(started) + } + + fn frame_run(&mut self) -> Result<FrameInitOrResult<EthFrame>, ContextDbError<Ctx>> { + self.evm.frame_run() + } + + fn frame_return_result( + &mut self, + result: FrameResult, + ) -> Result<Option<FrameResult>, ContextDbError<Ctx>> { + let returned = self.evm.frame_return_result(result)?; + if returned.is_some() { + return Ok(returned); + } + let caller = self.evm.frame_stack.get(); + let created = matches!(self.plan.at_start, Some(AtStart::Create)); + let output = if is_call_to(&caller.input, CHILD) && created { + AFTER_ITS_CHILD + } else if is_call_to(&caller.input, PARENT) && self.plan.on_resume { + ON_RESUME + } else { + return Ok(None); + }; + let action = returning(caller, output); + caller.interpreter.bytecode.set_action(action); + Ok(None) + } + + /// Writes the result it got into the inspector's lines, by the frame on top of the stack, and + /// rewrites [`CHILD`]'s halt as [`Plan::rewrite`] says. + fn frame_run_result(&mut self, result: &mut FrameResult) -> Result<(), ContextDbError<Ctx>> { + let frame = self.evm.frame_stack.get(); + let (account, got) = (target(&frame.input), result.instruction_result()); + self.evm + .inspector + .events + .push(format!("hook {account} {got:?}")); + if self.plan.rewrite && got == InstructionResult::InvalidFEOpcode { + let result = result.interpreter_result_mut(); + result.result = InstructionResult::Revert; + result.output = Bytes::from_static(REWRITTEN); + } + Ok(()) + } +} + +impl InspectorEvmTr for Consumer { + type Inspector = Recorder; + + fn all_inspector( + &self, + ) -> ( + &Self::Context, + &Self::Instructions, + &Self::Precompiles, + &FrameStack<Self::Frame>, + &Self::Inspector, + ) { + self.evm.all_inspector() + } + + fn all_mut_inspector( + &mut self, + ) -> ( + &mut Self::Context, + &mut Self::Instructions, + &mut Self::Precompiles, + &mut FrameStack<Self::Frame>, + &mut Self::Inspector, + ) { + self.evm.all_mut_inspector() + } +} + +/// [`PARENT`]'s code, calling `callee`. +fn parent_code(callee: Address) -> Bytecode { + let mut code = vec![PUSH0, PUSH0, PUSH0, PUSH0, PUSH0, PUSH20]; + code.extend_from_slice(callee.as_slice()); + code.push(PUSH3); + code.extend_from_slice(&CHILD_GAS); + code.extend_from_slice(&[ + CALL, + // Mark slot 0: the frame resumed. + PUSH1, + 1, + PUSH0, + SSTORE, + // The status at 0, the return data after it. + PUSH0, + MSTORE, + RETURNDATASIZE, + PUSH0, + PUSH1, + 32, + RETURNDATACOPY, + RETURNDATASIZE, + PUSH1, + 32, + ADD, + PUSH0, + RETURN, + ]); + Bytecode::new_raw(code.into()) +} + +/// [`CHILD`]'s code. +fn child_code() -> Bytecode { + Bytecode::new_raw(Bytes::from_static(&[PUSH1, 1, PUSH0, SSTORE, INVALID])) +} + +/// What one transaction did. +#[derive(Debug)] +struct Run { + result: ExecutionResult, + /// The inspector's lines; empty on the plain path. + events: Vec<String>, + /// Whether [`PARENT`]'s and [`CHILD`]'s slot 0 hold the mark. + marked: (bool, bool), +} + +impl Run { + fn output(&self) -> &Bytes { + match &self.result { + ExecutionResult::Success { + output: Output::Call(output), + .. + } => output, + other => panic!("the transaction returns, got {other:?}"), + } + } + + /// The lines of `account`'s steps. + fn steps(&self, account: &str) -> Vec<&str> { + let prefix = format!("step {account} "); + self.lines(|line| line.starts_with(&prefix)) + } + + /// The consumer's hook lines. + fn hooks(&self) -> Vec<&str> { + self.lines(|line| line.starts_with("hook ")) + } + + /// Every line but the steps: the frames' starts and ends, and the hook's. + fn ends(&self) -> Vec<&str> { + self.lines(|line| !line.starts_with("step")) + } + + /// The lines `keep` keeps, in order. + fn lines(&self, keep: impl Fn(&str) -> bool) -> Vec<&str> { + self.events + .iter() + .map(String::as_str) + .filter(|line| keep(line)) + .collect() + } +} + +/// Runs a transaction to [`PARENT`], calling [`CHILD`], through the mainnet handler on the +/// consumer's EVM, inspected or not. +fn run(plan: Plan, inspected: bool) -> Run { + run_calling(Callee::Child, plan, inspected) +} + +/// [`run`], with [`PARENT`] calling `callee`. +fn run_calling(callee: Callee, plan: Plan, inspected: bool) -> Run { + run_to(PARENT, callee, plan, inspected) +} + +/// [`run_calling`], with the transaction sent to `to`. +fn run_to(to: Address, callee: Callee, plan: Plan, inspected: bool) -> Run { + let (address, answer, halt_at_init, return_at_init) = match callee { + Callee::Child => (CHILD, false, false, false), + Callee::Precompile => (IDENTITY, false, false, false), + Callee::Answered => (CHILD, true, false, false), + Callee::HaltedAtInit => (CHILD, false, true, false), + Callee::ReturnedAtInit => (CHILD, false, false, true), + }; + let mut db = Db::default(); + db.insert_account_info( + BENCH_CALLER, + AccountInfo::from_balance(U256::from(10u128.pow(21))), + ); + for (address, code) in [(PARENT, parent_code(address)), (CHILD, child_code())] { + db.insert_account_info( + address, + AccountInfo::new(U256::ZERO, 1, code.hash_slow(), code), + ); + } + let ctx = Context::mainnet() + .with_db(db) + .modify_cfg_chained(|cfg| cfg.set_spec_and_mainnet_gas_params(SPEC)); + let mut consumer = Consumer { + evm: ctx.build_mainnet_with_inspector(Recorder { + answer, + halt_at_init, + return_at_init, + ..Recorder::default() + }), + plan, + }; + consumer.evm.ctx.set_tx( + TxEnv::builder_for_bench() + .kind(TxKind::Call(to)) + .gas_price(0) + .gas_limit(GAS_LIMIT) + .build_fill(), + ); + + let mut handler = MainnetHandler::<Consumer, Error, EthFrame>::default(); + let result = if inspected { + handler.inspect_run(&mut consumer) + } else { + handler.run(&mut consumer) + } + .expect("the transaction runs"); + + let state = consumer.evm.ctx.journal_mut().finalize(); + let mark = |address: Address| { + state + .get(&address) + .and_then(|account| account.storage.get(&U256::ZERO)) + .is_some_and(|slot| slot.present_value == U256::from(1)) + }; + Run { + result, + events: core::mem::take(&mut consumer.evm.inspector.events), + marked: (mark(PARENT), mark(CHILD)), + } +} + +/// The 32-byte status word of a call, followed by its return data. +fn status_and(success: bool, data: &[u8]) -> Bytes { + let mut output = U256::from(success as u8).to_be_bytes_vec(); + output.extend_from_slice(data); + output.into() +} + +/// Without a plan the consumer is revm: the frames run as their code says. +#[test] +fn test_without_a_pending_action_every_frame_runs() { + for inspected in [false, true] { + let run = run(Plan::default(), inspected); + + assert_eq!(run.output(), &status_and(false, &[]), "{inspected}"); + assert_eq!( + run.marked, + (true, false), + "the halt took the child's mark back" + ); + if inspected { + assert_eq!(run.steps("CHILD").len(), 4, "PUSH1 PUSH0 SSTORE INVALID"); + } + } +} + +/// An interpreter whose next action is set before it runs returns that action: no instruction +/// runs and the inspector sees no `step` or `step_end`. +#[test] +fn test_inspect_instructions_returns_a_pending_action_without_a_step() { + let mut ctx: Ctx = Context::mainnet().with_db(Db::default()); + let mut interpreter = Interpreter::<EthInterpreter>::new( + SharedMemory::new(), + ExtBytecode::new(child_code()), + InputsImpl::default(), + false, + SPEC, + GAS_LIMIT, + ); + let action = InterpreterAction::new_return( + InstructionResult::Return, + Bytes::from_static(AT_START), + interpreter.gas, + ); + interpreter.bytecode.set_action(action.clone()); + let instructions = EthInstructions::<EthInterpreter, Ctx>::new_mainnet_with_spec(SPEC); + let mut recorder = Recorder::default(); + + let returned = inspect_instructions( + &mut ctx, + &mut interpreter, + &mut recorder, + instructions.instruction_table(), + instructions.gas_table(), + ); + + assert_eq!(returned, action); + assert_eq!(recorder.events, Vec::<String>::new()); + assert_eq!(interpreter.bytecode.pc(), 0, "no instruction ran"); + assert_eq!( + interpreter.gas.remaining(), + GAS_LIMIT, + "no instruction charged" + ); +} + +/// An action the consumer sets on a frame revm built is the frame's result: its code does not +/// run, on either path, and the inspector sees the frame start and end with nothing between, no +/// `initialize_interp` and no step. +#[test] +fn test_an_action_set_at_a_frames_start_is_its_result() { + let plan = Plan { + at_start: Some(AtStart::Return), + ..Plan::default() + }; + for inspected in [false, true] { + let run = run(plan, inspected); + + assert_eq!(run.output(), &status_and(true, AT_START), "{inspected}"); + assert_eq!(run.marked, (true, false), "the child ran no instruction"); + assert_eq!(run.hooks(), ["hook CHILD Return", "hook PARENT Return"]); + if inspected { + let seen = run.lines(|line| line.contains("CHILD")); + let end = format!("call_end CHILD Return {}", Bytes::from_static(AT_START)); + assert_eq!(seen, ["hook CHILD Return", &end, "frame_end CHILD Return"]); + } + } +} + +/// A frame whose action the consumer set at its start is not handed to `initialize_interp`, so an +/// inspector that halts the frame there does not replace the consumer's action: the consumer's +/// action is the frame's result. +#[test] +fn test_an_inspector_cannot_halt_a_frame_whose_action_is_set_at_its_start() { + let plan = Plan { + at_start: Some(AtStart::Return), + ..Plan::default() + }; + let run = run_calling(Callee::HaltedAtInit, plan, true); + + assert_eq!(run.output(), &status_and(true, AT_START)); + let end = format!("call_end CHILD Return {}", Bytes::from_static(AT_START)); + assert_eq!( + run.lines(|line| line.contains("CHILD")), + ["hook CHILD Return", &end, "frame_end CHILD Return"] + ); +} + +/// An inspector that halts a frame in `initialize_interp` ends it before its first instruction +/// and before any `step` (upstream's run calls `step` once first): the halt is the frame's result, +/// and its caller gets a failed call and none of its gas back, the transaction's result when the +/// frame's own `INVALID` halts it. +#[test] +fn test_an_inspectors_halt_in_initialize_interp_ends_the_frame_without_a_step() { + let halted = run_calling(Callee::HaltedAtInit, Plan::default(), true); + + assert_eq!(halted.output(), &status_and(false, &[])); + assert_eq!(halted.result, run(Plan::default(), true).result); + assert_eq!( + halted.lines(|line| line.contains("CHILD")), + [ + "initialize_interp CHILD", + "hook CHILD OutOfGas", + "call_end CHILD OutOfGas 0x", + "frame_end CHILD OutOfGas" + ] + ); +} + +/// An action an inspector sets in `initialize_interp` is returned before the frame's first `step` +/// (upstream's run calls that `step` first), so whatever that `step` would do is not done: here +/// the `step` edits the pending return, and the frame returns what `initialize_interp` set, where +/// upstream's returns the edit. +#[test] +fn test_an_inspectors_action_in_initialize_interp_is_returned_without_the_step_that_edits_it() { + let run = run_calling(Callee::ReturnedAtInit, Plan::default(), true); + + assert_eq!(run.output(), &status_and(true, AT_INIT)); + assert_eq!(run.marked, (true, false), "the child runs no instruction"); + let end = format!("call_end CHILD Return {}", Bytes::from_static(AT_INIT)); + assert_eq!( + run.lines(|line| line.contains("CHILD")), + [ + "initialize_interp CHILD", + "hook CHILD Return", + &end, + "frame_end CHILD Return" + ] + ); +} + +/// An action the consumer sets on a caller once its child's result is in it is the caller's +/// result: the rest of its code does not run, and the inspector sees no step of it after the +/// child's end. +#[test] +fn test_an_action_set_on_a_frames_resume_is_its_result() { + let plan = Plan { + on_resume: true, + ..Plan::default() + }; + for inspected in [false, true] { + let run = run(plan, inspected); + + assert_eq!(run.output(), &Bytes::from_static(ON_RESUME), "{inspected}"); + assert_eq!( + run.marked, + (false, false), + "the parent ran nothing after the call" + ); + if inspected { + let child_end = run + .events + .iter() + .position(|line| line == "frame_end CHILD InvalidFEOpcode") + .expect("the child ends"); + let end = format!("call_end PARENT Return {}", Bytes::from_static(ON_RESUME)); + assert_eq!( + &run.events[child_end + 1..], + ["hook PARENT Return", &end, "frame_end PARENT Return"] + ); + } + } +} + +/// A child the consumer starts from a frame's start runs before the frame does, and the frame +/// returns the action the consumer sets once the child's result is in it: the frame runs no +/// instruction of its own, on either path, and the inspector sees no step of it. +#[test] +fn test_a_child_started_at_a_frames_start_runs_before_the_frame() { + let plan = Plan { + at_start: Some(AtStart::Create), + ..Plan::default() + }; + for inspected in [false, true] { + let run = run(plan, inspected); + + assert_eq!( + run.output(), + &status_and(true, AFTER_ITS_CHILD), + "{inspected}" + ); + assert_eq!(run.marked, (true, false), "the child ran no instruction"); + assert_eq!( + run.hooks(), + [ + "hook CREATION Return", + "hook CHILD Return", + "hook PARENT Return" + ], + "{inspected}" + ); + if inspected { + assert_eq!(run.steps("CHILD"), Vec::<&str>::new()); + let created = run + .events + .iter() + .position(|line| line == "frame_end CREATION Return"); + let child_ends = run + .events + .iter() + .position(|line| line == "frame_end CHILD Return"); + assert!( + created < child_ends, + "the creation ends first: {:?}", + run.events + ); + } + } +} + +/// A frame that resumes with no action set, from a child the consumer started at its start, runs +/// its code then, on either path; the inspector sees a step before each instruction, though the +/// frame was not handed to `initialize_interp`. +#[test] +fn test_a_frame_resumed_from_a_child_started_at_its_start_runs_its_code() { + let plan = Plan { + at_start: Some(AtStart::CreateThenRun), + ..Plan::default() + }; + for inspected in [false, true] { + let run = run(plan, inspected); + + assert_eq!(run.output(), &status_and(false, &[]), "{inspected}"); + assert_eq!( + run.hooks(), + [ + "hook CREATION Return", + "hook CHILD InvalidFEOpcode", + "hook PARENT Return" + ], + "{inspected}" + ); + if inspected { + let steps = [ + "step CHILD 0", + "step CHILD 2", + "step CHILD 3", + "step CHILD 4", + ]; + assert_eq!(run.steps("CHILD"), steps, "PUSH1 PUSH0 SSTORE INVALID"); + assert_eq!( + run.lines(|line| line.contains("CHILD") && !line.starts_with("step")), + [ + "hook CHILD InvalidFEOpcode", + "call_end CHILD InvalidFEOpcode 0x", + "frame_end CHILD InvalidFEOpcode" + ] + ); + } + } +} + +/// The result of each frame that ran reaches the consumer once, as it leaves the frame's run, on +/// both paths; on the inspected path, before the inspector's `call_end` and `frame_end`. +#[test] +fn test_a_frames_run_result_reaches_the_consumer_once_before_the_inspector() { + for inspected in [false, true] { + let run = run(Plan::default(), inspected); + + assert_eq!( + run.hooks(), + ["hook CHILD InvalidFEOpcode", "hook PARENT Return"], + "{inspected}" + ); + if inspected { + let parent_end = format!("call_end PARENT Return {}", status_and(false, &[])); + assert_eq!( + run.ends(), + [ + "initialize_interp PARENT", + "initialize_interp CHILD", + "hook CHILD InvalidFEOpcode", + "call_end CHILD InvalidFEOpcode 0x", + "frame_end CHILD InvalidFEOpcode", + "hook PARENT Return", + &parent_end, + "frame_end PARENT Return", + ] + ); + } + } +} + +/// What the consumer leaves in a frame's result is what the inspector and the caller see: the +/// child's halt, made a revert with output, reaches the inspector's ends and the caller's status +/// and return data as that revert. +#[test] +fn test_the_consumers_rewrite_is_what_the_inspector_and_the_caller_see() { + let plan = Plan { + rewrite: true, + ..Plan::default() + }; + for inspected in [false, true] { + let run = run(plan, inspected); + + assert_eq!(run.output(), &status_and(false, REWRITTEN), "{inspected}"); + assert_eq!( + run.marked, + (true, false), + "the revert took the child's mark back" + ); + if inspected { + let child_end = format!("call_end CHILD Revert {}", Bytes::from_static(REWRITTEN)); + let seen = run.ends(); + let from = seen + .iter() + .position(|line| *line == "hook CHILD InvalidFEOpcode") + .expect("the hook saw the halt"); + assert_eq!( + seen[from + 1..from + 3], + [&child_end, "frame_end CHILD Revert"] + ); + } + } +} + +/// What the consumer leaves in the transaction's own frame's result is the transaction's result: a +/// transaction to [`CHILD`], whose halt the consumer makes a revert with output, ends as that +/// revert on both paths, and gets back the gas the frame left, as a revert does and a halt does +/// not. +#[test] +fn test_the_consumers_rewrite_of_the_transactions_frame_is_the_transactions_result() { + let plan = Plan { + rewrite: true, + ..Plan::default() + }; + for inspected in [false, true] { + let halted = run_to(CHILD, Callee::Child, Plan::default(), inspected); + let rewritten = run_to(CHILD, Callee::Child, plan, inspected); + + assert_eq!( + halted.result.tx_gas_used(), + GAS_LIMIT, + "a halt spends it all" + ); + let ExecutionResult::Revert { output, .. } = &rewritten.result else { + panic!("the transaction reverts, got {:?}", rewritten.result); + }; + assert_eq!(output, &Bytes::from_static(REWRITTEN), "{inspected}"); + // 21,000 for the transaction, then PUSH1 3, PUSH0 2 and SSTORE's cold zero-to-one 22,100. + assert_eq!(rewritten.result.tx_gas_used(), 43_105, "{inspected}"); + assert_eq!( + rewritten.marked, + (false, false), + "the halt took the mark back" + ); + if inspected { + let end = format!("call_end CHILD Revert {}", Bytes::from_static(REWRITTEN)); + assert_eq!( + rewritten.ends(), + [ + "initialize_interp CHILD", + "hook CHILD InvalidFEOpcode", + &end, + "frame_end CHILD Revert" + ] + ); + } + } +} + +/// A result given without a run does not reach the consumer: neither a precompile's answer, which +/// revm gives at the frame's start, nor an inspector's. +#[test] +fn test_a_result_given_without_a_run_does_not_reach_the_consumer() { + for inspected in [false, true] { + let run = run_calling(Callee::Precompile, Plan::default(), inspected); + + assert_eq!(run.output(), &status_and(true, &[]), "{inspected}"); + assert_eq!(run.hooks(), ["hook PARENT Return"], "{inspected}"); + } + + let run = run_calling(Callee::Answered, Plan::default(), true); + + assert_eq!(run.output(), &status_and(false, ANSWERED)); + assert_eq!(run.hooks(), ["hook PARENT Return"]); +} diff --git a/crates/inspector/tests/reservoir_settlement.rs b/crates/inspector/tests/reservoir_settlement.rs new file mode 100644 index 0000000000..32546ef06b --- /dev/null +++ b/crates/inspector/tests/reservoir_settlement.rs @@ -0,0 +1,475 @@ +//! An outcome an inspector builds to answer a start settles its reservoir as built, in place of +//! the caller's, and a consumer that keeps part of the caller's reservoir adds back what the +//! caller held. +//! +//! The caller's start copies its reservoir into the input, and the answer's reservoir replaces the +//! caller's, as a frame's does. An answer built on `Gas::new` carries no reservoir: by default the +//! caller is left with none, as upstream's settlement leaves it; with 98% forwarded by a consumer +//! that keeps the rest for the caller ([`KeepingContext`]), the caller is left with the 2% it kept. +//! An answer that carries the input's reservoir gives the caller back what it forwarded. +//! +//! A creation's answer settles through the same arm as a call's: the caller also paid the +//! creation's upfront state charge before the forward, which an answer that copies the input's +//! charge gives back and one built with `CreateOutcome::new` does not. + +use context::{ + context_interface::{ + cfg::{GasId, GasParams, StateGasSite}, + context::{SStoreResult, SelfDestructResult, StateLoad}, + host::{FrameSettle, FrameSplit, FrameStart, LifecycleEnd, LoadError}, + journaled_state::AccountInfoLoad, + Database, + }, + BlockEnv, CfgEnv, Context, ContextError, ContextSetters, ContextTr, Evm, Host, Journal, + LocalContext, TxEnv, +}; +use database::{CacheDB, EmptyDB, BENCH_CALLER}; +use handler::{ + instructions::EthInstructions, EthFrame, EthPrecompiles, MainContext, MainnetContext, +}; +use interpreter::{ + interpreter::EthInterpreter, CallInputs, CallOutcome, CreateInputs, CreateOutcome, Gas, + GasTracker, InstructionResult, InterpreterResult, +}; +use primitives::{ + address, hardfork::SpecId, Address, Bytes, Log, StorageKey, StorageValue, TxKind, B256, U256, +}; +use revm_inspector::{InspectEvm, Inspector}; +use state::{ + bytecode::opcode::{CALL, CREATE, POP, PUSH0, PUSH1, PUSH20, PUSH3, SSTORE, STOP}, + AccountInfo, Bytecode, +}; + +type Db = CacheDB<EmptyDB>; +type DbError = <Db as Database>::Error; +type Ctx = KeepingContext; + +const SPEC: SpecId = SpecId::AMSTERDAM; +const GAS_LIMIT: u64 = 3_000_000; +/// The reservoir the transaction starts with: the regular cap is this far below [`GAS_LIMIT`]. +const RESERVOIR: u64 = 1_000_000; +/// State gas of a new storage slot on Amsterdam's schedule, which [`PARENT`] pays. +const SLOT: u64 = 97_920; +/// What [`PARENT`] holds when it calls [`OK`]. +const BEFORE_THE_CALL: u64 = RESERVOIR - SLOT; +/// Its share at 98: all but the 2% the consumer keeps, rounded down (18,041.6 → 18,041). +const SHARE: u64 = 884_039; + +/// The state charge a creation's start pays for its account on Amsterdam's schedule, before the +/// forward. +const ACCOUNT: u64 = 183_600; +/// What [`PARENT`] holds when it creates, once the creation's charge is paid. +const BEFORE_THE_CREATION: u64 = BEFORE_THE_CALL - ACCOUNT; +/// Its share at 98: all but the 2% the consumer keeps, rounded down (14,369.6 → 14,369). +const CREATION_SHARE: u64 = 704_111; + +/// The mainnet context, with the start lifecycle's hooks of a consumer that keeps part of each +/// caller's reservoir for the caller, when told to ([`KeepingContext::percent`]). +/// +/// The frame-start hook takes `100 - percent` per cent of the caller's reservoir, rounded down, +/// for the caller, and names the rest as the child's reservoir; the settlement hook adds the +/// reservoir the caller held back to it once revm has settled a child into it. The transaction's +/// frame is given the whole reservoir, so nothing is added back to the transaction's gas. Each +/// settlement's depth and held reservoir is recorded, told to keep or not. +struct KeepingContext { + inner: MainnetContext<Db>, + /// The per cent of a caller's reservoir a child receives, if the consumer keeps the rest. + percent: Option<u64>, + /// Every settlement's depth and `held_reservoir`, in the order revm settled them. + held: Vec<(usize, u64)>, +} + +impl ContextTr for KeepingContext { + type Block = BlockEnv; + type Tx = TxEnv; + type Cfg = CfgEnv; + type Db = Db; + type Journal = Journal<Db>; + type Chain = (); + type Local = LocalContext; + + fn all( + &self, + ) -> ( + &Self::Block, + &Self::Tx, + &Self::Cfg, + &Self::Db, + &Self::Journal, + &Self::Chain, + &Self::Local, + ) { + self.inner.all() + } + + fn all_mut( + &mut self, + ) -> ( + &Self::Block, + &Self::Tx, + &Self::Cfg, + &mut Self::Journal, + &mut Self::Chain, + &mut Self::Local, + ) { + self.inner.all_mut() + } + + fn error(&mut self) -> &mut Result<(), ContextError<DbError>> { + self.inner.error() + } +} + +impl ContextSetters for KeepingContext { + fn set_tx(&mut self, tx: Self::Tx) { + self.inner.set_tx(tx); + } + + fn set_block(&mut self, block: Self::Block) { + self.inner.set_block(block); + } +} + +impl Host for KeepingContext { + fn frame_starting(&mut self, start: &mut FrameStart, gas: &mut GasTracker) -> bool { + if let Some(percent) = self.percent { + let reservoir = gas.reservoir(); + let kept = reservoir * (100 - percent) / 100; + start.reservoir = Some(reservoir - kept); + gas.set_reservoir(kept); + } + true + } + + fn frame_split(&mut self, split: &FrameSplit) { + self.inner.frame_split(split); + } + + fn frame_settle(&mut self, settle: &FrameSettle, gas: &mut GasTracker) { + self.held.push((settle.depth, settle.held_reservoir)); + if self.percent.is_some() && settle.depth > 0 { + gas.set_reservoir(gas.reservoir() + settle.held_reservoir); + } + self.inner.frame_settle(settle, gas); + } + + fn frame_lifecycle_end(&mut self, end: LifecycleEnd) { + self.inner.frame_lifecycle_end(end); + } + + fn state_gas_price(&mut self, id: GasId, site: StateGasSite) -> Option<u64> { + self.inner.state_gas_price(id, site) + } + + fn basefee(&self) -> U256 { + self.inner.basefee() + } + + fn blob_gasprice(&self) -> U256 { + self.inner.blob_gasprice() + } + + fn gas_limit(&self) -> U256 { + self.inner.gas_limit() + } + + fn difficulty(&self) -> U256 { + self.inner.difficulty() + } + + fn prevrandao(&self) -> Option<U256> { + self.inner.prevrandao() + } + + fn block_number(&self) -> U256 { + self.inner.block_number() + } + + fn timestamp(&self) -> U256 { + self.inner.timestamp() + } + + fn beneficiary(&self) -> Address { + self.inner.beneficiary() + } + + fn slot_num(&self) -> U256 { + self.inner.slot_num() + } + + fn chain_id(&self) -> U256 { + self.inner.chain_id() + } + + fn effective_gas_price(&self) -> U256 { + self.inner.effective_gas_price() + } + + fn caller(&self) -> Address { + self.inner.caller() + } + + fn blob_hash(&self, number: usize) -> Option<U256> { + self.inner.blob_hash(number) + } + + fn max_initcode_size(&self) -> usize { + self.inner.max_initcode_size() + } + + fn gas_params(&self) -> &GasParams { + self.inner.gas_params() + } + + fn is_amsterdam_eip8037_enabled(&self) -> bool { + self.inner.is_amsterdam_eip8037_enabled() + } + + fn block_hash(&mut self, number: u64) -> Option<B256> { + self.inner.block_hash(number) + } + + fn selfdestruct( + &mut self, + address: Address, + target: Address, + skip_cold_load: bool, + ) -> Result<StateLoad<SelfDestructResult>, LoadError> { + self.inner.selfdestruct(address, target, skip_cold_load) + } + + fn log(&mut self, log: Log) { + self.inner.log(log) + } + + fn sstore_skip_cold_load( + &mut self, + address: Address, + key: StorageKey, + value: StorageValue, + skip_cold_load: bool, + ) -> Result<StateLoad<SStoreResult>, LoadError> { + self.inner + .sstore_skip_cold_load(address, key, value, skip_cold_load) + } + + fn sload_skip_cold_load( + &mut self, + address: Address, + key: StorageKey, + skip_cold_load: bool, + ) -> Result<StateLoad<StorageValue>, LoadError> { + self.inner + .sload_skip_cold_load(address, key, skip_cold_load) + } + + fn tstore(&mut self, address: Address, key: StorageKey, value: StorageValue) { + self.inner.tstore(address, key, value) + } + + fn tload(&mut self, address: Address, key: StorageKey) -> StorageValue { + self.inner.tload(address, key) + } + + fn load_account_info_skip_cold_load( + &mut self, + address: Address, + load_code: bool, + skip_cold_load: bool, + ) -> Result<AccountInfoLoad<'_>, LoadError> { + self.inner + .load_account_info_skip_cold_load(address, load_code, skip_cold_load) + } +} + +/// Writes a new slot, calls [`OK`] (or creates a contract with empty init code) and stops. +const PARENT: Address = address!("0x00000000000000000000000000000000000c0de0"); +/// Stops, when it runs. +const OK: Address = address!("0x0000000000000000000000000000000000000c00"); + +/// What [`PARENT`] starts after writing its slot. +#[derive(Clone, Copy, Debug)] +enum Start { + /// A call to [`OK`]. + Call, + /// A creation with empty init code. + Create, +} + +/// What the inspector does with the call to [`OK`]. +#[derive(Clone, Copy, Debug)] +enum Answer { + /// Lets it run. + Runs, + /// Answers it with a revert built on `Gas::new`, as a tool does. + AsBuilt, + /// Answers it with a revert that carries the input's reservoir. + WithTheShares, +} + +/// Answers the call to [`OK`], or the creation, as told, and records the reservoir the start was +/// given and [`PARENT`]'s reservoir as its frame returned, before the transaction settled it. +struct Answering { + answer: Answer, + given: Option<u64>, + parent_returned: Option<u64>, +} + +impl Answering { + /// The gas of the answer to a start of `gas_limit` given `reservoir`, or `None` to let the + /// start run. + const fn gas(&mut self, gas_limit: u64, reservoir: u64) -> Option<Gas> { + self.given = Some(reservoir); + match self.answer { + Answer::Runs => None, + Answer::AsBuilt => Some(Gas::new(gas_limit)), + Answer::WithTheShares => Some(Gas::new_with_regular_gas_and_reservoir( + gas_limit, reservoir, + )), + } + } +} + +impl Inspector<Ctx, EthInterpreter> for Answering { + fn call(&mut self, _: &mut Ctx, inputs: &mut CallInputs) -> Option<CallOutcome> { + if inputs.target_address != OK { + return None; + } + let gas = self.gas(inputs.gas_limit, inputs.reservoir)?; + Some(CallOutcome::new( + InterpreterResult::new(InstructionResult::Revert, Bytes::new(), gas), + inputs.return_memory_offset.clone(), + )) + } + + fn create(&mut self, _: &mut Ctx, inputs: &mut CreateInputs) -> Option<CreateOutcome> { + let gas = self.gas(inputs.gas_limit(), inputs.reservoir())?; + let mut outcome = CreateOutcome::new( + InterpreterResult::new(InstructionResult::Revert, Bytes::new(), gas), + None, + ); + if let Answer::WithTheShares = self.answer { + outcome.charged_create_state_gas = inputs.charged_create_state_gas(); + outcome.charged_state_gas_address = inputs.charged_state_gas_address(); + } + Some(outcome) + } + + fn call_end(&mut self, _: &mut Ctx, inputs: &CallInputs, outcome: &mut CallOutcome) { + if inputs.target_address == PARENT { + self.parent_returned = Some(outcome.result.gas.reservoir()); + } + } +} + +/// [`PARENT`]'s reservoir as its frame returned, and the reservoir its `start` was given, with +/// `percent` per cent of a caller's reservoir forwarded by a consumer that keeps the rest +/// ([`KeepingContext`]), or the whole reservoir. +fn run(answer: Answer, percent: Option<u64>, start: Start) -> (u64, u64) { + let mut db = Db::default(); + db.insert_account_info( + BENCH_CALLER, + AccountInfo::from_balance(U256::from(10u128.pow(21))), + ); + let mut parent = vec![PUSH1, 1, PUSH0, SSTORE]; + match start { + // `CALL(100_000, OK, 0, 0, 0, 0, 0)`. + Start::Call => { + parent.extend_from_slice(&[PUSH0, PUSH0, PUSH0, PUSH0, PUSH0, PUSH20]); + parent.extend_from_slice(OK.as_slice()); + parent.extend_from_slice(&[PUSH3, 0x01, 0x86, 0xa0, CALL]); + } + // `CREATE(0, 0, 0)`. + Start::Create => parent.extend_from_slice(&[PUSH0, PUSH0, PUSH0, CREATE]), + } + parent.extend_from_slice(&[POP, STOP]); + for (address, code) in [(PARENT, parent), (OK, vec![STOP])] { + db.insert_account_info( + address, + AccountInfo::default() + .with_nonce(1) + .with_code(Bytecode::new_raw(code.into())), + ); + } + let ctx = Context::mainnet().with_db(db).modify_cfg_chained(|cfg| { + cfg.set_spec_and_mainnet_gas_params(SPEC); + cfg.tx_gas_limit_cap = Some(GAS_LIMIT - RESERVOIR); + }); + let ctx = KeepingContext { + inner: ctx, + percent, + held: Vec::new(), + }; + let mut evm: Evm< + Ctx, + Answering, + EthInstructions<EthInterpreter, Ctx>, + EthPrecompiles, + EthFrame, + > = Evm::new_with_inspector( + ctx, + Answering { + answer, + given: None, + parent_returned: None, + }, + EthInstructions::new_mainnet_with_spec(SPEC), + EthPrecompiles::new(SPEC), + ); + let tx = TxEnv::builder_for_bench() + .kind(TxKind::Call(PARENT)) + .gas_price(0) + .gas_limit(GAS_LIMIT) + .build_fill(); + let outcome = evm.inspect_tx(tx).expect("the transaction runs"); + assert!(outcome.result.is_success(), "{:?}", outcome.result); + ( + evm.inspector.parent_returned.expect("PARENT returned"), + evm.inspector.given.expect("the call to OK started"), + ) +} + +#[test] +fn test_an_answer_the_inspector_builds_settles_its_reservoir_as_built() { + for (answer, whole, kept_98) in [ + (Answer::Runs, BEFORE_THE_CALL, BEFORE_THE_CALL), + // The settlement gives the caller the answer's empty reservoir in place of its own; the + // consumer that kept 2% adds that back. + (Answer::AsBuilt, 0, BEFORE_THE_CALL - SHARE), + (Answer::WithTheShares, BEFORE_THE_CALL, BEFORE_THE_CALL), + ] { + assert_eq!( + run(answer, None, Start::Call), + (whole, BEFORE_THE_CALL), + "{answer:?}, the whole reservoir forwarded" + ); + assert_eq!( + run(answer, Some(98), Start::Call), + (kept_98, SHARE), + "{answer:?}, 98% forwarded" + ); + } +} + +/// A creation's answer settles as a call's: as built, the caller gets back the part the consumer +/// kept, and keeps the creation's charge; with the share and the input's charges, the caller gets +/// back what it held before the creation's start. +#[test] +fn test_an_answer_the_inspector_builds_for_a_creation_settles_its_reservoir_as_built() { + for (answer, whole, kept_98) in [ + (Answer::Runs, BEFORE_THE_CREATION, BEFORE_THE_CREATION), + (Answer::AsBuilt, 0, BEFORE_THE_CREATION - CREATION_SHARE), + (Answer::WithTheShares, BEFORE_THE_CALL, BEFORE_THE_CALL), + ] { + assert_eq!( + run(answer, None, Start::Create), + (whole, BEFORE_THE_CREATION), + "{answer:?}, the whole reservoir forwarded" + ); + assert_eq!( + run(answer, Some(98), Start::Create), + (kept_98, CREATION_SHARE), + "{answer:?}, 98% forwarded" + ); + } +} diff --git a/crates/inspector/tests/start_lifecycle.rs b/crates/inspector/tests/start_lifecycle.rs new file mode 100644 index 0000000000..4c03df7138 --- /dev/null +++ b/crates/inspector/tests/start_lifecycle.rs @@ -0,0 +1,845 @@ +//! The start lifecycle on revm's own runners, plain and inspected: every start revm opens settles +//! once, innermost first, and the transaction's boundary ends the lifecycle. +//! +//! The tests of the record and of the fatal errors run in every build. The tests that read the +//! events the hooks received need the lifecycle mirror the context keeps in debug builds only. +//! +//! [`PARENT`] calls [`CHILD`] (or the callee a test names) and then writes its slot 0; [`CHILD`] +//! writes its slot 0. + +use context::{ + context_interface::context::ContextError, + result::{EVMError, HaltReason}, + Context, ContextSetters, ContextTr, Evm, JournalTr, LocalContextTr, TxEnv, +}; +use database::{CacheDB, EmptyDB, BENCH_CALLER}; +use handler::{ + execution::settle_first_frame, instructions::EthInstructions, lifecycle, EthFrame, + EthPrecompiles, EvmTr, ExecuteEvm, FrameResult, Handler, ItemOrResult, MainBuilder, + MainContext, MainnetContext, MainnetHandler, +}; +use interpreter::{ + interpreter::EthInterpreter, interpreter_types::LoopControl, CallInputs, CallOutcome, + FrameInput, Gas, GasTracker, InstructionResult, Interpreter, InterpreterAction, + InterpreterResult, +}; +use primitives::{address, hardfork::SpecId, Address, Bytes, TxKind, U256}; +use revm_inspector::{InspectEvm, Inspector, InspectorHandler}; +use state::{ + bytecode::opcode::{CALL, CREATE, PUSH0, PUSH1, PUSH20, PUSH3, SSTORE, STOP}, + AccountInfo, Bytecode, +}; +use std::convert::Infallible; + +type Db = CacheDB<EmptyDB>; +type Ctx = MainnetContext<Db>; +type MainEvm<I> = Evm<Ctx, I, EthInstructions<EthInterpreter, Ctx>, EthPrecompiles, EthFrame>; +type Error = EVMError<Infallible>; + +const PARENT: Address = address!("0x00000000000000000000000000000000000c0de0"); +const CHILD: Address = address!("0x00000000000000000000000000000000000c0de1"); +const CREATOR: Address = address!("0x00000000000000000000000000000000000c0de2"); +const ECRECOVER: Address = address!("0x0000000000000000000000000000000000000001"); +const GAS_LIMIT: u64 = 1_000_000; + +/// What an inspector does to the run. Most modes are read by the event tests, which need a debug +/// build. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[cfg_attr(not(debug_assertions), allow(dead_code))] +enum Mode { + Observe, + /// In `step_end` after the `CALL`: a fresh interpreter in place of the running one, which + /// returns at once. + ReplaceInterpreter, + /// In `step_end` after the `CALL`: the running frame's input depth rewritten, and the + /// `NewFrame` replaced with a return. + RewriteInputDepth, + /// In `step_end` after the `CALL`: the `NewFrame`'s input dropped and a copy put in its place. + ReplaceInput, + /// In `call(CHILD)`: a transaction run on a clone of the running context. + CloneSimulation, + /// In `call(CHILD)`: a transaction run on an EVM of its own. + IndependentEvm, + /// In `call(CHILD)`, once: a fatal error recorded on the context, as a failed lookup records + /// one. + FatalChildError, +} + +struct Edit { + mode: Mode, + done: bool, +} + +impl Edit { + const fn new(mode: Mode) -> Self { + Self { mode, done: false } + } +} + +impl Inspector<Ctx> for Edit { + fn step_end(&mut self, interp: &mut Interpreter, _: &mut Ctx) { + if self.done { + return; + } + let Some(InterpreterAction::NewFrame(FrameInput::Call(inputs))) = interp.bytecode.action() + else { + return; + }; + let copy = (**inputs).clone(); + let ret = InterpreterAction::Return(InterpreterResult::new( + InstructionResult::Return, + Bytes::new(), + Gas::new(0), + )); + match self.mode { + Mode::ReplaceInterpreter => { + *interp = Interpreter::default(); + interp.bytecode.set_action(ret); + } + Mode::RewriteInputDepth => { + interp.input.depth += 1; + *interp.bytecode.action() = Some(ret); + } + Mode::ReplaceInput => { + drop(interp.bytecode.action().take()); + *interp.bytecode.action() = Some(InterpreterAction::NewFrame(FrameInput::Call( + Box::new(copy), + ))); + } + _ => return, + } + self.done = true; + } + + fn call(&mut self, ctx: &mut Ctx, inputs: &mut CallInputs) -> Option<CallOutcome> { + if inputs.target_address != CHILD || self.done { + return None; + } + match self.mode { + Mode::CloneSimulation => { + let mut nested = ctx.clone().build_mainnet(); + let tx = precompile_tx().nonce(1).build_fill(); + assert!(nested + .transact(tx) + .expect("the simulation runs") + .result + .is_success()); + } + Mode::IndependentEvm => { + let mut nested = Context::mainnet().with_db(Db::default()).build_mainnet(); + let tx = precompile_tx().build_fill(); + assert!(nested + .transact(tx) + .expect("the nested EVM runs") + .result + .is_success()); + } + Mode::FatalChildError => { + *ctx.error() = Err(ContextError::Custom("injected".into())); + } + _ => return None, + } + self.done = true; + None + } +} + +fn precompile_tx() -> context::tx::TxEnvBuilder { + TxEnv::builder_for_bench() + .kind(TxKind::Call(ECRECOVER)) + .gas_price(0) + .gas_limit(GAS_LIMIT) +} + +fn account(code: Vec<u8>) -> AccountInfo { + let code = Bytecode::new_raw(code.into()); + AccountInfo::new(U256::ZERO, 1, code.hash_slow(), code) +} + +/// [`PARENT`] calling `callee`, [`CHILD`], and [`CREATOR`], which creates an empty contract. +fn db(callee: Address) -> Db { + let mut db = Db::default(); + db.insert_account_info( + BENCH_CALLER, + AccountInfo::from_balance(U256::from(10u128.pow(21))), + ); + let mut parent = vec![PUSH0, PUSH0, PUSH0, PUSH0, PUSH0, PUSH20]; + parent.extend_from_slice(callee.as_slice()); + parent.extend_from_slice(&[PUSH3, 0x01, 0x00, 0x00, CALL, PUSH1, 1, PUSH0, SSTORE, STOP]); + db.insert_account_info(PARENT, account(parent)); + db.insert_account_info(CHILD, account(vec![PUSH1, 2, PUSH0, SSTORE, STOP])); + db.insert_account_info(CREATOR, account(vec![PUSH0, PUSH0, PUSH0, CREATE, STOP])); + db +} + +fn context(callee: Address, spec: SpecId) -> Ctx { + Context::mainnet() + .with_db(db(callee)) + .modify_cfg_chained(|cfg| cfg.set_spec_and_mainnet_gas_params(spec)) +} + +fn evm() -> MainEvm<()> { + context(CHILD, SpecId::OSAKA).build_mainnet() +} + +fn inspected(mode: Mode) -> MainEvm<Edit> { + context(CHILD, SpecId::OSAKA).build_mainnet_with_inspector(Edit::new(mode)) +} + +fn tx(to: Address, nonce: u64) -> TxEnv { + TxEnv::builder_for_bench() + .kind(TxKind::Call(to)) + .nonce(nonce) + .gas_price(0) + .gas_limit(GAS_LIMIT) + .build_fill() +} + +/// The record is as a transaction's boundary leaves it: no lifecycle under way, nothing open. +fn assert_clear<I>(evm: &mut MainEvm<I>) { + assert!( + !evm.frame_stack.lifecycle_active(), + "a lifecycle is still under way" + ); + assert!(evm.frame_stack.lifecycle_settled(), "a start is still open"); +} + +fn assert_fatal<T: core::fmt::Debug>(result: Result<T, Error>, message: &str) { + match result { + Err(EVMError::Custom(error)) => assert!(error.contains(message), "{error}"), + other => panic!("expected the fatal error {message:?}, got {other:?}"), + } +} + +/// Every transaction a reused EVM runs, plain and inspected, starts from a clear record and +/// leaves one. (`transact` commits nothing to the database, so each runs at nonce 0.) +#[test] +fn test_a_reused_evm_runs_each_transaction_on_a_clear_record() { + let mut evm = inspected(Mode::Observe); + for _ in 0..3 { + assert!(evm + .transact(tx(PARENT, 0)) + .expect("runs") + .result + .is_success()); + assert_clear(&mut evm); + assert!(evm + .inspect_tx(tx(PARENT, 0)) + .expect("runs") + .result + .is_success()); + assert_clear(&mut evm); + } +} + +/// A fatal error in a child discards the lifecycle at the handler's fatal boundary, and the EVM +/// runs the next transaction. +#[test] +fn test_a_fatal_child_error_discards_the_lifecycle_and_the_evm_is_reused() { + let mut evm = inspected(Mode::FatalChildError); + assert_fatal(evm.inspect_tx(tx(PARENT, 0)), "injected"); + assert_clear(&mut evm); + assert!(evm + .inspect_tx(tx(PARENT, 0)) + .expect("reused") + .result + .is_success()); + assert_clear(&mut evm); +} + +/// A caller of `run_without_catch_error` that drops an error makes the cleanup `catch_error` +/// makes before it reuses the EVM: discarding the lifecycle alone leaves the frame stack's index, +/// so the next transaction's start would open under a frame with no start. +#[test] +fn test_reuse_after_an_uncaught_error_needs_the_frame_stack_cleared() { + let fail = |evm: &mut MainEvm<Edit>| { + evm.inspector.done = false; + evm.ctx.set_tx(tx(PARENT, 0)); + let mut handler = MainnetHandler::<_, Error, EthFrame>::default(); + assert!(handler.inspect_run_without_catch_error(evm).is_err()); + assert!( + evm.frame_stack.lifecycle_active(), + "nothing discarded the lifecycle" + ); + }; + + // With nothing cleaned up, the journal still holds the dropped transaction's nonce. + let mut evm = inspected(Mode::FatalChildError); + fail(&mut evm); + assert_fatal( + evm.inspect_tx(tx(PARENT, 1)), + "a start opened where one is still open", + ); + + let mut evm = inspected(Mode::FatalChildError); + fail(&mut evm); + lifecycle::discard_transaction(&mut evm); + evm.ctx.journal_mut().discard_tx(); + assert_fatal(evm.inspect_tx(tx(PARENT, 0)), "under a frame with no start"); + + let mut evm = inspected(Mode::FatalChildError); + fail(&mut evm); + lifecycle::discard_transaction(&mut evm); + evm.ctx.journal_mut().discard_tx(); + evm.ctx.local_mut().clear(); + evm.frame_stack.clear(); + assert!(evm + .inspect_tx(tx(PARENT, 0)) + .expect("reused") + .result + .is_success()); + assert_clear(&mut evm); +} + +/// The mainnet handler with a `last_frame_result` that settles the transaction's frame but does +/// not close the transaction's start, as an override that misses the call would. +#[derive(Default)] +struct MissesTheClose; + +impl Handler for MissesTheClose { + type Evm = MainEvm<()>; + type Error = Error; + type HaltReason = HaltReason; + + fn last_frame_result( + &mut self, + evm: &mut Self::Evm, + frame_result: &mut FrameResult, + parent_gas: &mut GasTracker, + ) -> Result<(), Self::Error> { + settle_first_frame::<_, Self::Error>(evm.ctx(), frame_result, parent_gas)?; + *frame_result.gas_mut().tracker_mut() = *parent_gas; + Ok(()) + } +} + +/// A missed settlement is a fatal error at the successful boundary, in every build, and the +/// boundary discards the lifecycle, so the EVM runs the next transaction. +#[test] +fn test_a_missed_settlement_fails_the_transaction_at_the_successful_boundary() { + let mut evm = evm(); + evm.ctx.set_tx(tx(PARENT, 0)); + assert_fatal( + MissesTheClose.run(&mut evm), + "the transaction ended with a start open", + ); + assert_clear(&mut evm); + assert!(evm + .transact(tx(PARENT, 0)) + .expect("reused") + .result + .is_success()); +} + +/// A runner that drives the transaction's frame itself without opening the transaction's start: +/// the frame's child has no parent, and the transaction's settlement finds no open start. +#[test] +fn test_a_runner_that_skips_the_transactions_start_is_refused() { + let mut runner = evm(); + runner.ctx.set_tx(tx(PARENT, 0)); + let mut handler = MainnetHandler::<_, Error, EthFrame>::default(); + let mut gas = handler.tx_gas(&mut runner, &Default::default()); + let init = handler + .first_frame_input(&mut runner, &mut gas) + .expect("the frame's input") + .expect("the runtime gas phase passes"); + let ItemOrResult::Item(_) = runner.frame_init(init).expect("the frame starts") else { + panic!("PARENT runs"); + }; + let error = runner.frame_run().expect_err("the call opens no start"); + assert!( + matches!(&error, ContextError::Custom(e) if e.contains("under a frame with no start")), + "{error:?}" + ); + + let mut evm = evm(); + let mut result = FrameResult::new_call_oog(GAS_LIMIT, 0..0, 0); + let mut gas = GasTracker::new(GAS_LIMIT, 0, 0); + let error = handler + .last_frame_result(&mut evm, &mut result, &mut gas) + .expect_err("the transaction's start is not open"); + assert!( + matches!(&error, EVMError::Custom(e) if e.contains("found no open start")), + "{error:?}" + ); +} + +/// A marked tracker and outcome compare, hash and print as the same values unmarked. +#[test] +fn test_the_marks_take_no_part_in_the_values() { + use interpreter::{CreateOutcome, OutcomeMark, StartMark}; + use std::hash::{BuildHasher, BuildHasherDefault, DefaultHasher}; + let hash = + |tracker: &GasTracker| BuildHasherDefault::<DefaultHasher>::default().hash_one(tracker); + + let plain = GasTracker::new(100, 90, 5); + let mut marked = plain; + marked.set_start_mark(StartMark::for_start(7)); + assert!(marked.start_mark().is_for(7)); + assert_eq!(marked, plain); + assert_eq!(hash(&marked), hash(&plain)); + assert_eq!(format!("{marked:?}"), format!("{plain:?}")); + + let result = InterpreterResult::new(InstructionResult::Stop, Bytes::new(), Gas::new(10)); + let call = CallOutcome::new(result.clone(), 0..0); + let marked_call = CallOutcome { + start_mark: OutcomeMark::for_start(7), + ..call.clone() + }; + assert_eq!(marked_call, call); + assert_eq!(format!("{marked_call:?}"), format!("{call:?}")); + let create = CreateOutcome::new(result, None); + let marked_create = CreateOutcome { + start_mark: OutcomeMark::for_start(7), + ..create.clone() + }; + assert_eq!(marked_create, create); + assert_eq!(format!("{marked_create:?}"), format!("{create:?}")); + for printed in [ + format!("{marked:?}"), + format!("{marked_call:?}"), + format!("{marked_create:?}"), + ] { + assert!(!printed.contains("Mark"), "{printed}"); + } +} + +/// An EVM on Amsterdam, where a value transfer to an empty account pays the account's state in the +/// transaction's runtime gas phase. +fn runtime_out_of_gas_evm() -> MainEvm<()> { + Context::mainnet() + .with_db(db(CHILD)) + .modify_cfg_chained(|cfg| { + cfg.set_spec_and_mainnet_gas_params(SpecId::AMSTERDAM); + cfg.tx_gas_limit_cap = Some(u64::MAX); + }) + .build_mainnet() +} + +/// A value transfer to an empty account funded for its intrinsic gas only: valid, and out of gas +/// in the runtime gas phase. +fn runtime_out_of_gas_tx() -> TxEnv { + use primitives::{eip2780, eip8038}; + TxEnv::builder_for_bench() + .kind(TxKind::Call(address!( + "0x00000000000000000000000000000000000000ab" + ))) + .value(U256::from(1)) + .gas_price(0) + .gas_limit(eip2780::TX_BASE_COST + eip8038::COLD_ACCOUNT_ACCESS + eip2780::TX_VALUE_COST) + .build_fill() +} + +/// The stand-in for the frame of a transaction whose runtime gas phase ran out of gas settles on +/// the transaction's start, so the transaction is included as a halt and leaves the record clear. +#[test] +fn test_the_runtime_out_of_gas_stand_in_leaves_the_record_clear() { + let mut evm = runtime_out_of_gas_evm(); + for _ in 0..2 { + assert!(evm + .transact(runtime_out_of_gas_tx()) + .expect("included") + .result + .is_halt()); + assert_clear(&mut evm); + } +} + +/// The events the hooks received, which the mirror the context keeps in debug builds records. +#[cfg(debug_assertions)] +mod events { + use super::*; + use context::context_interface::{ + host::{FrameSplit, LifecycleEnd}, + FrameStack, Host, LifecycleEvent, + }; + + fn describe(event: &LifecycleEvent) -> String { + match event { + LifecycleEvent::Split(split) => format!( + "split {} parent {:?} depth {}", + split.id, split.parent, split.depth + ), + LifecycleEvent::Settle(settle) => { + let mut line = format!( + "settle {} depth {} {:?}", + settle.id, settle.depth, settle.status + ); + if let Some(created) = settle.created { + line.push_str(&format!(" created {created}")); + } + for (flag, name) in [ + (settle.inspector_answer, "inspector-answer"), + (settle.gas_replaced, "gas-replaced"), + (settle.outcome_rebuilt, "outcome-rebuilt"), + ] { + if flag { + line.push(' '); + line.push_str(name); + } + } + line + } + LifecycleEvent::End(end) => format!("end {end:?}"), + } + } + + pub(super) fn events<I>(evm: &mut MainEvm<I>) -> Vec<String> { + let mirror = evm + .ctx + .local + .lifecycle_mirror() + .expect("a debug build keeps one"); + mirror.events().iter().map(describe).collect() + } + + pub(super) const PAIRED: [&str; 5] = [ + "split 1 parent None depth 0", + "split 2 parent Some(1) depth 1", + "settle 2 depth 1 Ok", + "settle 1 depth 0 Ok", + "end Settled", + ]; + + const ROOT_ONLY: [&str; 3] = [ + "split 1 parent None depth 0", + "settle 1 depth 0 Ok", + "end Settled", + ]; + + fn inspect(mode: Mode, callee: Address) -> Vec<String> { + let mut evm = context(callee, SpecId::OSAKA).build_mainnet_with_inspector(Edit::new(mode)); + let result = evm.inspect_tx(tx(PARENT, 0)).expect("runs"); + assert!(result.result.is_success(), "{mode:?}: {:?}", result.result); + events(&mut evm) + } + + #[test] + fn test_a_plain_run_settles_one_start_per_frame() { + let mut evm = evm(); + assert!(evm + .transact(tx(PARENT, 0)) + .expect("runs") + .result + .is_success()); + assert_eq!(events(&mut evm), PAIRED); + } + + #[test] + fn test_an_observed_run_settles_one_start_per_frame() { + assert_eq!(inspect(Mode::Observe, CHILD), PAIRED); + } + + #[test] + fn test_a_precompiles_answer_settles_the_start_it_answers() { + assert_eq!(inspect(Mode::Observe, ECRECOVER), PAIRED); + } + + #[test] + fn test_a_replaced_interpreter_leaves_no_start_open() { + assert_eq!(inspect(Mode::ReplaceInterpreter, CHILD), ROOT_ONLY); + } + + #[test] + fn test_a_rewritten_input_depth_changes_no_start() { + assert_eq!(inspect(Mode::RewriteInputDepth, CHILD), ROOT_ONLY); + } + + #[test] + fn test_a_replaced_input_opens_its_own_start() { + assert_eq!(inspect(Mode::ReplaceInput, CHILD), PAIRED); + } + + #[test] + fn test_a_simulation_on_a_cloned_context_leaves_the_outer_lifecycle_paired() { + assert_eq!(inspect(Mode::CloneSimulation, CHILD), PAIRED); + } + + #[test] + fn test_an_independent_nested_evm_leaves_the_outer_lifecycle_paired() { + assert_eq!(inspect(Mode::IndependentEvm, CHILD), PAIRED); + } + + #[test] + fn test_a_fatal_child_error_ends_the_lifecycle_discarded() { + let mut evm = inspected(Mode::FatalChildError); + assert!(evm.inspect_tx(tx(PARENT, 0)).is_err()); + assert_eq!( + events(&mut evm), + [ + "split 1 parent None depth 0", + "split 2 parent Some(1) depth 1", + "end Discarded", + ] + ); + assert!(evm + .inspect_tx(tx(PARENT, 0)) + .expect("reused") + .result + .is_success()); + assert_eq!(events(&mut evm), PAIRED); + } + + #[test] + fn test_a_creation_reports_the_address_it_took() { + let mut evm = evm(); + assert!(evm + .transact(tx(CREATOR, 0)) + .expect("runs") + .result + .is_success()); + assert_eq!( + events(&mut evm), + [ + "split 1 parent None depth 0", + "split 2 parent Some(1) depth 1", + "settle 2 depth 1 Ok created true", + "settle 1 depth 0 Ok", + "end Settled", + ] + ); + let creation = TxEnv::builder_for_bench() + .kind(TxKind::Create) + .data(Bytes::from_static(&[STOP])) + .gas_price(0) + .gas_limit(GAS_LIMIT) + .build_fill(); + assert!(evm.transact(creation).expect("runs").result.is_success()); + assert_eq!( + events(&mut evm), + [ + "split 1 parent None depth 0", + "settle 1 depth 0 Ok created true", + "end Settled", + ] + ); + } + + /// A transaction whose runtime gas phase runs out of gas settles the stand-in for its frame + /// on the transaction's start. + #[test] + fn test_the_runtime_out_of_gas_stand_in_settles_the_transactions_start() { + let mut evm = runtime_out_of_gas_evm(); + assert!(evm + .transact(runtime_out_of_gas_tx()) + .expect("included") + .result + .is_halt()); + assert_eq!( + events(&mut evm), + [ + "split 1 parent None depth 0", + "settle 1 depth 0 Halt", + "end Settled", + ] + ); + } + + #[test] + fn test_a_system_call_settles_every_start() { + use handler::SystemCallEvm; + let mut evm = evm(); + let result = evm + .system_call_one(PARENT, Bytes::new()) + .expect("the system call runs"); + assert!(result.is_success()); + assert_eq!(events(&mut evm), PAIRED); + } + + /// What an inspector does to a start's result, which revm reports on the settlement. + #[derive(Clone, Copy, Debug, PartialEq, Eq)] + enum Flag { + /// `call` answers with an outcome a constructor built. + Answer, + /// `call_end` puts a constructor-built tracker in the result's gas. + ReplaceGas, + /// `call_end` restores the tracker it saved when the frame's interpreter started. + RestoreSnapshot, + /// `call_end` rewrites the status only. + RewriteStatus, + /// `call_end` builds a new outcome around the same result. + RebuildOutcome, + /// `call_end` rebuilds the outcome and its result, keeping the outcome's other fields and + /// the result's gas. + KeepOutcome, + /// `create_end` builds a new outcome around the same result and address. + RebuildCreation, + } + + struct Rewrite { + flag: Flag, + target: Address, + snapshot: Option<Gas>, + } + + impl Inspector<Ctx> for Rewrite { + fn initialize_interp(&mut self, interp: &mut Interpreter, _: &mut Ctx) { + if interp.input.target_address == self.target { + self.snapshot = Some(interp.gas); + } + } + + fn call(&mut self, _: &mut Ctx, inputs: &mut CallInputs) -> Option<CallOutcome> { + (self.flag == Flag::Answer && inputs.target_address == self.target).then(|| { + CallOutcome::new( + InterpreterResult::new( + InstructionResult::Return, + Bytes::new(), + Gas::new(inputs.gas_limit), + ), + inputs.return_memory_offset.clone(), + ) + }) + } + + fn call_end(&mut self, _: &mut Ctx, inputs: &CallInputs, outcome: &mut CallOutcome) { + if inputs.target_address != self.target { + return; + } + match self.flag { + Flag::ReplaceGas => outcome.result.gas = Gas::new(inputs.gas_limit), + Flag::RestoreSnapshot => { + outcome.result.gas = self.snapshot.expect("the frame's interpreter started"); + } + Flag::RewriteStatus => outcome.result.result = InstructionResult::Revert, + Flag::RebuildOutcome => { + *outcome = + CallOutcome::new(outcome.result.clone(), outcome.memory_offset.clone()); + } + Flag::KeepOutcome => { + let result = InterpreterResult::new( + outcome.result.result, + outcome.result.output.clone(), + outcome.result.gas, + ); + *outcome = CallOutcome { + result, + ..outcome.clone() + }; + } + Flag::Answer | Flag::RebuildCreation => {} + } + } + + fn create_end( + &mut self, + _: &mut Ctx, + _: &interpreter::CreateInputs, + outcome: &mut interpreter::CreateOutcome, + ) { + if self.flag == Flag::RebuildCreation { + *outcome = interpreter::CreateOutcome::new(outcome.result.clone(), outcome.address); + } + } + } + + /// The events of [`PARENT`]'s transaction, calling `callee`, under `flag`, or of + /// [`CREATOR`]'s for a creation's flag. + fn flagged(flag: Flag, target: Address, callee: Address) -> Vec<String> { + let mut evm = context(callee, SpecId::OSAKA).build_mainnet_with_inspector(Rewrite { + flag, + target, + snapshot: None, + }); + let to = if flag == Flag::RebuildCreation { + CREATOR + } else { + PARENT + }; + let result = evm.inspect_tx(tx(to, 0)).expect("runs"); + assert!(result.result.is_success(), "{flag:?}: {:?}", result.result); + events(&mut evm) + } + + /// [`PAIRED`] with the child's settlement as `child`. + fn paired_with(child: &str) -> Vec<String> { + let mut events = PAIRED.map(String::from).to_vec(); + events[2] = child.to_string(); + events + } + + #[test] + fn test_an_inspectors_answer_is_flagged() { + assert_eq!( + flagged(Flag::Answer, CHILD, CHILD), + paired_with("settle 2 depth 1 Ok inspector-answer") + ); + } + + #[test] + fn test_an_inspectors_answer_to_the_transactions_frame_is_flagged() { + assert_eq!( + flagged(Flag::Answer, PARENT, CHILD), + [ + "split 1 parent None depth 0", + "settle 1 depth 0 Ok inspector-answer", + "end Settled", + ] + ); + } + + #[test] + fn test_a_replaced_tracker_is_flagged() { + assert_eq!( + flagged(Flag::ReplaceGas, CHILD, CHILD), + paired_with("settle 2 depth 1 Ok gas-replaced") + ); + assert_eq!( + flagged(Flag::ReplaceGas, ECRECOVER, ECRECOVER), + paired_with("settle 2 depth 1 Ok gas-replaced"), + "a precompile's answer" + ); + } + + /// A snapshot taken before revm marked the result is a replacement, even of the same + /// start's tracker. + #[test] + fn test_a_restored_snapshot_is_flagged() { + assert_eq!( + flagged(Flag::RestoreSnapshot, CHILD, CHILD), + paired_with("settle 2 depth 1 Ok gas-replaced") + ); + } + + #[test] + fn test_a_status_only_rewrite_is_not_flagged() { + assert_eq!( + flagged(Flag::RewriteStatus, CHILD, CHILD), + paired_with("settle 2 depth 1 Revert") + ); + } + + #[test] + fn test_an_outcome_rebuilt_around_the_same_result_is_flagged() { + assert_eq!( + flagged(Flag::RebuildOutcome, CHILD, CHILD), + paired_with("settle 2 depth 1 Ok outcome-rebuilt") + ); + assert_eq!( + flagged(Flag::RebuildCreation, CHILD, CHILD), + [ + "split 1 parent None depth 0", + "split 2 parent Some(1) depth 1", + "settle 2 depth 1 Ok created true outcome-rebuilt", + "settle 1 depth 0 Ok", + "end Settled", + ] + ); + } + + #[test] + fn test_a_rebuild_that_keeps_the_outcome_and_the_gas_is_not_flagged() { + assert_eq!(flagged(Flag::KeepOutcome, CHILD, CHILD), PAIRED); + } + + /// The context hands every event to its mirror: one that does not fit fails the check. + #[test] + #[should_panic(expected = "the transaction's start 1 at depth 5")] + fn test_the_contexts_hooks_feed_the_mirror() { + let mut ctx = context(CHILD, SpecId::OSAKA); + let mut stack = FrameStack::<EthFrame>::new(); + let split: FrameSplit = stack.open_start(5).expect("the record opens it"); + ctx.frame_split(&split); + ctx.frame_lifecycle_end(LifecycleEnd::Settled); + } +} diff --git a/crates/interpreter/src/gas.rs b/crates/interpreter/src/gas.rs index 796eeaed50..468a24cb3a 100644 --- a/crates/interpreter/src/gas.rs +++ b/crates/interpreter/src/gas.rs @@ -236,6 +236,34 @@ impl Gas { self.tracker.refill_reservoir(amount); } + /// The part of [`state_gas_spilled`](Self::state_gas_spilled) halts below this frame already + /// consumed. See [`GasTracker::halted_regular_paid`]. + #[inline] + pub const fn halted_regular_paid(&self) -> u64 { + self.tracker.halted_regular_paid() + } + + /// Consumes, after the rollback of a frame that halts, the part of its charges regular gas + /// paid. See [`GasTracker::consume_regular_paid_charges`]. + #[inline] + pub const fn consume_regular_paid_charges(&mut self) { + self.tracker.consume_regular_paid_charges(); + } + + /// Whether every give-back of state or history gas credits the reservoir alone. See + /// [`GasTracker::reservoir_only_give_backs`]. + #[inline] + pub const fn reservoir_only_give_backs(&self) -> bool { + self.tracker.reservoir_only_give_backs() + } + + /// Sets whether every give-back of state or history gas credits the reservoir alone. See + /// [`GasTracker::set_reservoir_only_give_backs`]. + #[inline] + pub const fn set_reservoir_only_give_backs(&mut self, on: bool) { + self.tracker.set_reservoir_only_give_backs(on); + } + /// Erases a gas cost from remaining (returns gas from child frame). #[inline] pub const fn erase_cost(&mut self, returned: u64) { @@ -353,6 +381,20 @@ impl Gas { self.tracker.record_history_cost(cost) } + /// Records a state gas cost that takes its legacy share, `min(cost, legacy_share)`, from + /// `gas_left` before it draws the reservoir. See + /// [`GasTracker::record_state_cost_with_legacy_share`]. + #[inline] + #[must_use = "In case of not enough gas, the interpreter should halt with an out-of-gas error"] + pub const fn record_state_cost_with_legacy_share( + &mut self, + cost: u64, + legacy_share: u64, + ) -> bool { + self.tracker + .record_state_cost_with_legacy_share(cost, legacy_share) + } + /// Records a regular gas cost: deducts from the spendable part of `remaining` only. /// Does not affect the reservoir. /// diff --git a/crates/interpreter/src/gas/failed_charge.rs b/crates/interpreter/src/gas/failed_charge.rs index e85117aab9..26674fafcf 100644 --- a/crates/interpreter/src/gas/failed_charge.rs +++ b/crates/interpreter/src/gas/failed_charge.rs @@ -37,8 +37,10 @@ impl Gas { /// failure that caused this halt, and it is kept; the unchecked charge's record also holds /// the regular gas from before the spendable part wrapped. With none there, nothing failed: /// the halt is a cold access the instruction refused before its charge, because the frame - /// could not pay it, or an out-of-gas a consumer's instruction returned itself. Either way the - /// regular gas is as it was when the frame stopped. + /// could not pay it, an out-of-gas a consumer's instruction returned itself, or one an + /// instruction hook asked for ([`Host::write_completed`](crate::Host::write_completed), + /// [`Host::frame_starting`](crate::Host::frame_starting)). Either way the regular gas is as it + /// was when the frame stopped. #[inline] pub(crate) const fn record_out_of_gas_halt(&mut self) { if self.failed_charge_remaining().is_none() { diff --git a/crates/interpreter/src/instructions.rs b/crates/interpreter/src/instructions.rs index 667f494022..313fb4d9ba 100644 --- a/crates/interpreter/src/instructions.rs +++ b/crates/interpreter/src/instructions.rs @@ -16,6 +16,7 @@ pub mod control; pub mod host; /// Signed 256-bit integer operations. pub mod i256; +mod instruction_hooks; /// Memory operations (MLOAD, MSTORE, MSIZE, etc.). pub mod memory; /// Stack operations (PUSH, POP, DUP, SWAP, etc.). diff --git a/crates/interpreter/src/instructions/contract.rs b/crates/interpreter/src/instructions/contract.rs index 90c6791052..eeb8c8e8ea 100644 --- a/crates/interpreter/src/instructions/contract.rs +++ b/crates/interpreter/src/instructions/contract.rs @@ -5,8 +5,13 @@ pub use call_helpers::{ load_account_delegated_handle_error, resize_memory, }; +use call_helpers::load_acc_and_calc_forward; + use crate::{ - instructions::utility::IntoAddress, + instructions::{ + instruction_hooks::{cache_created_address, frame_starting}, + utility::IntoAddress, + }, interpreter_action::FrameInput, interpreter_types::{ InputsTr, InterpreterTypes as ITy, LoopControl, MemoryTr, ReturnData, RuntimeFlag, StackTr, @@ -16,6 +21,7 @@ use crate::{ }; use context_interface::{ cfg::{GasId, StateGasCharge, StateGasSite}, + host::{FrameStart, FrameStartKind}, CreateScheme, }; use primitives::{ @@ -142,10 +148,17 @@ pub fn create<const IS_CREATE2: bool, IT: ITy, H: Host + ?Sized>( .host .state_gas_charge(charge) .ok_or(InstructionResult::FatalExternalError)?; - state_gas!(context.interpreter, price); + let share = context.host.gas_params().create_state_gas_legacy_share(); + state_gas_with_legacy_share!(context.interpreter, price, share); create_inputs.set_charged_create_state_gas(true); create_inputs.set_charged_state_gas_address(created_address); } + } else { + cache_created_address( + context.host, + &create_inputs, + context.interpreter.input.depth(), + )?; } let mut gas_limit = context.interpreter.gas.remaining(); @@ -170,8 +183,22 @@ pub fn create<const IS_CREATE2: bool, IT: ITy, H: Host + ?Sized>( return Err(InstructionResult::OutOfGas); } + let kind = if IS_CREATE2 { + FrameStartKind::Create2 + } else { + FrameStartKind::Create + }; + let start = FrameStart::new( + kind, + create_inputs.caller(), + create_inputs.cached_created_address(), + value, + gas_limit, + ); + let reservoir = frame_starting(&mut context.interpreter.gas, context.host, start)?; + create_inputs.set_gas_limit(gas_limit); - create_inputs.set_reservoir(context.interpreter.gas.reservoir()); + create_inputs.set_reservoir(reservoir); context .interpreter .bytecode @@ -215,8 +242,8 @@ pub fn call<const KIND: u8, IT: ITy, H: Host + ?Sized>(mut context: Ictx<'_, H, get_memory_input_and_out_ranges(context.interpreter, context.host.gas_params())?; let is_call = KIND == CALL; - let (gas_limit, bytecode, bytecode_hash, charged_new_account_state_gas) = - load_acc_and_calc_gas(&mut context, to, has_transfer, is_call, local_gas_limit)?; + let (gas_limit, bytecode, bytecode_hash, charged_new_account_state_gas, forward) = + load_acc_and_calc_forward(&mut context, to, has_transfer, is_call, local_gas_limit)?; let target_address = if matches!(KIND, CALLCODE | DELEGATECALL) { context.interpreter.input.target_address() @@ -242,6 +269,16 @@ pub fn call<const KIND: u8, IT: ITy, H: Host + ?Sized>(mut context: Ictx<'_, H, }; let is_static = context.interpreter.runtime_flag.is_static() || KIND == STATICCALL; + let kind = match KIND { + CALL => FrameStartKind::Call, + CALLCODE => FrameStartKind::CallCode, + DELEGATECALL => FrameStartKind::DelegateCall, + _ => FrameStartKind::StaticCall, + }; + let transferred = value.transfer().unwrap_or_default(); + let start = FrameStart::new(kind, caller, Some(target_address), transferred, forward); + let reservoir = frame_starting(&mut context.interpreter.gas, context.host, start)?; + // Call host to interact with target contract context .interpreter @@ -258,7 +295,7 @@ pub fn call<const KIND: u8, IT: ITy, H: Host + ?Sized>(mut context: Ictx<'_, H, scheme, is_static, return_memory_offset, - reservoir: context.interpreter.gas.reservoir(), + reservoir, charged_new_account_state_gas, }, )))); diff --git a/crates/interpreter/src/instructions/contract/call_helpers.rs b/crates/interpreter/src/instructions/contract/call_helpers.rs index 0e38e2759b..5e7c6d8744 100644 --- a/crates/interpreter/src/instructions/contract/call_helpers.rs +++ b/crates/interpreter/src/instructions/contract/call_helpers.rs @@ -62,7 +62,7 @@ pub fn resize_memory( /// (transfers value into a previously-empty account). Callers should propagate /// it onto `CallInputs` so the parent can refund the charge if the resulting /// frame reverts/halts. -#[inline(never)] +#[inline] pub fn load_acc_and_calc_gas<H: Host + ?Sized>( context: &mut Ictx<'_, H, impl ITy>, to: Address, @@ -70,6 +70,30 @@ pub fn load_acc_and_calc_gas<H: Host + ?Sized>( create_empty_account: bool, stack_gas_limit: u64, ) -> Result<(u64, Bytecode, B256, bool), InstructionResult> { + load_acc_and_calc_forward( + context, + to, + transfers_value, + create_empty_account, + stack_gas_limit, + ) + .map(|(gas_limit, bytecode, code_hash, charged, _)| (gas_limit, bytecode, code_hash, charged)) +} + +/// [`load_acc_and_calc_gas`], also returning the forward, the gas taken from the caller for the +/// frame, which is the frame's gas limit without a value call's stipend. +/// +/// Returns `(gas_limit, bytecode, code_hash, charged_new_account_state_gas, forward)`. The forward +/// comes last, after the fields [`load_acc_and_calc_gas`] returns: placed second, it changed how +/// the others are stored and cost two more instructions per call. +#[inline(never)] +pub(super) fn load_acc_and_calc_forward<H: Host + ?Sized>( + context: &mut Ictx<'_, H, impl ITy>, + to: Address, + transfers_value: bool, + create_empty_account: bool, + stack_gas_limit: u64, +) -> Result<(u64, Bytecode, B256, bool, u64), InstructionResult> { // Transfer value cost if transfers_value { gas!( @@ -82,13 +106,19 @@ pub fn load_acc_and_calc_gas<H: Host + ?Sized>( let (gas, state_gas_cost, bytecode, code_hash) = load_account_delegated_handle_error(context, to, transfers_value, create_empty_account)?; let charged_new_account_state_gas = state_gas_cost > 0; - let interpreter = &mut context.interpreter; // deduct dynamic gas. - gas!(interpreter, gas); + gas!(context.interpreter, gas); - // deduct state gas (EIP-8037) if any. - state_gas!(interpreter, state_gas_cost); + // deduct state gas (EIP-8037) if any, its legacy share first from regular gas, before the + // forward is computed. + if charged_new_account_state_gas { + let legacy_share = context + .host + .gas_params() + .new_account_state_gas_legacy_share(); + state_gas_with_legacy_share!(context.interpreter, state_gas_cost, legacy_share); + } let interpreter = &mut context.interpreter; let host = &mut context.host; @@ -109,6 +139,8 @@ pub fn load_acc_and_calc_gas<H: Host + ?Sized>( return Err(InstructionResult::OutOfGas); } + let forward = gas_limit; + // Add call stipend if there is value to be transferred. if transfers_value { gas_limit = gas_limit.saturating_add(host.gas_params().call_stipend()); @@ -119,6 +151,7 @@ pub fn load_acc_and_calc_gas<H: Host + ?Sized>( bytecode, code_hash, charged_new_account_state_gas, + forward, )) } diff --git a/crates/interpreter/src/instructions/host.rs b/crates/interpreter/src/instructions/host.rs index e0b52ec219..532822fa01 100644 --- a/crates/interpreter/src/instructions/host.rs +++ b/crates/interpreter/src/instructions/host.rs @@ -1,11 +1,14 @@ use crate::{ - instructions::utility::{IntoAddress, IntoU256}, + instructions::{ + instruction_hooks::{running_account, write_completed}, + utility::{IntoAddress, IntoU256}, + }, interpreter_types::{InputsTr, InterpreterTypes as ITy, MemoryTr, RuntimeFlag, StackTr}, Gas, Host, InstructionExecResult as Result, InstructionResult, }; use context_interface::{ cfg::{GasId, StateGasCharge, StateGasSite}, - host::LoadError, + host::{CompletedWrite, LoadError}, journaled_state::AccountInfoLoad, }; use core::cmp::min; @@ -256,7 +259,11 @@ pub fn sstore<IT: ITy, H: Host + ?Sized>(context: Ictx<'_, H, IT>) -> Result { .state_gas_charge(charge) .ok_or(InstructionResult::FatalExternalError)?; if charges_state_gas { - state_gas!(context.interpreter, price); + let share = context + .host + .gas_params() + .sstore_set_state_gas_legacy_share(); + state_gas_with_legacy_share!(context.interpreter, price, share); } // EIP-8037 issue #2: 0→x→0 storage restoration refills the reservoir // directly rather than routing the state gas through the capped refund @@ -275,7 +282,12 @@ pub fn sstore<IT: ITy, H: Host + ?Sized>(context: Ictx<'_, H, IT>) -> Result { .gas_params() .sstore_refund(is_istanbul, &state_load.data), ); - Ok(()) + let write = CompletedWrite::Sstore { + address: target, + key: index, + result: &state_load.data, + }; + write_completed(context.interpreter, context.host, write) } /// EIP-1153: Transient storage opcodes @@ -336,7 +348,12 @@ pub fn log<const N: usize, H: Host + ?Sized>(context: Ictx<'_, H, impl ITy>) -> }; context.host.log(log); - Ok(()) + let write = CompletedWrite::Log { + address: context.interpreter.input.target_address(), + topics: N as u8, + data_len: len as u64, + }; + write_completed(context.interpreter, context.host, write) } /// Implements the SELFDESTRUCT instruction. @@ -351,6 +368,8 @@ pub fn selfdestruct<IT: ITy, H: Host + ?Sized>(context: Ictx<'_, H, IT>) -> Resu let cold_load_gas = context.host.gas_params().selfdestruct_cold_cost(); let skip_cold_load = context.interpreter.gas.remaining() < cold_load_gas; + // The account's balance before the write, for the completed-write hook. + let (balance, _) = running_account(context.host, context.interpreter.input.target_address())?; let res = context.host.selfdestruct( context.interpreter.input.target_address(), target, @@ -382,7 +401,11 @@ pub fn selfdestruct<IT: ITy, H: Host + ?Sized>(context: Ictx<'_, H, IT>) -> Resu .host .state_gas_charge(charge) .ok_or(InstructionResult::FatalExternalError)?; - state_gas!(context.interpreter, price); + let share = context + .host + .gas_params() + .selfdestruct_new_account_state_gas_legacy_share(); + state_gas_with_legacy_share!(context.interpreter, price, share); } if !res.previously_destroyed { @@ -392,5 +415,12 @@ pub fn selfdestruct<IT: ITy, H: Host + ?Sized>(context: Ictx<'_, H, IT>) -> Resu .record_refund(context.host.gas_params().selfdestruct_refund()); } + let write = CompletedWrite::SelfDestruct { + address: context.interpreter.input.target_address(), + target, + balance, + result: &res.data, + }; + write_completed(context.interpreter, context.host, write)?; Err(InstructionResult::SelfDestruct) } diff --git a/crates/interpreter/src/instructions/instruction_hooks.rs b/crates/interpreter/src/instructions/instruction_hooks.rs new file mode 100644 index 0000000000..e292b652ef --- /dev/null +++ b/crates/interpreter/src/instructions/instruction_hooks.rs @@ -0,0 +1,94 @@ +//! The instructions' side of the [`Host`] instruction hooks: what an instruction does with the +//! answer of [`Host::write_completed`] and [`Host::frame_starting`]. + +use crate::{ + interpreter_types::{InterpreterTypes as ITy, LoopControl}, + CreateInputs, Gas, Host, InstructionExecResult as Result, InstructionResult, Interpreter, + InterpreterAction, +}; +use context_interface::host::{CompletedWrite, FrameStart, WriteVerdict}; +use primitives::{constants::CALL_STACK_LIMIT, hints_util::cold_path, Address, Bytes, U256}; + +/// Hands `write`, which the running instruction completed after its last charge, to +/// [`Host::write_completed`] with the frame's gas, and applies the verdict: the instruction goes +/// on, fails out of gas, or ends the frame as a `Revert` with the verdict's output on the gas as +/// the hook left it. +#[inline] +pub(crate) fn write_completed<IT: ITy, H: Host + ?Sized>( + interpreter: &mut Interpreter<IT>, + host: &mut H, + write: CompletedWrite<'_>, +) -> Result { + match host.write_completed(write, interpreter.gas.tracker_mut()) { + WriteVerdict::Continue => Ok(()), + WriteVerdict::OutOfGas => { + cold_path(); + Err(InstructionResult::OutOfGas) + } + WriteVerdict::Revert(output) => revert(interpreter, output), + } +} + +/// Ends the frame as a `Revert` with `output`, as `REVERT` does. +#[cold] +#[inline(never)] +fn revert<IT: ITy>(interpreter: &mut Interpreter<IT>, output: Bytes) -> Result { + interpreter + .bytecode + .set_action(InterpreterAction::new_return( + InstructionResult::Revert, + output, + interpreter.gas, + )); + Err(InstructionResult::Revert) +} + +/// Hands `start`, whose forward the running instruction has taken from `gas`, to +/// [`Host::frame_starting`]. `true` returns the reservoir the frame's input carries: the child's +/// reservoir if the hook took it itself and named it on `start`, or else a copy of the reservoir +/// the hook left in `gas`. `false` fails the instruction out of gas. +#[inline] +pub(crate) fn frame_starting<H: Host + ?Sized>( + gas: &mut Gas, + host: &mut H, + mut start: FrameStart, +) -> core::result::Result<u64, InstructionResult> { + if host.frame_starting(&mut start, gas.tracker_mut()) { + Ok(start.reservoir.unwrap_or(gas.reservoir())) + } else { + cold_path(); + Err(InstructionResult::OutOfGas) + } +} + +/// Computes the address the creation `inputs` takes into their cache, for the frame-start hook, +/// when EIP-8037 is off; with it on, the creation instruction's EIP-8037 branch computes it. It does +/// so after the checks that branch makes, so a creation the handler fails before it takes an +/// address gets none: an endowment above the caller's balance, a caller's nonce at its maximum, or +/// a creating frame (at `depth`) at the depth limit. The handler builds the frame from the cache, +/// so the address and a `CREATE2`'s init-code hash are computed once. +#[inline] +pub(crate) fn cache_created_address<H: Host + ?Sized>( + host: &mut H, + inputs: &CreateInputs, + depth: usize, +) -> Result { + let (balance, nonce) = running_account(host, inputs.caller())?; + if balance >= inputs.value() && nonce != u64::MAX && depth < CALL_STACK_LIMIT as usize { + inputs.created_address(nonce); + } + Ok(()) +} + +/// The balance and nonce of `address`, the running frame's own account, for a hook's facts. The +/// journal holds that account warm, so reading it loads nothing cold. +#[inline] +pub(crate) fn running_account<H: Host + ?Sized>( + host: &mut H, + address: Address, +) -> core::result::Result<(U256, u64), InstructionResult> { + let account = host + .load_account_info_skip_cold_load(address, false, false)? + .account; + Ok((account.balance, account.nonce)) +} diff --git a/crates/interpreter/src/instructions/macros.rs b/crates/interpreter/src/instructions/macros.rs index a5f5503141..96ce92adc1 100644 --- a/crates/interpreter/src/instructions/macros.rs +++ b/crates/interpreter/src/instructions/macros.rs @@ -41,6 +41,23 @@ macro_rules! state_gas { }}; } +/// Records a state gas cost (EIP-8037) that takes its legacy share, `min(gas, share)`, from +/// regular gas before it draws the reservoir, and fails the instruction if the frame's regular gas +/// cannot pay the share and what the reservoir cannot. A share of zero is [`state_gas!`]. +#[macro_export] +#[collapse_debuginfo(yes)] +macro_rules! state_gas_with_legacy_share { + ($interpreter:expr, $gas:expr, $share:expr) => {{ + if !$interpreter + .gas + .record_state_cost_with_legacy_share($gas, $share) + { + $crate::primitives::hints_util::cold_path(); + return Err($crate::InstructionResult::OutOfGas); + } + }}; +} + /// Records a `gas` cost and fails the instruction if it would exceed the available gas. #[macro_export] #[collapse_debuginfo(yes)] diff --git a/crates/interpreter/src/interpreter.rs b/crates/interpreter/src/interpreter.rs index 370593d38a..9ed5931406 100644 --- a/crates/interpreter/src/interpreter.rs +++ b/crates/interpreter/src/interpreter.rs @@ -323,6 +323,9 @@ impl<IW: InterpreterTypes> Interpreter<IW> { } /// Executes the interpreter until it returns or stops. + /// + /// An action set before the run ([`LoopControl::set_action`]) is returned before any + /// instruction runs. #[inline] pub fn run_plain<H: Host + ?Sized>( &mut self, @@ -330,6 +333,10 @@ impl<IW: InterpreterTypes> Interpreter<IW> { gas_table: &GasTable, host: &mut H, ) -> InterpreterAction { + if self.bytecode.is_end() { + cold_path(); + return self.take_next_action(); + } let e = loop { if let Err(e) = self.step(instruction_table, gas_table, host) { cold_path(); diff --git a/crates/interpreter/src/interpreter_action/call_outcome.rs b/crates/interpreter/src/interpreter_action/call_outcome.rs index 3d55a79b30..bcd70dfea8 100644 --- a/crates/interpreter/src/interpreter_action/call_outcome.rs +++ b/crates/interpreter/src/interpreter_action/call_outcome.rs @@ -1,4 +1,4 @@ -use crate::{Gas, InstructionResult, InterpreterResult}; +use crate::{Gas, InstructionResult, InterpreterResult, OutcomeMark}; use core::ops::Range; use primitives::{Address, Bytes, Log}; use std::vec::Vec; @@ -12,7 +12,7 @@ use std::vec::Vec; /// /// * `result` - The result of the interpreter's execution, including output data and gas usage. /// * `memory_offset` - The range in memory where the output data is located. -#[derive(Clone, Debug, PartialEq, Eq)] +#[derive(Clone, PartialEq, Eq)] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub struct CallOutcome { /// The result of the interpreter's execution, including output data and gas usage @@ -36,9 +36,34 @@ pub struct CallOutcome { /// was taken even when the price varies per account. Meaningless while /// `charged_new_account_state_gas` is `false`. /// - /// Encodings made before this field existed decode it as [`Address::ZERO`]. + /// In a format that carries field names, such as JSON, encodings made before this field existed + /// decode it as [`Address::ZERO`]. #[cfg_attr(feature = "serde", serde(default))] pub charged_state_gas_address: Address, + /// The start revm marked this outcome for before an inspector's end callbacks + /// ([`OutcomeMark`]): none on an outcome a constructor builds. No part of the outcome's value: + /// equality, the debug output and the encoding leave it out, and a decoded outcome carries + /// none. + #[cfg_attr(feature = "serde", serde(skip))] + pub start_mark: OutcomeMark, +} + +impl core::fmt::Debug for CallOutcome { + /// The output the derive gives the outcome's other fields, in their order; the mark is left + /// out. + fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { + f.debug_struct("CallOutcome") + .field("result", &self.result) + .field("memory_offset", &self.memory_offset) + .field("was_precompile_called", &self.was_precompile_called) + .field("precompile_call_logs", &self.precompile_call_logs) + .field( + "charged_new_account_state_gas", + &self.charged_new_account_state_gas, + ) + .field("charged_state_gas_address", &self.charged_state_gas_address) + .finish() + } } impl CallOutcome { @@ -58,6 +83,7 @@ impl CallOutcome { precompile_call_logs: Vec::new(), charged_new_account_state_gas: false, charged_state_gas_address: Address::ZERO, + start_mark: OutcomeMark::NONE, } } diff --git a/crates/interpreter/src/interpreter_action/create_inputs.rs b/crates/interpreter/src/interpreter_action/create_inputs.rs index 6f1ef6217e..87135cbf11 100644 --- a/crates/interpreter/src/interpreter_action/create_inputs.rs +++ b/crates/interpreter/src/interpreter_action/create_inputs.rs @@ -26,7 +26,8 @@ pub struct CreateInputs { /// EIP-8037: the account `charged_create_state_gas` was priced for, so the refund re-prices /// the same address. Meaningless while `charged_create_state_gas` is `false`. /// - /// Encodings made before this field existed decode it as [`Address::ZERO`]. + /// In a format that carries field names, such as JSON, encodings made before this field existed + /// decode it as [`Address::ZERO`]. #[cfg_attr(feature = "serde", serde(default))] charged_state_gas_address: Address, /// Cached created address. This is computed lazily and cached to avoid @@ -77,6 +78,12 @@ impl CreateInputs { }) } + /// The created address, if [`created_address`](Self::created_address) has computed it since + /// the caller, the scheme or the init code last changed. + pub(crate) fn cached_created_address(&self) -> Option<Address> { + self.cached_address.get().copied() + } + /// Returns the keccak256 hash of the init code. /// /// The result is cached so that `created_address()` and frame initialization diff --git a/crates/interpreter/src/interpreter_action/create_outcome.rs b/crates/interpreter/src/interpreter_action/create_outcome.rs index 50b0db729f..0207596a2e 100644 --- a/crates/interpreter/src/interpreter_action/create_outcome.rs +++ b/crates/interpreter/src/interpreter_action/create_outcome.rs @@ -1,4 +1,4 @@ -use crate::{Gas, InstructionResult, InterpreterResult}; +use crate::{Gas, InstructionResult, InterpreterResult, OutcomeMark}; use primitives::{Address, Bytes}; /// Represents the outcome of a create operation in an interpreter. @@ -6,7 +6,7 @@ use primitives::{Address, Bytes}; /// This struct holds the result of the operation along with an optional address. /// /// It provides methods to determine the next action based on the result of the operation. -#[derive(Debug, Clone, PartialEq, Eq)] +#[derive(Clone, PartialEq, Eq)] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub struct CreateOutcome { /// The result of the interpreter operation @@ -23,9 +23,29 @@ pub struct CreateOutcome { /// was taken even when the price varies per account. Meaningless while /// `charged_create_state_gas` is `false`. /// - /// Encodings made before this field existed decode it as [`Address::ZERO`]. + /// In a format that carries field names, such as JSON, encodings made before this field existed + /// decode it as [`Address::ZERO`]. #[cfg_attr(feature = "serde", serde(default))] pub charged_state_gas_address: Address, + /// The start revm marked this outcome for before an inspector's end callbacks + /// ([`OutcomeMark`]): none on an outcome a constructor builds. No part of the outcome's value: + /// equality, the debug output and the encoding leave it out, and a decoded outcome carries + /// none. + #[cfg_attr(feature = "serde", serde(skip))] + pub start_mark: OutcomeMark, +} + +impl core::fmt::Debug for CreateOutcome { + /// The output the derive gives the outcome's other fields, in their order; the mark is left + /// out. + fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { + f.debug_struct("CreateOutcome") + .field("result", &self.result) + .field("address", &self.address) + .field("charged_create_state_gas", &self.charged_create_state_gas) + .field("charged_state_gas_address", &self.charged_state_gas_address) + .finish() + } } impl CreateOutcome { @@ -45,6 +65,7 @@ impl CreateOutcome { address, charged_create_state_gas: false, charged_state_gas_address: Address::ZERO, + start_mark: OutcomeMark::NONE, } } diff --git a/crates/interpreter/src/lib.rs b/crates/interpreter/src/lib.rs index b0063510fa..252155a256 100644 --- a/crates/interpreter/src/lib.rs +++ b/crates/interpreter/src/lib.rs @@ -36,7 +36,7 @@ pub use context_interface::{ context::{SStoreResult, SelfDestructResult, StateLoad}, host, CreateScheme, Host, }; -pub use gas::{Gas, GasTracker}; +pub use gas::{Gas, GasTracker, OutcomeMark, StartMark}; pub use instruction_context::InstructionContext; pub use instruction_result::*; pub use instructions::{ diff --git a/crates/interpreter/tests/charged_state_gas_address_serde.rs b/crates/interpreter/tests/charged_state_gas_address_serde.rs index fc098fd247..0d3f88c14e 100644 --- a/crates/interpreter/tests/charged_state_gas_address_serde.rs +++ b/crates/interpreter/tests/charged_state_gas_address_serde.rs @@ -1,7 +1,10 @@ //! Serde encoding of `charged_state_gas_address` on the frame inputs and outcomes. //! -//! New encodings carry the field. Encodings made before it existed lack it and still decode, to -//! [`Address::ZERO`], which is what a frame without a charge carries. +//! New encodings carry the field. In a format that carries field names, such as the JSON these +//! tests use, encodings made before it existed lack it and still decode, to [`Address::ZERO`], +//! which is what a frame without a charge carries. A format that encodes a struct by position, +//! such as bincode, cannot read an encoding made before it existed, as with upstream's own field +//! additions. #![cfg(feature = "serde")] use core::fmt::Debug; @@ -50,7 +53,7 @@ const fn interpreter_result() -> InterpreterResult { } #[test] -fn test_create_inputs_decode_with_and_without_the_charged_address() { +fn test_create_inputs_decode_from_json_with_and_without_the_charged_address() { let inputs = |charged_address| { let mut inputs = CreateInputs::new( address!("0x00000000000000000000000000000000000c0de0"), @@ -71,7 +74,7 @@ fn test_create_inputs_decode_with_and_without_the_charged_address() { } #[test] -fn test_call_outcome_decodes_with_and_without_the_charged_address() { +fn test_call_outcome_decodes_from_json_with_and_without_the_charged_address() { let outcome = |charged_address| { let mut outcome = CallOutcome::new(interpreter_result(), 0..8); outcome.charged_new_account_state_gas = true; @@ -83,7 +86,7 @@ fn test_call_outcome_decodes_with_and_without_the_charged_address() { } #[test] -fn test_create_outcome_decodes_with_and_without_the_charged_address() { +fn test_create_outcome_decodes_from_json_with_and_without_the_charged_address() { let outcome = |charged_address| { let created = address!("0x000000000000000000000000000000000000c4ea"); let mut outcome = CreateOutcome::new(interpreter_result(), Some(created)); diff --git a/crates/interpreter/tests/history_gas_serde.rs b/crates/interpreter/tests/history_gas_serde.rs index e120052867..44db2f1b0e 100644 --- a/crates/interpreter/tests/history_gas_serde.rs +++ b/crates/interpreter/tests/history_gas_serde.rs @@ -1,7 +1,10 @@ //! Serde encoding of the history gas counter on [`GasTracker`], and so on [`Gas`]. //! -//! New encodings carry the counter. Encodings made before it existed lack it and still decode, to -//! zero, which is what a tracker that never charged history gas carries. +//! New encodings carry the counter. In a format that carries field names, such as the JSON these +//! tests use, encodings made before it existed lack it and still decode, to zero, which is what a +//! tracker that never charged history gas carries. A format that encodes a struct by position, +//! such as bincode, cannot read an encoding made before it existed, as with upstream's own field +//! additions. #![cfg(feature = "serde")] use revm_interpreter::{Gas, GasTracker}; @@ -34,7 +37,7 @@ fn remove_field(tracker: &mut Value) -> Option<Value> { } #[test] -fn test_gas_tracker_decodes_with_and_without_the_history_counter() { +fn test_gas_tracker_decodes_from_json_with_and_without_the_history_counter() { let tracker = charged_tracker(); let mut encoded = serde_json::to_value(tracker).unwrap(); assert_eq!( @@ -50,7 +53,7 @@ fn test_gas_tracker_decodes_with_and_without_the_history_counter() { } #[test] -fn test_gas_decodes_with_and_without_the_history_counter() { +fn test_gas_decodes_from_json_with_and_without_the_history_counter() { let mut gas = Gas::new_with_regular_gas_and_reservoir(100_000, 20_000); assert!(gas.record_history_cost(CHARGED)); let mut encoded = serde_json::to_value(gas).unwrap(); diff --git a/crates/interpreter/tests/instruction_hooks.rs b/crates/interpreter/tests/instruction_hooks.rs new file mode 100644 index 0000000000..d633bb537c --- /dev/null +++ b/crates/interpreter/tests/instruction_hooks.rs @@ -0,0 +1,1314 @@ +//! The instruction hooks, at the instructions that call them. +//! +//! `SSTORE`, `LOG0`–`LOG4` and `SELFDESTRUCT` hand the write they completed to +//! [`Host::write_completed`] after their last charge, and apply its verdict. The call and creation +//! instructions hand the frame they are about to start to [`Host::frame_starting`] once the forward +//! is taken and before the frame's input is built. Each test runs one frame on [`HookHost`], which +//! records every hook call with the gas the hook was handed, charges history gas on that gas if +//! told to, and answers as the test tells it. + +use bytecode::{opcode::*, Bytecode}; +use context_interface::{ + cfg::{GasId, GasParams, StateGasSite}, + context::{SStoreResult, SelfDestructResult, StateLoad}, + host::{CompletedWrite, FrameStart, FrameStartKind, LoadError, WriteVerdict}, + journaled_state::AccountInfoLoad, +}; +use primitives::{ + address, constants::CALL_STACK_LIMIT, hardfork::SpecId, Address, Bytes, Log, StorageKey, + StorageValue, B256, KECCAK_EMPTY, U256, +}; +use revm_interpreter::{ + host::DummyHost, + instruction_table, + instructions::gas_table_spec, + interpreter::{EthInterpreter, ExtBytecode}, + FrameInput, Gas, GasTracker, Host, InputsImpl, InstructionResult, Interpreter, + InterpreterAction, SharedMemory, +}; +use state::AccountInfo; +use std::borrow::Cow; + +/// The account the frame runs as. +const CONTRACT: Address = address!("0x000000000000000000000000000000000000c0de"); +/// The frame's caller. +const CALLER: Address = address!("0x00000000000000000000000000000000000ca11e"); +/// The account a call or `SELFDESTRUCT` names. +const TARGET: Address = address!("0x0000000000000000000000000000000000007a59"); +/// The value the frame was called with, which `DELEGATECALL` passes on without transferring it. +const APPARENT_VALUE: u64 = 7; +/// Gas enough for every frame here. +const AMPLE: u64 = 1_000_000; +/// What a reverting hook returns. +const STOP_OUTPUT: &[u8] = b"stop"; + +/// A write the hook saw, owned. +#[derive(Clone, Debug, PartialEq, Eq)] +enum Write { + Sstore(Address, StorageKey, SStoreResult), + Log(Address, u8, u64), + SelfDestruct(Address, Address, U256, SelfDestructResult), +} + +impl Write { + fn of(write: CompletedWrite<'_>) -> Self { + match write { + CompletedWrite::Sstore { + address, + key, + result, + } => Self::Sstore(address, key, result.clone()), + CompletedWrite::Log { + address, + topics, + data_len, + } => Self::Log(address, topics, data_len), + CompletedWrite::SelfDestruct { + address, + target, + balance, + result, + } => Self::SelfDestruct(address, target, balance, result.clone()), + } + } +} + +/// A [`DummyHost`] whose state answers as configured, and whose hooks record each call with the +/// gas they were handed, charge [`HookHost::charge`] of history gas on it, and answer +/// [`HookHost::verdict`] or [`HookHost::admit`]. +struct HookHost { + dummy: DummyHost, + /// Every account and slot is cold, and a cold load the instruction asks to skip is refused. + cold: bool, + /// Every account is empty. + empty: bool, + /// Every account's balance; `SELFDESTRUCT` moves it out. + balance: U256, + /// Every account's nonce. + nonce: u64, + /// The original and present value of every slot. + slot: StorageValue, + /// What `SELFDESTRUCT` finds. + destruct: SelfDestructResult, + /// Every state-gas price lookup fails. + price_fails: bool, + /// History gas each hook charges on the gas it is handed before it answers. + charge: u64, + verdict: WriteVerdict, + admit: bool, + /// The reservoir the hook leaves the caller when it takes the child's reservoir itself and + /// names it on the start. + kept_reservoir: Option<u64>, + /// Every write the hook saw, with the gas as the hook found it. + writes: Vec<(Write, GasTracker)>, + /// Every start the hook saw, with the gas as the hook found it. + starts: Vec<(FrameStart, GasTracker)>, +} + +impl HookHost { + fn new(spec: SpecId) -> Self { + Self { + dummy: DummyHost::new(spec), + cold: false, + empty: false, + balance: U256::from(AMPLE), + nonce: 0, + slot: StorageValue::ZERO, + destruct: SelfDestructResult::default(), + price_fails: false, + charge: 0, + verdict: WriteVerdict::Continue, + admit: true, + kept_reservoir: None, + writes: Vec::new(), + starts: Vec::new(), + } + } + + const fn cold(mut self) -> Self { + self.cold = true; + self + } + + const fn empty(mut self) -> Self { + self.empty = true; + self + } + + fn with_balance(mut self, balance: u64) -> Self { + self.balance = U256::from(balance); + self + } + + const fn with_nonce(mut self, nonce: u64) -> Self { + self.nonce = nonce; + self + } + + fn holding(mut self, slot: u64) -> Self { + self.slot = StorageValue::from(slot); + self + } + + /// `SELFDESTRUCT` of an account with a balance in favour of an account that does not exist. + const fn destructs_into_a_new_account(mut self) -> Self { + self.destruct = SelfDestructResult { + had_value: true, + target_exists: false, + previously_destroyed: false, + }; + self + } + + const fn price_fails(mut self) -> Self { + self.price_fails = true; + self + } + + const fn charging(mut self, charge: u64) -> Self { + self.charge = charge; + self + } + + fn answering(mut self, verdict: WriteVerdict) -> Self { + self.verdict = verdict; + self + } + + const fn refusing(mut self) -> Self { + self.admit = false; + self + } + + const fn keeping_reservoir(mut self, kept: u64) -> Self { + self.kept_reservoir = Some(kept); + self + } + + const fn refuses_cold(&self, skip_cold_load: bool) -> Result<(), LoadError> { + if self.cold && skip_cold_load { + Err(LoadError::ColdLoadSkipped) + } else { + Ok(()) + } + } + + /// The one write the hook saw. + fn write(&self) -> &(Write, GasTracker) { + assert_eq!(self.writes.len(), 1, "one write: {:?}", self.writes); + &self.writes[0] + } + + /// The one start the hook saw. + fn start(&self) -> &(FrameStart, GasTracker) { + assert_eq!(self.starts.len(), 1, "one start: {:?}", self.starts); + &self.starts[0] + } + + const fn reached(&self) -> bool { + !self.writes.is_empty() || !self.starts.is_empty() + } +} + +impl Host for HookHost { + fn write_completed(&mut self, write: CompletedWrite<'_>, gas: &mut GasTracker) -> WriteVerdict { + self.writes.push((Write::of(write), *gas)); + if self.charge > 0 { + let _ = gas.record_history_cost(self.charge); + } + self.verdict.clone() + } + + fn frame_starting(&mut self, start: &mut FrameStart, gas: &mut GasTracker) -> bool { + self.starts.push((*start, *gas)); + if self.charge > 0 { + let _ = gas.record_history_cost(self.charge); + } + if let Some(kept) = self.kept_reservoir { + start.reservoir = Some(gas.reservoir() - kept); + gas.set_reservoir(kept); + } + self.admit + } + + fn state_gas_price(&mut self, id: GasId, _site: StateGasSite) -> Option<u64> { + (!self.price_fails).then(|| self.gas_params().get(id)) + } + + fn basefee(&self) -> U256 { + self.dummy.basefee() + } + fn blob_gasprice(&self) -> U256 { + self.dummy.blob_gasprice() + } + fn gas_limit(&self) -> U256 { + self.dummy.gas_limit() + } + fn difficulty(&self) -> U256 { + self.dummy.difficulty() + } + fn prevrandao(&self) -> Option<U256> { + self.dummy.prevrandao() + } + fn block_number(&self) -> U256 { + self.dummy.block_number() + } + fn timestamp(&self) -> U256 { + self.dummy.timestamp() + } + fn beneficiary(&self) -> Address { + self.dummy.beneficiary() + } + fn slot_num(&self) -> U256 { + self.dummy.slot_num() + } + fn chain_id(&self) -> U256 { + self.dummy.chain_id() + } + fn effective_gas_price(&self) -> U256 { + self.dummy.effective_gas_price() + } + fn caller(&self) -> Address { + self.dummy.caller() + } + fn blob_hash(&self, number: usize) -> Option<U256> { + self.dummy.blob_hash(number) + } + fn max_initcode_size(&self) -> usize { + usize::MAX + } + fn gas_params(&self) -> &GasParams { + self.dummy.gas_params() + } + fn is_amsterdam_eip8037_enabled(&self) -> bool { + self.dummy.is_amsterdam_eip8037_enabled() + } + fn block_hash(&mut self, number: u64) -> Option<B256> { + self.dummy.block_hash(number) + } + + fn selfdestruct( + &mut self, + _address: Address, + _target: Address, + skip_cold_load: bool, + ) -> Result<StateLoad<SelfDestructResult>, LoadError> { + self.refuses_cold(skip_cold_load)?; + // The write moves the balance out. + self.balance = U256::ZERO; + Ok(StateLoad::new(self.destruct.clone(), self.cold)) + } + + fn log(&mut self, log: Log) { + self.dummy.log(log) + } + + fn sstore_skip_cold_load( + &mut self, + _address: Address, + _key: StorageKey, + value: StorageValue, + skip_cold_load: bool, + ) -> Result<StateLoad<SStoreResult>, LoadError> { + self.refuses_cold(skip_cold_load)?; + let result = SStoreResult { + original_value: self.slot, + present_value: self.slot, + new_value: value, + }; + Ok(StateLoad::new(result, self.cold)) + } + + fn sload_skip_cold_load( + &mut self, + address: Address, + key: StorageKey, + skip_cold_load: bool, + ) -> Result<StateLoad<StorageValue>, LoadError> { + self.dummy + .sload_skip_cold_load(address, key, skip_cold_load) + } + + fn tstore(&mut self, address: Address, key: StorageKey, value: StorageValue) { + self.dummy.tstore(address, key, value) + } + + fn tload(&mut self, address: Address, key: StorageKey) -> StorageValue { + self.dummy.tload(address, key) + } + + fn load_account_info_skip_cold_load( + &mut self, + _address: Address, + _load_code: bool, + skip_cold_load: bool, + ) -> Result<AccountInfoLoad<'_>, LoadError> { + self.refuses_cold(skip_cold_load)?; + Ok(AccountInfoLoad { + account: Cow::Owned(AccountInfo::from_balance(self.balance).with_nonce(self.nonce)), + is_cold: self.cold, + is_empty: self.empty, + }) + } +} + +/// Runs `code` as [`CONTRACT`], called by [`CALLER`] with [`APPARENT_VALUE`], with `gas_limit` +/// regular gas and `reservoir`, and returns what the frame asked for and its gas. +fn run( + spec: SpecId, + code: &[u8], + gas_limit: u64, + reservoir: u64, + host: &mut HookHost, +) -> (InterpreterAction, Gas) { + run_at_depth(spec, code, gas_limit, reservoir, 0, host) +} + +/// [`run`] in a frame at `depth`. +fn run_at_depth( + spec: SpecId, + code: &[u8], + gas_limit: u64, + reservoir: u64, + depth: usize, + host: &mut HookHost, +) -> (InterpreterAction, Gas) { + let mut interpreter = Interpreter::<EthInterpreter>::new( + SharedMemory::new(), + ExtBytecode::new(Bytecode::new_raw(Bytes::copy_from_slice(code))), + InputsImpl { + target_address: CONTRACT, + caller_address: CALLER, + call_value: U256::from(APPARENT_VALUE), + depth, + ..Default::default() + }, + false, + spec, + gas_limit, + ); + interpreter.gas = Gas::new_with_regular_gas_and_reservoir(gas_limit, reservoir); + let table = instruction_table::<EthInterpreter, HookHost>(); + let action = interpreter.run_plain(&table, &gas_table_spec(spec), host); + (action, interpreter.gas) +} + +/// The result a frame returned with, and its result's gas. +fn returned(action: InterpreterAction) -> (InstructionResult, Bytes, Gas) { + match action { + InterpreterAction::Return(result) => (result.result, result.output, result.gas), + other => panic!("expected the frame to return, got {other:?}"), + } +} + +/// The frame a frame asked to start. +fn started(action: InterpreterAction) -> FrameInput { + match action { + InterpreterAction::NewFrame(input) => input, + other => panic!("expected a new frame, got {other:?}"), + } +} + +/// The static gas of `op` on `spec`. +const fn static_gas(spec: SpecId, op: u8) -> u64 { + gas_table_spec(spec)[op as usize] as u64 +} + +/// `SSTORE(0, 1)`, then `STOP`. +const SSTORE_CODE: [u8; 6] = [PUSH1, 1, PUSH1, 0, SSTORE, STOP]; +/// `SSTORE(0, 0)`, then `STOP`. +const CLEAR_CODE: [u8; 6] = [PUSH1, 0, PUSH1, 0, SSTORE, STOP]; +/// What `SSTORE` finds when [`SSTORE_CODE`] sets a slot from zero. +fn set_from_zero() -> SStoreResult { + SStoreResult { + original_value: StorageValue::ZERO, + present_value: StorageValue::ZERO, + new_value: StorageValue::from(1), + } +} + +/// `LOG1` of `len` bytes of memory at offset 0, then `STOP`. +fn log1_code(len: u8) -> Vec<u8> { + vec![PUSH1, 0xaa, PUSH1, len, PUSH1, 0, LOG1, STOP] +} + +/// `SELFDESTRUCT` in favour of [`TARGET`]. +fn selfdestruct_code() -> Vec<u8> { + let mut code = vec![PUSH20]; + code.extend_from_slice(TARGET.as_slice()); + code.push(SELFDESTRUCT); + code +} + +/// `op` (a call) to [`TARGET`] with `gas`, `value` (for `CALL` and `CALLCODE`), `in_len` bytes of +/// input at offset 0 and no output, then `STOP`. +fn call_code(op: u8, gas: u32, value: u8, in_len: u8) -> Vec<u8> { + let mut code = vec![PUSH1, 0, PUSH1, 0, PUSH1, in_len, PUSH1, 0]; + if matches!(op, CALL | CALLCODE) { + code.extend_from_slice(&[PUSH1, value]); + } + code.push(PUSH20); + code.extend_from_slice(TARGET.as_slice()); + code.push(PUSH4); + code.extend_from_slice(&gas.to_be_bytes()); + code.extend_from_slice(&[op, STOP]); + code +} + +/// The gas [`call_code`]'s pushes cost. +const fn call_pushes(op: u8) -> u64 { + if matches!(op, CALL | CALLCODE) { + 7 * 3 + } else { + 6 * 3 + } +} + +/// `op` (`CREATE` or `CREATE2`) of `len` bytes of memory at offset 0, endowed with `value`, then +/// `STOP`. +fn create_code(op: u8, len: u8, value: u8) -> Vec<u8> { + let mut code = Vec::new(); + if op == CREATE2 { + code.extend_from_slice(&[PUSH1, 0x5a]); + } + code.extend_from_slice(&[PUSH1, len, PUSH1, 0, PUSH1, value, op, STOP]); + code +} + +/// The gas [`create_code`]'s pushes cost. +const fn create_pushes(op: u8) -> u64 { + if op == CREATE2 { + 4 * 3 + } else { + 3 * 3 + } +} + +/// A write instruction under test: its name, code, the host it runs on, the write the hook sees, +/// and the result of a frame one gas short of the instruction's last charge. +type WriteCase = ( + &'static str, + Vec<u8>, + fn(SpecId) -> HookHost, + Write, + InstructionResult, +); + +/// The write instructions, each on a host that makes it charge everything it can: a cold slot set +/// from zero, a cold slot cleared, which earns a refund, a log of 32 bytes, and a cold +/// `SELFDESTRUCT` into a new account, which earns a refund before EIP-3529. +fn write_cases() -> Vec<WriteCase> { + let destruct = SelfDestructResult { + had_value: true, + target_exists: false, + previously_destroyed: false, + }; + vec![ + ( + "SSTORE", + SSTORE_CODE.to_vec(), + |spec| HookHost::new(spec).cold(), + Write::Sstore(CONTRACT, StorageKey::ZERO, set_from_zero()), + InstructionResult::OutOfGas, + ), + ( + "SSTORE clearing a slot", + CLEAR_CODE.to_vec(), + |spec| HookHost::new(spec).cold().holding(1), + Write::Sstore( + CONTRACT, + StorageKey::ZERO, + SStoreResult { + original_value: StorageValue::from(1), + present_value: StorageValue::from(1), + new_value: StorageValue::ZERO, + }, + ), + InstructionResult::OutOfGas, + ), + ( + "LOG1", + log1_code(32), + HookHost::new, + Write::Log(CONTRACT, 1, 32), + InstructionResult::MemoryOOG, + ), + ( + "SELFDESTRUCT", + selfdestruct_code(), + |spec| { + HookHost::new(spec) + .cold() + .destructs_into_a_new_account() + .with_balance(5) + }, + Write::SelfDestruct(CONTRACT, TARGET, U256::from(5), destruct), + InstructionResult::OutOfGas, + ), + ] +} + +/// Each write instruction hands its write to the hook after its last charge: the frame ends on the +/// gas the hook was handed, so nothing is charged after it, and a frame one gas short of what the +/// instruction charges before the hook fails without reaching it. On a spec with and without +/// EIP-8037, so the last charge is the state-gas charge where there is one, and on one before +/// EIP-3529, where `SELFDESTRUCT` earns a refund. +#[test] +fn test_a_write_reaches_the_hook_after_every_charge() { + for spec in [SpecId::BERLIN, SpecId::OSAKA, SpecId::AMSTERDAM] { + for (name, code, host, write, short) in write_cases() { + let mut ample = host(spec); + let (action, gas) = run(spec, &code, AMPLE, 0, &mut ample); + let (result, _, result_gas) = returned(action); + let (seen, at_hook) = ample.write().clone(); + assert_eq!(seen, write, "{name} on {spec:?}"); + assert!(result.is_ok(), "{name} on {spec:?}: {result:?}"); + assert_eq!( + *result_gas.tracker(), + at_hook, + "{name} on {spec:?}: nothing is charged after the hook" + ); + assert_eq!(*gas.tracker(), at_hook); + let refunds = name == "SSTORE clearing a slot" + || (name == "SELFDESTRUCT" && !spec.is_enabled_in(SpecId::LONDON)); + assert_eq!( + at_hook.refunded() > 0, + refunds, + "{name} on {spec:?}: the refund is made before the hook" + ); + + // What the instruction charges before the hook reaches it with nothing left; one gas + // less does not reach it. + let needed = AMPLE - at_hook.remaining(); + let mut exact = host(spec); + let (action, _) = run(spec, &code, needed, 0, &mut exact); + assert!(returned(action).0.is_ok(), "{name} on {spec:?}"); + assert_eq!(exact.write().1.remaining(), 0, "{name} on {spec:?}"); + + let mut one_short = host(spec); + let (action, _) = run(spec, &code, needed - 1, 0, &mut one_short); + assert_eq!(returned(action).0, short, "{name} on {spec:?}"); + assert!( + !one_short.reached(), + "{name} on {spec:?}: the hook is not reached" + ); + } + } +} + +/// A failure before the hook: its name, the spec, the code, the host, the gas limit and the result +/// the frame fails with. +type FailureCase<Name> = (Name, SpecId, Vec<u8>, HookHost, u64, InstructionResult); + +/// Every earlier failure of a write instruction, a charge or a check before its last charge, ends +/// the instruction before the hook. +#[test] +fn test_a_write_that_fails_before_its_last_charge_never_reaches_the_hook() { + let osaka = GasParams::new_spec(SpecId::OSAKA); + let amsterdam = GasParams::new_spec(SpecId::AMSTERDAM); + let petersburg = GasParams::new_spec(SpecId::PETERSBURG); + let set = set_from_zero(); + let cases: Vec<FailureCase<&str>> = vec![ + ( + "SSTORE with the stipend left", + SpecId::OSAKA, + SSTORE_CODE.to_vec(), + HookHost::new(SpecId::OSAKA), + 6 + osaka.call_stipend(), + InstructionResult::ReentrancySentryOOG, + ), + ( + "SSTORE's static charge, before EIP-2200's stipend check", + SpecId::PETERSBURG, + SSTORE_CODE.to_vec(), + HookHost::new(SpecId::PETERSBURG), + 6 + petersburg.sstore_static_gas() - 1, + InstructionResult::OutOfGas, + ), + ( + "SSTORE's dynamic charge, before its state-gas charge", + SpecId::AMSTERDAM, + SSTORE_CODE.to_vec(), + HookHost::new(SpecId::AMSTERDAM).cold(), + 6 + amsterdam.sstore_static_gas() + amsterdam.sstore_dynamic_gas(true, &set, true) - 1, + InstructionResult::OutOfGas, + ), + ( + "SSTORE's state-gas price", + SpecId::AMSTERDAM, + SSTORE_CODE.to_vec(), + HookHost::new(SpecId::AMSTERDAM).price_fails(), + AMPLE, + InstructionResult::FatalExternalError, + ), + ( + "LOG1's log charge, before its memory", + SpecId::OSAKA, + log1_code(32), + HookHost::new(SpecId::OSAKA), + 9 + static_gas(SpecId::OSAKA, LOG1) + osaka.log_cost(1, 32) - 1, + InstructionResult::OutOfGas, + ), + ( + "SELFDESTRUCT's cold target, refused", + SpecId::OSAKA, + selfdestruct_code(), + HookHost::new(SpecId::OSAKA).cold(), + 3 + static_gas(SpecId::OSAKA, SELFDESTRUCT) + osaka.selfdestruct_cold_cost() - 1, + InstructionResult::OutOfGas, + ), + ( + "SELFDESTRUCT's charge, before its state-gas charge", + SpecId::AMSTERDAM, + selfdestruct_code(), + HookHost::new(SpecId::AMSTERDAM) + .cold() + .destructs_into_a_new_account(), + 3 + static_gas(SpecId::AMSTERDAM, SELFDESTRUCT) + + amsterdam.selfdestruct_cost(true, true) + - 1, + InstructionResult::OutOfGas, + ), + ( + "SELFDESTRUCT's state-gas price", + SpecId::AMSTERDAM, + selfdestruct_code(), + HookHost::new(SpecId::AMSTERDAM) + .destructs_into_a_new_account() + .price_fails(), + AMPLE, + InstructionResult::FatalExternalError, + ), + ]; + for (name, spec, code, mut host, gas_limit, expected) in cases { + let (action, _) = run(spec, &code, gas_limit, 0, &mut host); + assert_eq!(returned(action).0, expected, "{name}"); + assert!(!host.reached(), "{name}: the hook is not reached"); + } +} + +/// `OutOfGas` fails the instruction as a failed charge does: the frame halts out of gas, and the +/// record of what it had left is what the hook left. +/// +/// The verdict tests run on Osaka, where the write instructions charge no state gas, so the hook +/// finds the frame's reservoir of 1,000 whole: a hook charge of 1,500 spills 500 into regular gas. +#[test] +fn test_out_of_gas_fails_the_write_on_the_gas_the_hook_left() { + for (name, code, host, _, _) in write_cases() { + let mut host = host(SpecId::OSAKA) + .charging(1_500) + .answering(WriteVerdict::OutOfGas); + let (action, _) = run(SpecId::OSAKA, &code, AMPLE, 1_000, &mut host); + let (result, _, gas) = returned(action); + let at_hook = host.write().1; + + assert_eq!(result, InstructionResult::OutOfGas, "{name}"); + assert_eq!(gas.remaining(), 0, "{name}: the halt spends all"); + assert_eq!( + gas.failed_charge_remaining(), + Some(at_hook.remaining() - 500), + "{name}: the record is what the hook left" + ); + } +} + +/// A hook's own failed charge is the record the halt keeps. +#[test] +fn test_out_of_gas_after_a_failed_hook_charge_keeps_its_record() { + let mut host = HookHost::new(SpecId::OSAKA) + .charging(AMPLE) + .answering(WriteVerdict::OutOfGas); + let (action, _) = run(SpecId::OSAKA, &log1_code(32), AMPLE, 0, &mut host); + let (result, _, gas) = returned(action); + + assert_eq!(result, InstructionResult::OutOfGas); + assert_eq!( + gas.failed_charge_remaining(), + Some(host.write().1.remaining()) + ); +} + +/// `Revert` ends the frame as a `Revert` with the verdict's output, on the gas the hook left: a +/// `SELFDESTRUCT` so reverted returns `Revert`, not `SelfDestruct`. +#[test] +fn test_revert_ends_the_frame_with_the_output_on_the_gas_the_hook_left() { + for (name, code, host, _, _) in write_cases() { + let mut host = host(SpecId::OSAKA) + .charging(400) + .answering(WriteVerdict::Revert(Bytes::from_static(STOP_OUTPUT))); + let (action, _) = run(SpecId::OSAKA, &code, AMPLE, 1_000, &mut host); + let (result, output, gas) = returned(action); + let mut expected = host.write().1; + assert!(expected.record_history_cost(400)); + + assert_eq!(result, InstructionResult::Revert, "{name}"); + assert_eq!(output, Bytes::from_static(STOP_OUTPUT), "{name}"); + assert_eq!(*gas.tracker(), expected, "{name}"); + assert_eq!(gas.reservoir(), 600, "{name}: the hook's charge stands"); + } +} + +/// `Continue` ends the instruction as it would have ended, on the gas the hook left: a +/// `SELFDESTRUCT` self-destructs. +#[test] +fn test_continue_ends_the_write_on_the_gas_the_hook_left() { + for ((name, code, host, _, _), ends) in write_cases().into_iter().zip([ + InstructionResult::Stop, + InstructionResult::Stop, + InstructionResult::Stop, + InstructionResult::SelfDestruct, + ]) { + let mut host = host(SpecId::OSAKA).charging(1_500); + let (action, _) = run(SpecId::OSAKA, &code, AMPLE, 1_000, &mut host); + let (result, _, gas) = returned(action); + let at_hook = host.write().1; + + assert_eq!(result, ends, "{name}"); + assert_eq!(gas.reservoir(), 0, "{name}"); + assert_eq!(gas.remaining(), at_hook.remaining() - 500, "{name}"); + assert_eq!(gas.history_gas_spent(), 1_500, "{name}"); + } +} + +/// The six frame-starting instructions, each with what the hook sees of it: kind, caller, target +/// and value. +fn start_cases() -> Vec<(&'static str, Vec<u8>, FrameStart)> { + let value = U256::from(3); + let start = |kind, caller, target, value| FrameStart::new(kind, caller, target, value, 0); + vec![ + ( + "CALL", + call_code(CALL, 50_000, 3, 0), + start(FrameStartKind::Call, CONTRACT, Some(TARGET), value), + ), + ( + "CALLCODE", + call_code(CALLCODE, 50_000, 3, 0), + start(FrameStartKind::CallCode, CONTRACT, Some(CONTRACT), value), + ), + ( + "DELEGATECALL", + call_code(DELEGATECALL, 50_000, 0, 0), + start( + FrameStartKind::DelegateCall, + CALLER, + Some(CONTRACT), + U256::ZERO, + ), + ), + ( + "STATICCALL", + call_code(STATICCALL, 50_000, 0, 0), + start( + FrameStartKind::StaticCall, + CONTRACT, + Some(TARGET), + U256::ZERO, + ), + ), + ( + "CREATE", + create_code(CREATE, 0, 3), + start( + FrameStartKind::Create, + CONTRACT, + Some(created(CREATE)), + value, + ), + ), + ( + "CREATE2", + create_code(CREATE2, 0, 3), + start( + FrameStartKind::Create2, + CONTRACT, + Some(created(CREATE2)), + value, + ), + ), + ] +} + +/// The address [`create_code`]`(op, 0, _)` creates at, [`CONTRACT`]'s nonce being `0`: `CREATE` +/// from the nonce, `CREATE2` from its salt `0x5a` and the hash of no init code. +fn created(op: u8) -> Address { + if op == CREATE2 { + CONTRACT.create2(B256::from(U256::from(0x5a)), KECCAK_EMPTY) + } else { + CONTRACT.create(0) + } +} + +/// The gas limit and reservoir of a frame's input. +fn input_gas(input: &FrameInput) -> (u64, u64) { + match input { + FrameInput::Call(inputs) => (inputs.gas_limit, inputs.reservoir), + FrameInput::Create(inputs) => (inputs.gas_limit(), inputs.reservoir()), + FrameInput::Empty => panic!("an empty frame input"), + } +} + +/// Each frame-starting instruction hands its start to the hook once the forward is taken, and +/// charges nothing after it: the instruction leaves the gas the hook was handed, its reservoir +/// included, which the frame's input copies, and the frame's input carries the forward, with a +/// value call's stipend on top. +#[test] +fn test_a_start_reaches_the_hook_with_the_forward_taken() { + let spec = SpecId::OSAKA; + let params = GasParams::new_spec(spec); + for (name, code, expected) in start_cases() { + let mut host = HookHost::new(spec); + let (action, gas) = run(spec, &code, AMPLE, 0, &mut host); + let input = started(action); + let (start, at_hook) = *host.start(); + let (gas_limit, reservoir) = input_gas(&input); + let op = code[code.len() - 2]; + let charged = if matches!(op, CREATE | CREATE2) { + create_pushes(op) + params.create_cost() + } else { + let transfer = if start.value.is_zero() { + 0 + } else { + params.transfer_value_cost() + }; + call_pushes(op) + static_gas(spec, op) + transfer + }; + let before_forward = AMPLE - charged; + let forward = if matches!(op, CREATE | CREATE2) { + before_forward - before_forward / 64 + } else { + 50_000 + }; + + let expected = FrameStart::new( + expected.kind, + expected.caller, + expected.target, + expected.value, + forward, + ); + assert_eq!(start, expected, "{name}: the start's facts"); + assert_eq!( + at_hook.remaining(), + before_forward - forward, + "{name}: the hook sees the forward taken" + ); + assert_eq!( + *gas.tracker(), + at_hook, + "{name}: nothing is charged or taken after the hook" + ); + let stipend = if matches!(op, CALL | CALLCODE) { + params.call_stipend() + } else { + 0 + }; + assert_eq!( + gas_limit, + forward + stipend, + "{name}: the frame's gas limit" + ); + assert_eq!(reservoir, 0, "{name}"); + } +} + +/// A creation's start carries the address the creation takes, with EIP-8037 and without it, up to +/// the frame below the depth limit, and the frame's input carries the same address, computed once: +/// the handler reuses it whatever nonce it reads. The input holds the address, and a `CREATE2`'s +/// init-code hash, as computed: a copy that has computed nothing differs from it until it computes +/// the address for the nonce the instruction read. +#[test] +fn test_a_creation_start_carries_the_address_its_input_caches() { + for spec in [SpecId::OSAKA, SpecId::AMSTERDAM] { + for op in [CREATE, CREATE2] { + for depth in [0, CALL_STACK_LIMIT as usize - 1] { + let mut host = HookHost::new(spec); + let code = create_code(op, 0, 3); + let (action, _) = run_at_depth(spec, &code, AMPLE, 0, depth, &mut host); + let FrameInput::Create(inputs) = started(action) else { + panic!("{spec:?} {op:#x} at {depth}: a creation's input"); + }; + + assert_eq!( + host.start().0.target, + Some(created(op)), + "{spec:?} {op:#x} at {depth}" + ); + assert_eq!( + inputs.created_address(7), + created(op), + "{spec:?} {op:#x} at {depth}: the input carries the address the hook saw" + ); + let mut uncached = (*inputs).clone(); + uncached.set_init_code(uncached.init_code().clone()); + assert_ne!(uncached, *inputs, "{spec:?} {op:#x} at {depth}"); + assert_eq!(uncached.created_address(0), created(op)); + assert_eq!( + uncached, *inputs, + "{spec:?} {op:#x} at {depth}: the address and a CREATE2's hash were computed" + ); + } + } + } +} + +/// Without EIP-8037, a creation the handler fails before it takes an address reaches the hook with +/// none, and its input holds nothing computed, neither the address nor a `CREATE2`'s init-code +/// hash: an endowment above the caller's balance, a caller's nonce at its maximum, and a frame at +/// the depth limit. With EIP-8037 the instruction ends each before the hook and pushes zero. +#[test] +fn test_a_creation_that_fails_before_its_address_starts_without_one() { + let cases = |spec| { + [ + ( + "an endowment above the balance", + HookHost::new(spec).with_balance(2), + 0, + ), + ( + "a nonce at its maximum", + HookHost::new(spec).with_nonce(u64::MAX), + 0, + ), + ( + "the depth limit", + HookHost::new(spec), + CALL_STACK_LIMIT as usize, + ), + ] + }; + for op in [CREATE, CREATE2] { + let code = create_code(op, 0, 3); + for (name, mut host, depth) in cases(SpecId::OSAKA) { + let (action, _) = run_at_depth(SpecId::OSAKA, &code, AMPLE, 0, depth, &mut host); + let FrameInput::Create(inputs) = started(action) else { + panic!("{op:#x}, {name}: a creation's input"); + }; + + assert_eq!(host.start().0.target, None, "{op:#x}, {name}"); + let mut uncached = (*inputs).clone(); + uncached.set_init_code(uncached.init_code().clone()); + assert_eq!( + uncached, *inputs, + "{op:#x}, {name}: the input holds nothing computed" + ); + } + for (name, mut host, depth) in cases(SpecId::AMSTERDAM) { + let (action, _) = run_at_depth(SpecId::AMSTERDAM, &code, AMPLE, 0, depth, &mut host); + + assert_eq!( + returned(action).0, + InstructionResult::Stop, + "{op:#x}, {name}" + ); + assert!(!host.reached(), "{op:#x}, {name}: the hook is not reached"); + } + } +} + +/// A call's forward is the gas it names when that is below 63/64 of what the caller has left, and +/// that cap otherwise, for every kind of call. +#[test] +fn test_the_forward_is_the_named_gas_or_the_63_64_cap() { + let spec = SpecId::OSAKA; + for op in [CALL, CALLCODE, DELEGATECALL, STATICCALL] { + let charged = call_pushes(op) + static_gas(spec, op); + let left = AMPLE - charged; + for (named, forward) in [(20_000, 20_000), (u32::MAX, left - left / 64)] { + let mut host = HookHost::new(spec); + let (action, _) = run(spec, &call_code(op, named, 0, 0), AMPLE, 0, &mut host); + + assert_eq!(host.start().0.forward, forward, "{op:#x}, named {named}"); + assert_eq!( + input_gas(&started(action)).0, + forward, + "{op:#x}, named {named}" + ); + } + } +} + +/// A value call's stipend is part of the frame's gas limit but not of the forward the hook sees: +/// the caller does not pay it. +#[test] +fn test_the_value_stipend_is_not_part_of_the_forward() { + let spec = SpecId::OSAKA; + let params = GasParams::new_spec(spec); + for op in [CALL, CALLCODE] { + let mut host = HookHost::new(spec); + let (action, gas) = run(spec, &call_code(op, 20_000, 1, 0), AMPLE, 0, &mut host); + let charged = call_pushes(op) + static_gas(spec, op) + params.transfer_value_cost(); + + assert_eq!(host.start().0.forward, 20_000); + assert_eq!( + input_gas(&started(action)).0, + 20_000 + params.call_stipend() + ); + assert_eq!(gas.remaining(), AMPLE - charged - 20_000); + } +} + +/// The frame's input copies the caller's reservoir as the hook left it, for every kind of start, +/// and the caller keeps it while the child runs, as upstream's instructions do. A charge the +/// reservoir covers leaves the forward and the caller's regular gas alone; one that spills draws +/// the caller's regular gas and empties the reservoir, and the forward is still what was taken +/// before. +#[test] +fn test_the_input_copies_the_reservoir_the_hook_left() { + let spec = SpecId::AMSTERDAM; + for (name, code, _) in start_cases() { + let mut quiet = HookHost::new(spec); + let (quiet_action, quiet_gas) = run(spec, &code, AMPLE, 10_000, &mut quiet); + let quiet_limit = input_gas(&started(quiet_action)).0; + + for (charge, reservoir, spilled) in [(4_000, 6_000, 0), (10_500, 0, 500)] { + let mut host = HookHost::new(spec).charging(charge); + let (action, gas) = run(spec, &code, AMPLE, 10_000, &mut host); + let (gas_limit, input_reservoir) = input_gas(&started(action)); + + assert_eq!(host.start().1.reservoir(), 10_000, "{name}"); + assert_eq!(input_reservoir, reservoir, "{name}, charge {charge}"); + assert_eq!( + gas.reservoir(), + reservoir, + "{name}, charge {charge}: the caller keeps the reservoir it copied" + ); + assert_eq!( + gas_limit, quiet_limit, + "{name}, charge {charge}: the forward" + ); + assert_eq!( + gas.remaining(), + quiet_gas.remaining() - spilled, + "{name}, charge {charge}" + ); + } + } +} + +/// A hook that takes the child's reservoir out of the caller's itself names it on the start +/// ([`FrameStart::reservoir`]): the frame's input carries it in place of the caller's reservoir, +/// and the caller keeps what the hook left. +#[test] +fn test_the_input_carries_the_child_reservoir_the_hook_names() { + let spec = SpecId::AMSTERDAM; + for (name, code, _) in start_cases() { + let mut quiet = HookHost::new(spec); + let (quiet_action, quiet_gas) = run(spec, &code, AMPLE, 10_000, &mut quiet); + let quiet_input = started(quiet_action); + + let mut host = HookHost::new(spec).keeping_reservoir(4_000); + let (action, gas) = run(spec, &code, AMPLE, 10_000, &mut host); + let input = started(action); + + assert_eq!( + host.start().0.reservoir, + None, + "{name}: the hook is handed none" + ); + assert_eq!( + input_gas(&input), + (input_gas(&quiet_input).0, 6_000), + "{name}" + ); + assert_eq!( + gas.reservoir(), + 4_000, + "{name}: the caller keeps what the hook left" + ); + assert_eq!(gas.remaining(), quiet_gas.remaining(), "{name}"); + } +} + +/// `false` fails the instruction out of gas and starts no frame. The forward stays taken, so the +/// halt records what the caller had left after it. +#[test] +fn test_a_refused_start_fails_out_of_gas_and_starts_no_frame() { + for (name, code, _) in start_cases() { + let mut host = HookHost::new(SpecId::OSAKA).refusing(); + let (action, _) = run(SpecId::OSAKA, &code, AMPLE, 0, &mut host); + let (result, _, gas) = returned(action); + + assert_eq!(result, InstructionResult::OutOfGas, "{name}"); + assert_eq!( + gas.failed_charge_remaining(), + Some(host.start().1.remaining()), + "{name}" + ); + } +} + +/// Every failure of a frame-starting instruction before its forward is taken ends the instruction +/// before the hook. +#[test] +fn test_a_start_that_fails_before_the_forward_never_reaches_the_hook() { + let osaka = GasParams::new_spec(SpecId::OSAKA); + let amsterdam = GasParams::new_spec(SpecId::AMSTERDAM); + let call = |params: &GasParams, spec| { + call_pushes(CALL) + static_gas(spec, CALL) + params.transfer_value_cost() + }; + let mut cases: Vec<FailureCase<String>> = Vec::new(); + for op in [CALL, CALLCODE, DELEGATECALL, STATICCALL] { + cases.push(( + format!("{op:#x}'s input memory"), + SpecId::OSAKA, + call_code(op, 1_000, 0, 32), + HookHost::new(SpecId::OSAKA), + call_pushes(op) + static_gas(SpecId::OSAKA, op) + 2, + InstructionResult::MemoryOOG, + )); + cases.push(( + format!("{op:#x}'s cold target, refused"), + SpecId::OSAKA, + call_code(op, 1_000, 0, 0), + HookHost::new(SpecId::OSAKA).cold(), + call_pushes(op) + static_gas(SpecId::OSAKA, op) + osaka.cold_account_additional_cost() + - 1, + InstructionResult::OutOfGas, + )); + } + cases.extend([ + ( + "CALL's value charge".to_string(), + SpecId::OSAKA, + call_code(CALL, 1_000, 1, 0), + HookHost::new(SpecId::OSAKA), + call(&osaka, SpecId::OSAKA) - 1, + InstructionResult::OutOfGas, + ), + ( + "CALL's account charge".to_string(), + SpecId::OSAKA, + call_code(CALL, 1_000, 1, 0), + HookHost::new(SpecId::OSAKA).cold().empty(), + call(&osaka, SpecId::OSAKA) + + osaka.cold_account_additional_cost() + + osaka.new_account_cost(true, true) + - 1, + InstructionResult::OutOfGas, + ), + ( + "CALL's state-gas charge".to_string(), + SpecId::AMSTERDAM, + call_code(CALL, 1_000, 1, 0), + HookHost::new(SpecId::AMSTERDAM).empty(), + call(&amsterdam, SpecId::AMSTERDAM) + + amsterdam.new_account_cost(true, true) + + amsterdam.get(GasId::new_account_state_gas()) + - 1, + InstructionResult::OutOfGas, + ), + ( + "CALL's state-gas price".to_string(), + SpecId::AMSTERDAM, + call_code(CALL, 1_000, 1, 0), + HookHost::new(SpecId::AMSTERDAM).empty().price_fails(), + AMPLE, + InstructionResult::FatalExternalError, + ), + ( + "CALL's forward, before EIP-150's cap".to_string(), + SpecId::HOMESTEAD, + call_code(CALL, 1_000, 0, 0), + HookHost::new(SpecId::HOMESTEAD), + call_pushes(CALL) + static_gas(SpecId::HOMESTEAD, CALL) + 999, + InstructionResult::OutOfGas, + ), + ]); + for op in [CREATE, CREATE2] { + let pushes = create_pushes(op); + let cost = if op == CREATE2 { + osaka.create2_cost(32) + } else { + osaka.create_cost() + }; + let amsterdam_cost = if op == CREATE2 { + amsterdam.create2_cost(32) + } else { + amsterdam.create_cost() + }; + cases.extend([ + ( + format!("{op:#x}'s init-code charge"), + SpecId::OSAKA, + create_code(op, 32, 0), + HookHost::new(SpecId::OSAKA), + pushes + osaka.initcode_cost(32) - 1, + InstructionResult::OutOfGas, + ), + ( + format!("{op:#x}'s memory"), + SpecId::OSAKA, + create_code(op, 32, 0), + HookHost::new(SpecId::OSAKA), + pushes + osaka.initcode_cost(32) + 2, + InstructionResult::MemoryOOG, + ), + ( + format!("{op:#x}'s creation charge"), + SpecId::OSAKA, + create_code(op, 32, 0), + HookHost::new(SpecId::OSAKA), + pushes + osaka.initcode_cost(32) + 3 + cost - 1, + InstructionResult::OutOfGas, + ), + ( + format!("{op:#x}'s state-gas charge"), + SpecId::AMSTERDAM, + create_code(op, 32, 0), + HookHost::new(SpecId::AMSTERDAM).empty(), + pushes + + amsterdam.initcode_cost(32) + + 3 + + amsterdam_cost + + amsterdam.get(GasId::create_state_gas()) + - 1, + InstructionResult::OutOfGas, + ), + ( + format!("{op:#x}'s state-gas price"), + SpecId::AMSTERDAM, + create_code(op, 32, 0), + HookHost::new(SpecId::AMSTERDAM).empty().price_fails(), + AMPLE, + InstructionResult::FatalExternalError, + ), + ]); + } + for (name, spec, code, mut host, gas_limit, expected) in cases { + let (action, _) = run(spec, &code, gas_limit, 0, &mut host); + assert_eq!(returned(action).0, expected, "{name}"); + assert!(!host.reached(), "{name}: the hook is not reached"); + } +} + +/// With exactly the gas a start needs before its forward, it reaches the hook: the cases above fail +/// on the charge they name, not on one they share. +#[test] +fn test_a_start_with_the_gas_it_needs_reaches_the_hook() { + let amsterdam = GasParams::new_spec(SpecId::AMSTERDAM); + let call = call_pushes(CALL) + + static_gas(SpecId::AMSTERDAM, CALL) + + amsterdam.transfer_value_cost() + + amsterdam.new_account_cost(true, true) + + amsterdam.get(GasId::new_account_state_gas()); + let create = create_pushes(CREATE) + + amsterdam.initcode_cost(32) + + 3 + + amsterdam.create_cost() + + amsterdam.get(GasId::create_state_gas()); + for (name, code, gas_limit) in [ + ("CALL", call_code(CALL, 1_000, 1, 0), call), + ("CREATE", create_code(CREATE, 32, 0), create), + ] { + let mut host = HookHost::new(SpecId::AMSTERDAM).empty(); + let (action, _) = run(SpecId::AMSTERDAM, &code, gas_limit, 0, &mut host); + + let _ = started(action); + assert_eq!( + host.start().0.forward, + 0, + "{name}: nothing is left to forward" + ); + } +} diff --git a/crates/interpreter/tests/pending_action.rs b/crates/interpreter/tests/pending_action.rs new file mode 100644 index 0000000000..65847a7ddb --- /dev/null +++ b/crates/interpreter/tests/pending_action.rs @@ -0,0 +1,83 @@ +//! An action set on an interpreter before it runs is what the run returns, before any +//! instruction. +//! +//! A consumer sets a frame's next action between the frame's start and its run (or after a child +//! returned into it) with `LoopControl::set_action`. The plain run returns that action as it was +//! set: no instruction runs, so the frame's gas, program counter and stack are as the consumer +//! left them, and the interpreter is ready to run again. + +use bytecode::{opcode::*, Bytecode}; +use primitives::{hardfork::SpecId, Bytes}; +use revm_interpreter::{ + host::DummyHost, + instruction_table, + instructions::gas_table_spec, + interpreter::{EthInterpreter, ExtBytecode}, + interpreter_types::{Jumps, LoopControl}, + InputsImpl, InstructionResult, Interpreter, InterpreterAction, SharedMemory, +}; + +const SPEC: SpecId = SpecId::OSAKA; +const GAS_LIMIT: u64 = 10_000; + +/// Code that would push twice and stop: every instruction it runs moves the program counter, the +/// stack and the gas. +const CODE: &[u8] = &[PUSH0, PUSH0, STOP]; + +/// An interpreter on [`CODE`] with a revert set as its next action, and that action. +fn pending() -> (Interpreter<EthInterpreter>, InterpreterAction) { + let mut interpreter = Interpreter::<EthInterpreter>::new( + SharedMemory::new(), + ExtBytecode::new(Bytecode::new_raw(Bytes::from_static(CODE))), + InputsImpl::default(), + false, + SPEC, + GAS_LIMIT, + ); + let action = InterpreterAction::new_return( + InstructionResult::Revert, + Bytes::from_static(b"set before the run"), + interpreter.gas, + ); + interpreter.bytecode.set_action(action.clone()); + (interpreter, action) +} + +/// Asserts that `interpreter` ran no instruction and is ready to run again. +fn assert_ran_nothing(interpreter: &Interpreter<EthInterpreter>) { + assert_eq!( + interpreter.bytecode.pc(), + 0, + "no instruction moved the counter" + ); + assert_eq!(interpreter.stack.len(), 0, "no instruction pushed"); + assert_eq!( + interpreter.gas.remaining(), + GAS_LIMIT, + "no instruction charged" + ); + assert!(interpreter.bytecode.is_not_end(), "the action was taken"); +} + +#[test] +fn test_run_plain_returns_a_pending_action_before_any_instruction() { + let (mut interpreter, action) = pending(); + let table = instruction_table::<EthInterpreter, DummyHost>(); + + let returned = interpreter.run_plain(&table, &gas_table_spec(SPEC), &mut DummyHost::new(SPEC)); + + assert_eq!(returned, action); + assert_ran_nothing(&interpreter); +} + +#[test] +fn test_run_plain_as_output_returns_a_pending_action_before_any_instruction() { + let (mut interpreter, action) = pending(); + let table = instruction_table::<EthInterpreter, DummyHost>(); + + let returned = + interpreter.run_plain_as_output(&table, &gas_table_spec(SPEC), &mut DummyHost::new(SPEC)); + + assert_eq!(returned, action); + assert_ran_nothing(&interpreter); +} diff --git a/crates/interpreter/tests/start_marks.rs b/crates/interpreter/tests/start_marks.rs new file mode 100644 index 0000000000..cfe640e868 --- /dev/null +++ b/crates/interpreter/tests/start_marks.rs @@ -0,0 +1,100 @@ +//! The marks revm writes on a frame result before an inspector's end callbacks keep the values' +//! public semantics: a marked gas tracker and a marked outcome print exactly as the derived debug +//! output printed them before the marks existed, and encode without them. + +use revm_interpreter::{ + CallOutcome, CreateOutcome, Gas, GasTracker, InstructionResult, InterpreterResult, OutcomeMark, + StartMark, +}; + +/// The derived debug output of these values before the marks existed. +const TRACKER: &str = "GasTracker { gas_limit: 100, remaining: 90, reservoir: 5, \ + state_gas_spent: 0, state_gas_spilled: 0, history_gas_spent: 0, refunded: 3, withheld: 0, \ + withheld_crossing: None, failed_charge_remaining: 0, failed_charge_recorded: false, \ + reservoir_only_give_backs: false, halted_regular_paid: 0 }"; +const RESULT: &str = "InterpreterResult { result: Stop, output: 0x, gas: Gas { tracker: \ + GasTracker { gas_limit: 10, remaining: 10, reservoir: 0, state_gas_spent: 0, \ + state_gas_spilled: 0, history_gas_spent: 0, refunded: 0, withheld: 0, withheld_crossing: \ + None, failed_charge_remaining: 0, failed_charge_recorded: false, \ + reservoir_only_give_backs: false, halted_regular_paid: 0 }, memory: MemoryGas { \ + words_num: 0, expansion_cost: 0 } } }"; + +const fn tracker() -> GasTracker { + let mut tracker = GasTracker::new(100, 90, 5); + tracker.record_refund(3); + tracker.set_start_mark(StartMark::for_start(7)); + tracker +} + +fn result() -> InterpreterResult { + let mut gas = Gas::new(10); + gas.tracker_mut().set_start_mark(StartMark::for_start(7)); + InterpreterResult::new(InstructionResult::Stop, Default::default(), gas) +} + +fn call() -> CallOutcome { + CallOutcome { + start_mark: OutcomeMark::for_start(7), + ..CallOutcome::new(result(), 1..2) + } +} + +fn create() -> CreateOutcome { + CreateOutcome { + start_mark: OutcomeMark::for_start(7), + ..CreateOutcome::new(result(), None) + } +} + +#[test] +fn test_marked_values_print_as_the_derived_output_did() { + assert_eq!(format!("{:?}", tracker()), TRACKER); + assert_eq!( + format!("{:?}", call()), + format!( + "CallOutcome {{ result: {RESULT}, memory_offset: 1..2, was_precompile_called: false, \ + precompile_call_logs: [], charged_new_account_state_gas: false, \ + charged_state_gas_address: 0x0000000000000000000000000000000000000000 }}" + ) + ); + assert_eq!( + format!("{:?}", create()), + format!( + "CreateOutcome {{ result: {RESULT}, address: None, charged_create_state_gas: false, \ + charged_state_gas_address: 0x0000000000000000000000000000000000000000 }}" + ) + ); +} + +#[test] +fn test_marked_values_equal_their_unmarked_selves() { + let mut unmarked = tracker(); + unmarked.set_start_mark(StartMark::NONE); + assert_eq!(tracker(), unmarked); + assert_eq!(call(), CallOutcome::new(result(), 1..2)); + assert_eq!(create(), CreateOutcome::new(result(), None)); +} + +/// An encoded value has no mark, and decodes equal with none. +#[cfg(feature = "serde")] +#[test] +fn test_marked_values_encode_without_their_marks() { + let json = serde_json::to_string(&tracker()).expect("encodes"); + assert!(!json.contains("mark"), "{json}"); + let decoded: GasTracker = serde_json::from_str(&json).expect("decodes"); + assert_eq!(decoded, tracker()); + assert!(!decoded.start_mark().is_for(7)); + + let json = serde_json::to_string(&call()).expect("encodes"); + assert!(!json.contains("mark"), "{json}"); + let decoded: CallOutcome = serde_json::from_str(&json).expect("decodes"); + assert_eq!(decoded, call()); + assert!(!decoded.start_mark.is_for(7)); + assert!(!decoded.result.gas.tracker().start_mark().is_for(7)); + + let json = serde_json::to_string(&create()).expect("encodes"); + assert!(!json.contains("mark"), "{json}"); + let decoded: CreateOutcome = serde_json::from_str(&json).expect("decodes"); + assert_eq!(decoded, create()); + assert!(!decoded.start_mark.is_for(7)); +} diff --git a/crates/interpreter/tests/withheld_gas.rs b/crates/interpreter/tests/withheld_gas.rs index a6b58886d7..6c30918f3c 100644 --- a/crates/interpreter/tests/withheld_gas.rs +++ b/crates/interpreter/tests/withheld_gas.rs @@ -34,8 +34,9 @@ const CONTRACT: Address = address!("0x00000000000000000000000000000000000c0de0") /// Account the `CALL` tests call. const CALLEE: Address = address!("0x00000000000000000000000000000000000ca11e"); -/// A host whose accounts and slots are all cold, and that records whether each load was made or -/// skipped because the frame could not pay for it. +/// A host whose accounts and slots are all cold but the running frame's own account, which a +/// journal holds warm, and that records whether each cold load was made or skipped because the +/// frame could not pay for it. #[derive(Debug)] struct ColdHost { gas_params: GasParams, @@ -187,13 +188,16 @@ impl Host for ColdHost { fn load_account_info_skip_cold_load( &mut self, - _address: Address, + address: Address, _load_code: bool, skip_cold_load: bool, ) -> Result<AccountInfoLoad<'_>, LoadError> { - self.load(skip_cold_load)?; + let is_cold = address != CONTRACT; + if is_cold { + self.load(skip_cold_load)?; + } Ok(AccountInfoLoad { - is_cold: true, + is_cold, ..Default::default() }) } diff --git a/crates/precompile/src/modexp.rs b/crates/precompile/src/modexp.rs index ae026f90de..d132c442b9 100644 --- a/crates/precompile/src/modexp.rs +++ b/crates/precompile/src/modexp.rs @@ -210,20 +210,20 @@ where let exp_len = U256::from_be_bytes(right_pad_with_offset::<32>(input, 32).into_owned()); let mod_len = U256::from_be_bytes(right_pad_with_offset::<32>(input, 64).into_owned()); - // Cast base and modulus to usize, it does not make sense to handle larger values - let base_len = usize::try_from(base_len).map_err(|_| PrecompileHalt::ModexpEip7823LimitSize)?; - let mod_len = usize::try_from(mod_len).map_err(|_| PrecompileHalt::ModexpEip7823LimitSize)?; - // cast exp len to the max size, it will fail later in gas calculation if it is too large. - let exp_len = usize::try_from(exp_len).unwrap_or(usize::MAX); - - // for EIP-7823 we need to check size of inputs - if OSAKA - && (base_len > eip7823::INPUT_SIZE_LIMIT - || mod_len > eip7823::INPUT_SIZE_LIMIT - || exp_len > eip7823::INPUT_SIZE_LIMIT) - { - return Err(PrecompileHalt::ModexpEip7823LimitSize); - } + let [base_len64, exp_len64, mod_len64] = if OSAKA { + // Osaka prices oversized lengths before rejecting them, independently of pointer width. + [base_len, exp_len, mod_len].map(|len| u64::try_from(len).unwrap_or(u64::MAX)) + } else { + // Earlier forks keep their original length checks and exponent saturation. + let base_len = + usize::try_from(base_len).map_err(|_| PrecompileHalt::ModexpEip7823LimitSize)?; + let mod_len = + usize::try_from(mod_len).map_err(|_| PrecompileHalt::ModexpEip7823LimitSize)?; + let exp_len = usize::try_from(exp_len).unwrap_or(usize::MAX); + [base_len as u64, exp_len as u64, mod_len as u64] + }; + let [base_len, exp_len, mod_len] = + [base_len64, exp_len64, mod_len64].map(|len| usize::try_from(len).unwrap_or(usize::MAX)); // Used to extract ADJUSTED_EXPONENT_LENGTH. let exp_highp_len = min(exp_len, 32); @@ -239,12 +239,20 @@ where U256::from_be_bytes(out.into_owned()) }; - // Check if we have enough gas. - let gas_cost = calc_gas(base_len as u64, exp_len as u64, mod_len as u64, &exp_highp); + let gas_cost = calc_gas(base_len64, exp_len64, mod_len64, &exp_highp); if gas_cost > gas_limit { return Err(PrecompileHalt::OutOfGas); } + // EIP-7823 checks the bound only after the formula's gas charge. + if OSAKA + && [base_len64, exp_len64, mod_len64] + .into_iter() + .any(|len| len > eip7823::INPUT_SIZE_LIMIT as u64) + { + return Err(PrecompileHalt::ModexpEip7823LimitSize); + } + if base_len == 0 && mod_len == 0 { return Ok(EthPrecompileOutput::new(gas_cost, Bytes::new())); } @@ -567,6 +575,109 @@ mod tests { assert_eq!(res.bytes, expected) } + #[test] + fn test_osaka_modexp_charges_before_the_size_bound() { + let input: Vec<u8> = [U256::from(1_025), U256::from(1), U256::from(1)] + .into_iter() + .flat_map(|len| len.to_be_bytes::<32>()) + .collect(); + // EIP-7883: 2 * ceil(1025 / 8)^2 * 1 = 33,282, with a zero exponent. + for (gas, expected) in [ + (499, PrecompileHalt::OutOfGas), + (500, PrecompileHalt::OutOfGas), + (33_281, PrecompileHalt::OutOfGas), + (33_282, PrecompileHalt::ModexpEip7823LimitSize), + (33_283, PrecompileHalt::ModexpEip7823LimitSize), + ] { + assert_eq!(osaka_run(&input, gas), Err(expected), "gas={gas}"); + } + } + + #[test] + fn test_osaka_modexp_over_bound_input_has_its_formula_price() { + for (lengths, price) in [ + ([1_025, 1, 1], 33_282), + ([1, 1_025, 1], 254_208), + ([1, 1, 1_025], 33_282), + ] { + let input: Vec<u8> = lengths + .map(U256::from) + .into_iter() + .flat_map(|len| len.to_be_bytes::<32>()) + .collect(); + assert_eq!( + OSAKA.required_gas(&input), + Some(price), + "lengths={lengths:?}" + ); + assert_eq!(osaka_run(&input, price - 1), Err(PrecompileHalt::OutOfGas)); + assert_eq!( + osaka_run(&input, price), + Err(PrecompileHalt::ModexpEip7823LimitSize) + ); + } + } + + #[test] + fn test_modexp_earlier_forks_keep_their_length_rules() { + let input: Vec<u8> = [U256::from(1_025), U256::from(1), U256::from(1)] + .into_iter() + .flat_map(|len| len.to_be_bytes::<32>()) + .collect(); + for (run, entry, price) in [ + ( + byzantium_run as fn(&[u8], u64) -> EthPrecompileResult, + BYZANTIUM, + 17_899, + ), + (berlin_run, BERLIN, 5_547), + ] { + let output = run(&input, price).unwrap(); + assert_eq!(output.gas_used, price); + assert_eq!(output.bytes.as_ref(), &[0]); + assert_eq!(entry.required_gas(&input), Some(price)); + + for position in [0, 2] { + let mut oversized = input.clone(); + oversized[position * 32..(position + 1) * 32] + .copy_from_slice(&(U256::from(1) << 64_usize).to_be_bytes::<32>()); + assert_eq!( + run(&oversized, 100_000), + Err(PrecompileHalt::ModexpEip7823LimitSize), + "price={price}, position={position}" + ); + } + } + } + + #[test] + fn test_osaka_modexp_unpayable_lengths_run_out_of_gas() { + for position in 0..3 { + for length in [U256::from(u64::MAX), U256::from(1) << 64, U256::MAX] { + let mut lengths = [U256::from(1); 3]; + lengths[position] = length; + let input: Vec<u8> = lengths + .into_iter() + .flat_map(|len| len.to_be_bytes::<32>()) + .collect(); + for gas in [0, 499, 500, 100_000, u64::MAX - 1] { + assert_eq!( + osaka_run(&input, gas), + Err(PrecompileHalt::OutOfGas), + "position={position}, length={length}, gas={gas}" + ); + } + // Like go-ethereum, a u64::MAX gas limit pays the saturated price before the bound. + assert_eq!( + osaka_run(&input, u64::MAX), + Err(PrecompileHalt::ModexpEip7823LimitSize), + "position={position}, length={length}" + ); + assert_eq!(OSAKA.required_gas(&input), Some(u64::MAX)); + } + } + } + #[test] fn test_osaka_modexp_input_len() { #[derive(Debug)] @@ -574,6 +685,7 @@ mod tests { base_len: U256, exp_len: U256, mod_len: U256, + gas: u64, expected: Option<PrecompileHalt>, } @@ -592,42 +704,48 @@ mod tests { base_len: U256::from(1025), exp_len: U256::from(1024), mod_len: U256::from(1024), + gas: u64::MAX, expected: Some(PrecompileHalt::ModexpEip7823LimitSize), }, TestInput { base_len: U256::from(1024), exp_len: U256::from(1025), mod_len: U256::from(1024), + gas: u64::MAX, expected: Some(PrecompileHalt::ModexpEip7823LimitSize), }, TestInput { base_len: U256::from(1024), exp_len: U256::from(1024), mod_len: U256::from(1025), + gas: u64::MAX, expected: Some(PrecompileHalt::ModexpEip7823LimitSize), }, TestInput { base_len: U256::from(0), exp_len: U256::from(0), mod_len: U256::from(1025), + gas: u64::MAX, expected: Some(PrecompileHalt::ModexpEip7823LimitSize), }, TestInput { base_len: U256::from(1024), exp_len: U256::from(1024), mod_len: U256::from(1024), + gas: 100_000_000, expected: Some(PrecompileHalt::OutOfGas), }, TestInput { base_len: U256::from(0), exp_len: U256::from(0), mod_len: U256::from(0), + gas: 100_000_000, expected: None, }, ]; for test in test_inputs { let input = test.input(); - let res = osaka_run(&input, 100_000_000).err(); + let res = osaka_run(&input, test.gas).err(); if res != test.expected { panic!("test failed: {test:?} result: {res:?}"); } diff --git a/crates/precompile/src/required_gas.rs b/crates/precompile/src/required_gas.rs index 9cf092ba44..b0290ee3d8 100644 --- a/crates/precompile/src/required_gas.rs +++ b/crates/precompile/src/required_gas.rs @@ -26,9 +26,12 @@ //! input's price is the gas that check asks for: every precompile with a flat price, the //! BN254 pairing on a length that is not a multiple of 192 bytes, KZG point evaluation on any //! malformed input, a `BLAKE2F` final-block flag other than 0 or 1; -//! - `MODEXP` checks the sizes in its header between its two gas checks: a header whose sizes -//! do not fit (EIP-7823 under Osaka, or `usize` everywhere) prices at the minimum the first -//! gas check asks for, 0, 200 or 500 by schedule. +//! - Osaka `MODEXP` prices every header by its formula before checking EIP-7823's bound, with +//! each length saturated to 64 bits. A formula price saturated to `u64::MAX` passes the gas +//! check at that exact gas limit and then fails the size bound. +//! Earlier schedules refuse a base or modulus length that +//! does not fit `usize` between the two gas checks, so those inputs keep the first check's +//! minimum price, 0 under Byzantium or 200 under Berlin. //! //! The price never tells whether a call with enough gas succeeds: an input that fails a check //! after the gas check is only told apart from one that succeeds by running it. @@ -215,10 +218,10 @@ pub fn modexp_osaka(input: &[u8]) -> u64 { } /// Prices a `MODEXP` call with the run's own header parsing: [`modexp::run_inner`] reads the -/// header, checks the sizes and prices the call exactly as a run does, and `gas_calc` is handed -/// to it as the price, recorded and then refused, so the run stops at its gas check before any -/// exponentiation. A header refused between the two gas checks never reaches `gas_calc`, and -/// prices at `min_gas`. +/// header and prices the call exactly as a run does, and `gas_calc` is handed to it as the price, +/// recorded and then refused, so the run stops at its gas check before any exponentiation. +/// Osaka prices every header before checking its size bound. Earlier forks still price a +/// header refused between the two gas checks at `min_gas`. fn modexp_price<const OSAKA: bool>( input: &[u8], min_gas: u64, diff --git a/crates/precompile/tests/required_gas.rs b/crates/precompile/tests/required_gas.rs index 15b74ca179..1a0f5f8202 100644 --- a/crates/precompile/tests/required_gas.rs +++ b/crates/precompile/tests/required_gas.rs @@ -250,7 +250,7 @@ fn made_inputs(id: &PrecompileId, rng: &mut StdRng) -> Vec<Vec<u8>> { let mut high_exp = modexp_input(rng, small(1), small(40), small(1), 42); high_exp[96 + 1] = 0xff; inputs.push(high_exp); - // Sizes EIP-7823 refuses under Osaka, between the two gas checks. + // Sizes EIP-7823 refuses under Osaka, after the formula price is charged. for (base, exp, modulus) in [(1_025, 1, 1), (1, 1_025, 1), (1, 1, 1_025)] { inputs.push(modexp_input( rng, @@ -452,12 +452,12 @@ fn malformed_inputs_price_as_documented() { Some(7) ); - // `MODEXP` sizes refused between its two gas checks: the first gas check's minimum. + // `MODEXP` under Osaka prices oversized lengths before checking its size bound. let mut rng = StdRng::seed_from_u64(2); let too_big = modexp_input(&mut rng, U256::from(1_025), U256::from(1), U256::from(1), 8); - assert_eq!(modexp::OSAKA.required_gas(&too_big), Some(500)); + assert_eq!(modexp::OSAKA.required_gas(&too_big), Some(33_282)); let unaddressable = modexp_input(&mut rng, U256::MAX, U256::from(1), U256::from(1), 8); - assert_eq!(modexp::OSAKA.required_gas(&unaddressable), Some(500)); + assert_eq!(modexp::OSAKA.required_gas(&unaddressable), Some(u64::MAX)); assert_eq!(modexp::BERLIN.required_gas(&unaddressable), Some(200)); assert_eq!(modexp::BYZANTIUM.required_gas(&unaddressable), Some(0)); } @@ -490,7 +490,7 @@ fn every_set_prices_with_its_own_schedule() { assert_eq!(modexp_price(PrecompileSpecId::BYZANTIUM), Some(0)); assert_eq!(modexp_price(PrecompileSpecId::BERLIN), Some(200)); assert_eq!(modexp_price(PrecompileSpecId::PRAGUE), Some(200)); - assert_eq!(modexp_price(PrecompileSpecId::OSAKA), Some(500)); + assert_eq!(modexp_price(PrecompileSpecId::OSAKA), Some(u64::MAX)); let p256 = |spec| { Precompiles::new(spec) diff --git a/crates/state/src/lib.rs b/crates/state/src/lib.rs index 57d3fb8557..7b96d294f7 100644 --- a/crates/state/src/lib.rs +++ b/crates/state/src/lib.rs @@ -7,6 +7,7 @@ extern crate alloc as std; mod account_info; pub mod bal; +mod original_info; mod types; pub use bytecode; diff --git a/crates/state/src/original_info.rs b/crates/state/src/original_info.rs new file mode 100644 index 0000000000..131ca2a114 --- /dev/null +++ b/crates/state/src/original_info.rs @@ -0,0 +1,133 @@ +//! The account's original info, read by reference. + +use crate::{Account, AccountInfo}; +use primitives::OnceLock; + +impl Account { + /// Returns a reference to the original account info: the info + /// [`original_info`](Self::original_info) returns, without cloning it. + /// + /// An account whose original info was never set reads the default info, as it does through + /// `original_info`. + #[inline] + pub fn original_info_ref(&self) -> &AccountInfo { + match self.original_info.as_deref() { + Some(info) => info, + None => default_info(), + } + } +} + +/// The default account info, built once and shared. +fn default_info() -> &'static AccountInfo { + static DEFAULT: OnceLock<AccountInfo> = OnceLock::new(); + DEFAULT.get_or_init(AccountInfo::default) +} + +#[cfg(test)] +mod tests { + use crate::{Account, AccountId, AccountInfo, TransactionId}; + use bytecode::Bytecode; + use primitives::{Bytes, U256}; + + fn info(balance: u64, nonce: u64) -> AccountInfo { + AccountInfo::from_balance(U256::from(balance)) + .with_code(Bytecode::new_legacy(Bytes::from_static(&[0x60, 0x00]))) + .with_nonce(nonce) + } + + /// [`info`] with an account id, which `AccountInfo`'s `PartialEq` ignores. + fn info_with_id(balance: u64, nonce: u64, id: usize) -> AccountInfo { + let mut info = info(balance, nonce); + info.account_id = AccountId::new(id); + info + } + + /// Asserts the reference is the info `original_info` returns, field by field: `AccountInfo`'s + /// `PartialEq` ignores the account id and the cached code. + #[track_caller] + fn assert_parity(account: &Account) { + let by_ref = account.original_info_ref(); + let cloned = account.original_info(); + assert_eq!(by_ref.balance, cloned.balance); + assert_eq!(by_ref.nonce, cloned.nonce); + assert_eq!(by_ref.code_hash, cloned.code_hash); + assert_eq!(by_ref.code, cloned.code); + assert_eq!(by_ref.account_id, cloned.account_id); + } + + /// An account whose original info was never set reads the default info, code and account id + /// included, whatever its info and status are now. + #[test] + fn test_an_unset_original_reads_the_default_info() { + let mut account = Account::new_not_existing(TransactionId::ZERO); + account.info = info_with_id(5, 1, 3); + assert_parity(&account); + let original = account.original_info_ref(); + assert!(original.is_default()); + assert_eq!(*original, AccountInfo::default()); + assert_eq!(original.code, Some(Bytecode::default())); + assert_eq!(original.account_id, None); + + account.mark_created(); + assert_parity(&account); + assert!(account.original_info_ref().is_default()); + assert_eq!(account.original_info_ref().account_id, None); + + account.mark_selfdestruct(); + assert_parity(&account); + assert!(account.original_info_ref().is_default()); + + account.unmark_created(); + assert_parity(&account); + assert!(account.original_info_ref().is_default()); + assert_eq!(account.original_info_ref().account_id, None); + } + + /// A set original is read where the account holds it, not from a copy, whatever the account's + /// status, and follows every change made through `original_info_mut` and + /// `set_current_info_as_original`. + #[test] + fn test_a_set_original_is_read_in_place() { + let mut account = Account::from(info_with_id(5, 1, 7)); + account.info = info_with_id(7, 2, 8); + assert_parity(&account); + assert_eq!(account.original_info_ref().balance, U256::from(5)); + assert_eq!(account.original_info_ref().nonce, 1); + assert_eq!(account.original_info_ref().account_id, AccountId::new(7)); + assert!(core::ptr::eq( + account.original_info_ref(), + account.original_info.as_deref().unwrap() + )); + + account.mark_created(); + assert_parity(&account); + assert_eq!(account.original_info_ref().nonce, 1); + assert_eq!(account.original_info_ref().account_id, AccountId::new(7)); + + account.mark_selfdestruct(); + assert_parity(&account); + assert_eq!(account.original_info_ref().nonce, 1); + + account.unmark_created(); + assert_parity(&account); + assert_eq!(account.original_info_ref().balance, U256::from(5)); + assert_eq!(account.original_info_ref().account_id, AccountId::new(7)); + + account.original_info_mut().nonce = 9; + account.original_info_mut().account_id = AccountId::new(11); + assert_parity(&account); + assert_eq!(account.original_info_ref().nonce, 9); + assert_eq!(account.original_info_ref().account_id, AccountId::new(11)); + + account.set_current_info_as_original(); + assert_parity(&account); + assert_eq!(account.original_info_ref().balance, U256::from(7)); + assert_eq!(account.original_info_ref().nonce, 2); + assert_eq!(account.original_info_ref().account_id, AccountId::new(8)); + assert!(core::ptr::eq( + account.original_info_ref(), + account.original_info.as_deref().unwrap() + )); + } +} diff --git a/rust-toolchain.toml b/rust-toolchain.toml index d0898ae4fc..b01310b9ba 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -3,11 +3,11 @@ # Upstream floats on `stable` and fixes each release's new clippy lints in its # own code; this fork carries upstream code it does not edit, so it pins the # toolchain and moves the pin deliberately: with each base-line move, or in a -# `mega:` commit of its own when a newer compiler is wanted. The channel is the -# stable release upstream's own CI ran on when the base tag was cut, so the -# upstream code in the tree is lint-clean by construction. The MSRV consumers -# see is still `rust-version` in Cargo.toml. +# commit of its own when a newer compiler is wanted. The channel is the stable +# release upstream's own CI ran on when the base tag was cut, or a later stable +# release taken for a compiler fix. The MSRV consumers see is still +# `rust-version` in Cargo.toml. [toolchain] -channel = "1.95.0" +channel = "1.97.0" components = ["clippy", "rustfmt"] targets = ["riscv32imac-unknown-none-elf", "riscv64imac-unknown-none-elf"]