[W.I.P] feat Add Vault fixed-precision design notes - #7885
Draft
Tapanito wants to merge 6 commits into
Draft
Conversation
Proposes a design-time sfPrecision ceiling for Vault rounding, decoupled from the Vault's internal running totals, plus a Dust Pseudo-account and sfDust accumulator to capture value a mandatory operation (loan repayment) would otherwise lose when that ceiling degrades.
Corrects SettleAdd's AssetsTotal update to stop double-counting principal under cash-basis accounting, resolves the contradiction between optional-operation and Case 2 dust routing, folds the loan's own total-value floor into the loan.precision formula, and documents several accepted risks and non-issues surfaced during review (Loan acceptance griefing, DebtTotal's separate rounding behavior, and Dust sweep-timing attribution).
Reorganizes the document into Problem / Summary / Technical Details (Fields, Algorithm) / Appendix for easier reading, fixes an sfLoanScale mislabel, and removes the sfDust ledger field in favor of the Dust Pseudo-account's real balance as the single source of truth - the old field was never decremented on the normal sweep path and would have drifted from the account it was meant to mirror.
Reorganizes the design into a tighter Problem/Summary/Technical Details(Fields, Algorithm)/Appendix layout and trims narrative prose into scannable bullets without dropping content. Closes the assetsTotalDelta open question: interest recognized on a cash-basis repayment now gets the same two-stage dust truncation as the settled custody amount, keyed to what AssetsTotal actually gains rather than what custody gains, so a large Vault can no longer round an entire interest payment to zero and lose it untracked. Renames SettleAdd/MaybeSweep's pseudocode variables (e0/e1/settled_0/ dust_1/etc.) to descriptive names throughout.
Replaces the three separate documents (fixed-precision, derived- precision, and the comparison memo) with a single design-vault- precision.md that presents sfPrecision and the no-field alternative as Option A / Option B, sharing the identical mechanism once and branching only where they actually diverge. Rewrites SettleAdd to perform the real AssetsTotal addition first and read off the resulting scale, instead of independently truncating amount and assetsTotalDelta against a precomputed boundary and subtracting the shortfall afterward. The old approach could produce a settled value that wasn't aligned to the vault's scale; the new one can't, by construction, and also proves settled can never go negative. Simplifies MaybeSweep to a direct transfer instead of routing through SettleAdd, since the swept amount is already trimmed to fit before the transfer happens.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposes a design-time sfPrecision ceiling for Vault rounding, decoupled from the Vault's internal running totals, plus a Dust Pseudo-account and sfDust accumulator to capture value a mandatory operation (loan repayment) would otherwise lose when that ceiling degrades.
High Level Overview of Change
Context of Change
API Impact
libxrplchange (any change that may affectlibxrplor dependents oflibxrpl)