|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to AI coding agents (Claude Code, Codex, Cursor, Copilot, and others) |
| 4 | +when working in this repository. It is loaded into agent context automatically — keep it concise. |
| 5 | + |
| 6 | +## Overview |
| 7 | + |
| 8 | +FlowYieldVaults is a Cadence yield-farming platform on Flow (`README.md`). It orchestrates yield-generating strategies (`TracerStrategy`, `FUSDEVStrategy`, `PMStrategiesV1`) composed from DeFi Actions connectors, with an AutoBalancer that rebalances positions against configured thresholds and a scheduled-rebalancing system built on `FlowTransactionScheduler`. Main contract addresses per `flow.json`: mainnet `0xb1d63873c3cc9f79`, testnet `0xd2580caf2ef07c2f`. The repo also contains Solidity sources and three git submodules in `lib/` (`FlowALP`, `flow-evm-bridge`, `flow-evm-gateway`) plus Solidity submodules under `solidity/lib/` (OpenZeppelin, forge-std, Uniswap v2, PunchSwap v3). |
| 9 | + |
| 10 | +## Setup |
| 11 | + |
| 12 | +- `git submodule update --init --recursive` — pulls `lib/FlowALP`, `lib/flow-evm-bridge`, `lib/flow-evm-gateway`, and Solidity libs under `solidity/lib/` (`.gitmodules`) |
| 13 | +- `flow deps install --skip-alias --skip-deployments` — installs Cadence deps (used by `local/setup_emulator.sh` and every CI workflow) |
| 14 | + |
| 15 | +## Build and Test Commands |
| 16 | + |
| 17 | +- `flow test ./cadence/tests/*_test.cdc` — run the full Cadence test suite (33 `*_test.cdc` files under `cadence/tests/`) |
| 18 | +- `flow test --cover --covercode="contracts" --coverprofile="coverage.lcov" ./cadence/tests/*_test.cdc` — CI coverage run (`.github/workflows/cadence_tests.yml`) |
| 19 | +- `./run_all_precision_tests.sh` — runs `rebalance_scenario{1,2,3a-d}_test.cdc` and prints precision diffs |
| 20 | +- Local bring-up sequence: `./local/run_emulator.sh` → `./local/setup_wallets.sh` → `./local/run_evm_gateway.sh` → `./local/setup_emulator.sh` (order mirrors `.github/workflows/e2e_tests.yml`) |
| 21 | +- `./local/e2e_test.sh` — end-to-end user-flow test (run after local bring-up) |
| 22 | +- `./local/punchswap/setup_punchswap.sh` + `./local/punchswap/e2e_punchswap.sh` — deploy KittyPunch/PunchSwap V3 via Foundry |
| 23 | +- `./local/incrementfi/setup_incrementfi.sh` — deploy IncrementFi swap contracts into emulator |
| 24 | +- `forge` — Solidity toolchain per `foundry.toml` (src `./solidity/src`, tests `./solidity/test`, libs `./solidity/lib`) |
| 25 | +- `docker build .` — reproduces the full seeded emulator + EVM gateway image (`Dockerfile`) |
| 26 | + |
| 27 | +## Architecture |
| 28 | + |
| 29 | +In-repo Cadence contracts (`cadence/contracts/*.cdc`, 8 files): |
| 30 | + |
| 31 | +- `FlowYieldVaults.cdc` — main platform contract (`YieldVault` / `YieldVaultManager` resources, strategy composition) |
| 32 | +- `FlowYieldVaultsAutoBalancers.cdc` — AutoBalancer instances; threshold-driven rebalancing |
| 33 | +- `FlowYieldVaultsStrategiesV2.cdc` — `FUSDEVStrategy`, `MorphoERC4626StrategyComposer`; deploy args are three EVM addresses (`flow.json` `deployments`) |
| 34 | +- `PMStrategiesV1.cdc` — PM strategy family; covered by `PMStrategiesV1_{deferred_redeem,FUSDEV,syWFLOWv}_test.cdc` |
| 35 | +- `FlowYieldVaultsSchedulerRegistry.cdc` + `FlowYieldVaultsSchedulerV1.cdc` — scheduled rebalancing on `FlowTransactionScheduler` |
| 36 | +- `FlowYieldVaultsClosedBeta.cdc` — beta-access gating (`grant_beta`, `issue_beta`, `revoke_beta` in `cadence/transactions/flow-yield-vaults/admin/`) |
| 37 | +- `UInt64LinkedList.cdc` — util used by the scheduler registry |
| 38 | + |
| 39 | +In-repo mocks tree (`cadence/contracts/mocks/`, full listing): |
| 40 | + |
| 41 | +- `EVM.cdc` — emulator EVM mock (aliased as `MockEVM` in `flow.json`) |
| 42 | +- `FlowTransactionScheduler.cdc` — emulator scheduler mock (aliased as `MockFlowTransactionScheduler`) |
| 43 | +- `FlowYieldVaultsClosedBeta_validate_beta_false.cdc` — alternate `FlowYieldVaultsClosedBeta` compiled with beta validation off (test-only drop-in) |
| 44 | +- `MockFlowALPConsumer.cdc` — test consumer for FlowALP integrations |
| 45 | +- `MockOracle.cdc`, `MockSwapper.cdc`, `MockStrategies.cdc` (contains `TracerStrategy`), `MockStrategy.cdc`, `YieldToken.cdc` |
| 46 | +- `incrementfi/SwapPairTemplate.cdc` — IncrementFi swap-pair template for emulator deployment |
| 47 | + |
| 48 | +External Cadence deps (sourced from `lib/FlowALP/…`, listed under `flow.json` `contracts`): `AdversarialReentrancyConnectors`, `AdversarialTypeSpoofingConnectors`, `BandOracleConnectors`, `DeFiActions`, `DeFiActionsUtils`, `DummyConnectors`, `ERC4626PriceOracles`, `ERC4626SinkConnectors`, `ERC4626SwapConnectors`, `ERC4626Utils`, `EVMAbiHelpers`, `EVMAmountUtils`, `EVMTokenConnectors`, `FlowALPMath`, `FlowALPv0`, `FungibleTokenConnectors`, `MOET`, `MockDexSwapper`, `MorphoERC4626SinkConnectors`, `MorphoERC4626SwapConnectors`, `SwapConnectors`, `UniswapV3SwapConnectors`. |
| 49 | + |
| 50 | +External mainnet-aliased deps (`flow.json` `dependencies`, fetched by `flow deps install`): `ArrayUtils`, `BandOracle`, `Burner`, `CrossVMMetadataViews`, `CrossVMNFT`, `CrossVMToken`, `EVM`, `FlowEVMBridge`, `FlowEVMBridgeAccessor`, `FlowEVMBridgeConfig`, `FlowEVMBridgeCustomAssociationTypes`, `FlowEVMBridgeCustomAssociations`, `FlowEVMBridgeHandlerInterfaces`, `FlowEVMBridgeHandlers`, `FlowEVMBridgeNFTEscrow`, `FlowEVMBridgeResolver`, `FlowEVMBridgeTemplates`, `FlowEVMBridgeTokenEscrow`, `FlowEVMBridgeUtils`, `FlowFees`, `FlowStorageFees`, `FlowToken`, `FlowTransactionScheduler`, `FlowTransactionSchedulerUtils`, `FungibleToken`, `FungibleTokenMetadataViews`, `IBridgePermissions`, `ICrossVM`, `ICrossVMAsset`, `IEVMBridgeNFTMinter`, `IEVMBridgeTokenMinter`, `IFlowEVMNFTBridge`, `IFlowEVMTokenBridge`, `MetadataViews`, `NonFungibleToken`, `ScopedFTProviders`, `Serialize`, `SerializeMetadata`, `StableSwapFactory`, `StringUtils`, `SwapConfig`, `SwapError`, `SwapFactory`, `SwapInterfaces`, `SwapRouter`, `USDCFlow`, `ViewResolver`. |
| 51 | + |
| 52 | +Solidity side: `solidity/src/tokens/USDC6.sol`, `solidity/src/tokens/WBTC8.sol`; submodules in `solidity/lib/`. |
| 53 | + |
| 54 | +Tx/script layout: `cadence/transactions/flow-yield-vaults/` for user ops (`create_yield_vault`, `deposit_to_yield_vault`, `withdraw_from_yield_vault`, `close_yield_vault`, `setup`) and `.../admin/` for 22 admin txs including `rebalance_auto_balancer_by_id`, `schedule_supervisor`, `upsert_strategy_config`, `upsert-pm-strategy-config`. Scripts mirror under `cadence/scripts/flow-yield-vaults/` (views, balances, scheduler status, beta metrics). |
| 55 | + |
| 56 | +## Conventions and Gotchas |
| 57 | + |
| 58 | +- Versioning (`CONTRACT_VERSIONING.md`): `main` is dev-only and never deployed; mainnet is deployed from a version branch (currently `v0`). Non-upgradable changes (storage/resource layout) require a new version branch and suffixed contract names (`V1`, `V2`). Contract names must remain stable within a version. |
| 59 | +- From `.cursor/rules/standards.mdc`: no emojis; all `.md` except `README.md` belong in `docs/`; never lower test expectations to match buggy behavior — fix the implementation instead; run all tests locally before pushing. |
| 60 | +- `flow.json` `testing` aliases: `FlowYieldVaults*` and `PMStrategiesV1` use `0x0000000000000009`; `BandOracle*`, `DeFiActions*`, `EVMAbiHelpers`, `FlowALPMath`, `FungibleTokenConnectors`, `SwapConnectors`, `UniswapV3SwapConnectors`, `MockDexSwapper` use `0x0000000000000007`; `FlowALPv0`, `MOET`, `DummyConnectors`, `AdversarialReentrancy/TypeSpoofingConnectors` use `0x0000000000000008`; `EVMAmountUtils`, `EVMTokenConnectors`, `ERC4626*`, `Morpho*` use `0x0000000000000009`; FlowEVMBridge + standard interfaces use `0x0000000000000001`; `YieldToken` uses `0x0000000000000010`. Don't reassign these. |
| 61 | +- Two rebalancing mechanisms coexist (`README.md`): AutoBalancer rebalancing (DFB value-ratio, thresholds `0.95`/`1.05`) and FlowALP position rebalancing (loan-health). Don't conflate them. |
| 62 | +- Emulator deploy order matters — see `deployments.emulator.emulator-flow-yield-vaults` in `flow.json`: `UInt64LinkedList` → `FlowYieldVaultsSchedulerRegistry` → `FlowYieldVaultsAutoBalancers` → `FlowYieldVaultsSchedulerV1` → `FlowYieldVaultsClosedBeta` → `FlowYieldVaults` → `FlowYieldVaultsStrategiesV2` → `PMStrategiesV1`. Strategy contracts take EVM-address string args. |
| 63 | +- CI (`.github/workflows/`) pins Go `1.23.x` and checks out submodules recursively across `cadence_tests.yml`, `e2e_tests.yml`, `scheduled_rebalance_tests.yml`, `incrementfi_tests.yml`, `punchswap.yml`, `build-flow-emulator.yml`. New files matching `cadence/tests/*_test.cdc` are auto-picked up by the coverage workflow; the scheduled-rebalance workflow enumerates specific files — update it when adding scheduler tests. |
| 64 | +- Mainnet admin accounts sign via Google KMS (`flow.json` `accounts.mainnet-admin`, `mainnet-flow-alp-deployer`, `mainnet-band-oracle-connectors`, `testnet-admin`, `testnet-flow-alp-deployer`). Do not add file-key entries for mainnet signers. |
| 65 | +- Code ownership: `@onflow/flow-defi` owns everything (`.github/CODEOWNERS`). |
| 66 | + |
| 67 | +## Files Not to Modify |
| 68 | + |
| 69 | +- `lib/FlowALP/`, `lib/flow-evm-bridge/`, `lib/flow-evm-gateway/` — git submodules |
| 70 | +- `solidity/lib/` — git submodules (OpenZeppelin, forge-std, Uniswap v2, PunchSwap v3) |
| 71 | +- `local/*.pkey` / `local/*.pubkey` — emulator dev keys |
| 72 | +- `SEO_AUDIT_REPORT.md`, `.audit-extract.json` — generated audit artifacts |
| 73 | +- `1-flow-yield-vaults-diagram.png`, `2-flow-yield-vaults-diagram.png`, `3-flow-yield-vaults-diagram.png` — architecture diagrams |
0 commit comments