xrpld_number/
xrpl_iou_value.rs

1//! # XRP Ledger Token Amount Format
2//!
3//! The XRP Ledger uses 64 bits to serialize the numeric amount of a (fungible) token.
4//! In JSON format, the numeric amount is the `value` field of a currency amount object.
5//! In binary format, the numeric amount consists of a "not XRP" bit, a sign bit,
6//! significant digits, and an exponent, in the following order:
7//!
8//! ## Bit Layout
9//!
10//! ```text
11//! [T][S][EEEEEEEE][MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM]
12//!  │  │  └─8 bits─┘└──────────────────54 bits───────────────────────────┘
13//!  │  └─ Sign (1=positive, 0=negative)
14//!  └─ Type (1=fungible token, 0=XRP/MPT)
15//! ```
16//!
17//! ## Field Descriptions
18//!
19//! ### Type Bit (T)
20//! - The first (most significant) bit for a token amount is `1` to indicate that it is not an XRP amount
21//! - XRP amounts always have the most significant bit set to `0` to distinguish them from this format
22//!
23//! ### Sign Bit (S)
24//! - The sign bit indicates whether the amount is positive or negative
25//! - Unlike standard two's complement integers, `1` indicates positive in the XRP Ledger format,
26//!   and `0` indicates negative
27//!
28//! ### Exponent (8 bits)
29//! - The next 8 bits represent the exponent as an unsigned integer
30//! - The exponent indicates the scale (what power of 10 the significant digits should be multiplied by)
31//! - Valid range: -96 to +80 (inclusive)
32//! - During serialization, we add 97 to the exponent to make it possible to serialize as an unsigned integer
33//! - Examples:
34//!   - Serialized value of `1` indicates an exponent of `-96`
35//!   - Serialized value of `177` indicates an exponent of `80`
36//!
37//! ### Mantissa (54 bits)
38//! - The remaining 54 bits represent the significant digits (mantissa) as an unsigned integer
39//! - During serialization, this value is normalized to the range:
40//!   - Minimum: 10^15 (`1000000000000000`)
41//!   - Maximum: 10^16-1 (`9999999999999999`)
42//! - **Special case for zero**: When the value is 0, the sign bit, exponent, and significant digits
43//!   are all zeroes, so the 64-bit value is serialized as `0x8000000000000000`
44
45pub type XrplIouValue = [u8; 8];
46pub const FLOAT_ZERO: [u8; 8] = [0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00];
47pub const FLOAT_ONE: [u8; 8] = [0xD4, 0x83, 0x8D, 0x7E, 0xA4, 0xC6, 0x80, 0x00];
48pub const FLOAT_NEGATIVE_ONE: [u8; 8] = [0x94, 0x83, 0x8D, 0x7E, 0xA4, 0xC6, 0x80, 0x00];
xrpld_number/xrpl_iou_value.rs

xrpld_number/
xrpl_iou_value.rs
