aftermath-ts-sdk
Version:
Aftermath TypeScript SDK
316 lines • 13 kB
TypeScript
import { AnyObjectType, Balance, CallerConfig, CoinDecimal, CoinMetadaWithInfo, CoinPriceInfo, CoinsToBalance, CoinsToDecimals, CoinSymbol, CoinSymbolToCoinTypes, CoinType, KeyType } from "../../types";
import { Caller } from "../../general/utils/caller";
import { AftermathApi } from "../../general/providers";
import { CoinMetadata } from "@mysten/sui/client";
/**
* The `Coin` class provides functionality to manage and inspect coin types,
* retrieve metadata and prices, and convert balances with respect to coin decimals.
* It can be instantiated with or without a specific `coinType` for convenience.
*
* @example
* ```typescript
*
* const afSdk = new Aftermath("MAINNET");
* await afSdk.init(); // initialize provider
*
* const coin = afSdk.Coin("0x2::sui::SUI");
*
* const metadata = await coin.getCoinMetadata(); // fetch metadata for SUI coin
* ```
*/
export declare class Coin extends Caller {
readonly coinType: CoinType | undefined;
private readonly Provider?;
/**
* Static configuration and defaults for Sui coin types, including the standard
* SUI coin type, default decimals, and coin object type path.
*/
static readonly constants: {
/**
* The canonical coin type string for SUI.
*/
suiCoinType: string;
/**
* The default number of decimals for SUI (9).
*/
suiCoinDecimals: number;
/**
* The canonical coin object type path for Sui's Move module, used in verifying coin objects.
*/
coinObjectType: string;
/**
* Default decimals for various blockchains or ecosystems. For instance,
* "sui" => 9, "evm" => 18, etc.
*/
defaultCoinDecimals: {
sui: number;
evm: number;
svm: number;
};
};
/**
* The Move package name portion of this coin type, e.g. the middle "module" from "0x2::sui::SUI".
* Will be empty if no `coinType` is provided.
*/
readonly coinTypePackageName: string;
/**
* The final part of the coin type (the "symbol" or short name) from "0x2::sui::SUI".
* Will be empty if no `coinType` is provided.
*/
readonly coinTypeSymbol: string;
/**
* If the coin type includes a generic argument (like `Coin<0x...>`), this is extracted. Else empty.
* E.g. "0x5::coin::Coin<0x2::sui::SUI>" => "0x2::sui::SUI".
*/
readonly innerCoinType: string;
/**
* An optional cached coin metadata object retrieved by `getCoinMetadata`.
*/
metadata: CoinMetadaWithInfo | undefined;
/**
* An optional cached price info object retrieved by `getPrice`.
*/
priceInfo: CoinPriceInfo | undefined;
/**
* Creates a new instance of `Coin`.
*
* @param coinType - The coin's type string (e.g., "0x2::sui::SUI"). If omitted, methods that require a type will need it passed in manually.
* @param config - Optional caller configuration (network, access token).
* @param Provider - An optional `AftermathApi` instance for coin-specific API calls.
*/
constructor(coinType?: CoinType | undefined, config?: CallerConfig, Provider?: AftermathApi | undefined);
/**
* Retrieves the decimals for multiple coins by calling the Aftermath API for metadata
* and extracting the `decimals` property.
*
* @param inputs - An object containing an array of coin types.
* @returns An object mapping each coin type to a numeric decimal count.
*
* @example
* ```typescript
* const decimals = await coin.getCoinsToDecimals({ coins: ["0x2::sui::SUI", "0x<...>"] });
* console.log(decimals); // { "0x2::sui::SUI": 9, "0x<...>": 6 }
* ```
*/
getCoinsToDecimals(inputs: {
coins: CoinType[];
}): Promise<CoinsToDecimals>;
/**
* Fetches the metadata (name, symbol, decimals) for this coin type or a provided one,
* caching it if already requested.
*
* @param coin - Optionally override the constructor coinType.
* @returns The `CoinMetadaWithInfo` object containing metadata and optional external references.
* @throws If neither constructor nor argument coinType is available.
*
* @example
* ```typescript
* const metadata = await coin.getCoinMetadata("0x2::sui::SUI");
* console.log(metadata.name, metadata.symbol, metadata.decimals);
* ```
*/
getCoinMetadata(coin?: CoinType): Promise<CoinMetadaWithInfo>;
/**
* Fetches metadata for multiple coins at once, returning an array in the same order
* as the coin types requested.
*
* @param inputs - An object with `coins`, an array of coin types.
* @returns An array of `CoinMetadaWithInfo` with length matching `coins`.
*
* @example
* ```typescript
* const metas = await coin.getCoinMetadatas({
* coins: ["0x2::sui::SUI", "0x<custom::TOKEN>"]
* });
* console.log(metas[0].symbol, metas[1].symbol);
* ```
*/
getCoinMetadatas(inputs: {
coins: CoinType[];
}): Promise<CoinMetadaWithInfo[]>;
/**
* Manually sets the metadata in this Coin instance, storing it in `this.metadata`.
*
* @param metadata - A `CoinMetadaWithInfo` object to cache in this instance.
*/
setCoinMetadata(metadata: CoinMetadaWithInfo): void;
/**
* Retrieves price information (including current price and 24h change) for this coin or a provided coin.
* If already fetched, it returns the cached data.
*
* @param coin - Optionally override the constructor coinType.
* @returns A `CoinPriceInfo` with `price` and `priceChange24HoursPercentage`.
* @throws If no valid coin type is present.
*
* @example
* ```typescript
* const priceInfo = await coin.getPrice("0x2::sui::SUI");
* console.log(priceInfo.price, priceInfo.priceChange24HoursPercentage);
* ```
*/
getPrice(coin?: CoinType): Promise<CoinPriceInfo>;
/**
* Manually sets the price info in this Coin instance, storing it in `this.priceInfo`.
*
* @param priceInfo - A `CoinPriceInfo` object to cache in this instance.
*/
setPriceInfo(priceInfo: CoinPriceInfo): void;
/**
* Fetches a list of "verified" coin types from the Aftermath backend. Verified coins
* typically pass certain safety or liquidity checks.
*
* @returns An array of `CoinType` strings that are considered verified.
*
* @example
* ```typescript
* const verified = await coin.getVerifiedCoins();
* console.log(verified); // e.g. ["0x2::sui::SUI", "0x...::MYCOIN", ...]
* ```
*/
getVerifiedCoins(): Promise<string[]>;
/**
* Extracts the Move package name portion from a coin type string.
* E.g., "0x2::sui::SUI" => "sui".
*
* @param coin - The coin type string (e.g., "0x2::sui::SUI").
* @returns The middle segment of the type or empty string if not parseable.
*/
static getCoinTypePackageName: (coin: CoinType) => string;
/**
* Extracts the final part of the coin type (the symbol or short name).
* For example, "0x2::sui::SUI" => "SUI".
*
* @param coin - The coin type string.
* @returns The extracted symbol or empty string if not found.
*/
static getCoinTypeSymbol: (coin: CoinType) => string;
/**
* Extracts the inner generic argument of a coin type if present. E.g.,
* "0x2::coin::Coin<0x2::sui::SUI>" => "0x2::sui::SUI".
*
* @param coin - The coin type with a possible `<...>` suffix.
* @returns The inner type or an empty string if not found.
*/
static getInnerCoinType: (coin: CoinType) => string;
/**
* If a `KeyType` string references a type in angle brackets, extracts the type
* inside. Typically for "0x2::coin::Coin<0x2::mycoin::MYCOIN>" -> "0x2::mycoin::MYCOIN".
*
* @param keyType - The key type string to parse.
* @returns The substring inside `<...>` or the original if no brackets found.
*/
static coinTypeFromKeyType: (keyType: KeyType) => string;
/**
* Checks if a coin type string corresponds to the canonical SUI coin.
*
* @param coin - A coin type string.
* @returns `true` if it matches "0x2::sui::SUI", otherwise `false`.
*/
static isSuiCoin: (coin: CoinType) => boolean;
/**
* Checks if an object type string is a `Coin<...>` object from the standard Sui Move module.
*
* @param objectType - The object type to test.
* @returns `true` if it matches "0x2::coin::Coin<...>", otherwise `false`.
*/
static isCoinObjectType: (objectType: AnyObjectType) => boolean;
/**
* Given a record of coin types => numeric amounts, filters out those
* with zero or negative amounts, returning only the positive pairs.
*
* @param coinAmounts - A record mapping coin types to numeric amounts.
* @returns An object with `coins` array and `amounts` array in matching indexes.
*/
static coinsAndAmountsOverZero: (coinAmounts: Record<CoinType, number>) => {
coins: string[];
amounts: number[];
};
/**
* Given a record of coin types => bigint balances, filters out those with zero
* or negative balances, returning only the positive pairs.
*
* @param coinsToBalance - A record mapping coin types to bigints.
* @returns An object with `coins` array and `balances` array in matching indexes.
*/
static coinsAndBalancesOverZero: (coinsToBalance: CoinsToBalance) => {
coins: string[];
balances: bigint[];
};
/**
* Filters a list of `coinTypes` by a textual query, matching against both zero-padded
* and non-padded forms as well as substring checks.
*
* @param inputs - Contains `filter` (the search string) and `coinTypes`.
* @returns An array of coin types that match the filter in either raw or zero-padded form.
*
* @example
* ```typescript
* const filtered = Coin.filterCoinsByType({
* filter: "sui",
* coinTypes: ["0x2::sui::SUI", "0x<...>"]
* });
* ```
*/
static filterCoinsByType: (inputs: {
filter: string;
coinTypes: CoinType[];
}) => CoinType[];
/**
* Filters a record of coin metadata by a textual query, matching both the coin type
* and the metadata's name/symbol fields.
*
* @param inputs - An object containing `filter` and a record of `coinMetadatas`.
* @returns An array of coin types that match the search criteria.
*/
static filterCoinsByMetadata: (inputs: {
filter: string;
coinMetadatas: Record<CoinType, CoinMetadata>;
}) => CoinType[];
/**
* Converts a user-friendly decimal number (e.g., 1.5) to a raw on-chain
* integer representation by scaling with the given coin decimals.
* For example, `1.5` with `decimals = 9` => `1500000000n`.
*
* @param balance - The user-friendly balance as a number.
* @param decimals - Number of decimal places for this coin.
* @returns A bigint representing the raw on-chain balance.
*/
static normalizeBalance: (balance: number, decimals: CoinDecimal) => Balance;
/**
* Scales a raw bigint or numeric `amount` down by `decimals` to get a display-friendly float.
* For example, `1500000000n` with `decimals = 9` => `1.5`.
*
* @param amount - The raw on-chain amount as `bigint` or `number`.
* @param decimals - Number of decimal places for this coin.
* @returns The resulting float as an easily readable balance.
*/
static balanceWithDecimals: (amount: bigint | number, decimals: number) => number;
/**
* Scales a raw `amount` down by `decimals` and multiplies by a `price` in USD,
* returning a final USD value. E.g., `1500000000n`, `decimals=9`, `price=2.0` => `3.0`.
*
* @param amount - The raw balance as bigint or number.
* @param decimals - The coin decimals.
* @param price - The coin's price in USD.
* @returns The computed float in USD.
*/
static balanceWithDecimalsUsd: (amount: bigint | number, decimals: number, price: number) => number;
/**
* Looks up a coin's symbol if it is known in a provided `coinSymbolToCoinTypes`
* record. For instance, if "SUI" => `["0x2::sui::SUI"]`, we can find "SUI" from
* the coin type "0x2::sui::SUI".
*
* @param inputs - An object with `coinType` and `coinSymbolToCoinTypes`.
* @returns The coin symbol string or `undefined` if not found.
*/
static coinSymbolForCoinType: (inputs: {
coinType: CoinType;
coinSymbolToCoinTypes: CoinSymbolToCoinTypes;
}) => CoinSymbol | undefined;
/**
* Internal method to retrieve a specialized coin-related API from `AftermathApi`.
* Throws an error if no provider is set.
*/
private useProvider;
}
//# sourceMappingURL=coin.d.ts.map