feat: add engine‑managed tipset gas reservations to ref‑fvm

[snissn]

feat: add engine‑managed tipset gas reservations to ref‑fvm

This PR implements engine‑managed tipset‑scope gas reservations inside ref‑fvm, as described in a pending FIP proposal.

Summary

• Add a reservation session ledger on the default executor keyed by ActorID.
• Implement begin_reservation_session / end_reservation_session with affordability checks and invariants.
• Rewrite preflight to assert coverage without pre‑deducting gas funds in reservation mode.
• Enforce transfers against free balance balance − reserved_remaining.
• Rewrite settlement to net‑charge gas and realize refunds via reservation release.
• Add reservation telemetry and tests (unit + integration).

Changes

Executor: session lifecycle and preflight

• fvm/src/executor/mod.rs

  • Add:
    • ReservationSession struct (re‑exported from default.rs) and ReservationError enum:
      • NotImplemented
      • InsufficientFundsAtBegin { sender }
      • SessionOpen
      • SessionClosed
      • NonZeroRemainder
      • PlanTooLarge
      • Overflow
      • ReservationInvariant(String)

• fvm/src/executor/default.rs

  • Add ReservationSession { reservations: HashMap<ActorID, TokenAmount>, open: bool } and an Arc<Mutex<_>> on DefaultExecutor.
  • Implement:
    • begin_reservation_session(&mut self, plan: &[(Address, TokenAmount)]) -> Result<(), ReservationError>:
      • Empty plan = no‑op (do not enter reservation mode).
      • Enforce MAX_SENDERS (65,536) and track plan failures via telemetry.
      • Resolve senders via the state tree (robust or ID addresses → ActorID).
      • Aggregate Σ(plan) per actor and enforce reserved_total <= balance per sender.
      • Enforce single active session.
    • end_reservation_session(&mut self) -> Result<(), ReservationError>:
      • Require open == true and all reservation entries to be zero.
      • Clear the ledger and close the session; update telemetry.
  • Preflight:
    • Compute gas_cost = gas_fee_cap * gas_limit using big‑int; treat negative results as ReservationError::Overflow.
    • In reservation mode:
      • Assert coverage via reservation_assert_coverage(sender, &gas_cost); do not pre‑deduct funds.
      • On prevalidation failures (invalid sender, bad nonce, inclusion gas > limit), call reservation_prevalidation_decrement so the ledger can end at zero.
    • Legacy mode:
      • Preserve existing behaviour (check balance ≥ gas_cost, pre‑deduct from sender).

Transfer enforcement and settlement

• fvm/src/call_manager/default.rs & fvm/src/call_manager/mod.rs

  • Thread Arc<Mutex<ReservationSession>> into the default call manager.
  • In transfer(from, to, value):
    • When the reservation session is open:
      • Compute reserved_remaining = reservations.get(from).unwrap_or(0).
      • Enforce value + reserved_remaining <= from.balance; otherwise return InsufficientFunds.
    • When no session is open:
      • Preserve existing value <= balance semantics.

• fvm/src/executor/default.rs

  • Settlement (finish_message) in reservation mode:
    • Compute GasOutputs as today.
    • Define consumption = base_fee_burn + over_estimation_burn + miner_tip.
    • Deduct consumption from the sender’s actor balance.
    • Deposit burns and tip to the existing reward/burn actors.
    • Do not deposit refund to the sender; the “refund effect” is realized by releasing the reservation ledger.
    • Decrement reservations[sender] by gas_cost using reservation_prevalidation_decrement, update telemetry, and remove entries at zero.
  • Legacy mode settlement is unchanged.
  • Preserve the invariant:
    • base_fee_burn + over_estimation_burn + refund + miner_tip == gas_cost.

Telemetry

• fvm/src/executor/telemetry.rs
  • Add ReservationTelemetry and helpers:
    • Track:
      • reservations_open
      • reservation_begin_failed
      • settle_basefee_burn
      • settle_tip_credit
      • settle_overburn
      • settle_refund_virtual
      • Per‑sender reservation totals and remaining amounts.
  • Expose snapshot() (for potential host export) and reset() under #[cfg(test)].

Kernel and test harness adjustments

• fvm/src/kernel/default.rs

  • Plumb the updated CallManager type where necessary so that all value‑moving operations (SendOps, SELFDESTRUCT, etc.) route through the reservation‑aware transfer.

• fvm/tests/dummy.rs

  • Update the dummy CallManager impl to accept the new ReservationSession argument in CallManager::new, keeping tests compiling against the updated trait.

Tests

• Unit tests in fvm/src/executor/default.rs:

  • Session lifecycle: empty plan, begin twice, end with non‑zero remainder, plan too large, unknown actors.
  • Preflight behaviour under reservations:
    • Coverage assertion, no balance deduction.
    • Under‑reserved ledger → ReservationError::Overflow.
  • Transfer enforcement:
    • transfer, send to existing actors, SELFDESTRUCT, and implicit sends must respect free balance.
  • Settlement invariants:
    • Net sender delta equals consumption.
    • Reservation ledger clears so end_reservation_session succeeds.
  • Gas output property test (with --features arb) continues to assert:
    • All components non‑negative.
    • base_fee_burn + over_estimation_burn + refund + miner_tip == gas_cost.

• Integration tests:

  • testing/integration/tests/reservation_transfer_enforcement.rs:
    • Uses the integration tester to exercise reservation mode and confirm that:
      • Sends and actor creation fail when value > free = balance − reserved_remaining.
      • Failed transfers do not credit receivers.

Activation and host behaviour

• ref‑fvm does not contain any network‑version logic for reservations.
• Hosts (e.g., Lotus) control:
  • When to call begin_reservation_session / end_reservation_session.
  • How to treat ReservationError variants (legacy fallback, tipset invalid, node error) based on network version and feature flags.

Notes

• This PR is designed to preserve receipts (ExitCode, GasUsed, events) and GasOutputs relative to pre‑reservation behaviour, while removing miner exposure to intra‑tipset underfunded messages when hosts enable reservations.

[snissn]

relevant PRs:

#2236
filecoin-project/lotus#13427
filecoin-project/filecoin-ffi#554

[codecov-commenter]

Codecov Report

❌ Patch coverage is 89.09091% with 132 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.90%. Comparing base (71c2f8c) to head (fc0efc9).
⚠️ Report is 5 commits behind head on master.

Files with missing lines	Patch %	Lines
fvm/src/executor/default.rs	89.32%	121 Missing ⚠️
fvm/src/call_manager/default.rs	77.14%	8 Missing ⚠️
fvm/src/executor/telemetry.rs	91.42%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2236      +/-   ##
==========================================
+ Coverage   77.58%   78.90%   +1.31%     
==========================================
  Files         147      148       +1     
  Lines       15789    16979    +1190     
==========================================
+ Hits        12250    13397    +1147     
- Misses       3539     3582      +43     

Files with missing lines	Coverage Δ
fvm/src/call_manager/mod.rs	83.33% <ø> (ø)
fvm/src/executor/mod.rs	93.93% <ø> (+72.72%)	⬆️
fvm/src/kernel/default.rs	82.26% <100.00%> (+0.02%)	⬆️
fvm/src/executor/telemetry.rs	91.42% <91.42%> (ø)
fvm/src/call_manager/default.rs	89.53% <77.14%> (-0.52%)	⬇️
fvm/src/executor/default.rs	88.19% <89.32%> (+10.47%)	⬆️

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull Request Overview

This PR implements engine-managed tipset-scope gas reservations in ref-fvm to prevent miners from being exposed to intra-tipset underfunded messages. The implementation adds a reservation session ledger that tracks per-actor gas commitments throughout tipset execution, with settlement realizing refunds through reservation release rather than direct balance transfers.

Key changes:

• Add ReservationSession ledger and lifecycle methods (begin_reservation_session/end_reservation_session) with affordability checks
• Modify preflight to assert coverage without pre-deducting funds in reservation mode
• Enforce transfer restrictions against free balance (balance - reserved_remaining)
• Update settlement to net-charge gas costs and realize refunds via reservation release
• Add reservation telemetry tracking and comprehensive test coverage

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
fvm/src/executor/mod.rs	Defines ReservationError enum and re-exports ReservationSession struct for public API
fvm/src/executor/default.rs	Core implementation of reservation session lifecycle, preflight validation, settlement logic, and extensive unit tests
fvm/src/executor/telemetry.rs	New telemetry module for tracking reservation metrics using global singleton with per-sender gauges
fvm/src/call_manager/mod.rs	Updates CallManager::new trait signature to accept ReservationSession parameter
fvm/src/call_manager/default.rs	Implements reservation-aware transfer enforcement by checking free balance against reserved amounts
fvm/src/kernel/default.rs	Minor formatting change to self-destruct error handling to route through reservation-aware transfer
fvm/tests/dummy.rs	Updates dummy CallManager implementation to accept new ReservationSession argument
testing/integration/tests/reservation_transfer_enforcement.rs	New integration tests verifying reservation enforcement for sends and actor creation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[snissn]

@copilot can you run a new review?

[Copilot]

@snissn I've opened a new pull request, #2242, to work on those changes. Once the pull request is ready, I'll request review from you.

[snissn]

( ok review requests from co_pilot can be initiated by clicking an icon next to their name in the reviewers box in the top right corner)

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.