feat: EIP-8037 — state gas reservoir model (Amsterdam) (#14)

* feat: EIP-8037 state gas reservoir model + EIP-7778 + EIP-7825 (rebase)

Signed-off-by: garyschulte <garyschulte@gmail.com>

Author: Gabriel-Trintinalia

src/bytecode/main.zig

@@ -226,9 +226,6 @@ pub const BASEFEE: u8 = 0x48;
 pub const BLOBHASH: u8 = 0x49;
 pub const BLOBBASEFEE: u8 = 0x4A;
 pub const SLOTNUM: u8 = 0x4B;
-pub const DUPN: u8 = 0xE6;
-pub const SWAPN: u8 = 0xE7;
-pub const EXCHANGE: u8 = 0xE8;
 pub const POP: u8 = 0x50;
 pub const MLOAD: u8 = 0x51;
 pub const MSTORE: u8 = 0x52;
@@ -314,6 +311,9 @@ pub const LOG1: u8 = 0xA1;
 pub const LOG2: u8 = 0xA2;
 pub const LOG3: u8 = 0xA3;
 pub const LOG4: u8 = 0xA4;
+pub const DUPN: u8 = 0xE6;
+pub const SWAPN: u8 = 0xE7;
+pub const EXCHANGE: u8 = 0xE8;
 pub const CREATE: u8 = 0xF0;
 pub const CALL: u8 = 0xF1;
 pub const CALLCODE: u8 = 0xF2;

src/handler/call_integration_tests.zig

@@ -118,6 +118,7 @@ test "SSTORE EIP-2200: fails when gas_remaining <= 2300 (Istanbul+)" {
         .gas_limit = 2300,
         .scheme = .call,
         .is_static = false,
+        .reservoir = 0,
     });
     try std.testing.expect(!result.success);
 }
@@ -149,6 +150,7 @@ test "SSTORE EIP-2200: succeeds with sufficient gas" {
         .gas_limit = 50_000,
         .scheme = .call,
         .is_static = false,
+        .reservoir = 0,
     });
     try std.testing.expect(result.success);
 }
@@ -188,6 +190,7 @@ test "gas refund propagation: SSTORE clear in sub-call surfaces in CallResult" {
         .gas_limit = 100_000,
         .scheme = .call,
         .is_static = false,
+        .reservoir = 0,
     });
 
     try std.testing.expect(result.success);

src/handler/main.zig

@@ -35,8 +35,13 @@ pub const ValidationError = validation.ValidationError;
 pub const ExecutionResult = struct {
     /// Execution status
     status: ExecutionStatus,
-    /// Gas used (final, after refund capping and floor enforcement)
+    /// Gas used for receipt cumulativeGasUsed (= regular + state for Amsterdam+).
     gas_used: u64,
+    /// EIP-8037 (Amsterdam+): gas used for block gas limit = max(regular, state).
+    /// Equals gas_used for pre-Amsterdam.
+    block_gas_used: u64,
+    /// EIP-8037 (Amsterdam+): total state gas charged during execution.
+    state_gas_used: u64,
     /// Gas refunded (final capped refund, set in postExecution)
     gas_refunded: u64,
     /// Logs emitted during execution
@@ -51,6 +56,8 @@ pub const ExecutionResult = struct {
         return ExecutionResult{
             .status = status,
             .gas_used = gas_used,
+            .block_gas_used = gas_used,
+            .state_gas_used = 0,
             .gas_refunded = 0,
             .logs = std.ArrayList(primitives.Log){},
             .return_data = @constCast(&[_]u8{}),
@@ -135,6 +142,9 @@ pub const FrameResult = struct {
     gas_remaining: u64,
     /// Raw refund counter from interpreter (before capping)
     gas_refunded: i64,
+    /// EIP-8037 (Amsterdam+): state gas reservoir remaining after execution.
+    /// Used in gasUsed formula: gas_used = tx.gas_limit - gas_remaining - reservoir_remaining.
+    reservoir_remaining: u64,
     /// Memory
     memory: interpreter.Memory,
     /// Stack
@@ -146,6 +156,7 @@ pub const FrameResult = struct {
             .result = result,
             .gas_remaining = gas_remaining,
             .gas_refunded = gas_refunded,
+            .reservoir_remaining = 0,
             .memory = interpreter.Memory.new(),
             .stack = interpreter.Stack.new(),
         };
@@ -305,14 +316,17 @@ pub const Frame = struct {
 
         const gas_used = self.interpreter.gas.getSpent();
         const gas_refunded = self.interpreter.gas.refunded;
+        const state_gas_used = self.interpreter.gas.state_gas_used;
         const status: ExecutionStatus = switch (self.interpreter.result) {
             .stop, .@"return", .selfdestruct => .Success,
             .revert => .Revert,
             else => .Halt,
         };
 
+        var exec_result = ExecutionResult.new(status, gas_used);
+        exec_result.state_gas_used = state_gas_used;
         return FrameResult.new(
-            ExecutionResult.new(status, gas_used),
+            exec_result,
             self.interpreter.gas.remaining,
             gas_refunded,
         );

src/handler/mainnet_builder.zig

@@ -84,6 +84,7 @@ test "precompile dispatch: IDENTITY returns input unchanged" {
         .gas_limit = 100_000,
         .scheme = .call,
         .is_static = false,
+        .reservoir = 0,
     });
 
     try std.testing.expect(result.success);
@@ -115,6 +116,7 @@ test "precompile dispatch: IDENTITY with no data returns empty" {
         .gas_limit = 100_000,
         .scheme = .call,
         .is_static = false,
+        .reservoir = 0,
     });
 
     try std.testing.expect(result.success);
@@ -145,6 +147,7 @@ test "precompile dispatch: out-of-gas fails and consumes all gas" {
         .gas_limit = 10, // not enough
         .scheme = .call,
         .is_static = false,
+        .reservoir = 0,
     });
 
     try std.testing.expect(!result.success);
@@ -174,6 +177,7 @@ test "precompile dispatch: null precompiles falls back to interpreter (no precom
         .gas_limit = 100_000,
         .scheme = .call,
         .is_static = false,
+        .reservoir = 0,
     });
 
     // Without precompile dispatch, IDENTITY address is an empty contract (STOP)

src/handler/precompile_dispatch_tests.zig

@@ -3,16 +3,21 @@ const primitives = @import("primitives");
 const context = @import("context");
 const state = @import("state");
 const main = @import("main.zig");
+const interpreter_mod = @import("interpreter");
 
 // Gas constants for intrinsic gas calculation
 const TX_BASE_COST: u64 = 21000;
 const TX_CREATE_COST: u64 = 32000;
+// EIP-8037 (Amsterdam+): reduced regular CREATE cost
+const TX_CREATE_COST_AMSTERDAM: u64 = 9000;
 const CALLDATA_ZERO_BYTE_COST: u64 = 4;
 const CALLDATA_NONZERO_BYTE_COST: u64 = 16;
 const ACCESS_LIST_ADDRESS_COST: u64 = 2400;
 const ACCESS_LIST_STORAGE_KEY_COST: u64 = 1900;
 // EIP-7702: per-authorization intrinsic gas (PER_EMPTY_ACCOUNT_COST per EIP-7702 spec)
 const TX_EIP7702_AUTH_COST: u64 = 25000;
+// EIP-8037 (Amsterdam+): reduced regular per-auth cost
+const TX_EIP7702_AUTH_COST_AMSTERDAM: u64 = 7500;
 // EIP-7623: token costs (different from calldata gas costs)
 const FLOOR_ZERO_TOKEN_COST: u64 = 1;
 const FLOOR_NONZERO_TOKEN_COST: u64 = 4;
@@ -92,20 +97,20 @@ pub const Validation = struct {
         const tx = &ctx.tx;
         const spec = ctx.cfg.spec;
 
-        // EIP-3860 (Shanghai+): initcode size limit for CREATE transactions
-        // EIP-7954 (Amsterdam+): limit doubled to 65536
+        // EIP-3860 (Shanghai+): initcode size limit for CREATE transactions.
+        // EIP-7954 (Amsterdam+): max code size doubles to 32768, so max initcode = 65536.
         if (primitives.isEnabledIn(spec, .shanghai)) {
             if (tx.kind == .Create) {
-                const calldata_len = if (tx.data) |d| d.items.len else 0;
                 const max_initcode: usize = if (primitives.isEnabledIn(spec, .amsterdam)) primitives.AMSTERDAM_MAX_INITCODE_SIZE else primitives.MAX_INITCODE_SIZE;
+                const calldata_len = if (tx.data) |d| d.items.len else 0;
                 if (calldata_len > max_initcode) {
                     return ValidationError.CreateInitcodeOverLimit;
                 }
             }
         }
 
         // Calculate initial gas cost
-        const initial_gas = calculateInitialGas(tx, spec);
+        const initial_gas = calculateInitialGas(tx, spec, ctx.block.gas_limit);
 
         // Calculate floor gas exec-portion (EIP-7623: tokens * 10, only calldata tokens).
         // Returns 0 if EIP-7623 is disabled via cfg flag.
@@ -125,9 +130,26 @@ pub const Validation = struct {
             }
         }
 
+        // EIP-8037 (Amsterdam+): compute the state gas portion of the intrinsic cost.
+        // This is needed to compute gasUsed = max(regular_gas, state_gas) for receipts.
+        var initial_state_gas: u64 = 0;
+        if (primitives.isEnabledIn(spec, .amsterdam)) {
+            const gas_costs = interpreter_mod.gas_costs;
+            const cpsb = gas_costs.costPerStateByte(ctx.block.gas_limit);
+            if (tx.kind == .Create) {
+                initial_state_gas += gas_costs.STATE_BYTES_PER_NEW_ACCOUNT * cpsb;
+            }
+            // EIP-7702: auth list state gas — 135*cpsb per auth (base 23 + new-account 112)
+            if (tx.authorization_list) |auth_list| {
+                const num_auths: u64 = @intCast(auth_list.items.len);
+                initial_state_gas += num_auths * ((gas_costs.STATE_BYTES_PER_AUTH_BASE + gas_costs.STATE_BYTES_PER_NEW_ACCOUNT) * cpsb);
+            }
+        }
+
         return InitialAndFloorGas{
             .initial_gas = initial_gas,
             .floor_gas = floor_gas,
+            .initial_state_gas = initial_state_gas,
         };
     }
 
@@ -258,18 +280,28 @@ pub const Validation = struct {
     ///
     /// Breakdown:
     ///   21,000 base (always)
-    /// + 32,000 for CREATE transactions
+    /// + 32,000 for CREATE transactions (pre-Amsterdam) or 9,000 + 112*cpsb (Amsterdam+)
     /// + 4 per zero calldata byte, 16 per non-zero calldata byte
     /// + 2,400 per access-list address, 1,900 per access-list storage slot
-    /// + 25,000 per EIP-7702 authorization list entry (PER_EMPTY_ACCOUNT_COST, Prague+)
+    /// + 25,000 per EIP-7702 authorization list entry (pre-Amsterdam) or 7,500 + 135*cpsb (Amsterdam+)
     /// + GAS_PER_BLOB per EIP-4844 blob hash
-    pub fn calculateInitialGas(tx: *const context.TxEnv, spec: primitives.SpecId) u64 {
+    pub fn calculateInitialGas(tx: *const context.TxEnv, spec: primitives.SpecId, block_gas_limit: u64) u64 {
+        const gas_costs = interpreter_mod.gas_costs;
+        const cpsb: u64 = if (primitives.isEnabledIn(spec, .amsterdam))
+            gas_costs.costPerStateByte(block_gas_limit)
+        else
+            0;
         var gas: u64 = TX_BASE_COST;
 
         // CREATE adds extra base cost (EIP-2, Homestead+).
-        // Frontier does NOT charge G_TXCREATE (32000) for CREATE transactions.
+        // Frontier does NOT charge G_TXCREATE for CREATE transactions.
+        // EIP-8037 (Amsterdam+): regular CREATE cost drops to 9000; state gas (112*cpsb) added.
         if (tx.kind == .Create and primitives.isEnabledIn(spec, .homestead)) {
-            gas += TX_CREATE_COST;
+            if (primitives.isEnabledIn(spec, .amsterdam)) {
+                gas += TX_CREATE_COST_AMSTERDAM + gas_costs.STATE_BYTES_PER_NEW_ACCOUNT * cpsb;
+            } else {
+                gas += TX_CREATE_COST;
+            }
         }
 
         // Calldata costs:
@@ -310,9 +342,16 @@ pub const Validation = struct {
         // Blob fees are deducted in validateAgainstStateAndDeductCaller.
 
         // EIP-7702: authorization list intrinsic gas (Prague+)
+        // EIP-8037 (Amsterdam+): per-auth cost = 7500 regular + 135*cpsb state (= 23+112 state bytes)
         if (primitives.isEnabledIn(spec, .prague)) {
             if (tx.authorization_list) |auth_list| {
-                gas += @as(u64, auth_list.items.len) * TX_EIP7702_AUTH_COST;
+                const num_auths: u64 = @intCast(auth_list.items.len);
+                if (primitives.isEnabledIn(spec, .amsterdam)) {
+                    const per_auth = TX_EIP7702_AUTH_COST_AMSTERDAM + (gas_costs.STATE_BYTES_PER_AUTH_BASE + gas_costs.STATE_BYTES_PER_NEW_ACCOUNT) * cpsb;
+                    gas += num_auths * per_auth;
+                } else {
+                    gas += num_auths * TX_EIP7702_AUTH_COST;
+                }
             }
         }
 
@@ -425,6 +464,13 @@ pub const InitialAndFloorGas = struct {
     /// 25,000 (PER_EMPTY_ACCOUNT_COST) added for each valid authorization that sets code.
     /// Applied in postExecution with the standard 1/5 cap against total gas used.
     auth_refund: i64 = 0,
+    /// EIP-8037 (Amsterdam+): state gas portion of the intrinsic cost.
+    /// For CREATE: STATE_BYTES_PER_NEW_ACCOUNT * CPSB.
+    /// For EIP-7702 auth entries: (STATE_BYTES_PER_AUTH_BASE + STATE_BYTES_PER_NEW_ACCOUNT) * CPSB per auth.
+    initial_state_gas: u64 = 0,
+    /// EIP-8037 (Amsterdam+): state gas refunded for valid auths to existing accounts.
+    /// 112*cpsb per valid auth applied to an existing (non-empty) account. Bypasses 1/5 cap.
+    auth_state_refund: u64 = 0,
 };
 
 /// Validation errors

src/handler/validation.zig

@@ -19,15 +19,15 @@ const InitialAndFloorGas = validation.InitialAndFloorGas;
 test "intrinsic gas: base CALL = 21000" {
     var tx = context.TxEnv.default();
     defer tx.deinit();
-    const gas = Validation.calculateInitialGas(&tx, primitives.SpecId.prague);
+    const gas = Validation.calculateInitialGas(&tx, primitives.SpecId.prague, 120_000_000);
     try std.testing.expectEqual(@as(u64, 21000), gas);
 }
 
-test "intrinsic gas: CREATE adds 32000" {
+test "intrinsic gas: CREATE adds 32000 (pre-Amsterdam)" {
     var tx = context.TxEnv.default();
     defer tx.deinit();
     tx.kind = context.TxKind.Create;
-    const gas = Validation.calculateInitialGas(&tx, primitives.SpecId.prague);
+    const gas = Validation.calculateInitialGas(&tx, primitives.SpecId.prague, 120_000_000);
     try std.testing.expectEqual(@as(u64, 21000 + 32000), gas);
 }
 
@@ -38,7 +38,7 @@ test "intrinsic gas: zero byte costs 4, nonzero costs 16" {
     try data.append(std.heap.c_allocator, 0x00); // 4 gas
     try data.append(std.heap.c_allocator, 0xFF); // 16 gas
     tx.data = data;
-    const gas = Validation.calculateInitialGas(&tx, primitives.SpecId.prague);
+    const gas = Validation.calculateInitialGas(&tx, primitives.SpecId.prague, 120_000_000);
     try std.testing.expectEqual(@as(u64, 21000 + 4 + 16), gas);
 }
 

src/handler/validation_tests.zig

@@ -5,10 +5,15 @@ const primitives = @import("primitives");
 pub const Gas = struct {
     /// The initial gas limit. This is constant throughout execution.
     limit: u64,
-    /// The remaining gas.
+    /// The remaining regular gas.
     remaining: u64,
     /// Refunded gas. This is used only at the end of execution.
     refunded: i64,
+    /// EIP-8037 (Amsterdam+): total state gas charged during this frame.
+    state_gas_used: u64,
+    /// EIP-8037 (Amsterdam+): state gas reservoir (state_gas_left).
+    /// State gas charges draw from here first, then spill into `remaining`.
+    reservoir: u64,
     /// Memoisation of values for memory expansion cost.
     memory: MemoryGas,
 
@@ -18,6 +23,8 @@ pub const Gas = struct {
             .limit = limit,
             .remaining = limit,
             .refunded = 0,
+            .state_gas_used = 0,
+            .reservoir = 0,
             .memory = MemoryGas.new(),
         };
     }
@@ -28,6 +35,8 @@ pub const Gas = struct {
             .limit = limit,
             .remaining = 0,
             .refunded = 0,
+            .state_gas_used = 0,
+            .reservoir = 0,
             .memory = MemoryGas.new(),
         };
     }
@@ -78,6 +87,28 @@ pub const Gas = struct {
         return true;
     }
 
+    /// EIP-8037 (Amsterdam+): Charge state gas.
+    /// Draws from the reservoir first; spills the remainder into `remaining`.
+    /// Returns false (OOG) if neither pool has enough gas.
+    pub fn spendStateGas(self: *Gas, amount: u64) bool {
+        if (self.reservoir >= amount) {
+            self.reservoir -= amount;
+        } else if (self.reservoir +| self.remaining >= amount) {
+            const spill = amount - self.reservoir;
+            self.reservoir = 0;
+            self.remaining -= spill;
+        } else {
+            return false;
+        }
+        self.state_gas_used +|= amount;
+        return true;
+    }
+
+    /// EIP-8037: Add state gas from a successful sub-frame.
+    pub fn addStateGasFromChild(self: *Gas, child_state_gas: u64) void {
+        self.state_gas_used += child_state_gas;
+    }
+
     /// Spend all remaining gas
     pub fn spendAll(self: *Gas) void {
         self.remaining = 0;