From 028c189d468a0c7e16d7d291f44cd27cb46e8ac6 Mon Sep 17 00:00:00 2001
From: teddy <teddy@defi.sucks>
Date: Fri, 1 Nov 2024 10:56:55 -0300
Subject: [PATCH] test: medusa testing campaign (#4)

---
 .github/workflows/medusa.yml                  |   29 +
 .../contracts/L1/winddown/BalanceClaimer.sol  |    2 +-
 .../contracts/test/BondManager.t.sol          |    2 +-
 .../contracts/test/L1StandardBridge.t.sol     |    2 +-
 .../contracts/test/SafeCall.t.sol             |    6 +-
 .../contracts/test/invariants/PROPERTIES.md   |   52 +
 .../invariants/balance-claimer/FuzzTest.t.sol |    8 +
 .../balance-claimer/generate-random-tree.sh   |   54 +
 .../handlers/guided/BalanceClaimer.t.sol      |   26 +
 .../handlers/unguided/BalanceClaimer.t.sol    |   51 +
 .../properties/BalanceClaimer.t.sol           |   23 +
 .../setup/BalanceClaimer.t.sol                |   66 ++
 .../balance-claimer/setup/ClaimList.t.sol     | 1025 +++++++++++++++++
 .../balance-claimer/setup/Claims.t.sol        |   91 ++
 .../balance-claimer/setup/Tokens.t.sol        |   30 +
 packages/contracts-bedrock/foundry.toml       |    5 +
 packages/contracts-bedrock/medusa.json        |   89 ++
 packages/contracts-bedrock/package.json       |    3 +-
 yarn.lock                                     |    8 +-
 19 files changed, 1561 insertions(+), 11 deletions(-)
 create mode 100644 .github/workflows/medusa.yml
 create mode 100644 packages/contracts-bedrock/contracts/test/invariants/PROPERTIES.md
 create mode 100644 packages/contracts-bedrock/contracts/test/invariants/balance-claimer/FuzzTest.t.sol
 create mode 100755 packages/contracts-bedrock/contracts/test/invariants/balance-claimer/generate-random-tree.sh
 create mode 100644 packages/contracts-bedrock/contracts/test/invariants/balance-claimer/handlers/guided/BalanceClaimer.t.sol
 create mode 100644 packages/contracts-bedrock/contracts/test/invariants/balance-claimer/handlers/unguided/BalanceClaimer.t.sol
 create mode 100644 packages/contracts-bedrock/contracts/test/invariants/balance-claimer/properties/BalanceClaimer.t.sol
 create mode 100644 packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/BalanceClaimer.t.sol
 create mode 100644 packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/ClaimList.t.sol
 create mode 100644 packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/Claims.t.sol
 create mode 100644 packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/Tokens.t.sol
 create mode 100644 packages/contracts-bedrock/medusa.json

diff --git a/.github/workflows/medusa.yml b/.github/workflows/medusa.yml
new file mode 100644
index 000000000000..f4676c7ba487
--- /dev/null
+++ b/.github/workflows/medusa.yml
@@ -0,0 +1,29 @@
+name: CI
+
+on: [push]
+
+jobs:
+  medusa-tests:
+    name: Medusa Test
+    runs-on: ubuntu-latest
+    container: ghcr.io/defi-wonderland/eth-security-toolbox-ci:dev
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup Node.js 16.x
+        uses: actions/setup-node@master
+        with:
+          node-version: 16.x
+          cache: yarn
+
+      - name: Install dependencies
+        working-directory: ./packages/contracts-bedrock
+        run: yarn --frozen-lockfile --network-concurrency 1
+
+      - name: Run Medusa
+        working-directory: ./packages/contracts-bedrock
+        run: medusa fuzz --test-limit 200000
diff --git a/packages/contracts-bedrock/contracts/L1/winddown/BalanceClaimer.sol b/packages/contracts-bedrock/contracts/L1/winddown/BalanceClaimer.sol
index 8fb3f34aa7bb..b4b208f13ad6 100644
--- a/packages/contracts-bedrock/contracts/L1/winddown/BalanceClaimer.sol
+++ b/packages/contracts-bedrock/contracts/L1/winddown/BalanceClaimer.sol
@@ -74,4 +74,4 @@ contract BalanceClaimer is Semver, IBalanceClaimer {
 
         _canClaimTokens = MerkleProof.verify(_proof, ROOT, _leaf);
     }
-}
\ No newline at end of file
+}
diff --git a/packages/contracts-bedrock/contracts/test/BondManager.t.sol b/packages/contracts-bedrock/contracts/test/BondManager.t.sol
index 8cae49c28fa7..994cbbe4d842 100644
--- a/packages/contracts-bedrock/contracts/test/BondManager.t.sol
+++ b/packages/contracts-bedrock/contracts/test/BondManager.t.sol
@@ -325,7 +325,7 @@ contract BondManager_Test is Test {
         unchecked {
             vm.assume(block.timestamp + minClaimHold > minClaimHold);
         }
-        assumeNoPrecompiles(owner);
+        assumeNotPrecompile(owner);
 
         // Post the bond
         vm.deal(address(this), amount);
diff --git a/packages/contracts-bedrock/contracts/test/L1StandardBridge.t.sol b/packages/contracts-bedrock/contracts/test/L1StandardBridge.t.sol
index e042ea5a9c0b..10011c08265d 100644
--- a/packages/contracts-bedrock/contracts/test/L1StandardBridge.t.sol
+++ b/packages/contracts-bedrock/contracts/test/L1StandardBridge.t.sol
@@ -742,7 +742,7 @@ contract L1StandardBridge_WithdrawErc20Balance_Test is Bridge_Initializer {
     {
         uint8 _claimArraySize;
         for (uint256 _i; _i < _fuzzBalances.length; _i++) {
-            assumeNoPrecompiles(_fuzzBalances[_i].token);
+            assumeNotPrecompile(_fuzzBalances[_i].token);
             if (_fuzzBalances[_i].balance > 0) {
                 _claimArraySize++;
                 vm.mockCall(
diff --git a/packages/contracts-bedrock/contracts/test/SafeCall.t.sol b/packages/contracts-bedrock/contracts/test/SafeCall.t.sol
index f5bb61b8fb27..c644697d11c5 100644
--- a/packages/contracts-bedrock/contracts/test/SafeCall.t.sol
+++ b/packages/contracts-bedrock/contracts/test/SafeCall.t.sol
@@ -14,7 +14,7 @@ contract SafeCall_Test is CommonTest {
         vm.assume(from.balance == 0);
         vm.assume(to.balance == 0);
         // no precompiles (mainnet)
-        assumeNoPrecompiles(to, 1);
+        assumeNotPrecompile(to, 1);
         // don't call the vm
         vm.assume(to != address(vm));
         vm.assume(from != address(vm));
@@ -54,7 +54,7 @@ contract SafeCall_Test is CommonTest {
         vm.assume(from.balance == 0);
         vm.assume(to.balance == 0);
         // no precompiles (mainnet)
-        assumeNoPrecompiles(to, 1);
+        assumeNotPrecompile(to, 1);
         // don't call the vm
         vm.assume(to != address(vm));
         vm.assume(from != address(vm));
@@ -94,7 +94,7 @@ contract SafeCall_Test is CommonTest {
         vm.assume(from.balance == 0);
         vm.assume(to.balance == 0);
         // no precompiles (mainnet)
-        assumeNoPrecompiles(to, 1);
+        assumeNotPrecompile(to, 1);
         // don't call the vm
         vm.assume(to != address(vm));
         vm.assume(from != address(vm));
diff --git a/packages/contracts-bedrock/contracts/test/invariants/PROPERTIES.md b/packages/contracts-bedrock/contracts/test/invariants/PROPERTIES.md
new file mode 100644
index 000000000000..acce7e3ffbe3
--- /dev/null
+++ b/packages/contracts-bedrock/contracts/test/invariants/PROPERTIES.md
@@ -0,0 +1,52 @@
+# Scope
+
+- OptimismPortal's withdrawEthBalance function: contracts/L1/OptimismPortal.sol:504
+- L1StandardBridge's  withdrawErc20Balance function: contracts/L1/L1StandardBridge.sol:272
+- BalanceClaimer contract: contracts/L1/winddown/BalanceClaimer.sol
+
+# Properties
+
+| Id  | Properties                                                                          | Type             | Checked |
+| --- | ---------------------------------------------------                                 | ------------     | ---     |
+| 1   | a valid claim should be redeemable once                                             | State transition | [x]     |
+| 2   | a valid claim should not be redeemable more than once                               | State transition | [x]     |
+| 3   | a user should be set as claimed when they process a claim                           | State transition | [x]     |
+| 4   | an invalid claim should not be redeemable                                           | State transition | [x]     |
+| 5   | for each token, token.balanceOf(L1StandardBridge) == initialBalance - sum of claims | High-level       | [x]     |
+| 6   | OptimismPortal.balance == initialBalance - sum of claims                            | High-level       | [x]     |
+
+
+## testing methodology
+The fact that the state root is not writeable in the lifetime of the contract is cool from a design standpoint, but that also means the root has to be generated, and the valid claims chosen, before it makes sense to call any other handler.
+
+As a first approach, we've meta-programmed a solidity source file with a hard-coded set of valid claims, which can be refreshed by calling  `./generate-random-tree.sh`.
+This is not ideal, as all fuzzing runs are going to run on the same merkle tree instead of letting the fuzzer explore new ones. Some alternatives are described below:
+
+### mutate the state root
+Idea for this is to initialize the BalanceClaimer in the campaign constructor with either
+
+- [ ] an empty state root (for ...purity? ie allowing the fuzzer choose the inputs with the greatest variability)
+- [ ] pre-filled state root (to cover code faster) and set of valid claims, with the downside of calls creating
+
+and have handlers to _add_ valid claims to the set, overwriting the state root
+
+This has the downside of being dissimilar to the actual production usage in a very crucial way, but also the invariant we would be breaking  (the state root not changing) can be easily enforced by the compiler (ie: make the field immutable), and the upside of exploring a lot of possible trees in a simpler way
+
+### use a modifier to ensure the first call of the sequence initializes a state root
+this would involve
+- [ ] not creating the balanceClaimer in the constructor
+- [ ] have a modifier (and an extra param of fuzzed input in every handler/property check) which will be used to initialize the state root on the first call
+- [ ] have all handlers afterwards only process claims (valid or not, obviously) and not create new ones
+
+This has the upside of being identical to the production setup, but would yield uglier code and potentially have worse pseudorandom input since we would be having all the state as fields of structs in arrays
+
+# nice to haves
+- [ ] use tokens' actual bytecode in the fuzzing campaign
+- [ ] use a full uint256 for the range of the amounts in merkle tree
+    - [ ] use bigger number in script
+    - [ ] handle fails caused by insufficient balances
+- [ ] create a larger share of claims with incomplete list of tokens or zero eth
+- [ ] handlers for withdraw{Erc20,Eth}Balance methods
+    - [ ] guided
+    - [ ] unguided
+
diff --git a/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/FuzzTest.t.sol b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/FuzzTest.t.sol
new file mode 100644
index 000000000000..1295b58f1170
--- /dev/null
+++ b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/FuzzTest.t.sol
@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.15;
+
+import {BalanceClaimerGuidedHandlers} from "./handlers/guided/BalanceClaimer.t.sol";
+import {BalanceClaimerUnguidedHandlers} from "./handlers/unguided/BalanceClaimer.t.sol";
+import {BalanceClaimerProperties} from "./properties/BalanceClaimer.t.sol";
+
+contract FuzzTest is BalanceClaimerGuidedHandlers, BalanceClaimerUnguidedHandlers, BalanceClaimerProperties {}
diff --git a/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/generate-random-tree.sh b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/generate-random-tree.sh
new file mode 100755
index 000000000000..fd0b1530f878
--- /dev/null
+++ b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/generate-random-tree.sh
@@ -0,0 +1,54 @@
+#!/bin/sh
+
+claims_file=./setup/ClaimList.t.sol
+claims_amount=100
+users_amount=100
+
+random_int() {
+  # 2^ 64 - 2 , max range for shuf, == 18e18, not ideal.
+  echo "$(shuf  -n 1 -i 0-18446744073709551614)"
+}
+
+cat - > "$claims_file" <<EOF
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.15;
+
+contract ClaimsList {
+    struct ClaimEntry {
+        address recipient;
+        uint256 ethAmount;
+        uint256 daiAmount;
+        uint256 gtcAmount;
+        uint256 usdtAmount;
+        uint256 usdcAmount;
+    }
+
+    ClaimEntry[] internal randomClaims;
+
+    constructor() {
+        // ensure at least one all-zero claim
+        randomClaims.push(ClaimEntry(0x0000000000000000000000000000000000010000, 0, 0, 0, 0, 0));
+        // one  zero-erc20 claim
+        randomClaims.push(ClaimEntry(0x0000000000000000000000000000000000020000, 1e18, 0, 0, 0, 0));
+        // one  zero-eth claim
+        randomClaims.push(ClaimEntry(0x0000000000000000000000000000000000030000, 0, 100e18, 0, 0, 0));
+        // remaining randomly-generated claims
+EOF
+for i in  $(seq "$claims_amount") ; do
+  # have some overlap with medusa's actors
+  recipient="address($(shuf -n 1 -i 1-${users_amount}) << 16)";
+  ethAmount=$(random_int)
+  daiAmount=$(random_int)
+  gtcAmount=$(random_int)
+  usdtAmount=$(random_int)
+  usdcAmount=$(random_int)
+  echo "        randomClaims.push(ClaimEntry($recipient, $ethAmount, $daiAmount, $gtcAmount, $usdtAmount, $usdcAmount));" >> "$claims_file"
+
+done
+
+
+cat - >> "$claims_file" <<EOF
+    }
+}
+EOF
+forge fmt "$claims_file"
diff --git a/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/handlers/guided/BalanceClaimer.t.sol b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/handlers/guided/BalanceClaimer.t.sol
new file mode 100644
index 000000000000..406897603acf
--- /dev/null
+++ b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/handlers/guided/BalanceClaimer.t.sol
@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.15;
+
+import {IErc20BalanceWithdrawer} from "contracts/L1/interfaces/winddown/IErc20BalanceWithdrawer.sol";
+import {BalanceClaimerSetup} from "../../setup/BalanceClaimer.t.sol";
+
+contract BalanceClaimerGuidedHandlers is BalanceClaimerSetup {
+    function handler_claim(uint256 claimIndex) external {
+        claimIndex = bound(claimIndex, 0, ghost_validClaims.length - 1);
+        Claim memory claim = ghost_validClaims[claimIndex];
+        bytes32 hashedClaim = _hashClaim(claim);
+        bytes32[] memory proof = getProof(tree, getIndex(tree, hashedClaim));
+        vm.prank(msg.sender);
+        // prop-id 1
+        try balanceClaimer.claim(proof, claim.user, claim.ethAmount, _claimToErc20ClaimArray(claim)) {
+            ghost_claimed[claim.user] = true;
+            ghost_claimedEther += claim.ethAmount;
+            for (uint256 i = 0; i < claim.tokens.length; i++) {
+                ghost_claimedTokens[claim.tokens[i]] += claim.tokenAmounts[i];
+            }
+        } catch {
+            // prop-id 2
+            assert(ghost_claimed[claim.user]);
+        }
+    }
+}
diff --git a/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/handlers/unguided/BalanceClaimer.t.sol b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/handlers/unguided/BalanceClaimer.t.sol
new file mode 100644
index 000000000000..082915fed6be
--- /dev/null
+++ b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/handlers/unguided/BalanceClaimer.t.sol
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.15;
+
+import {BalanceClaimerSetup} from "../../setup/BalanceClaimer.t.sol";
+import {IErc20BalanceWithdrawer} from "contracts/L1/interfaces/winddown/IErc20BalanceWithdrawer.sol";
+import {IBalanceClaimer} from "contracts/L1/interfaces/winddown/IBalanceClaimer.sol";
+
+contract BalanceClaimerUnguidedHandlers is BalanceClaimerSetup {
+    function handler_claim(
+        bytes32[] calldata _proof,
+        address _user,
+        uint256 _ethBalance,
+        IErc20BalanceWithdrawer.Erc20BalanceClaim[] calldata _erc20Claim,
+        address _caller
+    ) external {
+        bytes32 hash = _hashClaim(_user, _ethBalance, _erc20Claim);
+        vm.prank(_caller);
+        try balanceClaimer.claim(_proof, _user, _ethBalance, _erc20Claim) {
+            //prop-id 1
+            assert(ghost_claimInTree[hash]);
+            //prop-id 2;
+            assert(!ghost_claimed[_user]);
+            ghost_claimed[_user]=true;
+        } catch {
+            assert(
+                !ghost_claimInTree[hash] // prop-id 4
+                    || ghost_claimed[_user] //prop-id 3
+            );
+        }
+    }
+
+    function handler_canClaim(
+        bytes32[] calldata _proof,
+        address _user,
+        uint256 _ethBalance,
+        IErc20BalanceWithdrawer.Erc20BalanceClaim[] calldata _erc20Claim
+    ) external {
+        bytes32 hash = _hashClaim(_user, _ethBalance, _erc20Claim);
+        if (balanceClaimer.canClaim(_proof, _user, _ethBalance, _erc20Claim)) {
+            //prop-id 1
+            assert(ghost_claimInTree[hash]);
+            // prop-id 2
+            assert(!ghost_claimed[_user]);
+        } else {
+            assert(
+                !ghost_claimInTree[hash] // prop-id 4
+                    || ghost_claimed[_user] //prop-id 3
+            );
+        }
+    }
+}
diff --git a/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/properties/BalanceClaimer.t.sol b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/properties/BalanceClaimer.t.sol
new file mode 100644
index 000000000000..2e73b01c10a7
--- /dev/null
+++ b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/properties/BalanceClaimer.t.sol
@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.15;
+
+import {BalanceClaimerSetup} from "../setup/BalanceClaimer.t.sol";
+
+contract BalanceClaimerProperties is BalanceClaimerSetup {
+    /// @custom:property-id 5
+    /// @custom:property for each token, token.balanceOf(L1StandardBridge) == initialBalance - sum of claims
+    function property_tokenBalancesSum() external view {
+        for (uint256 i = 0; i < supportedTokens.length; i++) {
+            assert(
+                supportedTokens[i].balanceOf(address(l1StandardBridge))
+                    == INITIAL_BALANCE - ghost_claimedTokens[address(supportedTokens[i])]
+            );
+        }
+    }
+
+    /// @custom:property-id 6
+    /// @custom:property OptimismPortal.balance == initialBalance - sum of claims
+    function property_ethBalancesSum() external view {
+        assert(address(optimismPortal).balance == INITIAL_BALANCE - ghost_claimedEther);
+    }
+}
diff --git a/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/BalanceClaimer.t.sol b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/BalanceClaimer.t.sol
new file mode 100644
index 000000000000..c9ec1cba37ed
--- /dev/null
+++ b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/BalanceClaimer.t.sol
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.15;
+
+import {BalanceClaimer} from "contracts/L1/winddown/BalanceClaimer.sol";
+import {OptimismPortal} from "contracts/L1/OptimismPortal.sol";
+import {L1StandardBridge} from "contracts/L1/L1StandardBridge.sol";
+import {L1ChugSplashProxy} from "contracts/legacy/L1ChugSplashProxy.sol";
+import {L2OutputOracle} from "contracts/L1/L2OutputOracle.sol";
+import {SystemConfig} from "contracts/L1/SystemConfig.sol";
+import {Proxy} from "contracts/universal/Proxy.sol";
+
+import {FuzzERC20} from "./Tokens.t.sol";
+import {Claims} from "./Claims.t.sol";
+
+import {CommonBase} from "forge-std/Base.sol";
+import {StdUtils} from "forge-std/StdUtils.sol";
+
+contract BalanceClaimerSetup is CommonBase, StdUtils, Claims {
+    L1StandardBridge internal l1StandardBridge;
+    OptimismPortal internal optimismPortal;
+    BalanceClaimer internal balanceClaimer;
+
+    constructor() {
+        Proxy balanceClaimerProxy = new Proxy(address(this));
+
+        L1StandardBridge l1StandardBridgeImpl = new L1StandardBridge(payable(0), payable(address(balanceClaimerProxy)));
+        OptimismPortal optimismPortalImpl = new OptimismPortal({
+            _l2Oracle: L2OutputOracle(address(0)),
+            _guardian: address(0),
+            _paused: false,
+            _config: SystemConfig(address(0)),
+            _balanceClaimer: address(balanceClaimerProxy)
+        });
+        // Get the proxies for L1StandardBridge and OptimismPortal
+        L1ChugSplashProxy l1StandardBridgeProxy = new L1ChugSplashProxy(address(this));
+        Proxy optimismPortalProxy = new Proxy(address(this));
+
+        BalanceClaimer balanceClaimerImpl =
+            new BalanceClaimer(address(optimismPortalProxy), address(l1StandardBridgeProxy), tree[0]);
+
+        // Set BalanceClaimer implementation
+        balanceClaimerProxy.upgradeTo(address(balanceClaimerImpl));
+        optimismPortalProxy.upgradeTo(address(optimismPortalImpl));
+        l1StandardBridgeProxy.setCode(address(l1StandardBridgeImpl).code);
+
+        optimismPortal = OptimismPortal(payable(optimismPortalProxy));
+        l1StandardBridge = L1StandardBridge(payable(l1StandardBridgeProxy));
+        balanceClaimer = BalanceClaimer(address(balanceClaimerProxy));
+
+        // cant do this in Tokens because l1StandardBridge address is not set at that time
+        vm.deal(address(optimismPortal), INITIAL_BALANCE);
+        for (uint256 i = 0; i < TOKENS; i++) {
+            FuzzERC20(address(supportedTokens[i])).mint(address(l1StandardBridge), INITIAL_BALANCE);
+        }
+    }
+
+    /// @custom:prop-id  0
+    /// @custom:prop sanity checks for setup
+    function property_setup() external {
+        assert(address(optimismPortal.BALANCE_CLAIMER()) == address(balanceClaimer));
+        assert(address(balanceClaimer.ETH_BALANCE_WITHDRAWER()) == address(optimismPortal));
+        assert(address(balanceClaimer.ERC20_BALANCE_WITHDRAWER()) == address(l1StandardBridge));
+        assert(address(l1StandardBridge.BALANCE_CLAIMER()) == address(balanceClaimer));
+        assert(balanceClaimer.ROOT() == tree[0]);
+    }
+}
diff --git a/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/ClaimList.t.sol b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/ClaimList.t.sol
new file mode 100644
index 000000000000..c139579d377c
--- /dev/null
+++ b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/ClaimList.t.sol
@@ -0,0 +1,1025 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.15;
+
+contract ClaimsList {
+    struct ClaimEntry {
+        address recipient;
+        uint256 ethAmount;
+        uint256 daiAmount;
+        uint256 gtcAmount;
+        uint256 usdtAmount;
+        uint256 usdcAmount;
+    }
+
+    ClaimEntry[] internal randomClaims;
+
+    constructor() {
+        // ensure at least one all-zero claim
+        randomClaims.push(ClaimEntry(0x0000000000000000000000000000000000010000, 0, 0, 0, 0, 0));
+        // one  zero-erc20 claim
+        randomClaims.push(ClaimEntry(0x0000000000000000000000000000000000020000, 1e18, 0, 0, 0, 0));
+        // one  zero-eth claim
+        randomClaims.push(ClaimEntry(0x0000000000000000000000000000000000030000, 0, 100e18, 0, 0, 0));
+        // remaining randomly-generated claims
+        randomClaims.push(
+            ClaimEntry(
+                address(58 << 16),
+                6730548794470647054,
+                11590444157502602728,
+                12718023387281120710,
+                15066971329122909045,
+                8820709711312173557
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(64 << 16),
+                15561172962793446325,
+                5285671925472856417,
+                924720487668030360,
+                1064832390704925156,
+                5056209461176779386
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(20 << 16),
+                3602196738687461481,
+                6851055749942573882,
+                8354592451108227467,
+                5852873411239234870,
+                4286387593946153737
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(84 << 16),
+                6730933948483637014,
+                7189442107796078484,
+                12555775610064000468,
+                6077367579688492778,
+                16022904295749462917
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(35 << 16),
+                8759816169088970866,
+                8263669773086519817,
+                17023768597823748627,
+                5642433543192774562,
+                319907188341182673
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(32 << 16),
+                9020334892007210643,
+                10200376871403360512,
+                2423426020243093192,
+                14510923783430848551,
+                10682919184931676947
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(34 << 16),
+                12146180231029406196,
+                6897599405845347946,
+                14296963053537753412,
+                1241056186264142820,
+                8879246414264288818
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(35 << 16),
+                7836781376844525429,
+                2973632641337605725,
+                18001226978949409707,
+                12378854783874049163,
+                13756077465320121861
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(27 << 16),
+                11427329298092932351,
+                4044901496082122835,
+                3518707381618188388,
+                8343643285970905388,
+                17529876161015459938
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(93 << 16),
+                2829278826529874407,
+                8680171942432455501,
+                15883475889218011334,
+                10293426862146047361,
+                16258106758572985876
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(81 << 16),
+                14809941383446709497,
+                6474071144312482108,
+                17578412448185719782,
+                3436241048006164571,
+                6962856914927072898
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(19 << 16),
+                15747431535556623097,
+                10702281674943337989,
+                14051548048460736844,
+                8820546307697287841,
+                11357871712906728191
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(72 << 16),
+                6313796466892837256,
+                8633634166440308026,
+                8419432183472092720,
+                833472199440874845,
+                124990967265372867
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(12 << 16),
+                6923375162002914455,
+                16078456798750557177,
+                9376290650393048127,
+                8708335392232160468,
+                9856821932335832759
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(62 << 16),
+                2286688976258567834,
+                11198176954525898917,
+                18178659418749650667,
+                2241067523133487187,
+                15064555168678745278
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(49 << 16),
+                1266260567438679408,
+                6344195984854902142,
+                2470253479332366925,
+                13155090495437305322,
+                1700351010839223894
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(59 << 16),
+                17931824126475362974,
+                10339878294238491739,
+                6240498709022299814,
+                2663930736862012266,
+                11545183156242371529
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(82 << 16),
+                3586384026540702637,
+                8788277384624799874,
+                2388394860881857615,
+                4472072750868512813,
+                7835000128660158113
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(95 << 16),
+                14382274015200284791,
+                14229905540989308418,
+                710094442548238055,
+                7890463888209452368,
+                461926064715800449
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(41 << 16),
+                8395278580780384348,
+                10778616130984974263,
+                12100280527978849308,
+                7008202694430902069,
+                6277280893621629917
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(90 << 16),
+                18391562002426052441,
+                17953947944404571802,
+                6575660734345139687,
+                10567667875948322545,
+                2026142355328382484
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(19 << 16),
+                8835034446485897092,
+                117303103927106414,
+                6484065707509377506,
+                5018484248220058231,
+                10035061173727331153
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(78 << 16),
+                2779007702621846423,
+                18051529713183364473,
+                14348153712742138195,
+                5833515127382793971,
+                15223234183045160290
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(66 << 16),
+                6902883944192340072,
+                1219212419868657970,
+                256472194390452575,
+                3211312617382142736,
+                16556175338934371697
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(15 << 16),
+                9413848360619842005,
+                1848388194797941476,
+                1092136547107789555,
+                8705556206303592799,
+                15999819157697647160
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(26 << 16),
+                672645744000059842,
+                13430813432556345595,
+                17786375652660549998,
+                4376136487576586554,
+                10170467751333448030
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(94 << 16),
+                2705283529850304203,
+                13052147649295292691,
+                3835508965528733660,
+                15192411817994193826,
+                10681167391035461325
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(74 << 16),
+                7148818553736733656,
+                15074703528112525159,
+                1965542821577860939,
+                15476800120190248525,
+                3348686387884439768
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(70 << 16),
+                15678966676811378539,
+                5423960188385936224,
+                5003710716602516664,
+                7692543749078985041,
+                5362056456869640736
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(87 << 16),
+                14817630203176812574,
+                503526727322245351,
+                4059338467137868721,
+                10112421545559953705,
+                5837194449423449575
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(67 << 16),
+                7543805440160233478,
+                15054450753295705996,
+                5155390228511331418,
+                16722319020821063341,
+                9132011666829000169
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(67 << 16),
+                15998074163280964488,
+                18158321488912104994,
+                2057679474114036997,
+                17238548404746514704,
+                853057595120638316
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(13 << 16),
+                7453724124951284729,
+                8364570297310971736,
+                12644186918887786658,
+                6179621561062748718,
+                14496746087684046748
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(15 << 16),
+                4840775977436637593,
+                10614790424971986499,
+                18257898706811476987,
+                1491735796947689365,
+                1079822045265180695
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(84 << 16),
+                16879424448964050380,
+                11743876131003135594,
+                6646514961938110802,
+                9103931153290148962,
+                18776131854192907
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(88 << 16),
+                15761026339663648264,
+                2828843287786216071,
+                10315728031397944987,
+                7878165044412799469,
+                4404176146679168554
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(89 << 16),
+                11926823301204826185,
+                5845662057693731083,
+                8321105571244724107,
+                4744902759608137251,
+                14053142543127688700
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(33 << 16),
+                10837098187373127545,
+                12015766705931175589,
+                15648895658053045957,
+                11594527027449832348,
+                1158164103844743382
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(69 << 16),
+                7033629636164677878,
+                9311853035696735935,
+                16030223432509916909,
+                18005670389652616876,
+                10994264202998992503
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(89 << 16),
+                2785398103629794652,
+                14269989510024848011,
+                16722156125176124965,
+                17788857644351982787,
+                15370102514278796256
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(92 << 16),
+                1948575994653353402,
+                14621743015455474634,
+                1005399802880780294,
+                8722413296034691235,
+                12338105798675713423
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(93 << 16),
+                12945666235941741016,
+                10283925825776441244,
+                10246432485988708709,
+                7923534839072644056,
+                2892750692993414030
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(84 << 16),
+                12845405114670765294,
+                737053958595926510,
+                12220736228543910728,
+                1180890550923769405,
+                9954275572638453282
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(46 << 16),
+                16917594245934963098,
+                1785132637082259216,
+                15079349038427336897,
+                13455857009033125846,
+                15137378925380838081
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(61 << 16),
+                16420337504541216552,
+                4991518354292595219,
+                10556128247750617480,
+                7292620161557115277,
+                11104896797722827464
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(95 << 16),
+                5855730631247509005,
+                11612948854830762133,
+                7830960392298256048,
+                10044442255100202362,
+                8400616345112124510
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(45 << 16),
+                8158107937172917953,
+                14886425612411481351,
+                289867399293123352,
+                6671996176692833651,
+                8110141707249251462
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(72 << 16),
+                4979864138349892357,
+                10357567632910888883,
+                694171787162609944,
+                3838372284072534168,
+                5446321078271231966
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(81 << 16),
+                13339477162259186997,
+                14718949516239657983,
+                18442347215033816767,
+                6292031354592698085,
+                12324330736320425906
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(40 << 16),
+                17024595786874595226,
+                639950442210659288,
+                16868397532792750275,
+                15072056807923799797,
+                3804358699897335824
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(99 << 16),
+                8760391947441090918,
+                6116408106790747066,
+                16468540711100345110,
+                9554061742456496605,
+                4867917447661548260
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(44 << 16),
+                2240397348628051821,
+                7741561510606949399,
+                3311597273640103804,
+                15436672972877559583,
+                17269076238050435481
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(54 << 16),
+                16328458181494001875,
+                7539821938746592457,
+                6192472348433905383,
+                9676446196409567604,
+                8366968231866322859
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(32 << 16),
+                7075693572695076452,
+                8654866182183330574,
+                18428121373973279043,
+                15198012025129939443,
+                6410247552350806306
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(81 << 16),
+                10814332091607766452,
+                13940416788872955635,
+                14101072599079722090,
+                6151809175738891177,
+                6263450240761624586
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(60 << 16),
+                12564228909539957559,
+                6872940206780545238,
+                16419642327331552360,
+                6360879523469504656,
+                6440336581599807161
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(11 << 16),
+                17222820319814584807,
+                11403419322835755299,
+                14424802217807224636,
+                3364497948563064611,
+                1467087561855014115
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(73 << 16),
+                14943315206222294557,
+                4241908955520980916,
+                17953647779998597219,
+                8977963811462385162,
+                4742349844301327604
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(62 << 16),
+                4619922866959096912,
+                14876728902659428260,
+                17123852543099709293,
+                4003786024576069823,
+                16069555635417598006
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(21 << 16),
+                15274695665847822543,
+                9766374136009093599,
+                1502803245754839083,
+                11613562929608798423,
+                16616073195667801257
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(70 << 16),
+                1533889398960637892,
+                14665510426740312288,
+                14327847561247406345,
+                17637093252930238232,
+                10088752342699793298
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(87 << 16),
+                17076838425139048883,
+                16130247730596826480,
+                9681201085079980778,
+                3054587787296933248,
+                8712048764360872602
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(64 << 16),
+                11479600612206828807,
+                3094535672188074034,
+                3061924033292083102,
+                8339575361656367103,
+                6142754310725618201
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(40 << 16),
+                8757983834309990758,
+                9357826176113078096,
+                2608601147696096656,
+                13798905767246844431,
+                6459134516418437566
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(44 << 16),
+                8331374121054561794,
+                7305270096480504581,
+                2083834107345704914,
+                12474293212516353173,
+                2711844442419601250
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(95 << 16),
+                8986907264241700742,
+                8822071077499484596,
+                13026247440276933379,
+                14817763143343065087,
+                4965570458529963555
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(32 << 16),
+                7285700089515597105,
+                11209150719202362854,
+                17569286151091815970,
+                4935633266002551551,
+                11244469769918192837
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(71 << 16),
+                1064233312795633922,
+                9253656315877624360,
+                2608263268358534684,
+                3473135356786538677,
+                15226195291283398179
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(30 << 16),
+                14095093428666017234,
+                6831967188837333813,
+                1050362786401479748,
+                5086264138006094024,
+                998873954610492462
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(54 << 16),
+                12921335492687864947,
+                4450797639166345318,
+                11265462418675663066,
+                41031479149291068,
+                9360514369646791999
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(31 << 16),
+                1094074149580457033,
+                16153992259578095334,
+                5897434698266212269,
+                10224713067493172508,
+                12760569634693829989
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(40 << 16),
+                13557954242821440957,
+                17759191274629226719,
+                17413452097710401724,
+                521689703780557705,
+                16155133588308086220
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(27 << 16),
+                12462688076163751874,
+                8162527743430546661,
+                18383432283495814504,
+                5521207905376356565,
+                3633290866039822514
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(76 << 16),
+                2002539417156955124,
+                5416436240969275501,
+                5316939805656298205,
+                2653303370010262435,
+                15160000651313754426
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(27 << 16),
+                15218917621826075749,
+                12193549995351476952,
+                12223123748078269333,
+                10493681658368677595,
+                13248110266809347975
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(93 << 16),
+                17156691416585807934,
+                1473069383880918075,
+                13461811891861917244,
+                2430949648809188229,
+                8687215518593307665
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(41 << 16),
+                17638289046717257747,
+                16869986067038028310,
+                15429674485810369936,
+                4016345587237925745,
+                862021245789620898
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(26 << 16),
+                9405294816536306433,
+                16620418099193207662,
+                14930472809554335022,
+                15656360011858688935,
+                14533091744678324817
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(32 << 16),
+                10407847198752187822,
+                2185885134019546640,
+                3314875989787258350,
+                6789454442130257801,
+                10797086471863671245
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(95 << 16),
+                13283705175140709446,
+                975128651364650534,
+                4350243887038674290,
+                4272963650879643466,
+                3670240771407124682
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(13 << 16),
+                13150297155000266768,
+                18067851345433930451,
+                13688224040906629579,
+                6663882427073853557,
+                16223390050383328106
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(19 << 16),
+                8792012456351943787,
+                5066652927846300965,
+                12887396847071645064,
+                2211893323662368591,
+                55350042886918230
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(99 << 16),
+                8259977086395525064,
+                59034514685236556,
+                6454957681690303466,
+                17838040203442642985,
+                4744562417162321981
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(82 << 16),
+                5849452704894603240,
+                769623176447363982,
+                1743283437234176137,
+                7665813740157474241,
+                2514220609466582774
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(4 << 16),
+                15526679096097524349,
+                17046010514238249409,
+                17904738424416909343,
+                1273070789328741953,
+                5694310115151634032
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(69 << 16),
+                15938139359953495130,
+                15286353416804559363,
+                1764827933084375793,
+                2683092045320269485,
+                10525469194728501526
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(45 << 16),
+                1500225872735785463,
+                16468542125371468652,
+                8654790792345365382,
+                10395952939107531734,
+                5058638574636002383
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(43 << 16),
+                11395868052738996726,
+                10590029349447262851,
+                11335015515226909995,
+                12307980527888312272,
+                6076498901804599065
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(37 << 16),
+                10198397269586317903,
+                3035090291233345309,
+                18406513221316689580,
+                2274944392845699735,
+                1167704103629102221
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(55 << 16),
+                5533907063086050842,
+                841648246974449445,
+                11059780425040299860,
+                968595211215821051,
+                18185735933654264947
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(42 << 16),
+                5453673792119155517,
+                17138896487781972498,
+                2000793481051869175,
+                16471077403695194399,
+                11784401144667903876
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(26 << 16),
+                16765775724055081834,
+                9752134412801783826,
+                4593881883058382069,
+                13863538197481282601,
+                16737522984891317582
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(75 << 16),
+                8765170513342008046,
+                4805361948656878403,
+                15601665519157974314,
+                1122510209689477185,
+                3167538201352716996
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(89 << 16),
+                13180864841340254748,
+                3839752719736903127,
+                10703989493067728969,
+                13265542791415536161,
+                13801704403344964650
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(4 << 16),
+                991093458338024834,
+                14582056275495054459,
+                718205587074859053,
+                8204083335484354957,
+                3452232817466342398
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(64 << 16),
+                13621972015809528226,
+                16915799983457212609,
+                17970161347797215730,
+                11614515126414258769,
+                13812130817853624206
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(6 << 16),
+                12554050826864822332,
+                4697804786400624415,
+                15464067415077195965,
+                2407611996857905171,
+                8970558984714933393
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(19 << 16),
+                17518449123409007948,
+                7984358523050028226,
+                8339164329290630615,
+                1035108422326142263,
+                8523972490349369094
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(20 << 16),
+                8482600047956052867,
+                16699433128888042182,
+                5427656832405124207,
+                14615113890335933842,
+                15374003245748057962
+            )
+        );
+        randomClaims.push(
+            ClaimEntry(
+                address(20 << 16),
+                17180658570558610977,
+                17254530005366517512,
+                12231865090606123935,
+                1448790249175993420,
+                18134697859674075755
+            )
+        );
+    }
+}
diff --git a/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/Claims.t.sol b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/Claims.t.sol
new file mode 100644
index 000000000000..9e1205bc9aed
--- /dev/null
+++ b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/Claims.t.sol
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.15;
+
+import {IErc20BalanceWithdrawer} from "contracts/L1/interfaces/winddown/IErc20BalanceWithdrawer.sol";
+import {MerkleTreeGenerator} from "contracts/test/libraries/MerkleTreeGenerator.t.sol";
+import {Tokens} from "./Tokens.t.sol";
+import {ClaimsList} from "./ClaimList.t.sol";
+
+contract Claims is Tokens, ClaimsList, MerkleTreeGenerator {
+    struct Claim {
+        address user;
+        uint256 ethAmount;
+        address[] tokens;
+        uint256[] tokenAmounts;
+    }
+
+    bytes32[] internal tree;
+    bytes32[] internal leaves;
+    Claim[] internal ghost_validClaims;
+    mapping(address => bool) internal ghost_claimed;
+    mapping(bytes32 => bool) internal ghost_claimInTree;
+    // only used as dynamic array
+    address[] private _tokens;
+    // only used as dynamic array
+    uint256[] private _amounts;
+
+    constructor() {
+        for (uint256 i = 0; i < randomClaims.length; i++) {
+            ClaimEntry memory rawClaim = randomClaims[i];
+            if (rawClaim.daiAmount > 0) {
+                _tokens.push(address(supportedTokens[0]));
+                _amounts.push(rawClaim.daiAmount);
+            }
+            if (rawClaim.gtcAmount > 0) {
+                _tokens.push(address(supportedTokens[1]));
+                _amounts.push(rawClaim.gtcAmount);
+            }
+            if (rawClaim.usdtAmount > 0) {
+                _tokens.push(address(supportedTokens[2]));
+                _amounts.push(rawClaim.usdtAmount);
+            }
+            if (rawClaim.usdcAmount > 0) {
+                _tokens.push(address(supportedTokens[3]));
+                _amounts.push(rawClaim.usdcAmount);
+            }
+            Claim memory claim = Claim({
+                user: rawClaim.recipient,
+                ethAmount: rawClaim.ethAmount,
+                tokens: _tokens,
+                tokenAmounts: _amounts
+            });
+            delete _amounts;
+            delete _tokens;
+            ghost_validClaims.push(claim);
+            leaves.push(_hashClaim(claim));
+        }
+        tree = generateMerkleTree(leaves);
+    }
+
+    function _hashClaim(Claim memory claim) internal pure returns (bytes32) {
+        IErc20BalanceWithdrawer.Erc20BalanceClaim[] memory erc20Claims =
+            new IErc20BalanceWithdrawer.Erc20BalanceClaim[](claim.tokens.length);
+        for (uint256 i = 0; i < claim.tokens.length; i++) {
+            erc20Claims[i].token = claim.tokens[i];
+            erc20Claims[i].balance = claim.tokenAmounts[i];
+        }
+        return keccak256(bytes.concat(keccak256(abi.encode(claim.user, claim.ethAmount, erc20Claims))));
+    }
+
+    function _hashClaim(address user, uint256 ethAmount, IErc20BalanceWithdrawer.Erc20BalanceClaim[] memory erc20Claims)
+        internal
+        pure
+        returns (bytes32)
+    {
+        return keccak256(bytes.concat(keccak256(abi.encode(user, ethAmount, erc20Claims))));
+    }
+
+    function _claimToErc20ClaimArray(Claim memory claim)
+        internal
+        pure
+        returns (IErc20BalanceWithdrawer.Erc20BalanceClaim[] memory)
+    {
+        IErc20BalanceWithdrawer.Erc20BalanceClaim[] memory erc20Claims =
+            new IErc20BalanceWithdrawer.Erc20BalanceClaim[](claim.tokens.length);
+        for (uint256 i = 0; i < claim.tokens.length; i++) {
+            erc20Claims[i].token = claim.tokens[i];
+            erc20Claims[i].balance = claim.tokenAmounts[i];
+        }
+        return erc20Claims;
+    }
+}
diff --git a/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/Tokens.t.sol b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/Tokens.t.sol
new file mode 100644
index 000000000000..ef591636b8d7
--- /dev/null
+++ b/packages/contracts-bedrock/contracts/test/invariants/balance-claimer/setup/Tokens.t.sol
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.15;
+
+import {MockERC20} from "forge-std/mocks/MockERC20.sol";
+import {IERC20} from "forge-std/interfaces/IERC20.sol";
+
+contract FuzzERC20 is MockERC20 {
+    function mint(address _to, uint256 _amount) public {
+        _mint(_to, _amount);
+    }
+}
+
+contract Tokens {
+    uint8 internal constant TOKENS = 4;
+    uint256 internal constant INITIAL_BALANCE = 100000e18;
+    IERC20[] internal supportedTokens;
+
+    mapping(address => uint256) internal ghost_claimedTokens;
+    uint256 internal ghost_claimedEther;
+
+    constructor() {
+        for (uint256 i = 0; i < TOKENS; i++) {
+            // TODO: use bytecode from production tokens
+            FuzzERC20 token = new FuzzERC20();
+            // TODO: use 6 decimals for usdt
+            token.initialize("name", "symbol", 18);
+            supportedTokens.push(token);
+        }
+    }
+}
diff --git a/packages/contracts-bedrock/foundry.toml b/packages/contracts-bedrock/foundry.toml
index 18e9f3361ed8..3b04c12b8cd4 100644
--- a/packages/contracts-bedrock/foundry.toml
+++ b/packages/contracts-bedrock/foundry.toml
@@ -24,6 +24,11 @@ fs_permissions = [
   { 'access'='read-write', 'path'='./.resource-metering.csv' },
 ]
 
+[profile.medusa]
+src='contracts/test/invariants/balance-claimer'
+test='contracts/test/invariants/balance-claimer'
+script='contracts/test/invariants/balance-claimer'
+
 [profile.ci]
 fuzz_runs = 512
 
diff --git a/packages/contracts-bedrock/medusa.json b/packages/contracts-bedrock/medusa.json
new file mode 100644
index 000000000000..ede7245d9619
--- /dev/null
+++ b/packages/contracts-bedrock/medusa.json
@@ -0,0 +1,89 @@
+{
+	"fuzzing": {
+		"workers": 10,
+		"workerResetLimit": 50,
+		"timeout": 0,
+		"testLimit": 0,
+		"shrinkLimit": 5000,
+		"callSequenceLength": 100,
+		"corpusDirectory": "corpus",
+		"coverageEnabled": true,
+		"coverageFormats": [
+			"html",
+			"lcov"
+		],
+		"targetContracts": ["FuzzTest"],
+		"predeployedContracts": {},
+		"targetContractsBalances": [],
+		"constructorArgs": {},
+		"deployerAddress": "0x30000",
+		"senderAddresses": [
+			"0x10000",
+			"0x20000",
+			"0x30000"
+		],
+		"blockNumberDelayMax": 60480,
+		"blockTimestampDelayMax": 604800,
+		"blockGasLimit": 125000000,
+		"transactionGasLimit": 12500000,
+		"testing": {
+			"stopOnFailedTest": false,
+			"stopOnFailedContractMatching": false,
+			"stopOnNoTests": true,
+			"testAllContracts": false,
+			"traceAll": false,
+			"assertionTesting": {
+				"enabled": true,
+				"testViewMethods": true,
+				"panicCodeConfig": {
+					"failOnCompilerInsertedPanic": false,
+					"failOnAssertion": true,
+					"failOnArithmeticUnderflow": false,
+					"failOnDivideByZero": false,
+					"failOnEnumTypeConversionOutOfBounds": false,
+					"failOnIncorrectStorageAccess": false,
+					"failOnPopEmptyArray": false,
+					"failOnOutOfBoundsArrayAccess": false,
+					"failOnAllocateTooMuchMemory": false,
+					"failOnCallUninitializedVariable": false
+				}
+			},
+			"propertyTesting": {
+				"enabled": false,
+				"testPrefixes": [
+					"property_"
+				]
+			},
+			"optimizationTesting": {
+				"enabled": false,
+				"testPrefixes": [
+					"optimize_"
+				]
+			},
+			"targetFunctionSignatures": [],
+			"excludeFunctionSignatures": []
+		},
+		"chainConfig": {
+			"codeSizeCheckDisabled": true,
+			"cheatCodes": {
+				"cheatCodesEnabled": true,
+				"enableFFI": false
+			},
+			"skipAccountChecks": true
+		}
+	},
+	"compilation": {
+		"platform": "crytic-compile",
+		"platformConfig": {
+			"target": ".",
+			"solcVersion": "",
+			"exportDirectory": "",
+			"args": ["--foundry-compile-all", "--foundry-out-directory",  "artifacts"]
+		}
+	},
+	"logging": {
+		"level": "info",
+		"logDirectory": "",
+		"noColor": false
+	}
+}
diff --git a/packages/contracts-bedrock/package.json b/packages/contracts-bedrock/package.json
index 743c74d50a89..a81ac2fea050 100644
--- a/packages/contracts-bedrock/package.json
+++ b/packages/contracts-bedrock/package.json
@@ -46,6 +46,7 @@
     "lint:fix": "yarn lint:contracts:fix && yarn lint:ts:fix",
     "lint": "yarn lint:fix && yarn lint:check",
     "typechain": "typechain --target ethers-v5 --out-dir dist/types --glob 'artifacts/!(build-info)/**/+([a-zA-Z0-9_]).json'",
+    "medusa": "FOUNDRY_PROFILE=medusa medusa fuzz",
     "echidna:aliasing": "echidna-test --contract EchidnaFuzzAddressAliasing --config ./echidna.yaml .",
     "echidna:burn:gas": "echidna-test --contract EchidnaFuzzBurnGas --config ./echidna.yaml .",
     "echidna:burn:eth": "echidna-test --contract EchidnaFuzzBurnEth --config ./echidna.yaml .",
@@ -81,7 +82,7 @@
     "dotenv": "^16.0.0",
     "ds-test": "https://github.com/dapphub/ds-test.git#9310e879db8ba3ea6d5c6489a579118fd264a3f5",
     "ethereum-waffle": "^3.0.0",
-    "forge-std": "https://github.com/foundry-rs/forge-std.git#46264e9788017fc74f9f58b7efa0bc6e1df6d410",
+    "forge-std": "https://github.com/foundry-rs/forge-std.git#v1.9.4",
     "glob": "^7.1.6",
     "hardhat": "^2.9.6",
     "hardhat-deploy": "^0.11.4",
diff --git a/yarn.lock b/yarn.lock
index cc9d66aa0cc5..8c31a3d61a57 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -11524,14 +11524,14 @@ forever-agent@~0.6.1:
   resolved "https://registry.yarnpkg.com/forever-agent/-/forever-agent-0.6.1.tgz#fbc71f0c41adeb37f96c577ad1ed42d8fdacca91"
   integrity sha1-+8cfDEGt6zf5bFd60e1C2P2sypE=
 
-"forge-std@https://github.com/foundry-rs/forge-std.git#46264e9788017fc74f9f58b7efa0bc6e1df6d410":
-  version "1.5.2"
-  resolved "https://github.com/foundry-rs/forge-std.git#46264e9788017fc74f9f58b7efa0bc6e1df6d410"
-
 "forge-std@https://github.com/foundry-rs/forge-std.git#53331f4cb2e313466f72440f3e73af048c454d02":
   version "1.2.0"
   resolved "https://github.com/foundry-rs/forge-std.git#53331f4cb2e313466f72440f3e73af048c454d02"
 
+"forge-std@https://github.com/foundry-rs/forge-std.git#v1.9.4":
+  version "1.9.4"
+  resolved "https://github.com/foundry-rs/forge-std.git#1eea5bae12ae557d589f9f0f0edae2faa47cb262"
+
 form-data@^2.2.0:
   version "2.5.1"
   resolved "https://registry.yarnpkg.com/form-data/-/form-data-2.5.1.tgz#f2cbec57b5e59e23716e128fe44d4e5dd23895f4"