Add rounding to Vault invariants #6217

Tapanito · 2026-01-14T19:59:58Z

This PR relaxes Vault Deposit, Withdraw and Clawback invariants for IOUs to allow minimal discrepancy between various balance changes.

High Level Overview of Change

Context of Change

Type of Change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Refactor (non-breaking change that only restructures code)
Performance (increase or change in throughput and/or latency)
Tests (you added tests for code that already exists, or your new feature included in this PR)
Documentation update
Chore (no impact to binary, e.g. .gitignore, formatting, dropping support for older tooling)
Release

API Impact

Public API: New feature (new methods and/or new fields)
Public API: Breaking change (in general, breaking changes should only impact the next api_version)
libxrpl change (any change that may affect libxrpl or dependents of libxrpl)
Peer protocol change (must be backward compatible or bump the peer protocol version)

codecov · 2026-01-14T20:17:48Z

Codecov Report

❌ Patch coverage is 98.36066% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 79.4%. Comparing base (66158d7) to head (f8d441b).

Files with missing lines	Patch %	Lines
src/xrpld/app/tx/detail/InvariantCheck.cpp	98.4%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #6217   +/-   ##
=======================================
  Coverage     79.4%   79.4%           
=======================================
  Files          839     839           
  Lines        71619   71633   +14     
  Branches      8236    8231    -5     
=======================================
+ Hits         56849   56872   +23     
+ Misses       14770   14761    -9

Files with missing lines	Coverage Δ
src/xrpld/app/tx/detail/InvariantCheck.h	`100.0% <ø> (ø)`
src/xrpld/app/tx/detail/InvariantCheck.cpp	`92.3% <98.4%> (+0.1%)`	⬆️

... and 4 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

- Requires a template for STAmount and Asset. - Update tests and computeMinScale from #6217 to use scale. - Convert a few other places to use "scale" correctly.

ximinez

I created #6246 to make the some of the changes I requested below. Pretty much everything except the changes to the actual ValidVault invariant checks.

ximinez · 2026-01-20T21:43:12Z

src/xrpld/app/tx/detail/InvariantCheck.cpp

+                auto const vaultDeltaAssets =
+                    roundToAsset(vaultAsset, *maybeVaultDeltaAssets, minScale);
+
+                if (vaultDeltaAssets > tx[sfAmount])


If this is using "round to nearest", it could round vaultDeltaAssets up while tx[sfAmount] doesn't, and yet still be valid. Maybe you should round both?

src/xrpld/app/tx/detail/InvariantCheck.cpp

ximinez · 2026-01-20T22:17:18Z

src/xrpld/app/tx/detail/InvariantCheck.cpp

+        if (value == beast::zero || asset.integral())
+            return 0;


If the Number series values are particularly small, and has one 0, this will throw the rounding off. At an extreme, all the values in the caller could round to 0. I suggest that if value is 0, return value.exponent() (which is the minimum int value) instead. That will guarantee that the result of max_element will represent the largest non-zero exponent.

ximinez · 2026-01-20T22:19:36Z

src/xrpld/app/tx/detail/InvariantCheck.cpp

+        if (value == beast::zero || asset.integral())
+            return 0;
+
+        auto mantissa = std::abs(value.mantissa());


I don't think taking the absolute value will make any difference. You're only dividing.

ximinez · 2026-01-20T23:51:48Z

src/xrpld/app/tx/detail/InvariantCheck.cpp

+        // Remove trailing zeros from mantissa, adjusting scale accordingly
+        while (mantissa % 10 == 0)
+        {
+            mantissa /= 10;
+            ++scale;
+        }


I don't think this is right. Let's take an example:

1.00000000 is going to have a mantissa of 1e18 and an exponent of -18.

After this loop, mantissa will be 1, and scale will be 0, so it returns 0.

Then 1.23456789 will return -8.

max_element will return the 0.

Later, roundToAsset, will round both of them to 1. They would look equal when they are definitely not equal.

The canonical way to correctly get the scale is to make an STNumber, and get its exponent.

src/test/app/Invariants_test.cpp

ximinez · 2026-01-21T01:05:32Z

src/test/app/Invariants_test.cpp

+            {
+                .name = "Mixed scales",
+                .expectedMinScale = -2,
+                .values = {Number{1, -2}, Number{5, -3}, Number{3, -2}},
+            },


Another case

{ .name = "Mixed mantissa sizes", .expectedMinScale = X, .values = {Number{1}, Number{1234, -3}, Number{12345, -6}, Number{123, 1}}, }

Tapanito · 2026-01-21T10:43:47Z

@ximinez apologies for the forced push, I haven't seen your review!

Tapanito · 2026-01-21T17:59:57Z

@ximinez as we discussed, I rewrote the Invariant to check relative distance between values within some tolerance. For IOU the tolerance is 1 * 10^-13, for MPT/XRP the tolerance is zero.

The IOU tolerance is the smallest tolerance that would cause the unit test to pass. If the tolerance was -14, the unit-test would fail.

gregtatcam · 2026-01-21T20:26:17Z

src/xrpld/app/tx/detail/InvariantCheck.cpp

-                        afterVault.assetsAvailable)
+                    auto const assetsTotalDelta =
+                        afterVault.assetsTotal - beforeVault.assetsTotal;
+                    if (assetsTotalDelta != vaultDeltaAssets)


Why is this first if needed?

attempt to fix rounding issues

4fe50c2

Tapanito requested a review from ximinez January 14, 2026 19:59

improves VaultWithdraw invariant rounding

6223ebe

Tapanito changed the title ~~Relax Vault Invariant to account for rounding errors~~ Add rounding to VaultWithdraw invariants Jan 15, 2026

Tapanito added 3 commits January 15, 2026 16:10

Merge branch 'develop' into tapanito/lending-vault-invariant

465e7b6

fixes formatting

add9071

Merge branch 'develop' into tapanito/lending-vault-invariant

ffe0a3c

Tapanito changed the title ~~Add rounding to VaultWithdraw invariants~~ Add rounding to Vault invariants Jan 20, 2026

Tapanito force-pushed the tapanito/lending-vault-invariant branch from a7e80dd to 6b5618e Compare January 20, 2026 12:40

adds missing incldues

9235ec4

Tapanito force-pushed the tapanito/lending-vault-invariant branch from 6b5618e to 9235ec4 Compare January 20, 2026 16:06

fixes a minor min bug

aa12210

ximinez added a commit that referenced this pull request Jan 21, 2026

Add canonical "scale" computation to Number

3bff525

- Requires a template for STAmount and Asset. - Update tests and computeMinScale from #6217 to use scale. - Convert a few other places to use "scale" correctly.

ximinez mentioned this pull request Jan 21, 2026

Add canonical "scale" computation to Number #6246

Open

3 tasks

ximinez added a commit that referenced this pull request Jan 21, 2026

Add canonical "scale" computation to Number

7ab9709

- Requires a template for STAmount and Asset. - Update tests and computeMinScale from #6217 to use scale. - Convert a few other places to use "scale" correctly.

ximinez requested changes Jan 21, 2026

View reviewed changes

adds invariant test

c6821ab

Tapanito force-pushed the tapanito/lending-vault-invariant branch from 6f9b206 to c6821ab Compare January 21, 2026 10:42

Tapanito added 2 commits January 21, 2026 11:50

addreses review comments

1af0f4b

flyby change removing unused includes

f76bf53

kennyzlei requested a review from gregtatcam January 21, 2026 17:07

Tapanito added 2 commits January 21, 2026 18:57

refactors vault invariant to use relative distance

0a9436d

Merge branch 'develop' into tapanito/lending-vault-invariant

5c87c4f

Tapanito requested a review from ximinez January 21, 2026 18:03

gregtatcam reviewed Jan 21, 2026

View reviewed changes

Tapanito added the Blocked label Jan 22, 2026

Merge branch 'develop' into tapanito/lending-vault-invariant

f8d441b

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add rounding to Vault invariants #6217

Add rounding to Vault invariants #6217

Tapanito commented Jan 14, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 14, 2026 •

edited

Loading

Uh oh!

ximinez left a comment

Uh oh!

ximinez Jan 20, 2026

Uh oh!

Uh oh!

Uh oh!

ximinez Jan 20, 2026

Uh oh!

ximinez Jan 20, 2026

Uh oh!

ximinez Jan 20, 2026

Uh oh!

Uh oh!

ximinez Jan 21, 2026

Uh oh!

Tapanito commented Jan 21, 2026

Uh oh!

Tapanito commented Jan 21, 2026

Uh oh!

gregtatcam Jan 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Add rounding to Vault invariants #6217

Are you sure you want to change the base?

Add rounding to Vault invariants #6217

Conversation

Tapanito commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

High Level Overview of Change

Context of Change

Type of Change

API Impact

Uh oh!

codecov bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ximinez left a comment

Choose a reason for hiding this comment

Uh oh!

ximinez Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ximinez Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

ximinez Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

ximinez Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ximinez Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Tapanito commented Jan 21, 2026

Uh oh!

Tapanito commented Jan 21, 2026

Uh oh!

gregtatcam Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Tapanito commented Jan 14, 2026 •

edited

Loading

codecov bot commented Jan 14, 2026 •

edited

Loading