feat: migrate to UFix128 + TidalMath; replace scaled UInt128 math; update tests/scripts; use native ops; register TidalMath; remove DeFiActionsMathUtils uses by kgrgpg · Pull Request #48 · onflow/FlowALP

kgrgpg · 2025-10-07T11:22:01Z

Overview

This PR migrates TidalProtocol from scaled UInt128 and DeFiActionsMathUtils to native UFix128 and a new TidalMath helper.

Why

Native decimals: precision and clarity with Cadence fixed-point UFix128.
Fewer pitfalls: remove implicit 1e24 scaling and conversion bugs.
Consistent rounding: centralize UFix64 conversions in TidalMath.
Simpler code: use native * and / for arithmetic.

What changed

Contracts
- Add cadence/lib/TidalMath.cdc with constants (one, zero), toUFix128, and UFix64 rounding helpers (toUFix64Round, toUFix64RoundUp, toUFix64RoundDown).
- Refactor cadence/contracts/TidalProtocol.cdc:
  - Use UFix128 for prices, factors, indices, health, and liquidation math.
  - TokenSnapshot fields renamed: creditIndex, debitIndex.
  - RiskParams stores decimal fractions for collateralFactor, borrowFactor, liquidationBonus (e.g., 0.05).
  - Rewrite scaledBalanceToTrueBalance, trueBalanceToScaledBalance, health, max-withdraw, and liquidation to native decimals.
  - Replace TidalMath.mul/div with native * and / for brevity.
  - Remove unused imports; avoid bitwise operations on UFix128.
Scripts
- position_health.cdc: return type UFix128.
- funds_req_for_target_health_after_withdraw.cdc: targetHealth: UFix128.
- funds_avail_above_target_health_after_deposit.cdc: targetHealth: UFix128.
Tests
- cadence/tests/test_helpers.cdc: UFix128 constants/helpers; deploy TidalMath before TidalProtocol.
- Migrate math/liquidation/insolvency/funds and integration tests to UFix128 semantics.
- Remove DeFiActionsMathUtils imports; use native ops or TidalMath rounding helpers.
- Align phase0_pure_math_test.cdc with new TokenSnapshot and RiskParams fields.
Config
- Update flow.json to register TidalMath; remove DeFiActionsMathUtils from emulator deployments.

How it works

Use UFix128 end-to-end for protocol math.
Use TidalMath only for conversions/rounding where needed.
Prefer native * and / for readability and less boilerplate.

Breaking changes

Scripts/transactions now accept/return UFix128 for health and ratios.
RiskParams.liquidationBonus is a fraction (e.g., 0.05), not 1 + LB.
TokenSnapshot uses creditIndex/debitIndex.

Validation

Full Cadence test suite passes on this branch.

DeFiActions utilities

DeFiActionsUtils and DeFiActionsMathUtils are no longer required by TidalProtocol; TidalMath supersedes them.

Follow-ups

Consider exponentiation-by-squaring if integer exponents reappear in interest compounding.

…date tests/scripts; use native ops; register TidalMath; remove DeFiActionsMathUtils uses

…sitive dependency)

codecov · 2025-10-07T11:33:50Z

Codecov Report

❌ Patch coverage is 79.54545% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cadence/lib/TidalMath.cdc	79.54%	9 Missing ⚠️

📢 Thoughts on this report? Let us know!

…ent, and justify UFix128 usage for recordDeposit/recordWithdrawal and TokenState

…ain and TidalMath; adopt Type in events; remove DeFiActionsMathUtils from risk math; keep UFix128 health APIs and conversions

… in risk math, adopt Type in events, fix healthComputation (∞ for 0/0 and debt=0), adjust tests/scripts to UFix128 health; all tests passing

…nst 0.0 as UFix128

Kay-Zee

A few things, it definitely felt like the mul function is kinda unnecessary, any reason we're keeping it instead of just using *?

Also, we have a constant for 1.0 and 0.0 as UFix128 but we pretty much only use the 1.0 and not really use the 0.0 constant. Any reasoning for why?

Kay-Zee · 2025-10-15T00:44:28Z

    }
    Test.assert(quote.seizeAmount > 0.0, message: "Expected positive seizeAmount")
-    Test.assert(quote.newHF > hAfter && quote.newHF < DeFiActionsMathUtils.e24)
+    Test.assert(quote.newHF > hAfter && quote.newHF < TidalMath.toUFix128(1.0))


looks like we have a constant for this, no?

Suggested change

Test.assert(quote.newHF > hAfter && quote.newHF < TidalMath.toUFix128(1.0))

Test.assert(quote.newHF > hAfter && quote.newHF < TidalMath.one)

Kay-Zee · 2025-10-15T00:45:29Z

-            lb: DeFiActionsMathUtils.e24
+            cf: UFix128(cf),
+            bf: UFix128(bf),
+            lb: UFix128(0.05)


why did this change to 0.05?

Kay-Zee · 2025-10-15T00:47:29Z

-		}
-	}
-}
+  "contracts": {


was this mostly an indentation issue?

Kay-Zee · 2025-10-15T00:49:52Z

@@ -0,0 +1,92 @@
+access(all) contract TidalMath {


You mention in the PR that:

DeFiActionsUtils and DeFiActionsMathUtils are no longer required by TidalProtocol; TidalMath supersedes them.

Can we give a quick explainer why we don't just update DeFiActionsUtils to use ufix128 then continue to use the DeFiActionsUtils?

Kay-Zee · 2025-10-15T00:54:51Z

-            self.debitInterestIndex = DeFiActionsMathUtils.e24
-            self.currentCreditRate = UInt128(DeFiActionsMathUtils.e24)
-            self.currentDebitRate = UInt128(DeFiActionsMathUtils.e24)
+            self.totalCreditBalance = 0.0 as UFix128


Did we not also have this as a constant?

Kay-Zee · 2025-10-15T01:33:21Z

@@ -1701,19 +1729,19 @@ access(all) contract TidalProtocol {
                if potentialHealth <= targetHealth {
                    // We will hit the health target before using up all of the withdraw token credit. We can easily
                    // compute how many units of the token would bring the position down to the target health.
-                    // let availableHealth = healthAfterDeposit == UInt128.max ? UInt128.max : healthAfterDeposit - targetHealth
-                    // let availableEffectiveValue = (effectiveDebtAfterDeposit == 0 || availableHealth == UInt128.max)
+                    // let availableHealth = healthAfterDeposit == UFix128.max ? UFix128.max : healthAfterDeposit - targetHealth


is this suppose to be part of the comments, or is it just commented out code? if so should we just remove?

Kay-Zee · 2025-10-15T01:35:16Z

-            let uintPrice = DeFiActionsMathUtils.toUInt128(self.priceOracle.price(ofToken: type)!)
-            let uintCollateralFactor = DeFiActionsMathUtils.toUInt128(self.collateralFactor[type]!)
-            let uintBorrowFactor = DeFiActionsMathUtils.toUInt128(self.borrowFactor[type]!)
+            let uintAmount = TidalMath.toUFix128(amount)


Noticed that most of these, even though the type is converted to ufix, the naming is still uint, should we adjust them, up to you how you want to name them, buti just feel like uint is misleading now that the type is changed

Kay-Zee · 2025-10-15T01:39:04Z

-        assert(perSecondScaledValue < UInt128.max, message: "Per-second interest rate \(perSecondScaledValue) is too high")
-        return UInt128(perSecondScaledValue + DeFiActionsMathUtils.e24)
+    access(all) view fun perSecondInterestRate(yearlyRate: UFix128): UFix128 {
+        let secondsInYearE24 = TidalMath.mul(31_536_000.0 as UFix128, TidalMath.one)


probably don't need to bother with this mul

Kay-Zee · 2025-10-15T01:42:10Z

    }

    /// Returns the compounded interest index reflecting the passage of time
    /// The result is: newIndex = oldIndex * perSecondRate ^ seconds
-    access(all) view fun compoundInterestIndex(oldIndex: UInt128, perSecondRate: UInt128, elapsedSeconds: UFix64): UInt128 {
+    access(all) view fun compoundInterestIndex(oldIndex: UFix128, perSecondRate: UFix128, elapsedSeconds: UFix64): UFix128 {
+        // For UFix128, we use repeated multiplication per second conservatively for now.


hmm, then should this be an area where we would consider keeping UInt128?

Kay-Zee · 2025-10-15T01:43:29Z

+        access(all) case RoundEven
+    }
+
+    access(all) view fun mul(_ x: UFix128, _ y: UFix128): UFix128 {


If mul is just a convenience function for * i do wonder what benefit there is to having it?

…lMath.one/zero, simplify perSecondInterestRate, rename locals for clarity, update tests; all Cadence tests passing

kgrgpg · 2025-10-15T14:00:36Z

UFix128 cleanup and math utilities consolidation

What changed

Removed TidalMath.mul and replaced with the built-in * across the codebase. Kept TidalMath.div for its division-by-zero precondition.
Standardized on TidalMath.one/TidalMath.zero; replaced ad‑hoc TidalMath.toUFix128(1.0) and 0.0 as UFix128. Tests updated accordingly.
Simplified perSecondInterestRate: compute yearlyRate / 31_536_000.0 as UFix128 and add TidalMath.one.
Kept UFix128 for compoundInterestIndex to match indices/rates and avoid type churn; can optimize exponentiation later if needed.
Renamed misleading locals (e.g., uintPrice, uintBorrowFactor) to descriptive names (price, borrowFactor, collateralFactor, depositPrice, withdrawBorrowFactor, etc.).
Removed commented‑out code and minor formatting noise.
Tightened zero comparisons where types are unsigned: use == TidalMath.zero instead of <= 0.0 as UFix128.

Why

The mul wrapper was a no‑op; built‑ins are clearer and idiomatic. Keeping div preserves safety semantics.
Using constants improves readability and consistency, and reduces mixed literal typing.
Decoupling protocol math from DeFiActions and standardizing on UFix128 simplifies interfaces and testing.

Responses to review points

mul convenience: removed; * works for UFix128.
one/zero constants: both used; zero is used in liquidation math and clamping.
liquidationBonus as 0.05: correct for fractional UFix128.
Indices/rates: use TidalMath.one to represent no‑interest; swapped remaining literals to constants.
Unsigned checks: changed <= 0.0 to == TidalMath.zero where appropriate.
Precondition optional‑chaining: explicit nil/type checks retained for clearer error messages.
Commented blocks: removed.
Variable names: moved away from uint* labels now that values are UFix128.
perSecondInterestRate: removed redundant multiply by one.
compoundInterestIndex: kept on UFix128; can revisit for faster exponentiation later.
decreaseDebitBalance saturating behavior: still clamp‑to‑zero to avoid negative accounting; can add an assert with small epsilon in a follow‑up if we want stricter guarantees.

Tests

All Cadence tests pass locally via ./run_tests.sh on feature/ufix128-upgrade.

kgrgpg · 2025-10-15T14:24:29Z

Interest compounding performance update

What changed

Added TidalMath.powUFix128(base, expSeconds) implementing exponentiation-by-squaring with integer-second exponent.
Updated TidalProtocol.compoundInterestIndex to compute oldIndex * powUFix128(perSecondRate, elapsedSeconds) instead of looping per-second.

Why

Keeps the math fully on UFix128 for consistency (rates/indices/health) while eliminating the O(seconds) loop. The new approach is O(log seconds) and avoids type churn to UInt128.
Floors elapsed time to whole seconds (as before), which matches Flow’s UFix64 timestamp semantics.

Tests

All Cadence tests pass locally with the new implementation via ./run_tests.sh.

…erestIndex to exponentiation-by-squaring; tests passing

Kay-Zee

Looks good! just 2 nits

Kay-Zee · 2025-10-15T18:22:07Z

+                            TidalMath.div(trueDebt * depositPrice2, depositBorrowFactor2)
                        effectiveCollateralAfterDeposit = balanceSheet.effectiveCollateral +
-                            TidalMath.mul(TidalMath.mul(uintDepositAmount - trueDebt, uintDepositPrice), uintDepositCollateralFactor)
+                            (depositAmountU - trueDebt) * depositPrice2 * depositCollateralFactor2


nit: not super fond of the 2 in the naming

Kay-Zee · 2025-10-15T18:24:36Z

        let remainder: UFix128 = value - truncatedAs128

-        if remainder <= 0.0 as UFix128 {
+        if remainder == 0.0 as UFix128 {


nit: might as well use the constant

Kay-Zee · 2025-10-15T18:30:25Z

@@ -0,0 +1,33 @@
+### UFix128 cleanup and math utilities consolidation


Let's not commit these, best for these just to live on the PR, i saw you had added the original PR body to your git ignore, but maybe this folder should be as well

Kay-Zee · 2025-10-15T18:32:04Z

Could we also take a look at coverage before merging please

…none present

…exponent checks vs naive multiplication

kgrgpg · 2025-10-17T16:52:19Z

Addressed latest comments and increased coverage

kgrgpg added 2 commits October 7, 2025 13:21

feat: migrate to UFix128 + TidalMath; replace scaled UInt128 math; up…

4eec1c0

…date tests/scripts; use native ops; register TidalMath; remove DeFiActionsMathUtils uses

test: deploy DeFiActionsMathUtils for MockDexSwapper quote test (tran…

19d045c

…sitive dependency)

chore: remove PR body file; ignore it

ff589c1

kgrgpg requested review from Kay-Zee and dete October 7, 2025 16:48

docs(TidalProtocol): add numeric types policy, fix scaledBalance comm…

e3276ff

…ent, and justify UFix128 usage for recordDeposit/recordWithdrawal and TokenState

kgrgpg force-pushed the feature/ufix128-upgrade branch from cae7c0d to e3276ff Compare October 13, 2025 17:53

kgrgpg added 3 commits October 13, 2025 20:34

Merge origin/main into feature/ufix128-upgrade preserving UFix128 dom…

c11408e

…ain and TidalMath; adopt Type in events; remove DeFiActionsMathUtils from risk math; keep UFix128 health APIs and conversions

Preserve UFix128 + TidalMath post-merge: replace DeFiActionsMathUtils…

3a8b175

… in risk math, adopt Type in events, fix healthComputation (∞ for 0/0 and debt=0), adjust tests/scripts to UFix128 health; all tests passing

Fix CI UFix128 comparison in governance_parameters_test: compare agai…

528708b

…nst 0.0 as UFix128

Kay-Zee reviewed Oct 15, 2025

View reviewed changes

UFix128 cleanup: remove TidalMath.mul in favor of *, standardize Tida…

d3bf325

…lMath.one/zero, simplify perSecondInterestRate, rename locals for clarity, update tests; all Cadence tests passing

Interest compounding: add TidalMath.powUFix128 and switch compoundInt…

623aba5

…erestIndex to exponentiation-by-squaring; tests passing

Kay-Zee approved these changes Oct 15, 2025

View reviewed changes

Kay-Zee reviewed Oct 15, 2025

View reviewed changes

Tidal CI added 2 commits October 17, 2025 18:43

Ignore PR body assets: add /.github/pr_bodies/ to .gitignore; remove …

d8a3922

…none present

Add unit tests for TidalMath.powUFix128: zero exp, base 1, and small …

fb09eb1

…exponent checks vs naive multiplication

kgrgpg merged commit dc59949 into main Oct 17, 2025
2 of 3 checks passed

kgrgpg deleted the feature/ufix128-upgrade branch October 17, 2025 16:52

	Test.assert(quote.newHF > hAfter && quote.newHF < TidalMath.toUFix128(1.0))
	Test.assert(quote.newHF > hAfter && quote.newHF < TidalMath.one)

		@@ -0,0 +1,33 @@
		### UFix128 cleanup and math utilities consolidation

Conversation

kgrgpg commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Why

What changed

How it works

Breaking changes

Validation

DeFiActions utilities

Follow-ups

Uh oh!

codecov Bot commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Kay-Zee left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kgrgpg commented Oct 15, 2025

UFix128 cleanup and math utilities consolidation

What changed

Why

Responses to review points

Tests

Uh oh!

kgrgpg commented Oct 15, 2025

Interest compounding performance update

What changed

Why

Tests

Uh oh!

Kay-Zee left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kay-Zee commented Oct 15, 2025

Uh oh!

kgrgpg commented Oct 17, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kgrgpg commented Oct 7, 2025 •

edited

Loading

codecov Bot commented Oct 7, 2025 •

edited

Loading