Merge branch 'main' into holyfuchs/FLO-19-dexOraclePriceDeviationInRange

Author: holyfuchs

.gitignore

@@ -7,3 +7,4 @@ coverage.json
 /.pr-body.md
 /.github/pr_bodies/
 lcov.info
+.flow-fork-cache

AGENTS.md

@@ -57,3 +57,9 @@ flow test cadence/tests/interest_accrual_integration_test.cdc --name test_combin
 ```bash
 grep "fun test" cadence/tests/interest_accrual_integration_test.cdc
 ```
+
+# Cadence Coding Guidelines
+
+- Use string templating, not concatenation: `"Hello \(name)"` not `"Hello ".concat(name)`
+- Use `equalWithinVariance` from `test_helpers.cdc` for equality assertions where rounding errors are possible
+- Use red-green TDD for bug fixes and extensions to functionality. Tests must use assertions (eg. `Test.assert`) to verify expected behaviour, not logs.

README.md

@@ -36,7 +36,7 @@
 
 ## 🏦 About FlowALP
 
-FlowALP is a decentralized lending and borrowing protocol built on the Flow blockchain. This repository contains the v1 Cadence implementation deployed as the `FlowALPv0` contract. It is token-agnostic (operates over any `FungibleToken.Vault`) and integrates with DeFi Actions for composability.
+FlowALP is a decentralized lending and borrowing protocol built on the Flow blockchain. This repository contains the current Cadence implementation deployed as the `FlowALPv0` contract. It is token-agnostic (operates over any `FungibleToken.Vault`) and integrates with DeFi Actions for composability.
 
 ### Key Features
 
@@ -179,7 +179,7 @@ FlowALP/
 
 - `FungibleToken.Vault`: Standard token operations
 - `DeFiActions.Sink/Source`: DeFi protocol composability
-- Entitlements: `FlowALPv0.EParticipant`, `FlowALPv0.EPosition`, `FlowALPv0.EGovernance`, `FlowALPv0.ERebalance`
+- Entitlements: `FlowALPModels.EParticipant`, `FlowALPModels.EPosition`, `FlowALPModels.EGovernance`, `FlowALPModels.ERebalance`
 
 ## 🛠️ Development
 

RebalanceArchitecture.md

@@ -1,14 +1,16 @@
 ## Updated Rebalance Architecture
 
-This system **rebalances Flow Credit Market (FCM) positions on a schedule**: at a configurable interval, a rebalancer triggers the position’s `rebalance` function. **FCM** holds positions and exposes `rebalance`.
+This system **rebalances FlowALP positions on a schedule**: at a configurable interval, a rebalancer triggers the position’s `rebalance` function. **FlowALP** holds positions and exposes `rebalance`.
+
+**Implementation note:** In the current implementation, the FlowALP pool is `FlowALPv0.Pool`.
 
 A **Rebalancer** when invoked, calls `rebalance` on the position and tries to schedules the next run.
 
 A **Supervisor** runs on its own schedule (cron) and calls `fixReschedule()` on each registered rebalancer so that transient scheduling failures (e.g. temporary lack of funds) don’t leave rebalancers stuck.
 
 ### Key Principles
 
-* **Isolation:** FCM, Rebalancer, and Supervisor are fully independent.
+* **Isolation:** FlowALP, Rebalancer, and Supervisor are fully independent.
 * **Least Privilege:** The Rebalancer can *only* trigger the `rebalance` function.
 * **Resilience:** The `fixReschedule()` call is idempotent and permissionless, ensuring the system can recover without complex auth (see below).
 
@@ -39,7 +41,7 @@ There are two rebalancer types; they behave the same for triggering rebalances;
 | **User’s control** | Full: config, fixReschedule, withdraw/destroy | Only: fixReschedule by UUID, or delete their RebalancerPaid (stops and removes the rebalancer) |
 | **Use case** | User wants full autonomy and to pay their own fees | Admin retains autonomy and pays fees for users (us only) |
 
-**Note:** The Supervisor and the Paid Rebalancer are only intended for use by us; the Standard Rebalancer is for users who self-custody. The bundled `FlowALPSupervisorV1` only tracks **paid** rebalancers (`addPaidRebalancer` / `removePaidRebalancer`). For standard rebalancers, users can call `fixReschedule()` themselves when needed.
+**Note:** The Supervisor and the Paid Rebalancer are only intended for use by us; the Standard Rebalancer is for users who self-custody. The bundled `FlowALPSupervisorv1` only tracks **paid** rebalancers (`addPaidRebalancer` / `removePaidRebalancer`). For standard rebalancers, users can call `fixReschedule()` themselves when needed.
 
 ### Why calls `fixReschedule()` are necessary
 
@@ -57,12 +59,12 @@ User creates a position, then creates a **paid** rebalancer (which lives in the
 sequenceDiagram
     actor admin
     actor User
-    participant FCM
+    participant FlowALP
     participant Paid as Paid Rebalancer Contract
     participant Supervisor
     Note over admin,Paid: One-time: admin sets defaultRecurringConfig (incl. txFunder)
     admin->>Paid: updateDefaultRecurringConfig(config)
-    User->>FCM: createPosition()
+    User->>FlowALP: createPosition()
     User->>Paid: createPaidRebalancer(positionRebalanceCapability)
     Paid-->>User: RebalancerPaid(uuid)
     User->>User: save RebalancerPaid
@@ -87,17 +89,17 @@ sequenceDiagram
 ```mermaid
 sequenceDiagram
     participant AB1 as AutoRebalancer1
-    participant FCM
+    participant FlowALP
     participant AB2 as AutoRebalancer2
     participant SUP as Supervisor
     loop every x min
-    AB1->>FCM: rebalance()
+    AB1->>FlowALP: rebalance()
     end
     loop every y min
-    AB2->>FCM: rebalance()
+    AB2->>FlowALP: rebalance()
     end
     loop every z min
     SUP->>AB2: fixReschedule()
     SUP->>AB1: fixReschedule()
     end
-```
+```

cadence/contracts/FlowALPEvents.cdc

@@ -141,11 +141,11 @@ access(all) contract FlowALPEvents {
     )
 
     /// Emitted when the insurance rate for a token is updated by governance.
-    /// The insurance rate is an annual fraction of debit interest diverted to the insurance fund.
+    /// The insurance rate is a fee of accrued debit interest diverted to the insurance fund.
     ///
     /// @param poolUUID the UUID of the pool containing the token
     /// @param tokenType the type identifier string of the token whose rate changed
-    /// @param insuranceRate the new annual insurance rate (e.g. 0.001 for 0.1%)
+    /// @param insuranceRate the new insurance fee (e.g. 0.001 for 0.1%)
     access(all) event InsuranceRateUpdated(
         poolUUID: UInt64,
         tokenType: String,
@@ -167,11 +167,11 @@ access(all) contract FlowALPEvents {
     )
 
     /// Emitted when the stability fee rate for a token is updated by governance.
-    /// The stability fee rate is an annual fraction of debit interest diverted to the stability fund.
+    /// The stability fee rate is a fee of accrued debit interest diverted to the stability fund.
     ///
     /// @param poolUUID the UUID of the pool containing the token
     /// @param tokenType the type identifier string of the token whose rate changed
-    /// @param stabilityFeeRate the new annual stability fee rate (e.g. 0.05 for 5%)
+    /// @param stabilityFeeRate the new stability fee (e.g. 0.05 for 5%)
     access(all) event StabilityFeeRateUpdated(
         poolUUID: UInt64,
         tokenType: String,

cadence/contracts/FlowALPInterestRates.cdc

@@ -4,7 +4,7 @@ access(all) contract FlowALPInterestRates {
     ///
     /// A simple interface to calculate interest rate for a token type.
     access(all) struct interface InterestCurve {
-        /// Returns the annual interest rate for the given credit and debit balance, for some token T.
+        /// Returns the annual nominal interest rate for the given credit and debit balance, for some token T.
         /// @param creditBalance The credit (deposit) balance of token T
         /// @param debitBalance The debit (withdrawal) balance of token T
         access(all) fun interestRate(creditBalance: UFix128, debitBalance: UFix128): UFix128 {
@@ -19,10 +19,10 @@ access(all) contract FlowALPInterestRates {
 
     /// FixedCurve
     ///
-    /// A fixed-rate interest curve implementation that returns a constant yearly interest rate
+    /// A fixed-rate interest curve implementation that returns a constant nominal yearly interest rate
     /// regardless of utilization. This is suitable for stable assets like MOET where predictable
     /// rates are desired.
-    /// @param yearlyRate The fixed yearly interest rate as a UFix128 (e.g., 0.05 for 5% APY)
+    /// @param yearlyRate The fixed yearly nominal rate as a UFix128 (e.g., 0.05 for a 5% nominal yearly rate)
     access(all) struct FixedCurve: InterestCurve {
 
         access(all) let yearlyRate: UFix128
@@ -64,7 +64,7 @@ access(all) contract FlowALPInterestRates {
     /// This matches the live TokenState accounting used by FlowALP.
     ///
     /// @param optimalUtilization The target utilization ratio (e.g., 0.80 for 80%)
-    /// @param baseRate The minimum yearly interest rate (e.g., 0.01 for 1% APY)
+    /// @param baseRate The minimum yearly nominal rate (e.g., 0.01 for a 1% nominal yearly rate)
     /// @param slope1 The total rate increase from 0% to optimal utilization (e.g., 0.04 for 4%)
     /// @param slope2 The total rate increase from optimal to 100% utilization (e.g., 0.60 for 60%)
     access(all) struct KinkCurve: InterestCurve {

cadence/contracts/FlowALPModels.cdc

@@ -1883,6 +1883,9 @@ access(all) contract FlowALPModels {
         /// Returns whether a queued deposit exists for the given token type
         access(all) view fun hasQueuedDeposit(_ type: Type): Bool
 
+        /// Returns the queued deposit balance for the given token type, or nil if none exists
+        access(all) view fun getQueuedDepositBalance(_ type: Type): UFix64?
+
         // --- Draw Down Sink ---
 
         /// Returns an authorized reference to the draw-down sink, or nil if none is configured.
@@ -2042,6 +2045,14 @@ access(all) contract FlowALPModels {
             return self.queuedDeposits[type] != nil
         }
 
+        /// Returns the queued deposit balance for the given token type, or nil if none exists.
+        access(all) view fun getQueuedDepositBalance(_ type: Type): UFix64? {
+            if let queued = &self.queuedDeposits[type] as &{FungibleToken.Vault}? {
+                return queued.balance
+            }
+            return nil
+        }
+
         // --- Draw Down Sink ---
 
         /// Returns an authorized reference to the draw-down sink, or nil if none is configured.
@@ -2114,6 +2125,9 @@ access(all) contract FlowALPModels {
 
         /// Rebalances the specified position.
         access(EPosition | ERebalance) fun rebalancePosition(pid: UInt64, force: Bool)
+
+        /// Queues the position for rebalance/update if its health bounds have changed.
+        access(EPosition) fun queuePositionForUpdateIfNecessary(pid: UInt64)
     }
 
     /// Factory function to create a new InternalPositionImplv1 resource.