Show / Hide Table of Contents

Class LedgerAmountGrid

The amounts the ledger can hold, and how to land on one.

Inheritance
object
LedgerAmountGrid
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 Source

IssuedSignificantDigits

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
| Edit this page View Source

SmallestXrp

The smallest positive XRP amount: one drop.

Declaration
public const decimal SmallestXrp = 0.000001
Field Value
Type Description
decimal
| Edit this page View Source

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 Source

IsBelowSmallest(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
| Edit this page View Source

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

true for XRP (drops), false for an issued amount.

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, RoundDown(1.23456799999999m, isXrp: true) is 1.234568, while 1.2345679m is cut to 1.234567.

| Edit this page View Source

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

true for XRP (drops), false for an issued amount.

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 400000 + 1e-16 stays 400000 for XRP.

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.

| Edit this page View Source

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

true for XRP (drops), false for an issued amount.

Returns
Type Description
decimal
Exceptions
Type Condition
ArgumentOutOfRangeException

value is zero: zero has no most significant digit and so no step. Applies to XRP as well, for one rule.

  • Edit this page
  • View Source
In this article
Back to top Generated by DocFX