@moveindustries/ts-sdk 5.1.4

package/src/api/faucet.ts

@@ -0,0 +1,94 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+import { AccountAddressInput } from "../core";
+import { fundAccount } from "../internal/faucet";
+import { waitForIndexer } from "../internal/transaction";
+import { UserTransactionResponse, WaitForTransactionOptions } from "../types";
+import { ProcessorType } from "../utils";
+import { MovementConfig } from "./movementConfig";
+
+/**
+ * A class to query all `Faucet` related queries on Movement.
+ * @group Faucet
+ */
+export class Faucet {
+  /**
+   * Initializes a new instance of the Movement client with the specified configuration.
+   *
+   * Note that only devnet has a publicly accessible faucet. For testnet, you must use
+   * the minting page at https://movement.dev/network/faucet.
+   *
+   * @param config - The configuration settings for the Movement client.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a configuration for the Movement client
+   *     const config = new MovementConfig({ network: Network.DEVNET }); // specify your own network if needed
+   *
+   *     // Initialize the Movement client with the configuration
+   *     const movement = new Movement(config);
+   *
+   *     console.log("Movement client initialized:", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group Faucet
+   */
+  constructor(readonly config: MovementConfig) { }
+
+  /**
+   * This function creates an account if it does not exist and mints the specified amount of coins into that account.
+   *
+   * Note that only devnet has a publicly accessible faucet. For testnet, you must use
+   * the minting page at https://movement.dev/network/faucet.
+   *
+   * @param args - The arguments for funding the account.
+   * @param args.accountAddress - The address of the account to fund.
+   * @param args.amount - The amount of tokens to fund the account with.
+   * @param args.options - Configuration options for waiting for the transaction.
+   * @returns Transaction hash of the transaction that funded the account.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.DEVNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *   // Fund an account with a specified amount of tokens
+   *   const transaction = await movement.fundAccount({
+   *     accountAddress: "0x1", // replace with your account address
+   *     amount: 100,
+   *   });
+   *
+   *   console.log("Transaction hash:", transaction.hash);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group Faucet
+   */
+  async fundAccount(args: {
+    accountAddress: AccountAddressInput;
+    amount: number;
+    options?: WaitForTransactionOptions;
+  }): Promise<UserTransactionResponse> {
+    const fundTxn = await fundAccount({ movementConfig: this.config, ...args });
+
+    // If the user explicitly says to NOT wait by setting waitForIndexer to false, then we skip this.
+    // But, by default we want to wait for the indexer.
+    if (args.options?.waitForIndexer === undefined || args.options?.waitForIndexer) {
+      await waitForIndexer({
+        movementConfig: this.config,
+        minimumLedgerVersion: BigInt(fundTxn.version),
+        processorType: ProcessorType.FUNGIBLE_ASSET_PROCESSOR,
+      });
+    }
+
+    return fundTxn;
+  }
+}

package/src/api/fungibleAsset.ts

@@ -0,0 +1,371 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+import { Account } from "../account";
+import { AccountAddress, AccountAddressInput } from "../core";
+import {
+  getCurrentFungibleAssetBalances,
+  getFungibleAssetActivities,
+  getFungibleAssetMetadata,
+  transferFungibleAsset,
+  transferFungibleAssetBetweenStores,
+} from "../internal/fungibleAsset";
+import { InputGenerateTransactionOptions } from "../transactions";
+import { SimpleTransaction } from "../transactions/instances/simpleTransaction";
+import {
+  AnyNumber,
+  GetCurrentFungibleAssetBalancesResponse,
+  GetFungibleAssetActivitiesResponse,
+  GetFungibleAssetMetadataResponse,
+  PaginationArgs,
+  WhereArg,
+} from "../types";
+import {
+  CurrentFungibleAssetBalancesBoolExp,
+  FungibleAssetActivitiesBoolExp,
+  FungibleAssetMetadataBoolExp,
+} from "../types/generated/types";
+import { ProcessorType } from "../utils/const";
+import { MovementConfig } from "./movementConfig";
+import { waitForIndexerOnVersion } from "./utils";
+
+/**
+ * A class for querying and managing fungible asset-related operations on the Movement blockchain.
+ * @group FungibleAsset
+ */
+export class FungibleAsset {
+  /**
+   * Initializes a new instance of the Movement class with the provided configuration.
+   * This allows you to interact with the Movement blockchain using the specified network settings.
+   *
+   * @param config - The configuration settings for connecting to the Movement network.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a configuration for the Movement client
+   *     const config = new MovementConfig({ network: Network.TESTNET }); // Specify your own network if needed
+   *
+   *     // Initialize the Movement client with the configuration
+   *     const movement = new Movement(config);
+   *
+   *     console.log("Movement client initialized:", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group FungibleAsset
+   */
+  constructor(readonly config: MovementConfig) { }
+
+  /**
+   * Queries all fungible asset metadata.
+   *
+   * @param args Optional parameters for the query.
+   * @param args.minimumLedgerVersion Optional ledger version to sync up to before querying.
+   * @param args.options Optional configuration for pagination and filtering.
+   *
+   * @returns A list of fungible asset metadata.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *   // Fetching fungible asset metadata
+   *   const fungibleAssets = await movement.getFungibleAssetMetadata();
+   *   console.log(fungibleAssets);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group FungibleAsset
+   */
+  async getFungibleAssetMetadata(args?: {
+    minimumLedgerVersion?: AnyNumber;
+    options?: PaginationArgs & WhereArg<FungibleAssetMetadataBoolExp>;
+  }): Promise<GetFungibleAssetMetadataResponse> {
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args?.minimumLedgerVersion,
+      processorType: ProcessorType.FUNGIBLE_ASSET_PROCESSOR,
+    });
+    return getFungibleAssetMetadata({ movementConfig: this.config, ...args });
+  }
+
+  /**
+   * Queries the fungible asset metadata for a specific asset type.
+   * This function helps retrieve detailed information about a fungible asset based on its type.
+   *
+   * @param args - The parameters for the query.
+   * @param args.assetType - The asset type of the fungible asset, e.g., "0x1::aptos_coin::AptosCoin" for Movement Coin.
+   * @param args.minimumLedgerVersion - Optional ledger version to sync up to before querying.
+   *
+   * @returns A fungible asset metadata item.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *   // Retrieve fungible asset metadata by asset type
+   *   const fungibleAsset = await movement.getFungibleAssetMetadataByAssetType({
+   *     assetType: "0x1::aptos_coin::AptosCoin" // replace with your asset type
+   *   });
+   *
+   *   console.log(fungibleAsset);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group FungibleAsset
+   */
+  async getFungibleAssetMetadataByAssetType(args: {
+    assetType: string;
+    minimumLedgerVersion?: AnyNumber;
+  }): Promise<GetFungibleAssetMetadataResponse[0]> {
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args?.minimumLedgerVersion,
+      processorType: ProcessorType.FUNGIBLE_ASSET_PROCESSOR,
+    });
+    const data = await getFungibleAssetMetadata({
+      movementConfig: this.config,
+      options: {
+        where: {
+          asset_type: { _eq: args.assetType },
+        },
+      },
+    });
+
+    return data[0];
+  }
+
+  /**
+   * Retrieves fungible asset metadata based on the creator address.
+   *
+   * This function allows you to query metadata for a specific fungible asset created by a given address.
+   *
+   * @param args - The parameters for the query.
+   * @param args.creatorAddress - The creator address of the fungible asset.
+   * @param args.minimumLedgerVersion - Optional ledger version to sync up to before querying.
+   *
+   * @returns A fungible asset metadata item.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *   // Retrieve fungible asset metadata by creator address
+   *   const fungibleAsset = await movement.getFungibleAssetMetadataByCreatorAddress({
+   *     creatorAddress: "0x123", // replace with a real creator address
+   *   });
+   *
+   *   console.log(fungibleAsset);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group FungibleAsset
+   */
+  async getFungibleAssetMetadataByCreatorAddress(args: {
+    creatorAddress: AccountAddressInput;
+    minimumLedgerVersion?: AnyNumber;
+  }): Promise<GetFungibleAssetMetadataResponse> {
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args?.minimumLedgerVersion,
+      processorType: ProcessorType.FUNGIBLE_ASSET_PROCESSOR,
+    });
+    const data = await getFungibleAssetMetadata({
+      movementConfig: this.config,
+      options: {
+        where: {
+          creator_address: { _eq: AccountAddress.from(args.creatorAddress).toStringLong() },
+        },
+      },
+    });
+
+    return data;
+  }
+
+  /**
+   * Queries all fungible asset activities and returns a list of their metadata.
+   *
+   * @param args Optional parameters for the query.
+   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying.
+   * @param args.options Optional configuration for pagination and filtering.
+   * @returns A list of fungible asset metadata.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *   // Fetching fungible asset activities
+   *   const fungibleAssetActivities = await movement.getFungibleAssetActivities();
+   *   console.log(fungibleAssetActivities);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group FungibleAsset
+   */
+  async getFungibleAssetActivities(args?: {
+    minimumLedgerVersion?: AnyNumber;
+    options?: PaginationArgs & WhereArg<FungibleAssetActivitiesBoolExp>;
+  }): Promise<GetFungibleAssetActivitiesResponse> {
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args?.minimumLedgerVersion,
+      processorType: ProcessorType.FUNGIBLE_ASSET_PROCESSOR,
+    });
+    return getFungibleAssetActivities({ movementConfig: this.config, ...args });
+  }
+
+  /**
+   * Queries all fungible asset balances.
+   *
+   * @param args Optional parameters for the query.
+   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying.
+   * @param args.options Optional configuration for pagination and filtering.
+   *
+   * @returns A list of fungible asset metadata.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *   // Fetching current fungible asset balances
+   *   const fungibleAssetBalances = await movement.getCurrentFungibleAssetBalances();
+   *
+   *   console.log(fungibleAssetBalances);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group FungibleAsset
+   */
+  async getCurrentFungibleAssetBalances(args?: {
+    minimumLedgerVersion?: AnyNumber;
+    options?: PaginationArgs & WhereArg<CurrentFungibleAssetBalancesBoolExp>;
+  }): Promise<GetCurrentFungibleAssetBalancesResponse> {
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args?.minimumLedgerVersion,
+      processorType: ProcessorType.FUNGIBLE_ASSET_PROCESSOR,
+    });
+    return getCurrentFungibleAssetBalances({ movementConfig: this.config, ...args });
+  }
+
+  /**
+   * Transfer a specified amount of fungible asset from the sender's primary store to the recipient's primary store.
+   * This method allows you to transfer any fungible asset, including fungible tokens.
+   *
+   * @param args - The arguments for the transfer operation.
+   * @param args.sender - The sender account.
+   * @param args.fungibleAssetMetadataAddress - The fungible asset account address. For example, if you're transferring USDT,
+   * this would be the USDT address.
+   * @param args.recipient - The recipient account address.
+   * @param args.amount - The number of assets to transfer.
+   * @param args.options - Optional parameters for generating the transaction.
+   *
+   * @returns A SimpleTransaction that can be simulated or submitted to the chain.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *   // Transfer fungible asset from sender to recipient
+   *   const transaction = await movement.transferFungibleAsset({
+   *     sender: Account.generate(), // replace with a real sender account
+   *     fungibleAssetMetadataAddress: "0x123", // replace with a real fungible asset address
+   *     recipient: "0x456", // replace with a real recipient account
+   *     amount: 5
+   *   });
+   *
+   *   console.log(transaction);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group FungibleAsset
+   */
+  async transferFungibleAsset(args: {
+    sender: Account;
+    fungibleAssetMetadataAddress: AccountAddressInput;
+    recipient: AccountAddressInput;
+    amount: AnyNumber;
+    options?: InputGenerateTransactionOptions;
+  }): Promise<SimpleTransaction> {
+    return transferFungibleAsset({ movementConfig: this.config, ...args });
+  }
+
+  /**
+   * Transfer a specified amount of fungible asset from the sender's any (primary or secondary) fungible store to any (primary or secondary) fungible store.
+   * This method allows you to transfer any fungible asset, including fungible tokens.
+   *
+   * @param args - The arguments for the transfer operation.
+   * @param args.sender - The sender account initiating the transfer.
+   * @param args.fromStore - The fungible store address initiating the transfer.
+   * @param args.toStore - The fungible store address receiving the asset.
+   * @param args.amount - The number of assets to transfer. Must be a positive number.
+   * @param args.options - Optional parameters for generating the transaction.
+   *
+   * @returns A SimpleTransaction that can be simulated or submitted to the chain.
+   *
+   * @throws Error if:
+   * - The sender account is invalid
+   * - The store addresses are invalid
+   * - The amount is negative or zero
+   * - The transaction fails to generate
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network, Account } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function transferAssets() {
+   *   // Transfer 100 units of the asset from senderStore to recipientStore
+   *   const transaction = await movement.transferFungibleAssetBetweenStores({
+   *     sender: Account.generate(), // replace with a real sender account
+   *     fromStore: "0x123", // replace with a real fungible store address
+   *     toStore: "0x456", // replace with a real fungible store address
+   *     amount: 100
+   *   });
+   *
+   *   console.log(transaction);
+   * }
+   *
+   * transferAssets().catch(console.error);
+   * ```
+   * @group FungibleAsset
+   */
+  async transferFungibleAssetBetweenStores(args: {
+    sender: Account;
+    fromStore: AccountAddressInput;
+    toStore: AccountAddressInput;
+    amount: AnyNumber;
+    options?: InputGenerateTransactionOptions;
+  }): Promise<SimpleTransaction> {
+    return transferFungibleAssetBetweenStores({ movementConfig: this.config, ...args });
+  }
+}