Merge branch 'main' into alex/ADR_user-balance_in_Earn-Product

Author: AlexHentschel

.gitignore

@@ -7,4 +7,3 @@ 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

@@ -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
 

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

@@ -1037,13 +1037,13 @@ access(all) contract FlowALPModels {
         /// (used when deposits are made)
         access(EImplementation) fun consumeDepositCapacity(_ amount: UFix64, pid: UInt64)
 
-        /// Returns the per-deposit limit based on depositCapacity * depositLimitFraction
-        /// Rationale: cap per-deposit size to a fraction of the time-based
-        /// depositCapacity so a single large deposit cannot monopolize capacity.
+        /// Returns the per-deposit limit based on user deposit limit and available deposit capacity.
+        /// Rationale: cap per-deposit size to a fraction of the total depositCapacityCap
+        /// so a single large deposit cannot monopolize capacity.
         /// Excess is queued and drained in chunks (see asyncUpdatePosition),
         /// enabling fair throughput across many deposits in a block. The 5%
         /// fraction is conservative and can be tuned by protocol parameters.
-        access(EImplementation) view fun depositLimit(): UFix64
+        access(EImplementation) view fun depositLimit(pid: UInt64): UFix64
 
         /// Updates interest indices and regenerates deposit capacity for elapsed time
         access(EImplementation) fun updateForTimeChange()
@@ -1376,9 +1376,15 @@ access(all) contract FlowALPModels {
             )
         }
 
-        /// Returns the per-deposit limit based on depositCapacity * depositLimitFraction.
-        access(EImplementation) view fun depositLimit(): UFix64 {
-            return self.depositCapacity * self.depositLimitFraction
+        /// Returns the maximum amount that can be deposited to the given position without being queued.
+        access(EImplementation) view fun depositLimit(pid: UInt64): UFix64 {
+            let userCap = self.getUserDepositLimitCap()
+            let userUsed = self.getDepositUsageForPosition(pid)
+            var available = userCap - userUsed
+            if self.depositCapacity < available {
+                available = self.depositCapacity
+            }
+            return available
         }
 
         /// Updates interest indices and regenerates deposit capacity for elapsed time.