aftermath-ts-sdk 1.2.64 → 1.2.65

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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"}

package/dist/packages/coin/coin.js

@@ -13,11 +13,33 @@ exports.Coin = void 0;
 const caller_1 = require("../../general/utils/caller");
 const helpers_1 = require("../../general/utils/helpers");
 const prices_1 = require("../../general/prices/prices");
+/**
+ * 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
+ * ```
+ */
 class Coin extends caller_1.Caller {
     // =========================================================================
     //  Constructor
     // =========================================================================
-    // TODO: update this class to not be instantiated with a coin type at all
+    /**
+     * 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 = undefined, config, Provider) {
         super(config, "coins");
         this.coinType = coinType;
@@ -25,6 +47,10 @@ class Coin extends caller_1.Caller {
         // =========================================================================
         //  Private Helpers
         // =========================================================================
+        /**
+         * Internal method to retrieve a specialized coin-related API from `AftermathApi`.
+         * Throws an error if no provider is set.
+         */
         this.useProvider = () => {
             var _a;
             const provider = (_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Coin();
@@ -33,6 +59,7 @@ class Coin extends caller_1.Caller {
             return provider;
         };
         this.coinType = coinType;
+        // Pre-extract segments for convenience
         this.coinTypePackageName = this.coinType
             ? Coin.getCoinTypePackageName(this.coinType)
             : "";
@@ -49,6 +76,19 @@ class Coin extends caller_1.Caller {
     // =========================================================================
     //  Inspections
     // =========================================================================
+    /**
+     * 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) {
         return __awaiter(this, void 0, void 0, function* () {
             const { coins } = inputs;
@@ -61,6 +101,20 @@ class Coin extends caller_1.Caller {
             return 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) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {
@@ -74,14 +128,48 @@ class Coin extends caller_1.Caller {
             return metadata;
         });
     }
+    /**
+     * 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) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("metadata", inputs);
         });
     }
+    /**
+     * 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) {
         this.metadata = metadata;
     }
+    /**
+     * 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) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {
@@ -99,9 +187,26 @@ class Coin extends caller_1.Caller {
             return priceInfo;
         });
     }
+    /**
+     * 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) {
         this.priceInfo = priceInfo;
     }
+    /**
+     * 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() {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("verified");
@@ -112,10 +217,27 @@ exports.Coin = Coin;
 // =========================================================================
 //  Constants
 // =========================================================================
+/**
+ * Static configuration and defaults for Sui coin types, including the standard
+ * SUI coin type, default decimals, and coin object type path.
+ */
 Coin.constants = {
+    /**
+     * The canonical coin type string for SUI.
+     */
     suiCoinType: "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
+    /**
+     * The default number of decimals for SUI (9).
+     */
     suiCoinDecimals: 9,
+    /**
+     * The canonical coin object type path for Sui's Move module, used in verifying coin objects.
+     */
     coinObjectType: "0x0000000000000000000000000000000000000000000000000000000000000002::coin::Coin",
+    /**
+     * Default decimals for various blockchains or ecosystems. For instance,
+     * "sui" => 9, "evm" => 18, etc.
+     */
     defaultCoinDecimals: {
         sui: 9,
         evm: 18,
@@ -128,7 +250,13 @@ Coin.constants = {
 // =========================================================================
 //  Coin Type
 // =========================================================================
-// TODO: remove in favor of sui js implementation Coin.getCoinStructTag() if it is the same
+/**
+ * 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.
+ */
 Coin.getCoinTypePackageName = (coin) => {
     const splitCoin = coin.split("::");
     if (splitCoin.length !== 3)
@@ -138,7 +266,13 @@ Coin.getCoinTypePackageName = (coin) => {
         return "";
     return packageName;
 };
-// TODO: remove in favor of sui js implementation ?
+/**
+ * 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.
+ */
 Coin.getCoinTypeSymbol = (coin) => {
     const startIndex = coin.lastIndexOf("::") + 2;
     // NOTE: should error if coin is not a valid coin type instead of empty string ?
@@ -149,32 +283,87 @@ Coin.getCoinTypeSymbol = (coin) => {
     const displayType = coin.slice(startIndex, endIndex);
     return displayType;
 };
+/**
+ * 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.
+ */
 Coin.getInnerCoinType = (coin) => coin.includes("<") ? coin.split("<")[1].slice(0, -1) : "";
+/**
+ * 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.
+ */
 Coin.coinTypeFromKeyType = (keyType) => {
     const startIndex = keyType.lastIndexOf("<") + 1;
     const endIndex = keyType.indexOf(">", startIndex);
     return keyType.slice(startIndex, endIndex);
 };
+/**
+ * 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`.
+ */
 Coin.isSuiCoin = (coin) => helpers_1.Helpers.stripLeadingZeroesFromType(coin) ===
     helpers_1.Helpers.stripLeadingZeroesFromType(Coin.constants.suiCoinType);
+/**
+ * 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`.
+ */
 Coin.isCoinObjectType = (objectType) => helpers_1.Helpers.stripLeadingZeroesFromType(objectType).startsWith(helpers_1.Helpers.stripLeadingZeroesFromType(Coin.constants.coinObjectType));
 // =========================================================================
 //  Helpers
 // =========================================================================
+/**
+ * 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.
+ */
 Coin.coinsAndAmountsOverZero = (coinAmounts) => {
-    // NOTE: will these loops always run in same order (is this a js gurantee or not) ?
+    // NOTE: will these loops always run in same order (is this a js guarantee or not) ?
     const coins = Object.keys(coinAmounts).filter((key) => coinAmounts[key] > 0);
     const amounts = Object.values(coinAmounts).filter((amount) => amount > 0);
     return { coins, amounts };
 };
+/**
+ * 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.
+ */
 Coin.coinsAndBalancesOverZero = (coinsToBalance) => {
-    // NOTE: will these loops always run in same order (is this a js gurantee or not) ?
+    // NOTE: will these loops always run in same order (is this a js guarantee or not) ?
     const coins = Object.keys(coinsToBalance).filter((key) => BigInt(coinsToBalance[key]) > BigInt(0));
     const balances = Object.values(coinsToBalance)
         .map(BigInt)
         .filter((amount) => amount > BigInt(0));
     return { coins, balances };
 };
+/**
+ * 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<...>"]
+ * });
+ * ```
+ */
 Coin.filterCoinsByType = (inputs) => {
     var _a;
     const filter = inputs.filter.toLowerCase().trim();
@@ -193,6 +382,13 @@ Coin.filterCoinsByType = (inputs) => {
             .includes(filter) || coinType.toLowerCase().includes(filter));
     });
 };
+/**
+ * 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.
+ */
 Coin.filterCoinsByMetadata = (inputs) => {
     var _a;
     return (_a = Object.entries(inputs.coinMetadatas)) === null || _a === void 0 ? void 0 : _a.filter(([coin, metadata]) => {
@@ -207,20 +403,48 @@ Coin.filterCoinsByMetadata = (inputs) => {
 // =========================================================================
 //  Conversions
 // =========================================================================
-/*
-    Convert user-inputted values into their onchain counterparts (e.g. u64)
-    TO-DO: change name
-*/
-Coin.normalizeBalance = (balance, decimals) => BigInt(
-// Take the floor in case user provides greater than `decimals` decimals
-Math.floor(balance * Math.pow(10, decimals)));
+/**
+ * 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.
+ */
+Coin.normalizeBalance = (balance, decimals) => BigInt(Math.floor(balance * Math.pow(10, decimals)));
+/**
+ * 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.
+ */
 Coin.balanceWithDecimals = (amount, decimals) => {
-    // TO-DO: make this conversion via string so no overflow or loss when bigint to number
+    // TODO: make this conversion via string so no overflow or loss when bigint to number ?
     return Number(amount) / Number(Math.pow(10, decimals));
 };
+/**
+ * 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.
+ */
 Coin.balanceWithDecimalsUsd = (amount, decimals, price) => {
     return Coin.balanceWithDecimals(amount, decimals) * price;
 };
+/**
+ * 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.
+ */
 Coin.coinSymbolForCoinType = (inputs) => {
     const { coinType, coinSymbolToCoinTypes } = inputs;
     try {
@@ -231,7 +455,7 @@ Coin.coinSymbolForCoinType = (inputs) => {
         const foundCoinSymbol = foundCoinData === null || foundCoinData === void 0 ? void 0 : foundCoinData[0];
         return foundCoinSymbol;
     }
-    catch (e) {
+    catch (_a) {
         return undefined;
     }
 };

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

@@ -1,36 +1,121 @@
 import { CoinMetadata } from "@mysten/sui/client";
 import { Balance, ObjectId, Percentage } from "../../general/types/generalTypes";
 import { CoinGeckoCoinApiId } from "../../types";
+/**
+ * Represents the decimal precision of a coin (e.g., 9 or 18).
+ */
 export type CoinDecimal = number;
+/**
+ * A string that uniquely identifies a coin type in the Sui network
+ * (e.g., "0x2::sui::SUI").
+ */
 export type CoinType = string;
+/**
+ * Represents a short symbol or ticker for a coin (e.g., "SUI", "BTC").
+ */
 export type CoinSymbol = string;
+/**
+ * Represents a coin with an amount in integer or floating form, typically used
+ * to specify a user’s holding or a transaction amount.
+ */
 export interface CoinWithAmount {
+    /**
+     * The coin type, e.g. "0x2::sui::SUI".
+     */
     coin: CoinType;
+    /**
+     * The amount of the coin, typically expressed as an integer number of smallest units.
+     */
     amount: number;
 }
+/**
+ * Represents a coin with an amount that can be `undefined`, typically for optional or
+ * deferred usage scenarios.
+ */
 export interface CoinWithAmountOrUndefined {
+    /**
+     * The coin type, e.g. "0x2::sui::SUI".
+     */
     coin: CoinType;
+    /**
+     * The amount of the coin, which can be `undefined`.
+     */
     amount: number | undefined;
 }
+/**
+ * Represents an amount in both coin denomination and USD value for reference.
+ */
 export interface AmountInCoinAndUsd {
+    /**
+     * The amount of the coin in smallest units.
+     */
     amount: number;
+    /**
+     * The USD equivalent of that coin amount.
+     */
     amountUsd: number;
 }
+/**
+ * Maps a coin type to a numerical balance. Typically used to store multiple
+ * coin balances under their respective coin types.
+ */
 export type CoinsToBalance = Record<CoinType, Balance>;
+/**
+ * Maps a coin type to a numerical balance, which may be `undefined`.
+ */
 export type CoinsToBalanceOrUndefined = Record<CoinType, Balance | undefined>;
+/**
+ * Maps a coin type to its price, typically as a number in USD or another fiat currency.
+ */
 export type CoinsToPrice = Record<CoinType, number>;
+/**
+ * Maps a coin type to its on-chain decimal precision.
+ */
 export type CoinsToDecimals = Record<CoinType, CoinDecimal>;
+/**
+ * Maps a coin type to price information, typically containing a price and a 24-hour change.
+ */
 export type CoinsToPriceInfo = Record<CoinType, CoinPriceInfo>;
+/**
+ * Maps a coin symbol (e.g., "SUI") to its price information, typically containing a price and a 24-hour change.
+ */
 export type CoinSymbolsToPriceInfo = Record<CoinSymbol, CoinPriceInfo>;
+/**
+ * Maps a coin symbol (e.g., "SUI") to an array of possible coin types (e.g., "0x2::sui::SUI").
+ */
 export type CoinSymbolToCoinTypes = Record<CoinSymbol, CoinType[]>;
+/**
+ * Represents pricing information for a coin, including current price and 24-hour percentage change.
+ */
 export interface CoinPriceInfo {
+    /**
+     * The current price in USD or another currency.
+     */
     price: number;
+    /**
+     * The 24-hour percentage change of the coin price.
+     * @remarks 0.54 = 54%
+     */
     priceChange24HoursPercentage: Percentage;
 }
+/**
+ * Extends the Sui `CoinMetadata` with optional properties relevant to external data
+ * sources (e.g., CoinGecko).
+ */
 export type CoinMetadaWithInfo = CoinMetadata & {
+    /**
+     * Indicates whether this coin's metadata was generated automatically.
+     */
     isGenerated?: boolean;
+    /**
+     * The associated CoinGecko API ID, if available.
+     */
     coingeckoId?: CoinGeckoCoinApiId;
 };
+/**
+ * Represents a coin reference in the Move environment, using either an on-chain ObjectId
+ * or an input index or result index from a transaction.
+ */
 export type ServiceCoinData = {
     Coin: ObjectId;
 } | {
@@ -40,6 +125,10 @@ export type ServiceCoinData = {
 } | {
     NestedResult: [number, number];
 };
+/**
+ * **Legacy type** representing a coin reference in the Move environment, using
+ * older transaction output indexing structures.
+ */
 export type ServiceCoinDataV2 = "gas" | {
     input: number;
 } | {
@@ -47,6 +136,10 @@ export type ServiceCoinDataV2 = "gas" | {
 } | {
     result: [number, number];
 };
+/**
+ * **Legacy type** representing how a transaction argument is encoded in the older
+ * Sui Transaction format.
+ */
 export type CoinTransactionObjectArgumentV0 = {
     kind: "Input";
     index: number;

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

@@ -1 +1 @@
-{"version":3,"file":"coinTypes.d.ts","sourceRoot":"","sources":["../../../src/packages/coin/coinTypes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACN,OAAO,EACP,QAAQ,EACR,UAAU,EACV,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAMjD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AACjC,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAC9B,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAMhC,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACzC,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAMD,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CAClB;AAMD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACvD,MAAM,MAAM,yBAAyB,GAAG,MAAM,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC;AAC9E,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AACpD,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;AAC/D,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;AACvE,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC;AAEnE,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B,EAAE,UAAU,CAAC;CACzC;AAMD,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG;IAC/C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,kBAAkB,CAAC;CACjC,CAAC;AAMF,MAAM,MAAM,eAAe,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC;AAEtC,MAAM,MAAM,iBAAiB,GAC1B,KAAK,GACL;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC;AAEhC,MAAM,MAAM,+BAA+B,GACxC;IACA,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACb,GACD;IACA,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACnB,GACD;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACb,CAAC"}
+{"version":3,"file":"coinTypes.d.ts","sourceRoot":"","sources":["../../../src/packages/coin/coinTypes.ts"],"names":[],"mappings":"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"}