|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +Guidance for AI coding agents (Claude Code, Codex, Cursor, Copilot, Gemini CLI) working in |
| 4 | +this repository. Loaded into agent context automatically — keep it concise. |
| 5 | + |
| 6 | +## Overview |
| 7 | + |
| 8 | +DeFiActions is a Cadence framework of composable "money LEGO" primitives (Source, Sink, |
| 9 | +Swapper, PriceOracle, Flasher, AutoBalancer) for building DeFi workflows on Flow. Core |
| 10 | +interfaces live in `cadence/contracts/interfaces/DeFiActions.cdc`; protocol adapters live |
| 11 | +under `cadence/contracts/connectors/`. The repo also contains a Foundry-managed Solidity |
| 12 | +side under `solidity/` for EVM-side contracts used by the EVM connectors. Status: beta — |
| 13 | +README explicitly warns "not yet intended for use in production systems." |
| 14 | + |
| 15 | +## Build and Test Commands |
| 16 | + |
| 17 | +All Cadence commands are driven by the `Makefile`: |
| 18 | + |
| 19 | +- `make test` — run the full Cadence test suite with coverage |
| 20 | + (`flow test --cover --covercode="contracts" --coverprofile="coverage.lcov" ./cadence/tests/*_test.cdc`) |
| 21 | +- `make lint` — run `flow cadence lint` over every `cadence/contracts/**/*.cdc` |
| 22 | +- `make ci` — `lint` + `test` (the job run by `.github/workflows/cadence_tests.yml`) |
| 23 | +- `flow deps install --skip-alias --skip-deployments` — install Flow dependencies |
| 24 | + (matches CI step; plain `flow deps install` is shown in README) |
| 25 | +- `flow test cadence/tests/<Specific>_test.cdc` — run one suite |
| 26 | + |
| 27 | +Solidity side (Foundry, configured via `foundry.toml`): |
| 28 | + |
| 29 | +- `forge fmt --check` — format check (CI gate, `.github/workflows/test.yml`) |
| 30 | +- `forge build --sizes --via-ir --optimize` — build (CI gate) |
| 31 | +- Sources in `solidity/src/`, tests in `solidity/test/`, libs in `solidity/lib/` |
| 32 | + (git submodules: forge-std, flow-sol-utils, openzeppelin-contracts, aave-v3-core, |
| 33 | + v2-core, v2-periphery, More-Vaults — see `.gitmodules`) |
| 34 | + |
| 35 | +CI uses Flow CLI `v2.15.3` and Go `1.23.x` (`.github/workflows/cadence_tests.yml`). |
| 36 | + |
| 37 | +## Architecture |
| 38 | + |
| 39 | +``` |
| 40 | +cadence/ |
| 41 | + contracts/ |
| 42 | + interfaces/DeFiActions.cdc # All core interfaces + AutoBalancer resource |
| 43 | + utils/ # DeFiActionsUtils, ERC4626Utils, EVMAbiHelpers |
| 44 | + connectors/ |
| 45 | + FungibleTokenConnectors.cdc # VaultSink, VaultSource, VaultSinkAndSource |
| 46 | + SwapConnectors.cdc # MultiSwapper, SwapSource, SwapSink, SequentialSwapper |
| 47 | + band-oracle/ # BandOracleConnectors.cdc |
| 48 | + increment-fi/ # Swap, Staking, PoolLiquidity, Flashloan connectors |
| 49 | + evm/ # UniswapV2/V3, ERC4626 (PriceOracle/Sink/Swap), |
| 50 | + # EVMNativeFLOW, EVMToken, EVMAmountUtils |
| 51 | + evm/morpho/ # MorphoERC4626 Sink + Swap connectors |
| 52 | + tests/ # *_test.cdc suites, fork/ (mainnet-fork tests), |
| 53 | + # contracts/ (mocks: MockOracle, MockSwapper, |
| 54 | + # TokenA/B/C, TestTokenMinter, ExecutionCallbackRecorder) |
| 55 | + transactions/ # Per-connector tx scripts (12 subfolders) |
| 56 | + scripts/ # Read-only query scripts per connector family |
| 57 | +solidity/ |
| 58 | + src/ test/ lib/ # Foundry layout (per foundry.toml) |
| 59 | +``` |
| 60 | + |
| 61 | +### Core interfaces (verified in `cadence/contracts/interfaces/DeFiActions.cdc`) |
| 62 | + |
| 63 | +| Name | Kind | Line | |
| 64 | +|---|---|---| |
| 65 | +| `Sink` | `struct interface` | 267 | |
| 66 | +| `Source` | `struct interface` | 299 | |
| 67 | +| `Swapper` | `struct interface` | 345 | |
| 68 | +| `PriceOracle` | `struct interface` | 430 | |
| 69 | +| `Flasher` | `struct interface` | 449 | |
| 70 | +| `Quote` | `struct interface` | 329 | |
| 71 | +| `UniqueIdentifier` | `struct` | 130 | |
| 72 | +| `ComponentInfo` | `struct` | 151 | |
| 73 | +| `AutoBalancer` | **`resource`** | 708 | |
| 74 | + |
| 75 | +The framework is primarily struct-based for lightweight composition, **except |
| 76 | +`AutoBalancer`**, which is a resource (conforms to `FungibleToken.Receiver`/`Provider`, |
| 77 | +`ViewResolver.Resolver`, `Burner.Burnable`, `FlowTransactionScheduler.TransactionHandler`). |
| 78 | +Do not claim "everything is a struct." |
| 79 | + |
| 80 | +## Conventions and Gotchas |
| 81 | + |
| 82 | +- **AutoBalancer is a resource, not a struct.** It wraps an inner `@{FungibleToken.Vault}?` |
| 83 | + and must be destroyed via `Burner.burn()` so the inner vault's `burnCallback()` runs |
| 84 | + (see field comments around line 725–727). |
| 85 | +- **Weak guarantees.** Source/Sink/Swapper interfaces intentionally promise very little; |
| 86 | + output validation is the caller's responsibility (README "Weak Guarantees Philosophy"). |
| 87 | +- **`testing` alias is `0x0000000000000009`** for every DeFiActions contract in `flow.json` |
| 88 | + except `BandOracleConnectors` and `SwapConnectors` (both `0x0000000000000007`) and the |
| 89 | + test token contracts `TokenA/B/C` + `TestTokenMinter` (`0x0000000000000010`). |
| 90 | +- **Deployed addresses live in `flow.json` aliases**, not in code. Verified mainnet/testnet |
| 91 | + pairs (partial list): |
| 92 | + - `DeFiActions` / `DeFiActionsUtils` — mainnet `0x6d888f175c158410`, testnet `0x0b11b1848a8aa2c0` |
| 93 | + - `FungibleTokenConnectors` — mainnet `0x0c237e1265caa7a3`, testnet `0x4cd02f8de4122c84` |
| 94 | + - `SwapConnectors` — mainnet `0xe1a479f0cb911df9`, testnet `0xad228f1c13a97ec1` |
| 95 | + - `BandOracleConnectors` — mainnet `0xe36ef556b8b5d955`, testnet `0xbb76ea2f8aad74a0` |
| 96 | + - `EVMNativeFLOWConnectors` / `EVMTokenConnectors` — mainnet `0x1a771b21fcceadc2`, |
| 97 | + testnet `0xbee3f3636cec263a` |
| 98 | + - IncrementFi connectors have `testing` aliases only — no mainnet/testnet in `flow.json` |
| 99 | + (README lists mainnet/testnet addresses `0xe844c7cf7430a77c` / `0x494536c102537e1e` |
| 100 | + which are not mirrored into `flow.json`; treat the README as the source for those). |
| 101 | +- **`mainnet-fork` network** is defined in `flow.json` (host `127.0.0.1:3569`, fork |
| 102 | + `mainnet`). Fork-only tests live in `cadence/tests/fork/`. |
| 103 | +- **Coverage output** lands at `coverage.lcov` at repo root (Makefile `test` target). |
| 104 | +- **Lint gate** (`make lint`) greps for `"Lint passed"` in `flow cadence lint` output — |
| 105 | + a lint warning fails CI. |
| 106 | +- **`emulator-account.pkey` is committed** intentionally (test key, not a real credential). |
| 107 | +- **Solidity submodules must be initialized** (`git submodule update --init --recursive`) |
| 108 | + before `forge build` — CI uses `submodules: recursive` on checkout. |
| 109 | + |
| 110 | +## Files Not to Modify |
| 111 | + |
| 112 | +- `solidity/lib/**` — git submodules (forge-std, openzeppelin-contracts, aave-v3-core, |
| 113 | + v2-core, v2-periphery, flow-sol-utils, More-Vaults) |
| 114 | +- `emulator-account.pkey` — emulator test key, required as-is by `flow.json` |
| 115 | +- `coverage.lcov` — generated by `make test` |
| 116 | +- `foundry.lock` — Foundry lockfile |
0 commit comments