Add Aave quote-push collateral supply and toggle hooks.

Extends AaveQuotePushFlashReceiver with before/after swap collateral steps, env-driven run scripts, forkproof parity, and scoped forge tests for supply/toggle callback ordering.

Co-authored-by: Cursor <cursoragent@cursor.com>

script/deploy/DeployAaveQuotePushFlashReceiver.s.sol

@@ -13,6 +13,9 @@ import {AaveQuotePushFlashReceiver} from "../../contracts/flash/AaveQuotePushFla
  *   AAVE_POOL_ADDRESS        optional; defaults to Aave V3 mainnet Pool
  *   QUOTE_PUSH_RECEIVER_OWNER optional; defaults to deployer derived from PRIVATE_KEY
  *
+ * Post-deploy: set AAVE_QUOTE_PUSH_RECEIVER_MAINNET; verify collateralHooksVersion() == 1.
+ * Redeploy wrapper: bash scripts/deployment/redeploy-aave-quote-push-receiver-mainnet.sh
+ *
  * Usage:
  *   forge script script/deploy/DeployAaveQuotePushFlashReceiver.s.sol:DeployAaveQuotePushFlashReceiver \
  *     --rpc-url $ETHEREUM_MAINNET_RPC --broadcast -vvvv
@@ -35,5 +38,6 @@ contract DeployAaveQuotePushFlashReceiver is Script {
         vm.stopBroadcast();
 
         console.log("AaveQuotePushFlashReceiver:", address(receiver));
+        console.log("collateralHooksVersion:", receiver.collateralHooksVersion());
     }
 }

script/flash/RunMainnetAaveCwusdcUsdcQuotePushOnce.s.sol

@@ -3,6 +3,7 @@ pragma solidity ^0.8.20;
 
 import {Script, console} from "forge-std/Script.sol";
 import {AaveQuotePushFlashReceiver} from "../../contracts/flash/AaveQuotePushFlashReceiver.sol";
+import {QuotePushCollateralEnv} from "./lib/QuotePushCollateralEnv.sol";
 
 interface IDODOPMMPoolQuote {
     function querySellQuote(address trader, uint256 payQuoteAmount) external view returns (uint256 receiveBaseAmount, uint256 mtFee);
@@ -45,6 +46,9 @@ interface IDODOPMMPoolQuote {
  *                                   set UNWIND_TWO_HOP_POOL_A, UNWIND_TWO_HOP_POOL_B, UNWIND_TWO_HOP_MID_TOKEN,
  *                                   optional UNWIND_MIN_MID_OUT_RAW, then UNWIND_INTERMEDIATE_TOKEN,
  *                                   UNWIND_MIN_INTERMEDIATE_OUT_RAW, UNWIND_V3_PATH_HEX
+ *
+ * Optional collateral hooks (receiver must expose collateralHooksVersion() == 1):
+ *   See script/flash/lib/QuotePushCollateralEnv.sol and docs/runbooks/AAVE_ATOMIC_COLLATERAL_TOGGLE_RUNBOOK.md
  */
 contract RunMainnetAaveCwusdcUsdcQuotePushOnce is Script {
     address internal constant DEFAULT_POOL = 0x69776fc607e9edA8042e320e7e43f54d06c68f0E;
@@ -141,7 +145,8 @@ contract RunMainnetAaveCwusdcUsdcQuotePushOnce is Script {
                 routeId: bytes32(0),
                 settlementMode: bytes32(0),
                 submitCommitment: false
-            })
+            }),
+            collateral: QuotePushCollateralEnv.loadCollateralParams()
         });
 
         console.log("receiver", receiver);

script/flash/RunManagedMainnetAaveCwusdcUsdcQuotePushCycle.s.sol

@@ -4,6 +4,7 @@ pragma solidity ^0.8.20;
 import {Script, console} from "forge-std/Script.sol";
 import {AaveQuotePushFlashReceiver} from "../../contracts/flash/AaveQuotePushFlashReceiver.sol";
 import {QuotePushTreasuryManager} from "../../contracts/flash/QuotePushTreasuryManager.sol";
+import {QuotePushCollateralEnv} from "./lib/QuotePushCollateralEnv.sol";
 
 interface IDODOPMMPoolQuoteManaged {
     function querySellQuote(address trader, uint256 payQuoteAmount) external view returns (uint256 receiveBaseAmount, uint256 mtFee);
@@ -164,7 +165,8 @@ contract RunManagedMainnetAaveCwusdcUsdcQuotePushCycle is Script {
                 routeId: bytes32(0),
                 settlementMode: bytes32(0),
                 submitCommitment: false
-            })
+            }),
+            collateral: QuotePushCollateralEnv.loadCollateralParams()
         });
 
         console.log("minOutPmm", minOutPmm);

script/flash/RunManagedMainnetAaveCwusdtUsdtQuotePushCycle.s.sol

@@ -4,6 +4,7 @@ pragma solidity ^0.8.20;
 import {Script, console} from "forge-std/Script.sol";
 import {AaveQuotePushFlashReceiver} from "../../contracts/flash/AaveQuotePushFlashReceiver.sol";
 import {QuotePushTreasuryManager} from "../../contracts/flash/QuotePushTreasuryManager.sol";
+import {QuotePushCollateralEnv} from "./lib/QuotePushCollateralEnv.sol";
 
 interface IDODOPMMPoolQuoteManagedUsdt {
     function querySellQuote(address trader, uint256 payQuoteAmount) external view returns (uint256 receiveBaseAmount, uint256 mtFee);
@@ -95,7 +96,8 @@ contract RunManagedMainnetAaveCwusdtUsdtQuotePushCycle is Script {
                 routeId: bytes32(0),
                 settlementMode: bytes32(0),
                 submitCommitment: false
-            })
+            }),
+            collateral: QuotePushCollateralEnv.loadCollateralParams()
         });
     }
 }

script/flash/lib/QuotePushCollateralEnv.sol

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Vm} from "forge-std/Vm.sol";
+import {Strings} from "@openzeppelin/contracts/utils/Strings.sol";
+import {AaveQuotePushFlashReceiver} from "../../../contracts/flash/AaveQuotePushFlashReceiver.sol";
+
+/**
+ * @title QuotePushCollateralEnv
+ * @notice Build `QuotePushParams.collateral` from optional env vars for mainnet quote-push scripts.
+ *
+ * Env (all optional — empty when counts are zero / unset):
+ *   QUOTE_PUSH_COLLATERAL_SUPPLY_COUNT
+ *   QUOTE_PUSH_COLLATERAL_SUPPLY_{i}_ASSET
+ *   QUOTE_PUSH_COLLATERAL_SUPPLY_{i}_AMOUNT_RAW
+ *
+ *   QUOTE_PUSH_COLLATERAL_TOGGLE_BEFORE_COUNT
+ *   QUOTE_PUSH_COLLATERAL_TOGGLE_BEFORE_{i}_ASSET
+ *   QUOTE_PUSH_COLLATERAL_TOGGLE_BEFORE_{i}_ENABLE   (1 = true, 0 = false)
+ *
+ *   QUOTE_PUSH_COLLATERAL_TOGGLE_AFTER_COUNT
+ *   QUOTE_PUSH_COLLATERAL_TOGGLE_AFTER_{i}_ASSET
+ *   QUOTE_PUSH_COLLATERAL_TOGGLE_AFTER_{i}_ENABLE
+ *
+ *   QUOTE_PUSH_COLLATERAL_TOGGLE_BEFORE_UNWIND_COUNT
+ *   QUOTE_PUSH_COLLATERAL_TOGGLE_BEFORE_UNWIND_{i}_ASSET
+ *   QUOTE_PUSH_COLLATERAL_TOGGLE_BEFORE_UNWIND_{i}_ENABLE
+ */
+library QuotePushCollateralEnv {
+    Vm private constant VM = Vm(address(uint160(uint256(keccak256("hevm cheat code")))));
+
+    function loadCollateralParams() internal view returns (AaveQuotePushFlashReceiver.CollateralParams memory params) {
+        params.supplyBeforeSwap = _loadSupplies();
+        params.toggleBeforeSwap = _loadToggles("QUOTE_PUSH_COLLATERAL_TOGGLE_BEFORE");
+        params.toggleAfterSwap = _loadToggles("QUOTE_PUSH_COLLATERAL_TOGGLE_AFTER");
+        params.toggleBeforeUnwind = _loadToggles("QUOTE_PUSH_COLLATERAL_TOGGLE_BEFORE_UNWIND");
+    }
+
+    function _loadSupplies()
+        private
+        view
+        returns (AaveQuotePushFlashReceiver.CollateralSupplyStep[] memory steps)
+    {
+        uint256 n = VM.envOr("QUOTE_PUSH_COLLATERAL_SUPPLY_COUNT", uint256(0));
+        steps = new AaveQuotePushFlashReceiver.CollateralSupplyStep[](n);
+        for (uint256 i = 0; i < n; ++i) {
+            string memory prefix = string.concat("QUOTE_PUSH_COLLATERAL_SUPPLY_", Strings.toString(i), "_");
+            steps[i].asset = VM.envAddress(string.concat(prefix, "ASSET"));
+            steps[i].amount = VM.envUint(string.concat(prefix, "AMOUNT_RAW"));
+        }
+    }
+
+    function _loadToggles(string memory groupPrefix)
+        private
+        view
+        returns (AaveQuotePushFlashReceiver.CollateralToggleStep[] memory steps)
+    {
+        string memory countKey = string.concat(groupPrefix, "_COUNT");
+        uint256 n = VM.envOr(countKey, uint256(0));
+        steps = new AaveQuotePushFlashReceiver.CollateralToggleStep[](n);
+        for (uint256 i = 0; i < n; ++i) {
+            string memory prefix = string.concat(groupPrefix, "_", Strings.toString(i), "_");
+            steps[i].asset = VM.envAddress(string.concat(prefix, "ASSET"));
+            steps[i].useAsCollateral = VM.envUint(string.concat(prefix, "ENABLE")) != 0;
+        }
+    }
+}