Merge branch 'main' into taras/173-liquidation-edge-cases

Author: mts1715

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.

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

@@ -99,9 +99,11 @@ access(all) contract FlowALPMath {
         return diffBps <= maxDeviationBps
     }
 
-    /// Converts a yearly interest rate to a per-second multiplication factor (stored in a UFix128 as a fixed point
-    /// number with 18 decimal places). The input to this function will be just the relative annual interest rate
-    /// (e.g. 0.05 for 5% interest), and the result will be the per-second multiplier (e.g. 1.000000000001).
+    /// 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 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 = yearlyRate / 31_557_600.0 // 365.25 * 24.0 * 60.0 * 60.0
         assert(
@@ -111,6 +113,19 @@ access(all) contract FlowALPMath {
         return perSecondScaledValue + 1.0
     }
 
+    /// Returns the effective annual yield (EAY) for a given nominal yearly rate, assuming discrete per-second compounding.
+    ///
+    /// Formula: EAY = (1 + nominalRate / secondsPerYear) ^ secondsPerYear - 1
+    ///
+    /// For example, a nominal rate of 100% (1.0) produces an effective rate of about 171.8281776413%
+    /// under discrete per-second compounding: (1 + 1 / 31_557_600) ^ 31_557_600 - 1.
+    /// This is extremely close to the continuous-compounding limit of e - 1.
+    access(all) view fun effectiveYearlyRate(nominalYearlyRate: UFix128): UFix128 {
+        let perSecondRate = FlowALPMath.perSecondInterestRate(yearlyRate: nominalYearlyRate)
+        let compounded = FlowALPMath.powUFix128(perSecondRate, 31_557_600.0)
+        return compounded - 1.0
+    }
+
     /// Returns the compounded interest index reflecting the passage of time
     /// The result is: newIndex = oldIndex * perSecondRate ^ seconds
     access(all) view fun compoundInterestIndex(

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

cadence/tests/auto_borrow_behavior_test.cdc

@@ -75,18 +75,24 @@ fun testAutoBorrowBehaviorWithTargetHealth() {
         message: "Expected MOET to be in Debit (borrowed) state")
 
     // Verify the amount is approximately what we calculated (within 0.01 tolerance)
-    Test.assert(moetBalance >= expectedDebt - 0.01 && moetBalance <= expectedDebt + 0.01,
-        message: "Expected MOET debt to be approximately \(expectedDebt), but got \(moetBalance)")
+    Test.assert(
+        equalWithinVariance(expectedDebt, moetBalance, 0.01),
+        message: "Expected MOET debt to be approximately \(expectedDebt), but got \(moetBalance)",
+    )
 
     // Verify position health is at target
     let health = getPositionHealth(pid: 0, beFailed: false)
-    Test.assert(equalWithinVariance(INT_TARGET_HEALTH, health),
-        message: "Expected health to be \(INT_TARGET_HEALTH), but got \(health)")
+    Test.assert(
+        equalWithinVariance(INT_TARGET_HEALTH, health, DEFAULT_UFIX128_VARIANCE),
+        message: "Expected health to be \(INT_TARGET_HEALTH), but got \(health)",
+    )
 
     // Verify the user actually received the borrowed MOET in their Vault (draw-down sink)
     let userMoetBalance = getBalance(address: user.address, vaultPublicPath: MOET.VaultPublicPath)!
-    Test.assert(userMoetBalance >= expectedDebt - 0.01 && userMoetBalance <= expectedDebt + 0.01,
-        message: "Expected user MOET Vault balance to be approximately \(expectedDebt), but got \(userMoetBalance)")
+    Test.assert(
+        equalWithinVariance(expectedDebt, userMoetBalance, 0.01),
+        message: "Expected user MOET Vault balance to be approximately \(expectedDebt), but got \(userMoetBalance)",
+    )
 }
 
 access(all)

cadence/tests/compute_available_withdrawal_test.cdc

@@ -86,7 +86,7 @@ fun test_atTargetHealth_nothingAvailable() {
         depositAmount: 0.0,
         beFailed: false
     )
-    Test.assert(equalWithinVariance(0.0, availableMOET),
+    Test.assert(equalWithinVariance(0.0, availableMOET, DEFAULT_UFIX_VARIANCE),
         message: "Expected 0 MOET available at target health, got \(availableMOET)")
 
     let availableFLOW = fundsAvailableAboveTargetHealthAfterDepositing(
@@ -97,7 +97,7 @@ fun test_atTargetHealth_nothingAvailable() {
         depositAmount: 0.0,
         beFailed: false
     )
-    Test.assert(equalWithinVariance(0.0, availableFLOW),
+    Test.assert(equalWithinVariance(0.0, availableFLOW, DEFAULT_UFIX_VARIANCE),
         message: "Expected 0 FLOW available at target health, got \(availableFLOW)")
 }
 
@@ -130,7 +130,7 @@ fun test_noCreditInWithdrawToken_zerodebt_fullBorrowCapacity() {
         depositAmount: 0.0,
         beFailed: false
     )
-    Test.assert(equalWithinVariance(expectedAvailable, actualAvailable),
+    Test.assert(equalWithinVariance(expectedAvailable, actualAvailable, DEFAULT_UFIX_VARIANCE),
         message: "Expected \(expectedAvailable) MOET available (zero-debt full capacity), got \(actualAvailable)")
 }
 
@@ -158,7 +158,7 @@ fun test_creditInWithdrawToken_partialCollateralOnly() {
 
     // Confirm the borrow happened and health is at target
     let healthAtCreation = getPositionHealth(pid: pid, beFailed: false)
-    Test.assert(equalWithinVariance(UFix64(INT_TARGET_HEALTH), UFix64(healthAtCreation)),
+    Test.assert(equalWithinVariance(UFix64(INT_TARGET_HEALTH), UFix64(healthAtCreation), DEFAULT_UFIX_VARIANCE),
         message: "Expected health ≈ 1.3 after creation with push, got \(healthAtCreation)")
 
     // Increase FLOW price to 2.0 → more headroom above target
@@ -180,7 +180,7 @@ fun test_creditInWithdrawToken_partialCollateralOnly() {
         depositAmount: 0.0,
         beFailed: false
     )
-    Test.assert(equalWithinVariance(expectedAvailable, actualAvailable),
+    Test.assert(equalWithinVariance(expectedAvailable, actualAvailable, DEFAULT_UFIX_VARIANCE),
         message: "Expected \(expectedAvailable) FLOW available (partial collateral withdrawal), got \(actualAvailable)")
 }
 
@@ -242,7 +242,7 @@ fun test_creditFlipsIntoDebt_availabilityExceedsCreditBalance() {
         depositAmount: 0.0,
         beFailed: false
     )
-    Test.assert(equalWithinVariance(expectedAvailable, actualAvailable),
+    Test.assert(equalWithinVariance(expectedAvailable, actualAvailable, DEFAULT_UFIX_VARIANCE),
         message: "Expected \(expectedAvailable) FLOW available (credit→debt flip), got \(actualAvailable)")
 }
 

cadence/tests/effective_interest_rate_test.cdc

@@ -0,0 +1,46 @@
+import Test
+import BlockchainHelpers
+
+import "FlowALPMath"
+import "test_helpers.cdc"
+
+access(all)
+fun setup() {
+    let err = Test.deployContract(
+        name: "FlowALPMath",
+        path: "../lib/FlowALPMath.cdc",
+        arguments: []
+    )
+    Test.expect(err, Test.beNil())
+}
+
+access(all) struct TestCase {
+    access(all) let nominal: UFix128
+    access(all) let expected: UFix128
+
+    init(nominal: UFix128, expected: UFix128) {
+        self.nominal = nominal
+        self.expected = expected
+    }
+}
+
+access(all)
+fun test_effectiveYearlyRate() {
+    let delta: UFix128 = 0.0001
+    let testCases = [
+        TestCase(nominal: 0.01, expected: 0.01005016708),   // ≈ e^0.01 - 1
+        TestCase(nominal: 0.02, expected: 0.02020134003),   // ≈ e^0.02 - 1
+        TestCase(nominal: 0.05, expected: 0.05127109638),   // ≈ e^0.05 - 1
+        TestCase(nominal: 0.50, expected: 0.6487212707),    // ≈ e^0.5  - 1
+        TestCase(nominal: 1.0,  expected: 1.7182818285),    // ≈ e^1    - 1
+        TestCase(nominal: 4.0,  expected: 53.5981500331)    // ≈ e^4    - 1
+    ]
+    for testCase in testCases {
+        let effective = FlowALPMath.effectiveYearlyRate(nominalYearlyRate: testCase.nominal)
+        let diff = effective > testCase.expected ? effective - testCase.expected : testCase.expected - effective
+        Test.assert(
+            diff <= delta,
+            message: "effectiveYearlyRate(\(testCase.nominal.toString())) expected ~\(testCase.expected.toString()), got \(effective.toString()), diff \(diff.toString()) exceeds delta \(delta.toString())"
+        )
+    }
+}

cadence/tests/funds_available_above_target_health_test.cdc

@@ -92,7 +92,7 @@ fun testFundsAvailableAboveTargetHealthAfterDepositingWithPushFromHealthy() {
     // assert expected starting point
     let balanceAfterBorrow = getBalance(address: userAccount.address, vaultPublicPath: MOET.VaultPublicPath)!
     let expectedBorrowAmount = (positionFundingAmount * flowCollateralFactor * flowStartPrice) / TARGET_HEALTH
-    Test.assert(equalWithinVariance(expectedBorrowAmount, balanceAfterBorrow),
+    Test.assert(equalWithinVariance(expectedBorrowAmount, balanceAfterBorrow, DEFAULT_UFIX_VARIANCE),
         message: "Expected MOET balance to be ~\(expectedBorrowAmount), but got \(balanceAfterBorrow)")
 
     let evts = Test.eventsOfType(Type<FlowALPEvents.Opened>())
@@ -113,10 +113,10 @@ fun testFundsAvailableAboveTargetHealthAfterDepositingWithPushFromHealthy() {
     }
     Test.assertEqual(positionFundingAmount, flowPositionBalance!.balance)
 
-    Test.assert(equalWithinVariance(expectedBorrowAmount, moetBalance!.balance),
+    Test.assert(equalWithinVariance(expectedBorrowAmount, moetBalance!.balance, DEFAULT_UFIX_VARIANCE),
         message: "Expected borrow amount to be \(expectedBorrowAmount), but got \(moetBalance!.balance)")
 
-    Test.assert(equalWithinVariance(INT_TARGET_HEALTH, health),
+    Test.assert(equalWithinVariance(INT_TARGET_HEALTH, health, DEFAULT_UFIX128_VARIANCE),
         message: "Expected health to be \(INT_TARGET_HEALTH), but got \(health)")
 
     log("[TEST] FLOW price set to \(flowStartPrice)")
@@ -297,7 +297,7 @@ fun testFundsAvailableAboveTargetHealthAfterDepositingWithoutPushFromOvercollate
     log("[TEST] Depositing: \(depositAmount)")
     log("[TEST] Expected Available: \(expectedAvailable)")
     log("[TEST] Actual Available: \(actualAvailable)")
-    Test.assert(equalWithinVariance(expectedAvailable, actualAvailable),
+    Test.assert(equalWithinVariance(expectedAvailable, actualAvailable, DEFAULT_UFIX_VARIANCE),
         message: "Values are not equal within variance - expected: \(expectedAvailable), actual: \(actualAvailable)")
 
     log("..............................")
@@ -315,7 +315,7 @@ fun testFundsAvailableAboveTargetHealthAfterDepositingWithoutPushFromOvercollate
     log("[TEST] Depositing: \(depositAmount)")
     log("[TEST] Expected Available: \(expectedAvailable)")
     log("[TEST] Actual Available: \(actualAvailable)")
-    Test.assert(equalWithinVariance(expectedAvailable, actualAvailable),
+    Test.assert(equalWithinVariance(expectedAvailable, actualAvailable, DEFAULT_UFIX_VARIANCE),
         message: "Values are not equal within variance - expected: \(expectedAvailable), actual: \(actualAvailable)")
 
     log("==============================")
@@ -354,6 +354,6 @@ fun runFundsAvailableAboveTargetHealthAfterDepositing(
     log("[TEST] Depositing: \(depositAmount)")
     log("[TEST] Expected Available: \(expectedAvailable)")
     log("[TEST] Actual Available: \(actualAvailable)")
-    Test.assert(equalWithinVariance(expectedAvailable, actualAvailable),
+    Test.assert(equalWithinVariance(expectedAvailable, actualAvailable, DEFAULT_UFIX_VARIANCE),
         message: "Values are not equal within variance - expected: \(expectedAvailable), actual: \(actualAvailable)")
 }

cadence/tests/funds_required_for_target_health_test.cdc

@@ -87,7 +87,7 @@ fun testFundsRequiredForTargetHealthAfterWithdrawingWithPushFromHealthy() {
     // assert expected starting point
     startingDebt = getBalance(address: userAccount.address, vaultPublicPath: MOET.VaultPublicPath)!
     let expectedStartingDebt = (positionFundingAmount * flowCollateralFactor * flowStartPrice) / TARGET_HEALTH
-    Test.assert(equalWithinVariance(expectedStartingDebt, startingDebt),
+    Test.assert(equalWithinVariance(expectedStartingDebt, startingDebt, DEFAULT_UFIX_VARIANCE),
         message: "Expected MOET balance to be ~\(expectedStartingDebt), but got \(startingDebt)")
 
     var evts = Test.eventsOfType(Type<FlowALPEvents.Opened>())
@@ -102,7 +102,7 @@ fun testFundsRequiredForTargetHealthAfterWithdrawingWithPushFromHealthy() {
     Test.assertEqual(rebalancedEvt.amount, startingDebt)
 
     let health = getPositionHealth(pid: positionID, beFailed: false)
-    Test.assert(equalWithinVariance(INT_TARGET_HEALTH, health),
+    Test.assert(equalWithinVariance(INT_TARGET_HEALTH, health, DEFAULT_UFIX128_VARIANCE),
         message: "Expected health to be \(INT_TARGET_HEALTH), but got \(health)")
 
     log("[TEST] FLOW price set to \(flowStartPrice)")
@@ -283,7 +283,7 @@ fun testFundsRequiredForTargetHealthAfterWithdrawingWithPushFromOvercollateraliz
     // assert expected starting point
     startingDebt = getBalance(address: userAccount.address, vaultPublicPath: MOET.VaultPublicPath)!
     let expectedStartingDebt = (positionFundingAmount * flowCollateralFactor * flowStartPrice) / TARGET_HEALTH
-    Test.assert(equalWithinVariance(expectedStartingDebt, startingDebt),
+    Test.assert(equalWithinVariance(expectedStartingDebt, startingDebt, DEFAULT_UFIX_VARIANCE),
         message: "Expected MOET balance to be ~\(expectedStartingDebt), but got \(startingDebt)")
 
     var evts = Test.eventsOfType(Type<FlowALPEvents.Opened>())
@@ -298,7 +298,7 @@ fun testFundsRequiredForTargetHealthAfterWithdrawingWithPushFromOvercollateraliz
     Test.assertEqual(rebalancedEvt.amount, startingDebt)
 
     let actualHealthBeforePriceIncrease = getPositionHealth(pid: positionID, beFailed: false)
-    Test.assert(equalWithinVariance(INT_TARGET_HEALTH, actualHealthBeforePriceIncrease),
+    Test.assert(equalWithinVariance(INT_TARGET_HEALTH, actualHealthBeforePriceIncrease, DEFAULT_UFIX128_VARIANCE),
         message: "Expected health to be \(INT_TARGET_HEALTH), but got \(actualHealthBeforePriceIncrease)")
 
     let priceIncrease = 0.25
@@ -438,7 +438,7 @@ fun testFundsRequiredForTargetHealthAfterWithdrawingWithPushFromUndercollaterali
     // assert expected starting point
     startingDebt = getBalance(address: userAccount.address, vaultPublicPath: MOET.VaultPublicPath)!
     let expectedStartingDebt = (positionFundingAmount * flowCollateralFactor * flowStartPrice) / TARGET_HEALTH
-    Test.assert(equalWithinVariance(expectedStartingDebt, startingDebt),
+    Test.assert(equalWithinVariance(expectedStartingDebt, startingDebt, DEFAULT_UFIX_VARIANCE),
         message: "Expected MOET balance to be ~\(expectedStartingDebt), but got \(startingDebt)")
 
     var evts = Test.eventsOfType(Type<FlowALPEvents.Opened>())
@@ -453,7 +453,7 @@ fun testFundsRequiredForTargetHealthAfterWithdrawingWithPushFromUndercollaterali
     Test.assertEqual(rebalancedEvt.amount, startingDebt)
 
     let actualHealthBeforePriceIncrease = getPositionHealth(pid: positionID, beFailed: false)
-    Test.assert(equalWithinVariance(INT_TARGET_HEALTH, actualHealthBeforePriceIncrease),
+    Test.assert(equalWithinVariance(INT_TARGET_HEALTH, actualHealthBeforePriceIncrease, DEFAULT_UFIX128_VARIANCE),
         message: "Expected health to be \(INT_TARGET_HEALTH), but got \(actualHealthBeforePriceIncrease)")
 
     let priceDecrease = 0.25
@@ -557,6 +557,6 @@ fun runFundsRequiredForTargetHealthAfterWithdrawing(
     log("[TEST] Withdrawing: \(withdrawAmount)")
     log("[TEST] Expected Required: \(ufixExpectedRequired)")
     log("[TEST] Actual Required: \(actualRequired)")
-    Test.assert(equalWithinVariance(ufixExpectedRequired, actualRequired),
+    Test.assert(equalWithinVariance(ufixExpectedRequired, actualRequired, DEFAULT_UFIX_VARIANCE),
         message: "Expected required funds to be \(ufixExpectedRequired), but got \(actualRequired)")
 }