FLO-18: rename perSecondInterestRate to use nominal label

[holyfuchs]

Closes: #227

Addresses FLO-18. The per-second rate uses linear (nominal) decomposition (r / secondsPerYear), which means exponential compounding produces an effective APY that exceeds the stated rate. Rather than changing the behavior, this PR clarifies the semantics:

Renames perSecondInterestRate(yearlyRate:) → perSecondInterestRate(nominalYearlyRate:) to make the nominal nature explicit
Adds effectiveYearlyRate(nominalYearlyRate:) view function computing (1 + r/n)^n - 1

[liobrasil]

For clarity, the current final state of this PR is broader than the original description.

What this branch now does:

• Clarifies that the rates configured by the interest curves are nominal yearly rates, not exact one-year effective yields.
• Keeps the protocol behavior unchanged: the configured yearly rate is still decomposed into a per-second rate and accrues through the existing index-based compounding logic.
• Makes the docs/comments consistent with the @holyfuchs and @Gornutz discussion: a stated yearly rate is nominal, so the realized one-year effective return can be slightly higher under compounding, and under variable utilization it should not be interpreted as a fixed promised APY.
• Cleans up fixed-curve commentary so it matches the actual protocol-fee spread logic. In practice, the deposit-side rate is derived from the borrow-side rate after applying the combined insurance/stability fee fractions; this PR does not change that logic, it only fixes wording that previously described it too loosely.
• Adds effectiveYearlyRate(nominalYearlyRate:) in FlowALPMath as an explicit helper for the constant-rate case, using the same discrete per-second compounding convention as the protocol: (1 + r / secondsPerYear)^secondsPerYear - 1.
• Adds coverage for that helper in cadence/tests/effective_interest_rate_test.cdc.
• Includes a follow-up merge fix to restore API consistency around perSecondInterestRate(yearlyRate: ...) after the branch history briefly mixed yearlyRate and nominalYearlyRate labels. The final code keeps yearlyRate at that call site; the nominal/effective distinction is documented in comments/docs rather than enforced through that parameter name.

Files touched in the final branch state:

• cadence/contracts/FlowALPEvents.cdc
• cadence/contracts/FlowALPInterestRates.cdc
• cadence/lib/FlowALPMath.cdc
• cadence/tests/TEST_COVERAGE.md
• cadence/tests/effective_interest_rate_test.cdc
• cadence/tests/interest_accrual_integration_test.cdc
• cadence/tests/interest_curve_advanced_test.cdc
• cadence/tests/interest_curve_test.cdc
• cadence/tests/kink_curve_utilization_regression_test.cdc
• cadence/tests/update_interest_rate_test.cdc
• cadence/transactions/flow-alp/pool-governance/add_supported_token_fixed_rate_curve.cdc
• cadence/transactions/flow-alp/pool-governance/add_supported_token_zero_rate_curve.cdc
• cadence/transactions/flow-alp/pool-governance/set_interest_curve_fixed.cdc
• docs/interest_rate_and_protocol_fees.md

Validation run on this branch:

• flow test cadence/tests/interest_curve_test.cdc
• flow test cadence/tests/update_interest_rate_test.cdc
• flow test cadence/tests/effective_interest_rate_test.cdc
• flow test cadence/tests/interest_curve_advanced_test.cdc
• flow test cadence/tests/interest_accrual_integration_test.cdc
• flow test cadence/tests/kink_curve_utilization_regression_test.cdc

So the net effect is: terminology/documentation cleanup, one explicit helper for effective annual yield in the constant-rate case, and no intended change to protocol economics.

[holyfuchs]

The rate is always positive (it’s a UFix128), so that’s already guaranteed.
What does “relative rate” mean here, relative to what?
“Slightly higher” doesn’t seem accurate. If the nominal rate reaches 100%, the effective rate exceeds 170%, which is significantly higher, not just a slight difference.

Suggested change

	/// 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.
	/// 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 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).
	/// The effective annual rate will be higher than the nominal rate
	/// because interest compounds over time.

[holyfuchs]

@liobrasil I can’t approve this PR since I created it, but it now reflects both of our changes, so I think it’s good to merge if you’re happy with it.

I left a small suggestion on the comment for the perSecondInterestRate function.