feat: Introduce Asset Scale for fractional asset support #301
+201
−156
Conversation
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
Bronek
reviewed
Jul 23, 2025
Bronek
reviewed
Jul 23, 2025
Bronek
reviewed
Jul 23, 2025
|
Thanks @Bronek for reviewing the spec., I addressed your comments. |
9 tasks
Bronek
reviewed
Sep 12, 2025
| ##### 2.1.6.1.3 `MPT` | ||
|
|
||
| When a vault holds **`XRP`**, the `Scale` is fixed at **0**. This aligns with XRP's native structure, where one share represents one "drop" (the smallest unit of XRP), and one XRP equals 1,000,000 drops. Therefore, a deposit of 10 XRP will result in the issuance of 10,000,000 shares ($10 \times 10^6$). | ||
| When a vault holds `MPT`, its `Scale` is fixed at **0**. This creates a 1-to-1 relationship between deposited MPT units and the shares issued (for example, depositing 10 MPTs to an empty Vault issues 10 shares). The value of a single MPT is determined at the issuer's discretion. If an MPT is set to represent a large value, the vault owner must be cautious. Because only whole MPT units can be deposited, any value that is not a multiple of a single MPT's value may be lost due to rounding during a transaction. |
There was a problem hiding this comment.
"the vault owner and depositors should be cautious. Since only whole MPT units are used in calculations, any value that is ..."
Bronek
reviewed
Sep 12, 2025
| | `MaximumAmount` | No limit to the number of shares that can be issued. | `0xFFFFFFFFFFFFFFFF` | | ||
| | `TransferFee` | The fee paid to transfer the shares. | 0 | | ||
| | `MPTokenMetadata` | Arbitrary metadata about the share MPT, in hex format. | - | | ||
| | `AssetScale` | Metadata representing the number of orders of magnitude between a standard unit and an MPT unit | `Vault.Scale` | |
There was a problem hiding this comment.
would also comment "only if the vault asset is an IOU", somewhere (probably not in the table ?)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Summary
This pull request introduces a crucial new vault parameter,
AssetScale, to enable support for fractional assets. Previously, the vault's accounting logic treated asset quantities as integers, leading to the truncation of any fractional part of a deposit and causing a loss of funds for the user.This change refactors the core exchange algorithms to use a fixed-point arithmetic approach, where fractional assets are converted to scaled, whole-number "share" equivalents upon deposit. This ensures all internal calculations are precise and prevents value loss from rounding or truncation errors.
The Problem
The previous integer-based logic could not handle assets that are commonly used in fractions (e.g., ETH, WBTC). A deposit of 20.3 WETH would be incorrectly credited as only 20 shares, resulting in an immediate and silent loss of 0.3 WETH for the depositor. This limitation severely restricted the types of assets the vault could support and eroded user trust.
The Solution
This PR implements the
AssetScaleparameter, which is defined once per vault.Scaling on Deposit:$\sigma = 10^{\text{AssetScale}}$ ). During a deposit, the asset amount is multiplied by this factor to create a scaled integer representation.
AssetScaleacts as an exponent for a power-of-10 multiplier (AssetScaleof6, a deposit of 20.3 assets is correctly converted to 20,300,000 shares (20.3 * 10^6).Precision in all Calculations: All subsequent vault operations (deposits, redemptions, and withdrawals) now use these scaled share values for their calculations. This maintains precision throughout the vault's lifecycle.
Accurate Payouts: The redeem and withdraw functions correctly interpret these scaled share values, converting them back into precise asset amounts for the user.
Key Changes
AssetScaleto the vault's core configuration.σto convert assets to shares. Subsequent calculations for deposits, redemptions, and withdrawals are updated to operate on these scaled values.