solana_kit_fixed_points 0.9.1

Fixed-point number helpers for the Solana Kit Dart SDK.

solana_kit_fixed_points

Fixed-point number types and arithmetic for Solana programs in Dart. Provides binary (power-of-2) and decimal fixed-point representations with full codec support. A port of @solana/fixed-points from the Solana TypeScript SDK.

Installation

Install the package directly:

dependencies:
  "solana_kit_fixed_points": ^0.9.1

If your app uses several Solana Kit packages together, you can also depend on the umbrella package instead:

dart pub add solana_kit

Inside this monorepo, Dart workspace resolution uses the local package automatically.

Documentation

• Package page: https://pub.dev/packages/solana_kit_fixed_points
• API reference: https://pub.dev/documentation/solana_kit_fixed_points/latest/
• Workspace docs: https://openbudgetfun.github.io/solana_kit/
• Package catalog entry: https://openbudgetfun.github.io/solana_kit/reference/package-catalog#solana_kit_fixed_points
• Source code: https://github.com/openbudgetfun/solana_kit/tree/main/packages/solana_kit_fixed_points

For architecture notes, getting-started guides, and cross-package examples, start with the workspace docs site and then drill down into the package README and API reference.

Binary fixed-point numbers

Binary fixed-point types store values as integers scaled by a power of 2. Use them when you need deterministic arithmetic at known bit widths, like Solana token amounts that represent fractional lamports or ticks.

Construct a BinaryFixedPoint by specifying the raw scaled integer, fractional bit count, and total bit width:

import 'package:solana_kit_fixed_points/solana_kit_fixed_points.dart';

void main() {
  // 1.0 stored as raw = 2^32, with 32 fractional bits in a 64-bit word
  final value = BinaryFixedPoint(
    raw: BigInt.from(1) << 32,
    fractionalBits: 32,
    totalBits: 64,
  );
  print(value.toDecimalString()); // '1'

  // Arithmetic with + and -
  final a = BinaryFixedPoint(raw: BigInt.from(3) << 32, fractionalBits: 32, totalBits: 64);
  final b = BinaryFixedPoint(raw: BigInt.from(2) << 32, fractionalBits: 32, totalBits: 64);
  print((a + b).toDecimalString()); // '5'

  // Comparisons use named functions, not operators
  print(gtBinaryFixedPoint(a, b)); // true
}

rawBinaryFixedPoint returns a factory function that constructs values with a fixed shape. BinaryFixedPoint.parse reads a decimal string and converts it to the binary representation:

import 'package:solana_kit_fixed_points/solana_kit_fixed_points.dart';

void main() {
  final make = rawBinaryFixedPoint(FixedPointSignedness.unsigned, 64, 32);
  final a = make(BigInt.from(3) << 32);
  print(a.toDecimalString()); // '3'

  final parsed = BinaryFixedPoint.parse('1.5', fractionalBits: 32, totalBits: 64);
  print(parsed.toDecimalString()); // '1.5'
}

Decimal fixed-point numbers

Decimal fixed-point types use a power-of-10 scale. Useful when the on-wire format stores fractional amounts as integers (for example, token decimals).

import 'package:solana_kit_fixed_points/solana_kit_fixed_points.dart';

void main() {
  // 1.5 SOL stored as 1_500_000_000 lamports (9 decimal places)
  final price = DecimalFixedPoint(raw: BigInt.from(1500000000), decimals: 9, totalBits: 64);
  print(price.toDecimalString()); // '1.5'

  final quantity = DecimalFixedPoint(raw: BigInt.from(2000000000), decimals: 9, totalBits: 64);
  print((price + quantity).toDecimalString()); // '3.5'

  // Parse from a decimal string
  final solAmount = DecimalFixedPoint.parse('0.075', decimals: 9, totalBits: 64);
  print(solAmount.raw); // BigInt.from(75000000)
}

Fixed-point codecs

getBinaryFixedPointCodec encodes and decodes binary fixed-point values. getDecimalFixedPointCodec does the same for decimal fixed-point values. Both take the signedness, total bit width, and fractional bit/decimal count:

import 'package:solana_kit_fixed_points/solana_kit_fixed_points.dart';

void main() {
  final binCodec = getBinaryFixedPointCodec(FixedPointSignedness.unsigned, 64, 32);
  final binValue = BinaryFixedPoint(raw: BigInt.from(1) << 32, fractionalBits: 32, totalBits: 64);
  final binEncoded = binCodec.encode(binValue);
  print(binCodec.decode(binEncoded).toDecimalString()); // '1'

  final decCodec = getDecimalFixedPointCodec(FixedPointSignedness.unsigned, 64, 9);
  final decValue = DecimalFixedPoint(raw: BigInt.from(1500000000), decimals: 9, totalBits: 64);
  final decEncoded = decCodec.encode(decValue);
  print(decCodec.decode(decEncoded).toDecimalString()); // '1.5'
}

Formatting

binaryFixedPointToString and decimalFixedPointToString produce human-readable strings. formatBinaryFixedPoint and formatDecimalFixedPoint pass the scientific-notation representation to a custom formatter:

import 'package:solana_kit_fixed_points/solana_kit_fixed_points.dart';

void main() {
  final value = BinaryFixedPoint(raw: BigInt.from(1) << 32, fractionalBits: 32, totalBits: 64);
  print(binaryFixedPointToString(value)); // '1'

  final formatted = formatBinaryFixedPoint((sci) => '$sci SOL', value);
  print(formatted); // '4294967296E-32 SOL'
}

Key APIs

Symbol	Description
BinaryFixedPoint	Power-of-2 fixed-point number
DecimalFixedPoint	Power-of-10 fixed-point number
BinaryFixedPoint.parse	Parse a decimal string into a binary fixed-point
DecimalFixedPoint.parse	Parse a decimal string into a decimal fixed-point
rawBinaryFixedPoint	Factory function for fixed-shape binary values
rawDecimalFixedPoint	Factory function for fixed-shape decimal values
getBinaryFixedPointCodec	Codec for binary fixed-point wire format
getDecimalFixedPointCodec	Codec for decimal fixed-point wire format
binaryFixedPointToString	Format a binary fixed-point as a string
decimalFixedPointToString	Format a decimal fixed-point as a string
formatBinaryFixedPoint	Format via a custom scientific-notation handler
formatDecimalFixedPoint	Format via a custom scientific-notation handler
gtBinaryFixedPoint, ltBinaryFixedPoint, etc.	Comparison functions
addBinaryFixedPoint, subtractBinaryFixedPoint, etc.	Arithmetic functions