Add stabilityFee parameter for Protocol Stability

[UlyanaAndrukhiv]

Closes: #85

Context

Implements a new stabilityFeeRate parameter for the FlowCreditMarket protocol that enables collecting stability fees from interest income to support stability.

The implementation follows the proposed solution from the issue discussion, with a default stability fee rate of 5%.

---

For contributor use:

• Targeted PR against master branch
• Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
• Code follows the standards mentioned here.
• Updated relevant documentation
• Re-reviewed Files changed in the Github PR explorer
• Added appropriate labels

[UlyanaAndrukhiv]

@turbolent, @Gornutz, could you please review the contract part changes of this PR when you get a chance? Thanks in advance!

[turbolent]

Nice, looks good from a Cadence code quality perspective 👍
Didn't review the actual logic

[Gornutz]

Actually noticed that with the current implementation that we can run into underflow issues if we a have a insuranceRate or stabilityFeeRate that is greater than the interest that's be generated. As we are subtracting that flat out instead of it being a proportional % to the total amount of interest being collected.

For a mental model that the two insuranceRate and stabilityFeeRate's behave very similar to AAVE's reserve rate. With how the fee amount generated is proportional to the interest generated, instead of it being a flat hurdle rate.

For an example with the current implementation and we have the following -
Current 10% Borrow Rate, 0.1% insurance, 5% stability -> 10% - 0.1% - 5% = 4.9%
then with the proportional model
10% Borrow Rate, 0.1% insurance, 5% stability -> 10% * (1 - (0.1% + 5%)) = 9.49%
Then if the borrow Rate was 3%
Current 3% Borrow Rate, 0.1% insurance, 5% stability -> 3% - 0.1% - 5% = -2.1%
then with the proportional model
3% Borrow Rate, 0.1% insurance, 5% stability -> 3% * (1- (0.1% + 5%)) = 2.85%

[jordanschalm]

Currently the protocol fees can have wildly different values depending on the interest rate curve being used. I'm guessing this is a mistake (from a prior PR), but if it is desired we should clearly document why it is desired, and document how protocolFeeRate and insuranceRate can be interpreted in different ways.

For example, suppose the debit interest rate is 10% and the protocol fee rate is 5%.

1. If we have a fixed rate curve, we will calculate creditRate = 0.1-0.05 = 0.05 = 5%.

• We interpret protocolFeeRate/insuranceRate as a percentage of a total debit balance

2. If we have a different rate curve, we will calculate creditRate = (0.1)(1-0.05)(debitBalance/creditBalance)

• If debitBalance/creditBalance is close to 1, then creditRate ~= 0.95 = 9.5%.
• We interpret protocolFeeRate/insuranceRate as a percentage of a debit income

[jordanschalm]

My understanding is that the protocol fees should be interpreted as a percentage of debit income, based on #105 (review).

[jordanschalm]

I also feel like that fact that we need to inspect the InterestCurve's implementation type here indicates that the current InterestCurve is a poor abstraction. This is literally the only usage of InterestCurve in the whole smart contract -- we should be able to use it without breaking that abstraction 😅.

[UlyanaAndrukhiv]

Updated in 2bbc399

[UlyanaAndrukhiv]

@Gornutz or @Kay-Zee would you mind taking a final look at it? Thanks!