@solana/fixed-points

@solana/fixed-points

This package provides fixed-point number types for JavaScript without relying on floating-point arithmetic. It can be used standalone, but it is also exported as part of Kit @solana/kit.

This package is also part of the @solana/codecs package which acts as an entry point for all codec packages as well as for their documentation.

Two flavors are provided: decimal fixed-points (scale is a power of 10) and binary fixed-points (scale is a power of 2). Use decimal fixed-points to represent prices, token amounts, and any quantity whose precision aligns with decimal digits. Use binary fixed-points when the scale can align with bits — such as audio samples, graphics, or probabilities — and you want to trade base-10 ergonomics for faster arithmetic.

// Track a USDC balance without losing pennies to floating-point rounding.
const usdc = decimalFixedPoint('unsigned', 64, 6);
const balance = addDecimalFixedPoint(usdc('1234.56'), usdc('10.00'));
decimalFixedPointToString(balance); // "1244.56"

Both kinds share the same mental model. A value is a frozen object carrying a bigint raw and some shape metadata (signedness, total bits, scale). A decimal fixed-point represents raw / 10 ** decimals; a binary fixed-point represents raw / 2 ** fractionalBits.

Creating fixed-points

The decimalFixedPoint and binaryFixedPoint functions each validate a shape once and return a factory you can call many times to build values of that shape.

const usdc = decimalFixedPoint('unsigned', 64, 6); // u64 with 6 decimals
usdc('42.5'); // raw === 42_500_000n, exact
usdc('0.1234567'); // throws STRICT_MODE_PRECISION_LOSS (8th decimal is lossy)

const audioSample = binaryFixedPoint('signed', 16, 15); // Q1.15
audioSample('0.5'); // raw === 16384n, exact
audioSample('0.1', 'round'); // raw === 3277n, rounded

Use the raw* factories when the raw bigint is already known — for instance when you already have the value stored in its lowest denomination.

const cents = rawDecimalFixedPoint('unsigned', 32, 2);
cents(4250n); // represents 42.50

Use the ratio* factories for values defined as a numerator over a denominator.

const probability = ratioBinaryFixedPoint('signed', 16, 15);
probability(1n, 4n); // represents 0.25 exactly
probability(1n, 3n, 'round'); // represents ~0.333, rounded

Rounding modes

Any operation that could lose precision accepts a RoundingMode.

Mode	Behavior
strict	Throws STRICT_MODE_PRECISION_LOSS when the result is not exact.
floor	Rounds towards negative infinity.
ceil	Rounds towards positive infinity.
trunc	Rounds towards zero.
round	Rounds half values away from zero.

The default is 'strict', so precision loss is always explicit. Pass a mode whenever you are willing to accept a rounded result.

Arithmetic

Every arithmetic helper preserves the shape of its first operand and throws ARITHMETIC_OVERFLOW if the result doesn't fit.

addDecimalFixedPoint(usdc('10'), usdc('3.25')); // represents 13.25
subtractDecimalFixedPoint(usdc('10'), usdc('3.25')); // represents 6.75
negateBinaryFixedPoint(audioSample('0.5')); // represents -0.5 (signed only)
absoluteBinaryFixedPoint(audioSample('-0.5')); // represents 0.5

multiply and divide accept either another fixed-point of the same signedness (any total bits or scale) or a bare bigint. The result always has the first operand's shape. They consult the rounding mode when the operation is inexact; divide throws DIVISION_BY_ZERO on a zero denominator.

multiplyBinaryFixedPoint(audioSample('0.6'), audioSample('0.8')); // ~0.48
divideDecimalFixedPoint(usdc('100'), 4n); // represents 25
divideDecimalFixedPoint(usdc('1'), usdc('3'), 'floor'); // represents 0.333333

Comparisons

Comparison helpers return a boolean, or -1 | 0 | 1 for cmp. Only kind and scale must match; signedness and totalBits may differ.

cmpBinaryFixedPoint(audioSample('0.25'), audioSample('0.5')); // -1
eqBinaryFixedPoint(audioSample('0.5'), audioSample('0.5')); // true
ltDecimalFixedPoint(usdc('10'), usdc('20')); // true
lteDecimalFixedPoint(usdc('20'), usdc('20')); // true
gtDecimalFixedPoint(usdc('20'), usdc('10')); // true
gteDecimalFixedPoint(usdc('20'), usdc('20')); // true

Shape conversions

Use toSigned* and toUnsigned* to change a value's signedness without touching its total bits or scale.

const signedByte = rawBinaryFixedPoint('signed', 8, 4);
const unsignedByte = rawBinaryFixedPoint('unsigned', 8, 4);

toUnsignedBinaryFixedPoint(signedByte(100n)); // unsigned, raw === 100n
toSignedBinaryFixedPoint(unsignedByte(200n)); // throws: 200 > i8 max

Use rescale* to change the total bits and scale in one call. Scale-up is always exact; scale-down consults the rounding mode.

// Bridge EVM USDC (u128 with 18 decimals) down to SPL USDC (u64 with 6 decimals).
const evmUsdc = decimalFixedPoint('unsigned', 128, 18);
rescaleDecimalFixedPoint(evmUsdc('100.123456789012345678'), 64, 6, 'floor');
// represents 100.123456

Formatting

*ToString returns the canonical decimal string. Trailing zeros are trimmed by default.

decimalFixedPointToString(usdc('42.5')); // "42.5"
decimalFixedPointToString(usdc('-0.05')); // "-0.05"
binaryFixedPointToString(audioSample('0.5')); // "0.5"

Binary fixed-points always have a finite decimal expansion, but that expansion can be long (up to fractionalBits digits). Pass options.decimals with a RoundingMode to cap the output.

binaryFixedPointToString(audioSample('0.1')); // "0.0999755859375"
binaryFixedPointToString(audioSample('0.1'), { decimals: 4, rounding: 'round' }); // "0.1"

Set options.padTrailingZeros to emit exactly that many fractional digits.

decimalFixedPointToString(usdc('42.5'), { padTrailingZeros: true }); // "42.500000"

*ToNumber returns a JavaScript number. It is inherently lossy — prefer *ToString when exactness matters.

decimalFixedPointToNumber(usdc('42.5')); // 42.5

For locale-aware output, pass any Intl.NumberFormat instance to formatDecimalFixedPoint or formatBinaryFixedPoint. The helpers route the raw bigint through string scientific notation so precision is preserved beyond JavaScript's number mantissa.

const eurc = decimalFixedPoint('unsigned', 64, 6);
const eurFormatter = new Intl.NumberFormat('de-DE', { currency: 'EUR', style: 'currency' });
formatDecimalFixedPoint(eurFormatter, eurc('1234.5')); // "1.234,50 €"

The same helper exists for binary fixed-points.

const fr = new Intl.NumberFormat('fr-FR', { maximumFractionDigits: 4 });
formatBinaryFixedPoint(fr, audioSample('0.1')); // "0,1"

To plug a binary fixed-point into a custom formatter, convert it to its exact base-10 representation with binaryFixedPointToBase10 first. Decimal fixed-points already carry raw and decimals directly on the value object, so no equivalent helper is needed for them.

binaryFixedPointToBase10(audioSample('0.5')); // { raw: 500000000000000n, decimals: 15 }

Type guards

The is* and assertIs* guards narrow an unknown value to a fixed-point. All shape arguments are optional — pass undefined for any dimension you don't care about.

isDecimalFixedPoint(value); // any decimal fixed-point?
isBinaryFixedPoint(value, 'signed', 16, 15); // specifically an `audioSample`?
assertIsDecimalFixedPoint(value); // throws SHAPE_MISMATCH if not a decimal fixed-point

Codecs

Fixed-points also come with byte-level codecs compatible with the rest of the @solana/codecs ecosystem. The codec is a FixedSizeCodec whose size is totalBits / 8 — totalBits must therefore be a multiple of 8.

const codec = getBinaryFixedPointCodec('signed', 16, 15);
const bytes = codec.encode(audioSample('0.5')); // 0x0040
codec.decode(bytes); // represents 0.5

Values serialize in little-endian by default. Pass { endian: 'be' } for big-endian.

getDecimalFixedPointCodec('unsigned', 64, 6, { endian: 'be' }).encode(usdc('42.5'));
// 0x0000000002879b9a

Signed values use two's-complement and the codec accepts any byte-aligned width, including non-standard ones like 24, 40, 72, or 136 bits.

Separate get*Encoder and get*Decoder functions are also available.

const bytes = getDecimalFixedPointEncoder('unsigned', 64, 6).encode(usdc('42.5'));
const value = getDecimalFixedPointDecoder('unsigned', 64, 6).decode(bytes);

Types

• BinaryFixedPoint<TSignedness, TTotalBits, TFractionalBits> — a binary fixed-point with mathematical value raw / 2 ** fractionalBits.
• DecimalFixedPoint<TSignedness, TTotalBits, TDecimals> — a decimal fixed-point with mathematical value raw / 10 ** decimals.
• Signedness — 'signed' | 'unsigned'.
• RoundingMode — 'ceil' | 'floor' | 'round' | 'strict' | 'trunc'.
• FixedPointToStringOptions — options accepted by *ToString (decimals, padTrailingZeros, rounding).
• FixedPointCodecConfig — options accepted by the codec factories (endian).