Class LedgerAmountGrid
The amounts the ledger can hold, and how to land on one.
Inheritance
Namespace: Xrpl.Amounts
Assembly: Xrpl.dll
Syntax
public static class LedgerAmountGrid
Remarks
XRP exists in whole drops: six decimal places. An issued amount keeps a mantissa in
[10^15, 10^16) (rippled's STAmount), so up to sixteen significant digits. That
is not a fixed number of decimal places: a value near a million has nine, one near 1e-9 has
twenty-four, and from 1e16 the step grows past one (10, 100, ...). An amount that is off the
grid is replaced by the ledger with a different one, or refused as malformed.
Direction matters. A figure promised to be received is rounded down
(RoundDown(decimal, bool)), as the ledger does; a figure that bounds a spend, such as
SendMax, is rounded up (RoundUp(decimal, bool)), because the ledger rejects a payment
whose SendMax is below what the delivery requires. Both work on the magnitude, so
"down" is toward zero and "up" is away from it, and the grid is symmetric around zero.
Everything is decimal arithmetic. A logarithm on a converted double lands on the wrong side of a power of ten often enough to give a digit too many or too few.
MPT amounts are not covered: they are whole numbers up to 2^63-1, which neither the XRP grid (six places) nor the issued one (sixteen significant digits) describes. Use System.Math.Truncate(decimal) and System.Math.Ceiling(decimal) for them.
Fields
| Edit this page View SourceIssuedSignificantDigits
Significant digits an issued amount keeps at most: the top of the mantissa range
[10^15, 10^16). A seventeenth digit is refused by the serializer, not trimmed.
Declaration
public const int IssuedSignificantDigits = 16
Field Value
| Type | Description |
|---|---|
| int |
SmallestXrp
The smallest positive XRP amount: one drop.
Declaration
public const decimal SmallestXrp = 0.000001
Field Value
| Type | Description |
|---|---|
| decimal |
XrpDecimals
Decimal places XRP has: one drop is 1e-6.
Declaration
public const int XrpDecimals = 6
Field Value
| Type | Description |
|---|---|
| int |
Methods
| Edit this page View SourceIsBelowSmallest(decimal, bool)
Whether a positive XRP amount is below one drop and so cannot be sent: it serializes as "0", which the ledger refuses as malformed instead of answering "no route". Issued amounts have no smallest magnitude, only a digit count, so they are never below it.
Declaration
public static bool IsBelowSmallest(decimal value, bool isXrp)
Parameters
| Type | Name | Description |
|---|---|---|
| decimal | value | |
| bool | isXrp |
Returns
| Type | Description |
|---|---|
| bool |
RoundDown(decimal, bool)
Rounds toward zero onto the grid: the form for anything presented as received. XRP and issued amounts only; an MPT amount is not on this grid.
Declaration
public static decimal RoundDown(decimal value, bool isXrp)
Parameters
| Type | Name | Description |
|---|---|---|
| decimal | value | The amount; zero is returned as is. |
| bool | isXrp |
Returns
| Type | Description |
|---|---|
| decimal | The grid value toward zero. Residue is removed first: the value is scaled to the
grid and rounded to six places (System.Math.Round(decimal, int), banker's rounding at
the midpoint) before the cut, so the result may land up to 5e-7 of a step on the other side
of the input, treating the difference as arithmetic residue. For XRP,
|
RoundUp(decimal, bool)
Rounds away from zero onto the grid: the form for anything that bounds a spend. XRP and issued amounts only; an MPT amount is not on this grid.
Declaration
public static decimal RoundUp(decimal value, bool isXrp)
Parameters
| Type | Name | Description |
|---|---|---|
| decimal | value | The amount; zero is returned as is. |
| bool | isXrp |
Returns
| Type | Description |
|---|---|
| decimal | The grid value away from zero. Residue is removed first, as in
RoundDown(decimal, bool): the result may land up to 5e-7 of a step on the other side of the
input, treating the difference as arithmetic residue, so |
Exceptions
| Type | Condition |
|---|---|
| OverflowException | The result would exceed the range of decimal; only possible for an issued amount within one step of decimal.MaxValue or decimal.MinValue, since the sign is applied after the magnitude is rounded. An XRP amount that large is returned unchanged. |
Step(decimal, bool)
The distance between two neighbouring grid values at the magnitude of
value: 1e-6 for XRP; for an issued amount 10^(msd - 15), which is
10, 100, ... from 1e16 and is never smaller than 1e-28, the finest a decimal
holds. The sign of value is ignored. XRP and issued amounts only; an MPT
amount has a step of one and is not covered.
Declaration
public static decimal Step(decimal value, bool isXrp)
Parameters
| Type | Name | Description |
|---|---|---|
| decimal | value | A nonzero amount. |
| bool | isXrp |
Returns
| Type | Description |
|---|---|
| decimal |
Exceptions
| Type | Condition |
|---|---|
| ArgumentOutOfRangeException |
|