Merge branch 'main' into vishal/add_cadence_linter

Author: turbolent

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

FlowActions

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

README.md

@@ -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/FlowALPEvents.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 {