@moveindustries/ts-sdk 5.1.4

package/src/utils/apiEndpoints.ts

@@ -0,0 +1,107 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @group Implementation
+ * @category Network
+ */
+export const NetworkToIndexerAPI: Record<string, string> = {
+  mainnet: "https://indexer.mainnet.movementnetwork.xyz/v1/graphql",
+  testnet: "https://indexer.testnet.movementnetwork.xyz/v1/graphql",
+  devnet: "https://indexer.devnet.movementnetwork.xyz/v1/graphql",
+  shelbynet: "https://api.shelbynet.shelby.xyz/v1/graphql",
+  netna: "https://api.netna.staging.aptoslabs.com/v1/graphql",
+  local: "http://127.0.0.1:8090/v1/graphql",
+};
+
+/**
+ * @group Implementation
+ * @category Network
+ */
+export const NetworkToNodeAPI: Record<string, string> = {
+  mainnet: "https://mainnet.movementnetwork.xyz/v1",
+  testnet: "https://testnet.movementnetwork.xyz/v1",
+  devnet: "https://devnet.movementnetwork.xyz/v1",
+  shelbynet: "https://api.shelbynet.shelby.xyz/v1",
+  netna: "https://api.netna.staging.aptoslabs.com/v1",
+  local: "http://127.0.0.1:8080/v1",
+};
+
+/**
+ * @group Implementation
+ * @category Network
+ */
+export const NetworkToFaucetAPI: Record<string, string> = {
+  testnet: "https://faucet.testnet.movementnetwork.xyz",
+  devnet: "https://faucet.devnet.movementnetwork.xyz",
+  shelbynet: "https://faucet.shelbynet.shelby.xyz",
+  netna: "https://faucet-dev-netna-us-central1-410192433417.us-central1.run.app",
+  local: "http://127.0.0.1:8081",
+};
+
+/**
+ * @group Implementation
+ * @category Network
+ */
+export const NetworkToPepperAPI: Record<string, string> = {
+  mainnet: "https://api.mainnet.aptoslabs.com/keyless/pepper/v0",
+  testnet: "https://api.testnet.aptoslabs.com/keyless/pepper/v0",
+  devnet: "https://api.devnet.aptoslabs.com/keyless/pepper/v0",
+  shelbynet: "https://api.shelbynet.aptoslabs.com/keyless/pepper/v0",
+  netna: "https://api.devnet.aptoslabs.com/keyless/pepper/v0",
+  // Use the devnet service for local environment
+  local: "https://api.devnet.aptoslabs.com/keyless/pepper/v0",
+};
+
+/**
+ * @group Implementation
+ * @category Network
+ */
+export const NetworkToProverAPI: Record<string, string> = {
+  mainnet: "https://api.mainnet.aptoslabs.com/keyless/prover/v0",
+  testnet: "https://api.testnet.aptoslabs.com/keyless/prover/v0",
+  devnet: "https://api.devnet.aptoslabs.com/keyless/prover/v0",
+  shelbynet: "https://api.shelbynet.aptoslabs.com/keyless/prover/v0",
+  netna: "https://api.devnet.aptoslabs.com/keyless/prover/v0",
+  // Use the devnet service for local environment
+  local: "https://api.devnet.aptoslabs.com/keyless/prover/v0",
+};
+
+/**
+ * Different network environments for connecting to services, ranging from production to development setups.
+ * @group Implementation
+ * @category Network
+ */
+export enum Network {
+  MAINNET = "mainnet",
+  TESTNET = "testnet",
+  DEVNET = "devnet",
+  SHELBYNET = "shelbynet",
+  NETNA = "netna",
+  LOCAL = "local",
+  CUSTOM = "custom",
+}
+
+/**
+ * @group Implementation
+ * @category Network
+ */
+export const NetworkToChainId: Record<string, number> = {
+  mainnet: 126,
+  testnet: 250,
+  local: 4,
+};
+
+/**
+ * @group Implementation
+ * @category Network
+ */
+export const NetworkToNetworkName: Record<string, Network> = {
+  mainnet: Network.MAINNET,
+  testnet: Network.TESTNET,
+  devnet: Network.DEVNET,
+  shelbynet: Network.SHELBYNET,
+  netna: Network.NETNA,
+  local: Network.LOCAL,
+  custom: Network.CUSTOM,
+};

package/src/utils/const.ts

@@ -0,0 +1,100 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Types of API endpoints used for routing requests in the Movement network.
+ * @group Implementation
+ * @category Utils
+ */
+export enum MovementApiType {
+  FULLNODE = "Fullnode",
+  INDEXER = "Indexer",
+  FAUCET = "Faucet",
+  PEPPER = "Pepper",
+  PROVER = "Prover",
+}
+
+/**
+ * The default max gas amount when none is given.
+ *
+ * This is the maximum number of gas units that will be used by a transaction before being rejected.
+ *
+ * Note that max gas amount varies based on the transaction.  A larger transaction will go over this
+ * default gas amount, and the value will need to be changed for the specific transaction.
+ * @group Implementation
+ * @category Utils
+ */
+export const DEFAULT_MAX_GAS_AMOUNT = 200000;
+
+/**
+ * The default transaction expiration seconds from now.
+ *
+ * This time is how long until the blockchain nodes will reject the transaction.
+ *
+ * Note that the transaction expiration time varies based on network connection and network load.  It may need to be
+ * increased for the transaction to be processed.
+ * @group Implementation
+ * @category Utils
+ */
+export const DEFAULT_TXN_EXP_SEC_FROM_NOW = 20;
+
+/**
+ * The default number of seconds to wait for a transaction to be processed.
+ *
+ * This time is the amount of time that the SDK will wait for a transaction to be processed when waiting for
+ * the results of the transaction.  It may take longer based on network connection and network load.
+ * @group Implementation
+ * @category Utils
+ */
+export const DEFAULT_TXN_TIMEOUT_SEC = 20;
+
+/**
+ * The default gas currency for the network.
+ * @group Implementation
+ * @category Utils
+ */
+export const MOVEMENT_COIN = "0x1::aptos_coin::AptosCoin";
+/**
+ * @group Implementation
+ * @category Utils
+ */
+export const MOVEMENT_FA = "0x000000000000000000000000000000000000000000000000000000000000000a";
+/**
+ * @group Implementation
+ * @category Utils
+ */
+export const RAW_TRANSACTION_SALT = "APTOS::RawTransaction";
+/**
+ * @group Implementation
+ * @category Utils
+ */
+export const RAW_TRANSACTION_WITH_DATA_SALT = "APTOS::RawTransactionWithData";
+
+export const ACCOUNT_ABSTRACTION_SIGNING_DATA_SALT = "APTOS::AASigningData";
+
+/**
+ * Supported processor types for the indexer API, sourced from the processor_status table in the indexer database.
+ * {@link https://cloud.hasura.io/public/graphiql?endpoint=https://mainnet.movementnetwork.xyz/v1/graphql}
+ * @group Implementation
+ * @category Utils
+ */
+export enum ProcessorType {
+  ACCOUNT_RESTORATION_PROCESSOR = "account_restoration_processor",
+  ACCOUNT_TRANSACTION_PROCESSOR = "account_transactions_processor",
+  DEFAULT = "default_processor",
+  EVENTS_PROCESSOR = "events_processor",
+  // Fungible asset processor also handles coins
+  FUNGIBLE_ASSET_PROCESSOR = "fungible_asset_processor",
+  STAKE_PROCESSOR = "stake_processor",
+  // Token V2 processor replaces Token processor (not only for digital assets)
+  TOKEN_V2_PROCESSOR = "token_v2_processor",
+  USER_TRANSACTION_PROCESSOR = "user_transaction_processor",
+  OBJECT_PROCESSOR = "objects_processor",
+}
+
+/**
+ * Regular expression pattern for Firebase Auth issuer URLs
+ * Matches URLs in the format: https://securetoken.google.com/[project-id]
+ * where project-id can contain letters, numbers, hyphens, and underscores
+ */
+export const FIREBASE_AUTH_ISS_PATTERN = /^https:\/\/securetoken\.google\.com\/[a-zA-Z0-9-_]+$/;

package/src/utils/helpers.ts

@@ -0,0 +1,287 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+import { decode } from "js-base64";
+import { createObjectAddress } from "../core/account/utils/address";
+import { AccountAddress } from "../core/accountAddress";
+import { MoveFunctionId, MoveStructId } from "../types";
+
+/**
+ * Sleep for the specified amount of time in milliseconds.
+ * This function can be used to introduce delays in asynchronous operations.
+ *
+ * @param timeMs - The time in milliseconds to sleep.
+ * @group Implementation
+ * @category Utils
+ */
+export async function sleep(timeMs: number): Promise<null> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, timeMs);
+  });
+}
+
+/**
+ * Get the error message from an unknown error.
+ *
+ * @param error The error to get the message from
+ * @returns The error message
+ * @group Implementation
+ * @category Utils
+ */
+export function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * @group Implementation
+ * @category Utils
+ */
+export const nowInSeconds = () => Math.floor(Date.now() / 1000);
+
+/**
+ * Floors the given timestamp to the nearest whole hour.
+ * This function is useful for normalizing timestamps to hourly intervals.
+ *
+ * @param timestampInSeconds - The timestamp in seconds to be floored.
+ * @group Implementation
+ * @category Utils
+ */
+export function floorToWholeHour(timestampInSeconds: number): number {
+  const date = new Date(timestampInSeconds * 1000);
+  // Reset minutes and seconds to zero
+  date.setMinutes(0);
+  date.setSeconds(0);
+  date.setMilliseconds(0);
+  return Math.floor(date.getTime() / 1000);
+}
+
+/**
+ * Decodes a base64 URL-encoded string into its original form.
+ * This function is useful for converting base64 URL-encoded data back to a readable format.
+ *
+ * @param base64Url - The base64 URL-encoded string to decode.
+ * @returns The decoded string.
+ * @group Implementation
+ * @category Utils
+ */
+export function base64UrlDecode(base64Url: string): string {
+  // Replace base64url-specific characters
+  const base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+  // Pad the string with '=' characters if needed
+  const paddedBase64 = base64 + "==".substring(0, (3 - (base64.length % 3)) % 3);
+  const decodedString = decode(paddedBase64);
+  return decodedString;
+}
+
+export function base64UrlToBytes(base64Url: string): Uint8Array {
+  // Convert Base64Url to Base64
+  let base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+  // Add padding if needed
+  while (base64.length % 4 !== 0) {
+    base64 += "=";
+  }
+  // Use Buffer to convert base64 to Uint8Array
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}
+
+/**
+ * Amount is represented in the smallest unit format on chain, this function converts
+ * a human-readable amount format to the smallest unit format
+ * @example
+ * human-readable amount format: 500
+ * on chain amount format when decimal is 8: 50000000000
+ *
+ * @param value The value in human-readable format
+ * @param decimal The token decimal
+ * @returns The value in the smallest units
+ * @group Implementation
+ * @category Utils
+ */
+export const convertAmountFromHumanReadableToOnChain = (value: number, decimal: number) => value * 10 ** decimal;
+
+/**
+ * Amount is represented in the smallest unit format on chain, this function converts
+ * the smallest unit format to a human-readable amount format
+ * @example
+ * human-readable amount format: 500
+ * on chain amount format when decimal is 8: 50000000000
+ *
+ * @param value The value in human-readable format
+ * @param decimal The token decimal
+ * @returns The value in the smallest units
+ * @group Implementation
+ * @category Utils
+ */
+export const convertAmountFromOnChainToHumanReadable = (value: number, decimal: number) => value / 10 ** decimal;
+
+/**
+ * Convert a hex string to an ascii string with the `0x` prefix.
+ *
+ * `0x6170746f735f636f696e` --> `aptos_coin`
+ *
+ * @param hex The hex string to convert (e.g. `0x6170746f735f636f696e`)
+ * @returns The ascii string
+ * @group Implementation
+ * @category Utils
+ */
+const hexToAscii = (hex: string) => {
+  let str = "";
+  for (let n = 2; n < hex.length; n += 2) {
+    str += String.fromCharCode(parseInt(hex.substring(n, n + 2), 16));
+  }
+  return str;
+};
+
+/**
+ * Convert an encoded struct to a MoveStructId.
+ *
+ * @example
+ * const structObj = {
+ *   account_address: "0x1",
+ *   module_name: "0x6170746f735f636f696e",
+ *   struct_name: "0x4170746f73436f696e",
+ * };
+ * // structId is "0x1::aptos_coin::AptosCoin"
+ * const structId = parseEncodedStruct(structObj);
+ *
+ * @param structObj The struct with account_address, module_name, and struct_name properties
+ * @returns The MoveStructId
+ * @group Implementation
+ * @category Utils
+ */
+export const parseEncodedStruct = (structObj: {
+  account_address: string;
+  module_name: string;
+  struct_name: string;
+}): MoveStructId => {
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  const { account_address, module_name, struct_name } = structObj;
+  const moduleName = hexToAscii(module_name);
+  const structName = hexToAscii(struct_name);
+  return `${account_address}::${moduleName}::${structName}`;
+};
+
+/**
+ * Determines whether the given object is an encoded struct type with the following properties:
+ * - account_address: string
+ * - module_name: string
+ * - struct_name: string
+ *
+ * @param structObj The object to check
+ * @returns Whether the object is an encoded struct type
+ * @group Implementation
+ * @category Utils
+ */
+export const isEncodedStruct = (
+  structObj: any,
+): structObj is {
+  account_address: string;
+  module_name: string;
+  struct_name: string;
+} =>
+  typeof structObj === "object" &&
+  !Array.isArray(structObj) &&
+  structObj !== null &&
+  "account_address" in structObj &&
+  "module_name" in structObj &&
+  "struct_name" in structObj &&
+  typeof structObj.account_address === "string" &&
+  typeof structObj.module_name === "string" &&
+  typeof structObj.struct_name === "string";
+
+/**
+ * Splits a function identifier into its constituent parts: module address, module name, and function name.
+ * This function helps in validating and extracting details from a function identifier string.
+ *
+ * @param functionArg - The function identifier string in the format "moduleAddress::moduleName::functionName".
+ * @returns An object containing the module address, module name, and function name.
+ * @throws Error if the function identifier does not contain exactly three parts.
+ * @group Implementation
+ * @category Transactions
+ */
+export function getFunctionParts(functionArg: MoveFunctionId) {
+  const funcNameParts = functionArg.split("::");
+  if (funcNameParts.length !== 3) {
+    throw new Error(`Invalid function ${functionArg}`);
+  }
+  const moduleAddress = funcNameParts[0];
+  const moduleName = funcNameParts[1];
+  const functionName = funcNameParts[2];
+  return { moduleAddress, moduleName, functionName };
+}
+
+/**
+ * Validates the provided function information.
+ *
+ * @param functionInfo - The function information to validate.
+ * @returns Whether the function information is valid.
+ * @group Implementation
+ * @category Utils
+ */
+export function isValidFunctionInfo(functionInfo: string): boolean {
+  const parts = functionInfo.split("::");
+  return parts.length === 3 && AccountAddress.isValid({ input: parts[0] }).valid;
+}
+
+/**
+ * Truncates the provided wallet address at the middle with an ellipsis.
+ *
+ * @param address - The wallet address to truncate.
+ * @param start - The number of characters to show at the beginning of the address.
+ * @param end - The number of characters to show at the end of the address.
+ * @returns The truncated address.
+ * @group Implementation
+ * @category Utils
+ */
+export function truncateAddress(address: string, start: number = 6, end: number = 5) {
+  return `${address.slice(0, start)}...${address.slice(-end)}`;
+}
+
+/**
+ * Constants for metadata address calculation
+ */
+const MOVE_COIN_TYPE_STR = "0x1::aptos_coin::AptosCoin";
+const MOVE_METADATA_ADDRESS_HEX = AccountAddress.A.toStringLong();
+
+/**
+ * Helper function to standardize Move type string by converting all addresses to short form,
+ * including addresses within nested type parameters
+ */
+function standardizeMoveTypeString(input: string): string {
+  // Regular expression to match addresses in the type string, including those within type parameters
+  // This regex matches "0x" followed by hex digits, handling both standalone addresses and those within <>
+  const addressRegex = /0x[0-9a-fA-F]+/g;
+
+  return input.replace(addressRegex, (match) => {
+    // Use AccountAddress to handle the address
+    return AccountAddress.from(match, { maxMissingChars: 63 }).toStringShort();
+  });
+}
+
+/**
+ * Calculates the paired FA metadata address for a given coin type.
+ * This function is tolerant of various address formats in the coin type string,
+ * including complex nested types.
+ *
+ * @example
+ * // All these formats are valid and will produce the same result:
+ * pairedFaMetadataAddress("0x1::aptos_coin::AptosCoin")  // simple form
+ * pairedFaMetadataAddress("0x0000000000000000000000000000000000000000000000000000000000000001::aptos_coin::AptosCoin")  // long form
+ * pairedFaMetadataAddress("0x00001::aptos_coin::AptosCoin")  // with leading zeros
+ * pairedFaMetadataAddress("0x1::coin::Coin<0x1412::a::struct<0x0001::aptos_coin::AptosCoin>>")  // nested type parameters
+ *
+ * @param coinType - The coin type string in any of these formats:
+ *   - Short form address: "0x1::aptos_coin::AptosCoin"
+ *   - Long form address: "0x0000000000000000000000000000000000000000000000000000000000000001::aptos_coin::AptosCoin"
+ *   - With leading zeros: "0x00001::aptos_coin::AptosCoin"
+ *   - With nested types: "0x1::coin::Coin<0x1412::a::struct<0x0001::aptos_coin::AptosCoin>>"
+ * @returns The calculated metadata address as an AccountAddress instance
+ */
+export function pairedFaMetadataAddress(coinType: `0x${string}::${string}::${string}`): AccountAddress {
+  // Standardize the coin type string to handle any address format
+  const standardizedMoveTypeName = standardizeMoveTypeString(coinType);
+
+  return standardizedMoveTypeName === MOVE_COIN_TYPE_STR
+    ? AccountAddress.A
+    : createObjectAddress(AccountAddress.A, standardizedMoveTypeName);
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from "./apiEndpoints";
+export * from "./const";
+export * from "./normalizeBundle";
+export * from "./helpers";

package/src/utils/memoize.ts

@@ -0,0 +1,76 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * The global cache Map shared across all functions.  Must keep care to ensure that the
+ * cache keys are unique across all functions.
+ * @group Implementation
+ * @category Utils
+ */
+const cache = new Map<string, { value: any; timestamp: number }>();
+
+/**
+ * A memoize higher-order function to cache the response of an async function.
+ * This function helps to improve performance by avoiding repeated calls to the same async function with the same arguments
+ * within a specified time-to-live (TTL).
+ *
+ * @param func The async function to cache the result of.
+ * @param key The cache key used to store the result.
+ * @param ttlMs The time-to-live in milliseconds for cached data.
+ * @returns The cached or latest result.
+ * @group Implementation
+ * @category Utils
+ */
+export function memoizeAsync<T>(
+  func: (...args: any[]) => Promise<T>,
+  key: string,
+  ttlMs?: number,
+): (...args: any[]) => Promise<T> {
+  return async (...args: any[]) => {
+    // Check if the cached result exists and is within TTL
+    if (cache.has(key)) {
+      const { value, timestamp } = cache.get(key)!;
+      if (ttlMs === undefined || Date.now() - timestamp <= ttlMs) {
+        return value;
+      }
+    }
+
+    // If not cached or TTL expired, compute the result
+    const result = await func(...args);
+
+    // Cache the result with a timestamp
+    cache.set(key, { value: result, timestamp: Date.now() });
+
+    return result;
+  };
+}
+
+/**
+ * Caches the result of a function call to improve performance on subsequent calls with the same arguments.
+ *
+ * @param key - The key to cache on, all accesses by this key will return the cached value.
+ * @param func - The function whose result will be cached.
+ * @param ttlMs - The time-to-live in milliseconds for cached data.
+ * @returns A memoized version of the provided function that returns the cached result if available and within TTL.
+ * @group Implementation
+ * @category Utils
+ */
+export function memoize<T>(func: (...args: any[]) => T, key: string, ttlMs?: number): (...args: any[]) => T {
+  return (...args: any[]) => {
+    // Check if the cached result exists and is within TTL
+    if (cache.has(key)) {
+      const { value, timestamp } = cache.get(key)!;
+      if (ttlMs === undefined || Date.now() - timestamp <= ttlMs) {
+        return value;
+      }
+    }
+
+    // If not cached or TTL expired, compute the result
+    const result = func(...args);
+
+    // Cache the result with a timestamp
+    cache.set(key, { value: result, timestamp: Date.now() });
+
+    return result;
+  };
+}

package/src/utils/normalizeBundle.ts

@@ -0,0 +1,34 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+import { Deserializer, Serializable } from "../bcs";
+/**
+ * @group Implementation
+ * @category Utils
+ */
+export type DeserializableClass<T extends Serializable> = {
+  /**
+   * Deserializes a serialized object using the provided deserializer.
+   * This function allows you to reconstruct an object from its serialized form.
+   *
+   * @param deserializer - An instance of the Deserializer used to read the serialized data.
+   * @group Implementation
+   * @category Utils
+   */
+  deserialize(deserializer: Deserializer): T;
+};
+
+/**
+ * Normalizes an instance of a class by deserializing it from its byte representation.
+ * This function allows the `instanceof` operator to work correctly when the input objects originate from a different bundle.
+ *
+ * @param cls - The class of the object to normalize.
+ * @param value - The instance to normalize.
+ * @group Implementation
+ * @category Utils
+ */
+export function normalizeBundle<T extends Serializable>(cls: DeserializableClass<T>, value: T) {
+  const serializedBytes = value.bcsToBytes();
+  const deserializer = new Deserializer(serializedBytes);
+  return cls.deserialize(deserializer);
+}

package/src/version.ts

@@ -0,0 +1,9 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * The current version of the SDK
+ *
+ * hardcoded for now, we would want to have it injected dynamically
+ */
+export const VERSION = "5.1.4";