Introduce SafeYieldManager (handler pattern) with Uniswap V3 / Aerodrome / Uniswap V4 support, staking + reward harvest, and heavy clean up

.env.sample

@@ -14,6 +14,13 @@ EXPLORER_KEY=
 # endpoint; a dedicated archive node is strongly recommended for reliable forking.
 BASE_RPC_URL=
 
+# [OPTIONAL] Pin the global Hardhat Base fork. Tests default to 49470000 for
+# deterministic protocol state; override this only when intentionally testing
+# newer Base state.
+# Leave empty when running ParaSwap integration tests because its API quotes
+# against the latest chain state. Set a block only for fully deterministic tests.
+BASE_FORK_BLOCK_NUMBER=
+
 # =============================================================================
 # ACCESS CONTROL ADDRESSES
 # =============================================================================
@@ -26,59 +33,85 @@ BASE_RPC_URL=
 ADMIN_ADDRESS=
 
 # [REQUIRED] Operator address that can call executeDebtSwap() and other SafeDebtManager/LeveragedPosition functions
-# This address is stored in ProtocolRegistry and can only be changed via TimelockController (8-hour delay by default)
+# This address is stored in ProtocolRegistry and can only be changed via TimelockController (2-day delay by default)
 SAFE_OPERATOR_ADDRESS=
 
 # [REQUIRED] Pauser address that can pause/unpause SafeDebtManager and LeveragedPosition in emergencies
 # Can be the same as ADMIN_ADDRESS, or a separate EOA for faster emergency response
 PAUSER_ADDRESS=
 
 # =============================================================================
-# TIMELOCK DEPLOYMENT (shared by deploy:1_core and deploy:2_univ3_helper)
+# TIMELOCK DEPLOYMENT (shared by deploy:1_core and deploy:2_yield_manager)
 # =============================================================================
 
 # [OPTIONAL] EOA/multisig granted BOTH proposer and executor roles on the deployed
 # TimelockController. Falls back to ADMIN_ADDRESS if unset.
 TIMELOCK_ADMIN=
 
 # [OPTIONAL] Minimum delay (seconds) before queued timelock ops can execute.
-# Defaults to 28800 (8 hours).
+# Defaults to 172800 (2 days).
 TIMELOCK_DELAY=
 
 # =============================================================================
-# UNISWAP V3 HELPER DEPLOYMENT (deploy:2_univ3_helper)
+# YIELD DEPLOY CONFIG — for deploy:2_yield_manager.
+#
+# Resolution order: SYM_* module override → shared unprefixed name below →
+# legacy RHP_* fallback (addresses only) → default. An EMPTY value (X=)
+# counts as unset and falls through, so leave optional variables commented
+# out unless you mean to override them.
 # =============================================================================
 
 # [REQUIRED] Treasury address that collects performance + collect fees.
-# The deploy reverts without a valid treasury.
-RHP_TREASURY=
+# The deploys revert without a valid treasury.
+TREASURY=
 
-# [OPTIONAL] ProtocolRegistry to wire RHP to. If unset, falls back to
+# [OPTIONAL] ProtocolRegistry to wire against. Falls back to
 # PROTOCOL_REGISTRY_ADDRESS in contractAddresses.ts (auto-synced by registry/core deploys).
-RHP_REGISTRY=
+# REGISTRY=
 
-# [OPTIONAL] DEFAULT_ADMIN_ROLE holder on RatehopperUniV3Positions. Falls back to ADMIN_ADDRESS.
-RHP_INITIAL_ADMIN=
+# [OPTIONAL] DEFAULT_ADMIN_ROLE holder. Falls back to ADMIN_ADDRESS.
+# INITIAL_ADMIN=
 
 # [OPTIONAL] Reuse an existing TimelockController instead of deploying a new one.
-# When set, the shared TimelockControllerModule is skipped for this deploy.
+# When set, the shared TimelockControllerModule is skipped. Read by
+# deploy:2_yield_manager only (module override: SYM_TIMELOCK); the registry
+# deploy uses REGISTRY_TIMELOCK below.
 RHP_TIMELOCK=
 
-# [OPTIONAL] Performance fee on net profit at closeLp (bps). Default 1000 (10%).
-RHP_PERFORMANCE_FEE_BPS=
-
-# [OPTIONAL] Fee on harvested LP fees via collectLp/closeLp (bps). Default 250 (2.5%).
-RHP_FEE_COLLECT_BPS=
-
-# [OPTIONAL] Hard upper bound on BOTH fees (bps). Default 2000 (20%).
-RHP_MAX_FEE_BPS=
-
-# [OPTIONAL] Floor on NPM mint liquidity (dust-close hardening). Default 10000. Set 0 to disable.
-RHP_MIN_POSITION_LIQUIDITY=
-
-# [OPTIONAL] Floor on pool.liquidity() for spot-price reads (manipulation hardening).
-# Default 0 (disabled). See 2_DeployUniV3Helper.ts docs / RUNBOOK before raising.
-RHP_MIN_POOL_LIQUIDITY=
+# [OPTIONAL] deploy:0_registry only — DEFAULT_ADMIN_ROLE holder on the new
+# ProtocolRegistry (falls back to ADMIN_ADDRESS) and an existing
+# TimelockController to reuse instead of the shared sub-module.
+# REGISTRY_INITIAL_ADMIN=
+# REGISTRY_TIMELOCK=
+
+# [OPTIONAL] Fee config (bps). Defaults: 1000 (10%) / 250 (2.5%) / 2000 (20%).
+# PERFORMANCE_FEE_BPS=1000
+# FEE_COLLECT_BPS=250
+# MAX_FEE_BPS=2000
+
+# [OPTIONAL] Floor on NPM mint liquidity (dust-close hardening) and on
+# pool.liquidity() for spot-price reads (manipulation hardening).
+# Defaults: 10000 / 0 (disabled). See the module docs in ignition/modules/ before raising.
+# MIN_POSITION_LIQUIDITY=10000
+# MIN_POOL_LIQUIDITY=0
+
+# SYM_* overrides (rarely needed): same suffix with the SYM_ prefix, e.g.
+# SYM_TREASURY / SYM_MAX_FEE_BPS. The pauser on SafeYieldManager comes from
+# SYM_PAUSER / PAUSER_ADDRESS / ADMIN_ADDRESS.
+# SafeYieldManager additionally supports per-protocol floors:
+# SYM_UNIV3_MIN_POSITION_LIQUIDITY=10000
+# SYM_AERODROME_MIN_POSITION_LIQUIDITY=10000
+# SYM_UNIV4_MIN_POSITION_LIQUIDITY=10000
+# SYM_UNIV3_MIN_POOL_LIQUIDITY=0
+# SYM_AERODROME_MIN_POOL_LIQUIDITY=0
+# SYM_UNIV4_MIN_POOL_LIQUIDITY=0
+
+# [OPTIONAL] Uniswap V4 address overrides — default to the canonical Base
+# addresses in contractAddresses.ts; only set when targeting another network.
+# SYM_UNIV4_POSITION_MANAGER=
+# SYM_UNIVERSAL_ROUTER=
+# SYM_PERMIT2=
+# SYM_UNIV4_STATE_VIEW=
 
 # =============================================================================
 # TESTING CONFIGURATION (for running tests and scripts)
@@ -92,9 +125,6 @@ TESTING_SAFE_OWNER_KEY=
 # [REQUIRED for Safe tests] Safe wallet address for integration tests
 TESTING_SAFE_WALLET_ADDRESS=
 
-# [OPTIONAL] Address of the Safe wallet owner (used in deployRolesProxy.ts as Roles module owner)
-TESTING_SAFE_OWNER_ADDRESS=
-
 # =============================================================================
 # TIMELOCK OPERATIONS (for post-deployment configuration changes)
 # =============================================================================
@@ -105,9 +135,12 @@ TIMELOCK_ADDRESS=
 # [REQUIRED] ProtocolRegistry contract address (set after deployment)
 PROTOCOL_REGISTRY_ADDRESS=
 
-# [REQUIRED] New Paraswap V6 address (for timelock-update-paraswap.ts script)
+# [REQUIRED] New Paraswap V6 address (for timelockUpdateParaswap.ts script)
 NEW_PARASWAP_ADDRESS=
 
+# [REQUIRED] New operator address (for timelockUpdateOperator.ts script)
+NEW_OPERATOR_ADDRESS=
+
 # [OPTIONAL] Set to "true" to execute a scheduled timelock operation (default: schedule only)
 EXECUTE=
 

.github/workflows/ci.yml

@@ -33,19 +33,27 @@ jobs:
       - name: Compile
         run: yarn compile
 
-      # Coverage is scoped to the RatehopperUniV3Positions suite. The legacy
-      # debt-swap / protocol-handler suites are Base-fork tests that are not
-      # yet fully covered; running them here would fail the step before the
-      # gate. Expand the --testfiles glob (in package.json `coverage:rhp`) as
-      # coverage for those contracts is brought up.
+      # Coverage is scoped to the RatehopperUniV3Positions and
+      # SafeYieldManager suites. The debt-swap / protocol-handler suites are
+      # Base-fork tests that are not yet fully covered; running them here
+      # would fail the step before the gate. Expand the --testfiles glob (in
+      # package.json `coverage:gated`) as coverage for those contracts is
+      # brought up.
       #
       # BASE_RPC_URL is recommended: an archive RPC secret gives reliable
       # forking. Without it the config falls back to the public
       # https://mainnet.base.org endpoint.
-      - name: Run coverage (RatehopperUniV3Positions)
+      #
+      # BASE_FORK_BLOCK_NUMBER pins the default-network fork so the run is
+      # deterministic: without it the fork tracks the latest Base block and
+      # the well-known Hardhat deployer accounts inherit whatever on-chain
+      # nonce they have there, shifting every mock deploy address (and the
+      # branch coverage that depends on address ordering) from run to run.
+      - name: Run coverage (gated contracts)
         env:
           BASE_RPC_URL: ${{ secrets.BASE_RPC_URL }}
-        run: yarn coverage:rhp
+          BASE_FORK_BLOCK_NUMBER: "49470000"
+        run: yarn coverage:gated
 
       - name: Enforce branch-coverage gate
         run: yarn coverage:check

.gitignore

@@ -21,7 +21,13 @@ node_modules
 
 # Hardhat Ignition default folder for deployments against a local node
 ignition/deployments/chain-*
+ignition/deployments/local-operator-v1/
+ignition/deployments/yield-v2/
+
+# Local deployment records (keep the stable Base manifest reviewable)
+/deployments/*
+!/deployments/base.json
 /.vscode
 yarn-error.log
 eth-sdk/abis/*
-.claude
+.claude

.solcover.js

@@ -1,9 +1,12 @@
 module.exports = {
     // Mocks are test-only scaffolding — exclude from instrumentation/report.
     skipFiles: ["mocks/"],
-    // RatehopperUniV3Positions compiles with viaIR; let coverage configure the
-    // Yul optimizer so instrumentation doesn't trip "stack too deep".
-    configureYulOptimizer: true,
+    // RatehopperUniV3Positions compiles with viaIR; instrumented branches in
+    // large frames (e.g. switchLp) trip "stack too deep" unless the Yul
+    // optimizer pipeline is reduced to the minimum (Foundry ir-minimum
+    // equivalent). Supersedes configureYulOptimizer, which stopped being
+    // enough once switchLp grew.
+    irMinimum: true,
     mocha: {
         parallel: false,
     },

CLAUDE.md

@@ -16,15 +16,24 @@ RateHopper Contracts is a DeFi smart contract system enabling automated debt pos
 ### Core Contracts
 
 - **SafeDebtManager.sol**: Main entry point for debt swaps via Gnosis Safe
+- **SafeYieldManager.sol**: Single Safe-module entry point for yield (LP) protocols; delegatecalls stateless yield handlers, shared state in ERC-7201 namespace (`YieldStorage`)
 - **LeveragedPosition.sol**: Creates leveraged positions across protocols
 - **ProtocolRegistry.sol**: Central registry for token mappings, operator, and protocol configs
-- **Types.sol**: Shared type definitions
+- **Types.sol**: Shared type definitions (`DebtProtocol` enum, `YIELD_PROTOCOL_*` uint8 id constants)
+- **RatehopperUniV3Positions.sol**: Legacy standalone yield module, deployed and serving existing positions; superseded by SafeYieldManager for new positions (coexistence — do not modify)
 
-### Protocol Handlers (`contracts/protocols/`, `contracts/protocolsSafe/`)
+### Protocol Handlers (`contracts/debt/handlers/`)
 
-- **AaveV3Handler.sol**, **CompoundHandler.sol**, **MoonwellHandler.sol**, **FluidSafeHandler.sol**
+- **AaveV3DebtHandler.sol**, **CompoundDebtHandler.sol**, **MorphoDebtHandler.sol**, **MoonwellDebtHandler.sol**, **FluidSafeDebtHandler.sol** extend **BaseDebtHandler.sol**
 - Each implements: `getDebtAmount`, `switchIn`, `switchFrom`, `switchTo`, `repay`
 
+### Yield Handlers (`contracts/yield/handlers/`)
+
+- **BaseYieldHandler.sol** owns the shared LP flow, protocol diffs in virtual hooks; **V3StyleYieldHandler.sol** implements the hooks against canonical Uniswap V3 interfaces (protocol id as constructor arg); **UniV3YieldHandler.sol** extends V3StyleYieldHandler, **AerodromeYieldHandler.sol** extends BaseYieldHandler directly
+- **UniV4YieldHandler.sol** implements `IYieldHandler` directly (V4 singleton/actions model doesn't fit the V3-shaped hooks): PoolKey pool params (`keccak256(poolParam)` == V4 PoolId), Permit2 two-step approvals, UniversalRouter swaps, native ETH pools supported; V4 math imported from exact-pinned npm packages (`@uniswap/v4-core@1.0.2`, `@uniswap/v4-periphery@1.0.3` — keep exact versions, no `^`); V4 interfaces remain hand-written minimal versions vendored under `contracts/interfaces/uniswapV4/` (do not replace with official interfaces — their `Currency`/`PositionInfo` types would leak into handler code)
+- Stateless delegatecall targets: MUST NOT declare storage variables; mutable state only via `YieldStorage._yieldStorage()`
+- Pool selection params are ABI-encoded bytes (`uint24` feeTier / `int24` tickSpacing / full V4 `PoolKey` tuple)
+
 ### Access Control
 
 - **DEFAULT_ADMIN_ROLE**: Routine operations (whitelist, token mappings)
@@ -42,14 +51,14 @@ RateHopper Contracts is a DeFi smart contract system enabling automated debt pos
 
 ### Naming
 
-- Handlers: `<Protocol>Handler.sol`
+- Handlers: `<Protocol>DebtHandler.sol` (debt) / `<Protocol>YieldHandler.sol` (yield)
 - Interfaces: `I<ContractName>.sol`
-- Tests: `test/<feature>.ts`
+- Tests: `test/<area>/<feature>.ts` — areas: `debt/`, `registry/`, `yield/`, `legacy/` (deployed standalone modules), `helpers/` (fixtures/utils, no tests)
 
 ## Key Files
 
 - `contractAddresses.ts`: Token and protocol addresses
-- `test/constants.ts`, `test/utils.ts`, `test/deployUtils.ts`: Test helpers
+- `test/helpers/constants.ts`, `test/helpers/utils.ts`, `test/helpers/deployUtils.ts`: Test helpers
 
 ## Security Requirements