docs: clarify nominal interest rate semantics

.github/workflows/cadence_tests.yml

@@ -28,6 +28,10 @@ jobs:
           key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
           restore-keys: |
             ${{ runner.os }}-go-
+      - uses: actions/cache@v4
+        with:
+          path: ./imports
+          key: flow-deps-${{ hashFiles('flow.json') }}
       - name: Install Flow CLI
         env:
           FLOW_CLI_VERSION: v2.7.2

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/lib/FlowALPMath.cdc

@@ -100,13 +100,11 @@ access(all) contract FlowALPMath {
     }
 
     /// Converts a nominal yearly interest rate to a per-second multiplication factor (stored in a UFix128 as a fixed
-    /// point number with 18 decimal places). The input is the nominal annual interest rate (e.g. 0.05 for 5%), and
-    /// the result is the per-second multiplier (e.g. 1.000000001585).
-    ///
-    /// NOTE: This uses linear (nominal) decomposition — the per-second rate is simply `nominalRate / secondsPerYear`.
-    /// Because interest is then applied as `rate^timeElapsed` (exponential compounding), the effective APY will
-    /// exceed the stated nominal rate. Use `effectiveYearlyRate` to compute the true effective annual yield.
-    access(all) view fun perSecondInterestRate(nominalYearlyRate: UFix128): UFix128 {
+    /// point number with 18 decimal places). The input to this function is the relative nominal annual rate
+    /// (e.g. 0.05 for a 5% nominal yearly rate), and the result is the per-second multiplier
+    /// (e.g. 1.000000000001). For positive rates, the effective one-year growth will be slightly higher than the
+    /// nominal rate because interest compounds over time.
+    access(all) view fun perSecondInterestRate(yearlyRate: UFix128): UFix128 {
         let perSecondScaledValue = nominalYearlyRate / 31_557_600.0 // 365.25 * 24.0 * 60.0 * 60.0
         assert(
             perSecondScaledValue < UFix128.max,

cadence/tests/TEST_COVERAGE.md

@@ -204,7 +204,7 @@ The `test_helpers.cdc` file provides:
 3. **FLOW Debit Interest**
    - KinkCurve-based interest rates
    - Variable rates based on utilization
-   - Interest compounds continuously
+   - Interest compounds via discrete per-second updates
 
 4. **FLOW Credit Interest**
    - LP earnings with insurance spread