chore: add CREATE2 replay and paymaster refill scripts (#23)

Deterministic replay scripts used for chain onboarding and incident response:

- replay-legacy: replays the v1.1.0/v2.0.0/v2.1.0 contract suites onto a new
  chain via the canonical CREATE2 proxy using recorded initcode, preserving
  canonical addresses (used for Robinhood Chain and Chiliz)
- replay-npf: Nexus paymaster factory replay for Robinhood
- replay-v210: v2.1.0 suite replay for Chiliz Spicy
- RefillChilizPaymasters: splits deployer CHZ across both node paymaster
  EntryPoint deposits (AA31 incident runbook; dynamic amount with gas buffer
  and dust guard)

Deploy order for legacy suites: validator, implementation, bootstrap,
forwarder, then factory last (v1.1.0 factory checks implementation code;
Nexus 1.2.0+ implementation constructor calls the validator).

Author: fichiokaku

script/deploy/replay-legacy/RefillChilizPaymasters.s.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import { Script } from "forge-std/Script.sol";
+import { console2 } from "forge-std/console2.sol";
+
+interface IEntryPointDeposit {
+    function depositTo(address account) external payable;
+    function balanceOf(address account) external view returns (uint256);
+}
+
+/// Emergency top-up of the Chiliz node paymaster EntryPoint deposits (first used for
+/// the 2026-07-12 AA31 incident; no auto-refill exists in mee-node, refills are manual).
+/// Splits the deployer's CHZ balance evenly between both node paymasters, keeping
+/// GAS_BUFFER for future deploy gas. Refuses to run if the split would be dust.
+contract RefillChilizPaymasters is Script {
+    IEntryPointDeposit constant EP = IEntryPointDeposit(0x0000000071727De22E5E9d8BAf0edAc6f37da032);
+    address constant PM_NODE0 = 0x130Ed027b1CDF13977D125f7B6bAB45ea2Aa17CE;
+    address constant PM_NODE1 = 0x3F801481fd20E5fb00df349AFD49B9e2085FD948;
+    uint256 constant GAS_BUFFER = 10 ether;
+    uint256 constant MIN_DEPOSIT_EACH = 50 ether;
+
+    function run() external {
+        uint256 pk;
+        try vm.envUint("MAINNET_PRIVATE_KEY") returns (uint256 v) {
+            pk = v;
+        } catch {
+            pk = uint256(vm.envBytes32("MAINNET_PRIVATE_KEY"));
+        }
+
+        address deployer = vm.addr(pk);
+        require(deployer.balance > GAS_BUFFER, "balance below gas buffer");
+        uint256 each = (deployer.balance - GAS_BUFFER) / 2;
+        require(each >= MIN_DEPOSIT_EACH, "split would be dust; bridge more first");
+        console2.log("depositing to each paymaster:", each);
+
+        vm.startBroadcast(pk);
+        EP.depositTo{ value: each }(PM_NODE0);
+        EP.depositTo{ value: each }(PM_NODE1);
+        vm.stopBroadcast();
+
+        console2.log("node-0 paymaster deposit:", EP.balanceOf(PM_NODE0));
+        console2.log("node-1 paymaster deposit:", EP.balanceOf(PM_NODE1));
+    }
+}

script/deploy/replay-legacy/ReplayLegacySuites.s.sol

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import { Script } from "forge-std/Script.sol";
+import { console2 } from "forge-std/console2.sol";
+
+/// Replays the v1.1.0, v2.0.0 and v2.1.0 MEE contract suites onto a new chain via the
+/// canonical deterministic CREATE2 deployer. Payloads are verbatim creation-tx inputs
+/// harvested from Chiliz mainnet (see creations.json in the scratchpad of the 2026-07-10
+/// session, or re-harvest via routescan). Constructor wrapper avoids forge's broadcast
+/// inspector mis-decoding old initcode against current artifacts.
+contract SuiteReplayer {
+    constructor(bytes[] memory payloads, address[] memory expected) {
+        for (uint256 i = 0; i < payloads.length; i++) {
+            if (expected[i].code.length > 0) continue;
+            (bool success, ) = 0x4e59b44847b379578588920cA78FbF26c0B4956C.call(payloads[i]);
+            require(success, "create2 deploy reverted");
+            require(expected[i].code.length > 0, "no code at expected address");
+        }
+    }
+}
+
+contract ReplayLegacySuites is Script {
+    string constant DIR = "script/deploy/replay-legacy/";
+
+    function run() external {
+        uint256 pk;
+        try vm.envUint("MAINNET_PRIVATE_KEY") returns (uint256 v) {
+            pk = v;
+        } catch {
+            pk = uint256(vm.envBytes32("MAINNET_PRIVATE_KEY"));
+        }
+
+        vm.startBroadcast(pk);
+        _suite110();
+        _suite200();
+        _suite210();
+        vm.stopBroadcast();
+    }
+
+    function _suite110() internal {
+        string[6] memory names = ["v110-implementation", "v110-bootstrap", "v110-validator", "v110-composable", "v110-forwarder", "v110-factory"];
+        address[] memory expected = new address[](6);
+        expected[0] = 0x000000001964d23C59962Fc7A912872EE8fB3b6A;
+        expected[1] = 0x000000c4781Be3349F81d341027fd7A4EdFa4Dd2;
+        expected[2] = 0x00000000E894100bEcFc7c934Ab7aC8FBA08A44c;
+        expected[3] = 0x000000eff5C221A6bdB12381868307c9Db5eB462;
+        expected[4] = 0x000000001f1c68bD5bF69aa1cCc1d429700D41Da;
+        expected[5] = 0x0000000C8B6b3329cEa5d15C9d8C15F1f254ec3C;
+        _deploy(_payloads6(names), expected, "v1.1.0");
+    }
+
+    function _suite200() internal {
+        string[5] memory names5 = ["v200-validator", "shared-forwarder", "v200-implementation", "v200-bootstrap", "v200-factory"];
+        address[] memory expected = new address[](5);
+        expected[0] = 0x00000000d12897DDAdC2044614A9677B191A2d95;
+        expected[1] = 0x000000Afe527A978Ecb761008Af475cfF04132a1;
+        expected[2] = 0x000000004F43C49e93C970E84001853a70923B03;
+        expected[3] = 0x00000000D3254452a909E4eeD47455Af7E27C289;
+        expected[4] = 0x000000001D1D5004a02bAfAb9de2D6CE5b7B13de;
+        bytes[] memory payloads = new bytes[](5);
+        for (uint256 i = 0; i < 5; i++) payloads[i] = _read(names5[i]);
+        _deploy(payloads, expected, "v2.0.0");
+    }
+
+    function _suite210() internal {
+        string[4] memory names4 = ["v210-validator", "v210-implementation", "v210-bootstrap", "v210-factory"];
+        address[] memory expected = new address[](4);
+        expected[0] = 0x0000000031ef4155C978d48a8A7d4EDba03b04fE;
+        expected[1] = 0x00000000383e8cBe298514674Ea60Ee1d1de50ac;
+        expected[2] = 0x0000003eDf18913c01cBc482C978bBD3D6E8ffA3;
+        expected[3] = 0x0000006648ED9B2B842552BE63Af870bC74af837;
+        bytes[] memory payloads = new bytes[](4);
+        for (uint256 i = 0; i < 4; i++) payloads[i] = _read(names4[i]);
+        _deploy(payloads, expected, "v2.1.0");
+    }
+
+    function _payloads6(string[6] memory names) internal view returns (bytes[] memory payloads) {
+        payloads = new bytes[](6);
+        for (uint256 i = 0; i < 6; i++) payloads[i] = _read(names[i]);
+    }
+
+    function _read(string memory name) internal view returns (bytes memory) {
+        return vm.parseBytes(vm.readFile(string.concat(DIR, name, ".calldata")));
+    }
+
+    function _deploy(bytes[] memory payloads, address[] memory expected, string memory label) internal {
+        new SuiteReplayer(payloads, expected);
+        console2.log(label, "suite deployed/verified");
+    }
+}

script/deploy/replay-legacy/shared-forwarder.calldata

@@ -0,0 +1 @@
+0x0000000000000000000000000000000000000000f9941fb84509c0031a6fc1046080806040523460155761014d908161001a8239f35b5f80fdfe60806040526004361015610018575b366100bd576100bd565b5f3560e01c63101e89520361000e5760203660031901126100b95760043573ffffffffffffffffffffffffffffffffffffffff81168082036100b95715610091575f8080809334905af11561006957005b7f096dc0e1000000000000000000000000000000000000000000000000000000005f5260045ffd5b7fd92e233d000000000000000000000000000000000000000000000000000000005f5260045ffd5b5f80fd5b60846040517f08c379a0000000000000000000000000000000000000000000000000000000008152602060048201526024808201527f55736520666f727761726428292066756e6374696f6e20746f2073656e64204560448201527f74686572000000000000000000000000000000000000000000000000000000006064820152fdfea164736f6c634300081b000a

script/deploy/replay-legacy/v110-bootstrap.calldata

@@ -0,0 +1 @@
+0x0000000000000000000000000000000000000000ab54a224202cc4025cc092c260c0346100a457601f61179138819003918201601f19168301916001600160401b038311848410176100a9578084926020946040528339810103126100a457516001600160a01b0381168082036100a45761009c57506f71727de22e5e9d8baf0edac6f37da0326080525b3060a0526040516116d190816100c082396080518181816102e10152818161043f015261050e015260a0518160de0152f35b60805261006a565b600080fd5b634e487b7160e01b600052604160045260246000fdfe6080604052600436101561001257600080fd5b60003560e01c80632825113f146100b75780634ce1f402146100b2578063584465f2146100ad5780635e765374146100a85780636d61fe70146100a35780638a91b0e31461009e578063c9ce75b114610099578063d60b347f14610094578063ea5a6d911461008f5763ecd059611461008a57600080fd5b6105f9565b6104c6565b610463565b610412565b6103be565b6103a7565b61027e565b6101c9565b610193565b3461013a576100c53661013f565b903073ffffffffffffffffffffffffffffffffffffffff7f000000000000000000000000000000000000000000000000000000000000000016146101105761010e9130916109d3565b005b7f52cafe320000000000000000000000000000000000000000000000000000000060005260046000fd5b600080fd5b90602060031983011261013a5760043567ffffffffffffffff811161013a578260238201121561013a5780600401359267ffffffffffffffff841161013a5760248460051b8301011161013a576024019190565b3461013a5761010e6101a43661013f565b3391610aa6565b73ffffffffffffffffffffffffffffffffffffffff81160361013a57565b3461013a57602060031936011261013a576004356101e6816101ab565b73ffffffffffffffffffffffffffffffffffffffff8116156102545761010e9033600052600060205260406000209073ffffffffffffffffffffffffffffffffffffffff167fffffffffffffffffffffffff0000000000000000000000000000000000000000825416179055565b7f8579befe0000000000000000000000000000000000000000000000000000000060005260046000fd5b3461013a57602060031936011261013a5773ffffffffffffffffffffffffffffffffffffffff6004356102b0816101ab565b1660008181526020819052604081205473ffffffffffffffffffffffffffffffffffffffff1661032c5750506103287f00000000000000000000000000000000000000000000000000000000000000005b60405173ffffffffffffffffffffffffffffffffffffffff90911681529081906020820190565b0390f35b6040816103289373ffffffffffffffffffffffffffffffffffffffff935280602052205416610301565b90602060031983011261013a5760043567ffffffffffffffff811161013a578260238201121561013a5780600401359267ffffffffffffffff841161013a576024848301011161013a576024019190565b3461013a5761010e6103b836610356565b906106a5565b3461013a576103cc36610356565b505033600052600060205260406000207fffffffffffffffffffffffff00000000000000000000000000000000000000008154169055600080f35b600091031261013a57565b3461013a57600060031936011261013a57602060405173ffffffffffffffffffffffffffffffffffffffff7f0000000000000000000000000000000000000000000000000000000000000000168152f35b3461013a57602060031936011261013a5773ffffffffffffffffffffffffffffffffffffffff600435610495816101ab565b166000526000602052602073ffffffffffffffffffffffffffffffffffffffff604060002054161515604051908152f35b6104cf3661013f565b907fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffec36013560601c73ffffffffffffffffffffffffffffffffffffffff7f00000000000000000000000000000000000000000000000000000000000000001681149081156105ca575b81156105c0575b50156105965734610556575b61010e913391610aa6565b600080808034335af1610567610d1a565b5061054b577f361241bd0000000000000000000000000000000000000000000000000000000060005260046000fd5b7f0e4204bc0000000000000000000000000000000000000000000000000000000060005260046000fd5b905033143861053f565b905033600052600060205273ffffffffffffffffffffffffffffffffffffffff60406000205416811490610538565b3461013a57602060031936011261013a57602060043560028114908115610626575b506040519015158152f35b60039150143861061b565b9060141161013a5790601490565b919091357fffffffffffffffffffffffffffffffffffffffff00000000000000000000000081169260148110610673575050565b7fffffffffffffffffffffffffffffffffffffffff000000000000000000000000929350829060140360031b1b161690565b9060148110156106b3575050565b33600052600060205273ffffffffffffffffffffffffffffffffffffffff60406000205416610767576106f56106ef6106fb9261076594610631565b9061063f565b60601c90565b6107253373ffffffffffffffffffffffffffffffffffffffff166000526000602052604060002090565b9073ffffffffffffffffffffffffffffffffffffffff167fffffffffffffffffffffffff0000000000000000000000000000000000000000825416179055565b565b61079a6106ef73ffffffffffffffffffffffffffffffffffffffff92336000526000602052836040600020541694610631565b60601c16036107a557565b7f93360fbf0000000000000000000000000000000000000000000000000000000060005273ffffffffffffffffffffffffffffffffffffffff331660045260246000fd5b7f4e487b7100000000000000000000000000000000000000000000000000000000600052604160045260246000fd5b90601f601f19910116810190811067ffffffffffffffff82111761083b57604052565b6107e9565b67ffffffffffffffff811161083b5760051b60200190565b604080519091906108698382610818565b6001815291601f19018260005b82811061088257505050565b806060602080938501015201610876565b3561089d816101ab565b90565b7f4e487b7100000000000000000000000000000000000000000000000000000000600052603260045260246000fd5b8051156108dc5760200190565b6108a0565b91908110156108dc5760051b810135907fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff618136030182121561013a570190565b9035907fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe18136030182121561013a570180359067ffffffffffffffff821161013a57602001918160051b3603831361013a57565b357fffffffff000000000000000000000000000000000000000000000000000000008116810361013a5790565b67ffffffffffffffff811161083b57601f01601f191660200190565b604051906109cd602083610818565b60008252565b919060005b8181106109e55750505050565b80610a6f846109f760019486896108e1565b610a19610a076060830183610921565b610a1360408501610975565b91610d4a565b73ffffffffffffffffffffffffffffffffffffffff82356000610a3b826101ab565b501615610a7557610a60610a54610a6892846002611641565b925b6080810190610921565b9190926108cf565b5191610e6f565b016109d8565b50610a68610a60610a84610858565b92610a8d6109be565b610a96856108cf565b52610aa0846108cf565b50610a56565b919060005b818110610ab85750505050565b80610b1484610aca60019486896108e1565b610ada610a076060830183610921565b73ffffffffffffffffffffffffffffffffffffffff82356000610afc826101ab565b501615610a7557610a60610a54610a68928489611641565b01610aab565b60005b838110610b2d5750506000910152565b8181015183820152602001610b1d565b60208183031261013a5780519067ffffffffffffffff821161013a570181601f8201121561013a57805190610b7182610840565b92610b7f6040519485610818565b82845260208085019360051b8301019181831161013a5760208101935b838510610bab57505050505090565b845167ffffffffffffffff811161013a5782019083603f8301121561013a57602082015190610bd9826109a2565b610be66040519182610818565b828152604084840101861061013a57610c0a60209493859460408685019101610b1a565b815201940193610b9c565b90601f606093601f1992845260406020850152610c418151809281604088015260208888019101610b1a565b0116010190565b6040513d6000823e3d90fd5b600090610cab610ce093610c9660405185602082015285602182015285602282015285602682015285602a82015260208152610c91604082610818565b611206565b926020610ca282610893565b91013590610fa7565b9060405193849283927fd691c96400000000000000000000000000000000000000000000000000000000845260048401610c15565b038183335af1908115610d1557600091610cf8575090565b61089d91503d806000833e610d0d8183610818565b810190610b3d565b610c48565b3d15610d45573d90610d2b826109a2565b91610d396040519384610818565b82523d6000602084013e565b606090565b9290917fffffffff000000000000000000000000000000000000000000000000000000006040519116602082015260048152610d87602482610818565b906000915b83831015610e28576000908360051b8601357fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffa187360301811215610e245760019291610ddc610e1c9289016110e9565b925060206040519382610df88694518092858088019101610b1a565b8301610e0c82518093858085019101610b1a565b010103601f198101835282610818565b920191610d8c565b8280fd5b9350915050565b91908110156108dc5760051b810135907fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc18136030182121561013a570190565b919060005b818110610e82575050505050565b610e8d818386610e2f565b9085610e9883611046565b610ea181611037565b610ed357610ecd90610eb98460206001960190611053565b50604081013590876020820135913561150d565b01610e74565b50906001610ee082611046565b610ee981611037565b03610f7d57806020610efc920190611053565b5090600080610f1d60408501358501604051918282602082943591016110a4565b039060208601355afa610f2e610d1a565b9015610f535786610f4e918460806001960135916060820135913561150d565b610ecd565b7f6e47f6190000000000000000000000000000000000000000000000000000000060005260046000fd5b7fe21219780000000000000000000000000000000000000000000000000000000060005260046000fd5b6054907fffffffffffffffffffffffffffffffffffffffff0000000000000000000000009361089d9360405195869360601b1660208401526034830152610ff78151809260208686019101610b1a565b81010301601f198101835282610818565b7f4e487b7100000000000000000000000000000000000000000000000000000000600052602160045260246000fd5b6002111561104157565b611008565b35600281101561013a5790565b9035907fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe18136030182121561013a570180359067ffffffffffffffff821161013a5760200191813603831361013a57565b908092918237016000815290565b9291926110be826109a2565b916110cc6040519384610818565b82948184528183011161013a578281602093846000960137010152565b6110f281611046565b6110fb81611037565b6111435761113c81602061089d9301906111376111188383611053565b6111326111286040860186610921565b93909236916110b2565b6113ae565b611053565b36916110b2565b600161114e82611046565b61115781611037565b036111dc5760008061116c6020840184611053565b5060405180611186816020858101358601803591016110a4565b0391355afa90611194610d1a565b91156111b2576111ab81604061089d930190610921565b90836113ae565b7f6533cc8d0000000000000000000000000000000000000000000000000000000060005260046000fd5b7f948579550000000000000000000000000000000000000000000000000000000060005260046000fd5b60208151910151906020811061121a575090565b7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff9060200360031b1b1690565b60408136031261013a57604051906040820182811067ffffffffffffffff82111761083b576040528035600481101561013a57825260208101359067ffffffffffffffff821161013a570136601f8201121561013a576112ae9036906020813591016110b2565b602082015290565b6004111561104157565b919082604091031261013a576020825192015190565b156112dd57565b7fa31844b000000000000000000000000000000000000000000000000000000000600052600360045260246000fd5b1561131357565b7fa31844b000000000000000000000000000000000000000000000000000000000600052600260045260246000fd5b1561134957565b7fa31844b000000000000000000000000000000000000000000000000000000000600052600160045260246000fd5b1561137f57565b7fa31844b000000000000000000000000000000000000000000000000000000000600052600060045260246000fd5b91806113b957505050565b60005b8181106113c95750505050565b6113dc6113d7828486610e2f565b611247565b9060208160051b860101519180516113f3816112b6565b6113fc816112b6565b61141f576001926114136020611419930151611206565b14611378565b016113bc565b6001815161142c816112b6565b611435816112b6565b036114595760019261144d6020611454930151611206565b1115611342565b611419565b60028151611466816112b6565b61146f816112b6565b0361148e576001926114876020611454930151611206565b101561130c565b6003815161149b816112b6565b6114a4816112b6565b036114e3576001926114c66020611454930151602080825183010191016112c0565b9082101591826114d8575b50506112d6565b1115905038806114d1565b7f2c50c45e0000000000000000000000000000000000000000000000000000000060005260046000fd5b9291939060005b84811061152357505050505050565b60208160051b830101519073ffffffffffffffffffffffffffffffffffffffff871691604051602081019061157681611568868b869091604092825260208201520190565b03601f198101835282610818565b519020833b1561013a576040517fa39e07870000000000000000000000000000000000000000000000000000000081526004810191909152602481019190915273ffffffffffffffffffffffffffffffffffffffff85166044820152916000908390606490829084905af1918215610d15576001926115f7575b5001611514565b80611606600061160c93610818565b80610407565b386115f0565b7f4e487b7100000000000000000000000000000000000000000000000000000000600052605160045260246000fd5b9190918060021461165c576001036116125761089d91610c54565b50906000611668610858565b926020833593611677856101ab565b013590604051933892602083519301915af1156116bb573d81523d6000602083013e60203d8201016040528151156108dc5760208201526116b7816108cf565b5090565b3d6000823e3d90fdfea164736f6c634300081b000a0000000000000000000000000000000071727de22e5e9d8baf0edac6f37da032