aftermath-ts-sdk 1.2.63 → 1.2.64-docs.1

package/dist/packages/coin/coin.d.ts

@@ -2,65 +2,315 @@ import { AnyObjectType, Balance, CallerConfig, CoinDecimal, CoinMetadaWithInfo,
 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

package/dist/packages/coin/coin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coin.d.ts","sourceRoot":"","sources":["../../../src/packages/coin/coin.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,aAAa,EACb,OAAO,EACP,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,eAAe,EACf,UAAU,EACV,qBAAqB,EACrB,QAAQ,EACR,OAAO,EAGP,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,qBAAa,IAAK,SAAQ,MAAM;aAmCd,QAAQ,EAAE,QAAQ,GAAG,SAAS;IAE9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAhC3B,gBAAuB,SAAS;;;;;;;;;MAW9B;IAMF,SAAgB,mBAAmB,EAAE,MAAM,CAAC;IAC5C,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC,SAAgB,aAAa,EAAE,MAAM,CAAC;IAE/B,QAAQ,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACzC,SAAS,EAAE,aAAa,GAAG,SAAS,CAAC;gBAQ3B,QAAQ,GAAE,QAAQ,GAAG,SAAqB,EAC1D,MAAM,CAAC,EAAE,YAAY,EACJ,QAAQ,CAAC,0BAAc;IAwB5B,kBAAkB,CAAC,MAAM,EAAE;QACvC,KAAK,EAAE,QAAQ,EAAE,CAAC;KAClB,GAAG,OAAO,CAAC,eAAe,CAAC;IAaf,eAAe,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAW7D,gBAAgB,CAAC,MAAM,EAAE;QACrC,KAAK,EAAE,QAAQ,EAAE,CAAC;KAClB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAO1B,eAAe,CAAC,QAAQ,EAAE,kBAAkB;IAItC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC;IAiBvD,YAAY,CAAC,SAAS,EAAE,aAAa;IAI/B,gBAAgB;IAa7B,OAAc,sBAAsB,SAAU,QAAQ,KAAG,MAAM,CAM7D;IAGF,OAAc,iBAAiB,SAAU,QAAQ,KAAG,MAAM,CAUxD;IAEF,OAAc,gBAAgB,SAAU,QAAQ,YACW;IAE3D,OAAc,mBAAmB,YAAa,OAAO,YAInD;IAEF,OAAc,SAAS,SAAU,QAAQ,aAEuB;IAEhE,OAAc,gBAAgB,eAAgB,aAAa,aAGxD;IAMH,OAAc,uBAAuB,gBACvB,OAAO,QAAQ,EAAE,MAAM,CAAC;;;MAWpC;IAEF,OAAc,wBAAwB,mBACrB,cAAc;;;MAW7B;IAEF,OAAc,iBAAiB,WAAY;QAC1C,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,QAAQ,EAAE,CAAC;KACtB,KAAG,QAAQ,EAAE,CAmBZ;IAEF,OAAc,qBAAqB,WAAY;QAC9C,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,OAAO,QAAQ,EAAE,YAAY,CAAC,CAAC;KAC9C,KAAG,QAAQ,EAAE,CAYZ;IAcF,OAAc,gBAAgB,YACpB,MAAM,YACL,WAAW,KACnB,OAAO,CAIP;IAEH,OAAc,mBAAmB,WACxB,MAAM,GAAG,MAAM,YACb,MAAM,YAIf;IAEF,OAAc,sBAAsB,WAC3B,MAAM,GAAG,MAAM,YACb,MAAM,SACT,MAAM,YAGZ;IAEF,OAAc,qBAAqB,WAAY;QAC9C,QAAQ,EAAE,QAAQ,CAAC;QACnB,qBAAqB,EAAE,qBAAqB,CAAC;KAC7C,KAAG,UAAU,GAAG,SAAS,CAgBxB;IAMF,OAAO,CAAC,WAAW,CAIjB;CACF"}
+{"version":3,"file":"coin.d.ts","sourceRoot":"","sources":["../../../src/packages/coin/coin.ts"],"names":[],"mappings":"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"}