Handle token amounts
Use exact token amounts and distinguish utility functions from transaction builders.
The source SDK @grapl/sdk exports exact amount conversion utilities alongside its direct transaction client. The package is not an announced npm release. Follow the Getting started to link the source package.
Amount API
| Export | Signature and behavior |
|---|---|
TOKEN_AMOUNT_MAX | bigint, equal to 2^64 - 1 |
assertTokenAmount | (amount: bigint): void; requires 0..u64::MAX |
parseTokenAmount | (text: string, decimals: number): bigint; parses unsigned decimal text |
parseSwapAmount | Same arguments; additionally rejects zero |
formatTokenAmount | (amount: bigint, decimals: number): string; exact canonical decimal output |
The number parameter is mint-decimal metadata, not a financial amount. Decimal metadata must be an integer in 0..255.
Convert a user amount
The SDK exposes exact parsing and formatting:
import { parseTokenAmount, formatTokenAmount } from "@grapl/sdk";
const atoms: bigint = parseTokenAmount("1.25", 6);
const display: string = formatTokenAmount(atoms, 6);Here atoms is 1250000n and display is "1.25". The import resolves to the source package linked in your application.
The parser rejects negative signs, exponent notation, leading-zero whole numbers other than zero, excessive fractional precision, and values above u64::MAX. It does not round invalid user input into a valid amount.
Construct instructions separately
These utilities only parse amounts. Use the separate direct client methods to prepare transactions, the IDL and instruction contract for account order, and wallet context for authorization.