c

.env.example

@@ -0,0 +1,9 @@
+SHAPE_SEPOLIA_RPC_URL=https://shape-sepolia.g.alchemy.com/v2/YOUR_KEY
+GASBACK_ADDRESS=0x21e34c5bea9253CDCd57671A1970BB31df4aBe83
+SPLITTER_ADDRESS=0x658E643b379b52Cd21605bFaF9C81e84713d8427
+GASBACK_TEST_CALLER_ADDRESS=0xA53D127f193858f5ef2Cf50dd1B3A94198ef811d
+GASBACK_LIVE_PROBE_ADDRESS=
+PRIVATE_KEY=
+MAX_WEI_SPEND=1000000000000000
+MAX_GAS_TO_BURN=120000
+REPORT_PATH=gasback-live-report.json

.github/workflows/ci.yml

@@ -5,12 +5,22 @@ on:
     branches: [main]
     paths:
       - '**.sol'
+      - '**.ts'
       - '**.yml'
+      - '.env.example'
+      - 'bun.lock'
+      - 'package.json'
+      - 'tsconfig.json'
   push:
     branches: [main]
     paths:
       - '**.sol'
+      - '**.ts'
       - '**.yml'
+      - '.env.example'
+      - 'bun.lock'
+      - 'package.json'
+      - 'tsconfig.json'
 jobs:
   tests:
     name: Forge Testing
@@ -34,12 +44,44 @@ jobs:
       - name: Run Tests with ${{ matrix.profile }}
         run: >
           ( [ "${{ matrix.profile }}" = "regular" ] &&
-            forge test
+            forge test --disable-labels
           ) ||
           ( [ "${{ matrix.profile }}" = "intense" ] &&
-            forge test --fuzz-runs 5000
+            forge test --disable-labels --fuzz-runs 5000
           )
 
+  gasback-live-system:
+    name: Gasback live system checks
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: nightly
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.9
+
+      - name: Install Foundry Dependencies
+        run: forge install
+
+      - name: Install TypeScript Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run TypeScript Tests
+        run: bun run lint
+
+      - name: Run Local Gasback Suite
+        run: bun run gasback:local
+
+      - name: Run Fork Gasback Suite
+        run: bun run gasback:fork
+
   codespell:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -57,4 +99,3 @@ jobs:
           check_filenames: true
           ignore_words_list: usera
           skip: ./.git,package-lock.json,ackee-blockchain-solady-report.pdf,EIP712Mock.sol
-

.gitignore

@@ -40,4 +40,8 @@ wake-coverage.cov
 create2
 
 # Coverage report
-report
+report
+
+# Gasback live test reports
+gasback-live-report.json
+gasback-live-report.*.json

README.md

@@ -8,33 +8,37 @@ A barebones implementation of a gasback contract that implements [RIP-7767](http
 
 - The `baseFeeVault` is deployed at `0x4200000000000000000000000000000000000019`.
 - The `WITHDRAWAL_NETWORK` of the `baseFeeVault` is set to `1`.
+- The `baseFeeVault` recipient is set to `ShapePaymentSplitter`.
+- `Gasback` receives only its configured share from `ShapePaymentSplitter`.
 
 ### Via script
 
-See `script/Delegate7702.s.sol` for an automated script that can help you deploy.
+See `script/DeployGasback.s.sol` and `script/DeployShapePaymentSplitter.s.sol` for deployment scripts.
 
-This script requires you to have the private key of the `baseFeeVault` recipient in your environment.
+These scripts require you to have `PRIVATE_KEY` in your environment.
 
 For more information on how to run a foundry script, see `https://getfoundry.sh/guides/scripting-with-solidity`.
 
 ### Manual steps
 
-1. Deploy the `gasback` contract which will be used as an implementation via EIP-7702.
+1. Deploy the `Gasback` contract.
 
-2. Use EIP-7702 to make the EOA `RECIPIENT` of the `baseFeeVault` delegated to the `gasback` implementation.  
-   After delegating, use the EOA to call functions on itself to initialize the parameters:
-
+2. Deploy `ShapePaymentSplitter` with `Gasback` as one of the payees.
+
+3. Set the `baseFeeVault` recipient to the deployed `ShapePaymentSplitter`.
+
+4. Configure `Gasback` via authorized calls:
+
+   - `setBaseFeeVault(address)`  
+     `0x4200000000000000000000000000000000000019`
+   - `setBaseFeeVaultShareNumerator(uint256)`  
+     `600000000000000000` (`0.6 ether`) and ensure it matches the splitter allocation for `Gasback`.
    - `setGasbackRatioNumerator(uint256)`  
-     `900000000000000000`
+     Must be less than or equal to `setBaseFeeVaultShareNumerator`.
    - `setGasbackMaxBaseFee(uint256)`  
      `115792089237316195423570985008687907853269984665640564039457584007913129639935`  
-   - `setBaseFeeVault(address)`  
-     `0x4200000000000000000000000000000000000019`
 
-4. Put or leave some ETH into the EOA `RECIPIENT`, which will be the actual `gasback` contract. 
-   The ETH will act as a buffer that will be temporarily dished out to contracts calling the EOA `RECIPIENT` in the span of a single block.
+5. Put or leave some ETH in `Gasback`.
+   The ETH acts as a buffer that is temporarily dished out to contracts calling `Gasback` in the span of a single block.
    The base fees collected in a block will only be accrued into the `baseFeeVault` at the end of a block.
-   Try not to empty ETH from the `RECIPIENT` when you are actually taking out ETH from it.
-
-5. For better discoverabiity (for the devX), deploy the `gasbackBeacon` and use the system address to set the EOA `RECIPIENT`.  
-   The exact CREATE2 instructions are in [`./deployments.md`](./deployments.md).
+   Try not to empty ETH from `Gasback` while actively serving gasback payouts.

foundry.toml

@@ -4,7 +4,7 @@
 
 # The Default Profile
 [profile.default]
-solc_version = "0.8.30"
+solc_version = "0.8.28"
 evm_version = "prague"
 auto_detect_solc = false
 optimizer = true

live/gasback-live.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from "bun:test";
+import {
+    DENOMINATOR,
+    assertSpendWithinBudget,
+    buildCanaryGasValues,
+    computeOracle,
+    parseWei,
+    normalizePrivateKeyInput,
+    receiptFee,
+    stringifyReport,
+} from "./gasback-live";
+import type { TransactionReceipt } from "viem";
+
+describe("gasback oracle", () => {
+    test("computes payout and accrued delta with integer rounding", () => {
+        const result = computeOracle({
+            gasToBurn: 333n,
+            baseFee: 100n,
+            ratioNumerator: 600_000_000_000_000_000n,
+            shareNumerator: 700_000_000_000_000_000n,
+            maxBaseFee: 1_000n,
+            gasbackBalanceBefore: 1_000_000n,
+        });
+
+        expect(result.ethFromGas).toBe(33_300n);
+        expect(result.expectedPayout).toBe(19_980n);
+        expect(result.expectedShare).toBe(23_310n);
+        expect(result.expectedAccruedDelta).toBe(3_330n);
+        expect(result.passThrough).toBe(false);
+    });
+
+    test("passes through when base fee exceeds max", () => {
+        const result = computeOracle({
+            gasToBurn: 30_000n,
+            baseFee: 101n,
+            ratioNumerator: DENOMINATOR,
+            shareNumerator: DENOMINATOR,
+            maxBaseFee: 100n,
+            gasbackBalanceBefore: 3_030_000n,
+        });
+
+        expect(result.expectedPayout).toBe(0n);
+        expect(result.expectedAccruedDelta).toBe(0n);
+        expect(result.passThrough).toBe(true);
+    });
+
+    test("passes through when the local gasback buffer is insufficient", () => {
+        const result = computeOracle({
+            gasToBurn: 30_000n,
+            baseFee: 100n,
+            ratioNumerator: DENOMINATOR,
+            shareNumerator: DENOMINATOR,
+            maxBaseFee: 100n,
+            gasbackBalanceBefore: 2_999_999n,
+        });
+
+        expect(result.expectedPayout).toBe(0n);
+        expect(result.expectedAccruedDelta).toBe(0n);
+        expect(result.passThrough).toBe(true);
+    });
+});
+
+describe("canary guards", () => {
+    test("selects zero, small, and bounded medium canaries", () => {
+        expect(buildCanaryGasValues(120_000n)).toEqual([0n, 30_000n, 120_000n]);
+        expect(buildCanaryGasValues(30_000n)).toEqual([0n, 30_000n]);
+        expect(buildCanaryGasValues(1n)).toEqual([0n]);
+    });
+
+    test("parses decimal and hex wei values", () => {
+        expect(parseWei("123", "VALUE")).toBe(123n);
+        expect(parseWei("0x10", "VALUE")).toBe(16n);
+        expect(() => parseWei("", "VALUE")).toThrow("VALUE is empty");
+        expect(() => parseWei("-1", "VALUE")).toThrow("VALUE must be non-negative");
+        expect(() => parseWei("1.2", "VALUE")).toThrow("VALUE must be a decimal or hex integer");
+    });
+
+    test("normalizes private keys without accepting malformed input", () => {
+        const raw = "1".repeat(64);
+        expect(normalizePrivateKeyInput(raw)).toBe(`0x${raw}`);
+        expect(normalizePrivateKeyInput(`0x${raw}`)).toBe(`0x${raw}`);
+        expect(() => normalizePrivateKeyInput("0x1")).toThrow("PRIVATE_KEY must be 32 bytes");
+    });
+
+    test("rejects estimated spend over the remaining budget", () => {
+        expect(() => assertSpendWithinBudget(10n, 10n, "case")).not.toThrow();
+        expect(() => assertSpendWithinBudget(11n, 10n, "case")).toThrow(
+            "case estimated cost 11 exceeds remaining budget 10",
+        );
+    });
+});
+
+describe("reporting", () => {
+    test("serializes bigint values as strings", () => {
+        expect(stringifyReport({ value: 1n })).toBe('{\n  "value": "1"\n}');
+    });
+
+    test("adds OP Stack fee fields to execution fees when present", () => {
+        const receipt = {
+            gasUsed: 10n,
+            effectiveGasPrice: 20n,
+            l1Fee: "0x64",
+        } as unknown as TransactionReceipt;
+        expect(receiptFee(receipt)).toEqual({
+            executionFee: 200n,
+            extraReceiptFee: 100n,
+            totalFee: 300n,
+        });
+    });
+});