aftermath-ts-sdk 1.2.64 → 1.2.65

package/dist/packages/auth/auth.js

@@ -12,42 +12,95 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Auth = void 0;
 const caller_1 = require("../../general/utils/caller");
 const utils_1 = require("../../general/utils");
+/**
+ * The `Auth` class manages creation and refreshing of access tokens
+ * to obtain higher rate limits on the Aftermath API. It includes methods
+ * to initialize authorization either by a direct callback-based approach
+ * or by importing a local Sui keystore. Optionally, administrative functions
+ * are provided for creating specialized auth accounts.
+ *
+ * @example
+ * ```typescript
+ * const auth = new Auth();
+ * const stopAuth = await auth.init({
+ *   walletAddress: "0x<address>",
+ *   signMessageCallback: async ({ message }) => {
+ *     // sign message
+ *   },
+ * });
+ * // ... make authenticated requests ...
+ * stopAuth(); // stop auto refresh
+ * ```
+ */
 class Auth extends caller_1.Caller {
     // =========================================================================
     //  Constructor
     // =========================================================================
+    /**
+     * Creates a new `Auth` instance for token-based rate limit increases.
+     *
+     * @param config - Optional caller configuration, including network and access token.
+     */
     constructor(config) {
         super(config, "auth");
         // =========================================================================
         //  Private Class Members
         // =========================================================================
+        /**
+         * Holds the timer reference for scheduled token refreshes.
+         */
         this.refreshTimer = null;
+        /**
+         * Indicates whether the user has canceled auto token refresh.
+         */
         this.isCanceled = false;
     }
     // =========================================================================
     //  User-Facing
     // =========================================================================
+    /**
+     * Initializes the auth system by fetching an access token for the provided wallet address.
+     * After obtaining the token, it automatically schedules periodic refresh calls until stopped.
+     *
+     * @param inputs - An object containing the user's `walletAddress` and a `signMessageCallback` function
+     *  for cryptographically signing messages.
+     *
+     * @returns A function that, when called, cancels further token refresh attempts.
+     *
+     * @example
+     * ```typescript
+     * const auth = new Auth();
+     * const stopAuth = await auth.init({
+     *   walletAddress: "0x<address>",
+     *   signMessageCallback: async ({ message }) => {
+     *     // sign the message with your private key / keypair
+     *   },
+     * });
+     *
+     * // ... make authorized calls ...
+     *
+     * stopAuth(); // Cancel further token refreshes
+     * ```
+     */
     init(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
-            // Step 1: Mark as "not canceled" before the new run
-            this.isCanceled = false;
-            // Step 2: Define a function that does the “work” + schedules next call
+            this.isCanceled = false; // Mark as active
             const startRefresh = () => __awaiter(this, void 0, void 0, function* () {
-                // If canceled at the time we enter, don’t do anything
                 if (this.isCanceled)
-                    return;
+                    return; // No-op if canceled
                 const { accessToken, expirationTimestamp } = yield this.getAccessToken(inputs);
                 this.setAccessToken(accessToken);
                 if (this.isCanceled)
-                    return; // double-check before scheduling next timer
+                    return; // Double-check after token fetch
+                // Provide a margin by refreshing before actual expiration
                 const TIMEOUT_REDUCTION_RATIO = 0.9;
                 const interval = (expirationTimestamp - Date.now()) * TIMEOUT_REDUCTION_RATIO;
-                // Store the timer so we can cancel it later
+                // Schedule next refresh
                 this.refreshTimer = setTimeout(startRefresh, interval);
             });
-            // Step 3: Kick off the first refresh
+            // Kick off first refresh
             yield startRefresh();
-            // Step 4: Return a function that cancels further refreshes
+            // Return cancellation function
             return () => {
                 this.isCanceled = true;
                 if (this.refreshTimer) {
@@ -56,26 +109,48 @@ class Auth extends caller_1.Caller {
             };
         });
     }
+    /**
+     * Initializes the auth system by reading a local Sui keystore file (on the server side),
+     * using the private keys matching a provided address to sign messages for token creation.
+     * After the token is obtained, it automatically schedules periodic refresh calls until stopped.
+     *
+     * @param inputs - An object containing the target `walletAddress` and an optional path to the `.keystore`.
+     *  If `path` is not provided, it defaults to `~/.sui/sui_config/sui.keystore`.
+     * @returns A function that, when called, cancels further token refresh attempts.
+     *
+     * @throws If this method is called in a browser environment (client-side).
+     *
+     * @example
+     * ```typescript
+     * // On server:
+     * const stopAuth = await auth.initFromSuiKeystore({
+     *   walletAddress: "0x<address>",
+     *   path: "/custom/path/to/keystore.json",
+     * });
+     * // authorized calls...
+     * stopAuth();
+     * ```
+     */
     // public async initFromSuiKeystore(inputs: {
     // 	walletAddress: SuiAddress;
     // 	path?: string;
     // }): Promise<() => void> {
     // 	const { walletAddress, path: pathStr } = inputs;
     // 	if (typeof window === "undefined") {
+    // 		// Node environment, proceed with reading a keystore
     // 		const fs = require("fs");
     // 		const path = require("path");
     // 		const os = require("os");
     // 		const keystorePath = pathStr
     // 			? path.join(pathStr)
     // 			: (() => {
-    // 					// Locate the user’s home directory
+    // 					// Default to ~/.sui/sui_config/sui.keystore
     // 					const homeDir = os.homedir();
     // 					if (!homeDir) {
     // 						throw new Error(
     // 							"cannot obtain home directory path"
     // 						);
     // 					}
-    // 					// Construct the path: ~/.sui/sui_config/sui.keystore
     // 					return path.join(
     // 						homeDir,
     // 						".sui",
@@ -83,7 +158,7 @@ class Auth extends caller_1.Caller {
     // 						"sui.keystore"
     // 					);
     // 			  })();
-    // 		// Read the JSON file from `keystorePath`
+    // 		// Read JSON with an array of private keys
     // 		let privateKeys: string[];
     // 		try {
     // 			const fileContent = fs.readFileSync(keystorePath, "utf-8");
@@ -99,6 +174,7 @@ class Auth extends caller_1.Caller {
     // 		if (privateKeys.length <= 0) {
     // 			throw new Error(`Empty keystore file`);
     // 		}
+    // 		// Find the matching key for the requested walletAddress
     // 		const foundKeypair = privateKeys
     // 			.map((privateKey) => Helpers.keypairFromPrivateKey(privateKey))
     // 			.find(
@@ -112,6 +188,7 @@ class Auth extends caller_1.Caller {
     // 				`No private key found in keystore file for ${walletAddress}`
     // 			);
     // 		}
+    // 		// Initialize with sign callback
     // 		return this.init({
     // 			walletAddress,
     // 			signMessageCallback: async ({ message }) =>
@@ -123,10 +200,24 @@ class Auth extends caller_1.Caller {
     // =========================================================================
     //  Admin
     // =========================================================================
-    // NOTE: admin only (should add docs)
+    /**
+     * **Admin-only**: Creates a new auth account with specific rate limits for a given
+     * `accountWalletAddress`. The `walletAddress` performing this action must have
+     * admin privileges, or the call will fail. Use this to create custom sub-accounts
+     * with limited scope or usage rates.
+     *
+     * @param inputs - Contains:
+     *  - `walletAddress`: The admin's wallet address
+     *  - `signMessageCallback`: The admin's signing callback
+     *  - `accountName`: A short name or identifier for the account
+     *  - `accountWalletAddress`: The Sui address representing this sub-account
+     *  - `rateLimits`: An array specifying the rate limits (method-based) for the sub-account
+     * @returns A promise resolving to `true` if successful, otherwise throws or returns `false`.
+     */
     adminCreateAuthAccount(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             const { walletAddress, signMessageCallback, accountName, accountWalletAddress, rateLimits, } = inputs;
+            // Prepare the data to sign
             const serializedJson = Auth.createSerializedJson("AccountCreate", {
                 sub: accountName,
                 wallet_address: utils_1.Helpers.addLeadingZeroesToType(accountWalletAddress),
@@ -144,9 +235,17 @@ class Auth extends caller_1.Caller {
     // =========================================================================
     //  Private
     // =========================================================================
+    /**
+     * Requests a new access token from the API by sending a signed message
+     * indicating the user wants a token.
+     *
+     * @param inputs - Contains the user's `walletAddress` and `signMessageCallback`.
+     * @returns A response object that includes the `accessToken` and an `expirationTimestamp`.
+     */
     getAccessToken(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             const { walletAddress, signMessageCallback } = inputs;
+            // Prepare signable data
             const serializedJson = Auth.createSerializedJson("GetAccessToken", {});
             const message = new TextEncoder().encode(serializedJson);
             const { signature } = yield signMessageCallback({ message });
@@ -160,14 +259,29 @@ class Auth extends caller_1.Caller {
     // =========================================================================
     //  Private Static
     // =========================================================================
+    /**
+     * Creates a JSON string with a standard format:
+     * ```json
+     * {
+     *   "date": <epoch-seconds>,
+     *   "nonce": <random_number>,
+     *   "method": <method_string>,
+     *   "value": <passed_value>
+     * }
+     * ```
+     *
+     * @param method - A short method name describing the action ("GetAccessToken", "AccountCreate", etc.).
+     * @param value - The data object to embed under the `value` field.
+     * @returns A JSON-serialized string for signing.
+     */
     static createSerializedJson(method, value) {
         const timestampSeconds = Math.floor(Date.now() / 1000);
         const random = Math.floor(Math.random() * 1024 * 1024);
         const data = {
             date: timestampSeconds,
             nonce: random,
-            method: method,
-            value: value,
+            method,
+            value,
         };
         return JSON.stringify(data);
     }

package/dist/packages/auth/authTypes.d.ts

@@ -1,6 +1,23 @@
 import { SuiAddress, Timestamp } from "../../types";
+/**
+ * Interface specifying allowable rate limits for an auth account.
+ * The `p` field indicates the path or endpoint (e.g., "/pools"),
+ * while `m` indicates the method-based limits (GET or POST, or both).
+ */
 export interface RateLimit {
+    /**
+     * The path or endpoint to be rate-limited, e.g. "/pools" or "/router/trade".
+     */
     p: string;
+    /**
+     * The method-based limit specification.
+     * For example:
+     * ```
+     * { GET: { l: 100 } }
+     * { POST: { l: 50 } }
+     * { GET: { l: 100 }, POST: { l: 100 } }
+     * ```
+     */
     m: {
         GET: {
             l: number;
@@ -18,19 +35,68 @@ export interface RateLimit {
         };
     };
 }
+/**
+ * The request body for creating a new auth account, typically
+ * reserved for admin usage. The admin signs a JSON containing
+ * an "AccountCreate" `method` plus desired sub-account data.
+ */
 export interface ApiCreateAuthAccountBody {
+    /**
+     * The admin's Sui address, zero-padded if necessary.
+     */
     walletAddress: SuiAddress;
+    /**
+     * The signature of the serialized JSON data, from the admin's private key.
+     */
     signature: string;
+    /**
+     * The JSON string that was signed, containing the method and sub-account details.
+     */
     serializedJson: string;
 }
+/**
+ * The request body for obtaining or refreshing an access token. The user signs
+ * a "GetAccessToken" method message plus any relevant fields.
+ */
 export interface ApiGetAccessTokenBody {
+    /**
+     * The user's Sui address, zero-padded if needed.
+     */
     walletAddress: SuiAddress;
+    /**
+     * The signature over the JSON-serialized request data (nonce, date, etc.).
+     */
     signature: string;
+    /**
+     * The actual JSON string that was signed, e.g.:
+     * ```
+     * {
+     *   "date": 1234567890,
+     *   "nonce": 512,
+     *   "method": "GetAccessToken",
+     *   "value": {}
+     * }
+     * ```
+     */
     serializedJson: string;
 }
+/**
+ * The response returned when a user obtains or refreshes an access token,
+ * containing the token string, the HTTP header name (usually "Authorization"),
+ * and the token's expiration timestamp in milliseconds.
+ */
 export interface ApiGetAccessTokenResponse {
+    /**
+     * The newly issued access token to be used in `Authorization` headers.
+     */
     accessToken: string;
+    /**
+     * The header key that should contain `accessToken` (e.g., "Authorization").
+     */
     header: string;
+    /**
+     * The UNIX timestamp (milliseconds) after which the token is invalid.
+     */
     expirationTimestamp: Timestamp;
 }
 //# sourceMappingURL=authTypes.d.ts.map

package/dist/packages/auth/authTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authTypes.d.ts","sourceRoot":"","sources":["../../../src/packages/auth/authTypes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAUpD,MAAM,WAAW,SAAS;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EACE;QAAE,GAAG,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACtB;QAAE,IAAI,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACvB;QAAE,GAAG,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,IAAI,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CAC/C;AAMD,MAAM,WAAW,wBAAwB;IACxC,aAAa,EAAE,UAAU,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACrC,aAAa,EAAE,UAAU,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,WAAW,yBAAyB;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,SAAS,CAAC;CAC/B"}
+{"version":3,"file":"authTypes.d.ts","sourceRoot":"","sources":["../../../src/packages/auth/authTypes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACzB;;OAEG;IACH,CAAC,EAAE,MAAM,CAAC;IACV;;;;;;;;OAQG;IACH,CAAC,EACE;QAAE,GAAG,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACtB;QAAE,IAAI,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACvB;QAAE,GAAG,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,IAAI,EAAE;YAAE,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CAC/C;AAMD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACxC;;OAEG;IACH,aAAa,EAAE,UAAU,CAAC;IAC1B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACrC;;OAEG;IACH,aAAa,EAAE,UAAU,CAAC;IAC1B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;OAUG;IACH,cAAc,EAAE,MAAM,CAAC;CACvB;AAMD;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACzC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,mBAAmB,EAAE,SAAS,CAAC;CAC/B"}

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