@wuwei-labs/srsly/dist/types/params/amount.d.ts

TypeScript SDK for SRSLY

/**
 * @purpose Amount parameter conversion utilities
 *
 * Converts user-friendly ATLAS amounts to stardust (smallest unit) for use with Solana programs.
 * 1 ATLAS = 100,000,000 stardust (8 decimal places)
 */
/**
 * Amount parameter type
 *
 * Accepts either:
 * - Plain `number` / `bigint` — interpreted as **stardust** (smallest unit)
 * - `{ atlas: number }` — convenience form for whole ATLAS with decimals
 * - `{ stardust: number | bigint }` — explicit smallest unit (same as a bare number)
 *
 * Bare numbers default to stardust because the on-chain program operates
 * in stardust — `convertAmount(100)` is 100 stardust (0.000001 ATLAS),
 * not 100 ATLAS. Pass `{ atlas: 100 }` for one hundred ATLAS.
 */
export type AmountParam = number | bigint | {
    atlas: number;
} | {
    stardust: number | bigint;
};
/**
 * Convert amount parameter to stardust (smallest unit)
 *
 * @param amount - Amount in any supported format
 * @returns Amount in stardust (u64 for Solana program)
 * @throws Error if amount is invalid, negative, or non-integer stardust
 *
 * @example
 * ```typescript
 * convertAmount(10_000_000_000)         // 10_000_000_000n stardust (100 ATLAS)
 * convertAmount({ atlas: 10 })          // 1_000_000_000n stardust (10 ATLAS)
 * convertAmount({ stardust: 1_000_000 }) // 1_000_000n stardust (0.01 ATLAS)
 * ```
 */
export declare function convertAmount(amount: AmountParam): bigint;
/**
 * Convert stardust to ATLAS for display
 *
 * @param stardust - Amount in stardust
 * @returns Amount in ATLAS (decimal)
 *
 * @example
 * ```typescript
 * stardustToAtlas(100_000_000n)  // 1.0 ATLAS
 * stardustToAtlas(150_000_000n)  // 1.5 ATLAS
 * ```
 */
export declare function stardustToAtlas(stardust: bigint | number): number;
/**
 * Format amount for display
 *
 * @param stardust - Amount in stardust
 * @param decimals - Number of decimal places (default: 8 for full precision)
 * @returns Formatted ATLAS amount string
 *
 * @example
 * ```typescript
 * formatAmount(100_000_000n)      // "1.00000000 ATLAS"
 * formatAmount(150_000_000n, 2)   // "1.50 ATLAS"
 * ```
 */
export declare function formatAmount(stardust: bigint | number, decimals?: number): string;
/**
 * Validate amount is within reasonable bounds
 *
 * @param stardust - Amount in stardust
 * @param min - Minimum allowed amount in stardust (default: 0)
 * @param max - Maximum allowed amount in stardust (default: MAX_U64)
 * @throws Error if amount is out of bounds
 */
export declare function validateAmount(stardust: bigint, min?: bigint, max?: bigint): void;
//# sourceMappingURL=amount.d.ts.map