@aptos-labs/ts-sdk 1.29.1 → 1.30.0

package/src/transactions/management/accountSequenceNumber.ts

@@ -28,12 +28,24 @@ import { Account } from "../../account";
 import { getInfo } from "../../internal/account";
 import { nowInSeconds, sleep } from "../../utils/helpers";
 
+/**
+ * Represents an account's sequence number management for transaction handling on the Aptos blockchain.
+ * This class provides methods to retrieve the next available sequence number, synchronize with the on-chain sequence number,
+ * and manage local sequence numbers while ensuring thread safety.
+ *
+ * @param aptosConfig - The configuration settings for Aptos.
+ * @param account - The account associated with the sequence number.
+ * @param maxWaitTime - The maximum time to wait for a transaction to commit.
+ * @param maximumInFlight - The maximum number of transactions that can be in flight at once.
+ * @param sleepTime - The time to wait before retrying to get the sequence number.
+ */
 export class AccountSequenceNumber {
   readonly aptosConfig: AptosConfig;
 
   readonly account: Account;
 
   // sequence number on chain
+  // TODO: Change to Uncommitted
   lastUncommintedNumber: bigint | null = null;
 
   // local sequence number
@@ -46,7 +58,7 @@ export class AccountSequenceNumber {
    * which can result in race conditions and data inconsistency.
    * This code actually doesn't do it though, since we aren't giving out a slot, it is still somewhat a race condition.
    *
-   * The ideal solution is likely that each thread grabs the next number from a incremental integer.
+   * The ideal solution is likely that each thread grabs the next number from an incremental integer.
    * When they complete, they increment that number and that entity is able to enter the `lock`.
    * That would guarantee ordering.
    */
@@ -58,6 +70,16 @@ export class AccountSequenceNumber {
 
   sleepTime: number;
 
+  /**
+   * Creates an instance of the class with the specified configuration and account details.
+   * This constructor initializes the necessary parameters for managing Aptos transactions.
+   *
+   * @param aptosConfig - The configuration settings for Aptos.
+   * @param account - The account associated with the Aptos transactions.
+   * @param maxWaitTime - The maximum time to wait for a transaction to be processed, in milliseconds.
+   * @param maximumInFlight - The maximum number of transactions that can be in flight at the same time.
+   * @param sleepTime - The time to sleep between transaction checks, in milliseconds.
+   */
   constructor(
     aptosConfig: AptosConfig,
     account: Account,
@@ -73,9 +95,10 @@ export class AccountSequenceNumber {
   }
 
   /**
-   * Returns the next available sequence number for this account
+   * Returns the next available sequence number for this account.
+   * This function ensures that the sequence number is updated and synchronized, handling potential delays in transaction commits.
    *
-   * @returns next available sequence number
+   * @returns {BigInt} The next available sequence number.
    */
   async nextSequenceNumber(): Promise<bigint | null> {
     /* eslint-disable no-await-in-loop */
@@ -99,7 +122,7 @@ export class AccountSequenceNumber {
           if (nowInSeconds() - startTime > this.maxWaitTime) {
             /* eslint-disable no-console */
             console.warn(
-              `Waited over 30 seconds for a transaction to commit, resyncing ${this.account.accountAddress.toString()}`,
+              `Waited over 30 seconds for a transaction to commit, re-syncing ${this.account.accountAddress.toString()}`,
             );
             await this.initialize();
           } else {
@@ -118,7 +141,11 @@ export class AccountSequenceNumber {
   }
 
   /**
-   * Initializes this account with the sequence number on chain
+   * Initializes this account with the sequence number on chain.
+   *
+   * @returns {Promise<void>} A promise that resolves when the account has been initialized.
+   *
+   * @throws {Error} Throws an error if the account information cannot be retrieved.
    */
   async initialize(): Promise<void> {
     const { sequence_number: sequenceNumber } = await getInfo({
@@ -130,9 +157,9 @@ export class AccountSequenceNumber {
   }
 
   /**
-   * Updates this account sequence number with the one on-chain
+   * Updates this account's sequence number with the one on-chain.
    *
-   * @returns on-chain sequence number for this account
+   * @returns The on-chain sequence number for this account.
    */
   async update(): Promise<bigint> {
     const { sequence_number: sequenceNumber } = await getInfo({
@@ -144,10 +171,10 @@ export class AccountSequenceNumber {
   }
 
   /**
-   * Synchronizes local sequence number with the seqeunce number on chain for this account.
+   * Synchronizes the local sequence number with the sequence number on-chain for the specified account.
+   * This function polls the network until all submitted transactions have either been committed or until the maximum wait time has elapsed.
    *
-   * Poll the network until all submitted transactions have either been committed or until
-   * the maximum wait time has elapsed
+   * @throws {Error} Throws an error if there is an issue synchronizing the account sequence number with the one on-chain.
    */
   async synchronize(): Promise<void> {
     if (this.lastUncommintedNumber === this.currentNumber) return;
@@ -166,7 +193,7 @@ export class AccountSequenceNumber {
         if (nowInSeconds() - startTime > this.maxWaitTime) {
           /* eslint-disable no-console */
           console.warn(
-            `Waited over 30 seconds for a transaction to commit, resyncing ${this.account.accountAddress.toString()}`,
+            `Waited over 30 seconds for a transaction to commit, re-syncing ${this.account.accountAddress.toString()}`,
           );
           await this.initialize();
         } else {

package/src/transactions/management/asyncQueue.ts

@@ -2,7 +2,7 @@
  * The AsyncQueue class is an async-aware data structure that provides a queue-like
  * behavior for managing asynchronous tasks or operations.
  * It allows to enqueue items and dequeue them asynchronously.
- * This is not thread-safe but it is async concurrency safe and
+ * This is not thread-safe, but it is async concurrency safe, and
  * it does not guarantee ordering for those that call into and await on enqueue.
  */
 
@@ -20,11 +20,10 @@ export class AsyncQueue<T> {
   private cancelled: boolean = false;
 
   /**
-   * The enqueue method adds an item to the queue. If there are pending dequeued promises,
-   * in the pendingDequeue, it resolves the oldest promise with the enqueued item immediately.
-   * Otherwise, it adds the item to the queue.
+   * Adds an item to the queue. If there are pending dequeued promises, it resolves the oldest promise with the enqueued item
+   * immediately; otherwise, it adds the item to the queue.
    *
-   * @param item T
+   * @param item - The item to be added to the queue.
    */
   enqueue(item: T): void {
     this.cancelled = false;
@@ -41,11 +40,8 @@ export class AsyncQueue<T> {
   }
 
   /**
-   * The dequeue method returns a promise that resolves to the next item in the queue.
-   * If the queue is not empty, it resolves the promise immediately with the next item.
-   * Otherwise, it creates a new promise. The promise's resolve function is stored
-   * in the pendingDequeue with a unique counter value as the key.
-   * The newly created promise is then returned, and it will be resolved later when an item is enqueued.
+   * Dequeues the next item from the queue and returns a promise that resolves to it.
+   * If the queue is empty, it creates a new promise that will be resolved when an item is enqueued.
    *
    * @returns Promise<T>
    */
@@ -60,18 +56,19 @@ export class AsyncQueue<T> {
   }
 
   /**
-   * The isEmpty method returns whether the queue is empty or not.
+   * Determine whether the queue is empty.
    *
-   * @returns boolean
+   * @returns boolean - Returns true if the queue has no elements, otherwise false.
    */
   isEmpty(): boolean {
     return this.queue.length === 0;
   }
 
   /**
-   * The cancel method cancels all pending promises in the queue.
-   * It rejects the promises with a AsyncQueueCancelledError error,
-   * ensuring that any awaiting code can handle the cancellation appropriately.
+   * Cancels all pending promises in the queue and rejects them with an AsyncQueueCancelledError.
+   * This ensures that any awaiting code can handle the cancellation appropriately.
+   *
+   * @returns {void}
    */
   cancel(): void {
     this.cancelled = true;
@@ -86,22 +83,28 @@ export class AsyncQueue<T> {
   }
 
   /**
-   * The isCancelled method returns whether the queue is cancelled or not.
+   * Determine whether the queue has been cancelled.
    *
-   * @returns boolean
+   * @returns boolean - Returns true if the queue is cancelled, otherwise false.
    */
   isCancelled(): boolean {
     return this.cancelled;
   }
 
   /**
-   * The pendingDequeueLength method returns the length of the pendingDequeue.
+   * Retrieve the length of the pending dequeue.
    *
-   * @returns number
+   * @returns number - The number of items currently in the pending dequeue.
    */
   pendingDequeueLength(): number {
     return this.pendingDequeue.length;
   }
 }
 
+/**
+ * Represents an error that occurs when an asynchronous queue operation is cancelled.
+ * This error extends the built-in Error class to provide additional context for cancellation events.
+ *
+ * @extends Error
+ */
 export class AsyncQueueCancelledError extends Error {}

package/src/transactions/management/transactionWorker.ts

@@ -13,8 +13,9 @@ import { SimpleTransaction } from "../instances/simpleTransaction";
 
 export const promiseFulfilledStatus = "fulfilled";
 
-// Event types the worker fires during execution and
-// the dapp can listen to
+/**
+ * Events emitted by the transaction worker during its operation, allowing the dapp to respond to various transaction states.
+ */
 export enum TransactionWorkerEventsEnum {
   // fired after a transaction gets sent to the chain
   TransactionSent = "transactionSent",
@@ -28,7 +29,14 @@ export enum TransactionWorkerEventsEnum {
   ExecutionFinish = "executionFinish",
 }
 
-// Typed interface of the worker events
+/**
+ * Defines the events emitted by the transaction worker during various stages of transaction processing. *
+ * @event transactionSent - Emitted when a transaction is successfully sent.
+ * @event transactionSendFailed - Emitted when sending a transaction fails.
+ * @event transactionExecuted - Emitted when a transaction is successfully executed.
+ * @event transactionExecutionFailed - Emitted when executing a transaction fails.
+ * @event executionFinish - Emitted when the execution process is finished.
+ */
 export interface TransactionWorkerEvents {
   transactionSent: (data: SuccessEventData) => void;
   transactionSendFailed: (data: FailureEventData) => void;
@@ -37,18 +45,24 @@ export interface TransactionWorkerEvents {
   executionFinish: (data: ExecutionFinishEventData) => void;
 }
 
-// Type for when the worker has finished its job
+/**
+ * The payload for when the worker has finished its job.
+ */
 export type ExecutionFinishEventData = {
   message: string;
 };
 
-// Type for a success event
+/**
+ * The payload for a success event.
+ */
 export type SuccessEventData = {
   message: string;
   transactionHash: string;
 };
 
-// Type for a failure event
+/**
+ * The payload for a failure event.
+ */
 export type FailureEventData = {
   message: string;
   error: string;
@@ -72,6 +86,7 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
   readonly account: Account;
 
   // current account sequence number
+  // TODO: Rename Sequnce -> Sequence
   readonly accountSequnceNumber: AccountSequenceNumber;
 
   readonly taskQueue: AsyncQueue<() => Promise<void>> = new AsyncQueue<() => Promise<void>>();
@@ -104,15 +119,15 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
   executedTransactions: Array<[string, bigint, any]> = [];
 
   /**
-   * Provides a simple framework for receiving payloads to be processed.
+   * Initializes a new instance of the class, providing a framework for receiving payloads to be processed.
    *
-   * @param aptosConfig - a config object
-   * @param sender - a sender as Account
-   * @param maxWaitTime - the max wait time to wait before resyncing the sequence number
-   * to the current on-chain state, default to 30
-   * @param maximumInFlight - submit up to `maximumInFlight` transactions per account.
-   * Mempool limits the number of transactions per account to 100, hence why we default to 100.
-   * @param sleepTime - If `maximumInFlight` are in flight, wait `sleepTime` seconds before re-evaluating, default to 10
+   * @param aptosConfig - A configuration object for Aptos.
+   * @param account - The account that will be used for sending transactions.
+   * @param maxWaitTime - The maximum wait time to wait before re-syncing the sequence number to the current on-chain state,
+   * default is 30 seconds.
+   * @param maximumInFlight - The maximum number of transactions that can be submitted per account, default is 100.
+   * @param sleepTime - The time to wait in seconds before re-evaluating if the maximum number of transactions are in flight,
+   * default is 10 seconds.
    */
   constructor(
     aptosConfig: AptosConfig,
@@ -135,10 +150,11 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
   }
 
   /**
-   * Gets the current account sequence number,
-   * generates the transaction with the account sequence number,
-   * adds the transaction to the outstanding transaction queue
-   * to be processed later.
+   * Submits the next transaction for the account by generating it with the current sequence number
+   * and adding it to the outstanding transaction queue for processing.
+   * This function continues to submit transactions until there are no more to process.
+   *
+   * @throws {Error} Throws an error if the transaction submission fails.
    */
   async submitNextTransaction() {
     try {
@@ -164,13 +180,15 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
   }
 
   /**
-   * Reads the outstanding transaction queue and submits the transaction to chain.
-   *
-   * If the transaction has fulfilled, it pushes the transaction to the processed
-   * transactions queue and fires a transactionsFulfilled event.
+   * Reads the outstanding transaction queue and submits the transactions to the chain.
+   * This function processes each transaction, checking their status and emitting events based on whether they were successfully
+   * sent or failed.
    *
-   * If the transaction has failed, it pushes the transaction to the processed
-   * transactions queue with the failure reason and fires a transactionsFailed event.
+   * @throws {Error} Throws an error if the process execution fails.
+   * @event TransactionWorkerEventsEnum.TransactionSent - Emitted when a transaction has been successfully committed to the chain.
+   * @event TransactionWorkerEventsEnum.TransactionSendFailed - Emitted when a transaction fails to commit, along with the error
+   * reason.
+   * @event TransactionWorkerEventsEnum.ExecutionFinish - Emitted when the execution of transactions is complete.
    */
   async processTransactions() {
     try {
@@ -226,9 +244,9 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
   }
 
   /**
-   * Once transaction has been sent to chain, we check for its execution status.
-   * @param sentTransaction transactions that were sent to chain and are now waiting to be executed
-   * @param sequenceNumber the account's sequence number that was sent with the transaction
+   * Once a transaction has been sent to the chain, this function checks for its execution status.
+   * @param sentTransaction - The transaction that was sent to the chain and is now waiting to be executed.
+   * @param sequenceNumber - The account's sequence number that was sent with the transaction.
    */
   async checkTransaction(sentTransaction: PromiseFulfilledResult<PendingTransactionResponse>, sequenceNumber: bigint) {
     try {
@@ -260,14 +278,15 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
   }
 
   /**
-   * Push transaction to the transactions queue
+   * Pushes a transaction to the transactions queue for processing.
    *
-   * @param transactionData Transaction payload
-   * @param transactionData.abi For all entry function payloads, the ABI to skip remote ABI lookups
-   * @param options.maxGasAmount Maximum gas amount for the transaction
-   * @param options.gasUnitPrice Gas unit price for the transaction
-   * @param options.expireTimestamp expiration timestamp on the transaction
-   * @param options.accountSequenceNumber the sequence number for the transaction
+   * @param transactionData - The transaction payload containing necessary details.
+   * @param transactionData.abi - For all entry function payloads, the ABI to skip remote ABI lookups.
+   * @param options - Optional parameters for transaction configuration.
+   * @param options.maxGasAmount - Maximum gas amount for the transaction.
+   * @param options.gasUnitPrice - Gas unit price for the transaction.
+   * @param options.expireTimestamp - Expiration timestamp on the transaction.
+   * @param options.accountSequenceNumber - The sequence number for the transaction.
    */
   async push(
     transactionData: InputGenerateTransactionPayloadData,
@@ -277,10 +296,11 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
   }
 
   /**
-   * Generates a signed transaction that can be submitted to chain
-   * @param account an Aptos account
-   * @param sequenceNumber a sequence number the transaction will be generated with
-   * @returns
+   * Generates a signed transaction that can be submitted to the chain.
+   *
+   * @param account - An Aptos account used as the sender of the transaction.
+   * @param sequenceNumber - A sequence number the transaction will be generated with.
+   * @returns A signed transaction object or undefined if the transaction queue is empty.
    */
   async generateNextTransaction(account: Account, sequenceNumber: bigint): Promise<SimpleTransaction | undefined> {
     if (this.transactionsQueue.isEmpty()) return undefined;
@@ -294,7 +314,9 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
   }
 
   /**
-   * Starts transaction submission and transaction processing.
+   * Starts transaction submission and processing by executing tasks from the queue until it is cancelled.
+   *
+   * @throws {Error} Throws an error if unable to start transaction batching.
    */
   async run() {
     try {
@@ -309,6 +331,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
 
   /**
    * Starts the transaction management process.
+   *
+   * @throws {Error} Throws an error if the worker has already started.
    */
   start() {
     if (this.started) {
@@ -321,7 +345,9 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
   }
 
   /**
-   * Stops the the transaction management process.
+   * Stops the transaction management process.
+   *
+   * @throws {Error} Throws an error if the worker has already stopped.
    */
   stop() {
     if (this.taskQueue.isCancelled()) {

package/src/transactions/transactionBuilder/helpers.ts

@@ -12,18 +12,45 @@ import { Bool, FixedBytes, MoveOption, MoveString, MoveVector, U128, U16, U256,
 import { AccountAddress } from "../../core";
 import { MoveFunction, MoveFunctionId } from "../../types";
 
+/**
+ * Determines if the provided argument is of type boolean.
+ * This can help in validating input types before processing them further.
+ *
+ * @param arg - The argument to check, which can be of various types.
+ * @returns A boolean indicating whether the argument is a boolean.
+ */
 export function isBool(arg: SimpleEntryFunctionArgumentTypes): arg is boolean {
   return typeof arg === "boolean";
 }
 
+/**
+ * Checks if the provided argument is of type string.
+ *
+ * @param arg - The value to be checked for string type.
+ * @returns A boolean indicating whether the argument is a string.
+ */
 export function isString(arg: any): arg is string {
   return typeof arg === "string";
 }
 
+/**
+ * Determines if the provided argument is of type number.
+ *
+ * @param arg - The argument to check, which can be of various types.
+ * @returns A boolean indicating whether the argument is a number.
+ */
 export function isNumber(arg: SimpleEntryFunctionArgumentTypes): arg is number {
   return typeof arg === "number";
 }
 
+/**
+ * Converts a number or a string representation of a number into a number type.
+ * This function is useful for ensuring that the input is in a consistent numeric format,
+ * which can help prevent type mismatches in further processing.
+ *
+ * @param arg - The input value to be converted. This can be a number, a string representing a number, or any other type.
+ * @returns Returns the converted number if the input is valid; otherwise, it returns undefined.
+ */
 export function convertNumber(arg: SimpleEntryFunctionArgumentTypes): number | undefined {
   if (isNumber(arg)) {
     return arg;
@@ -35,27 +62,101 @@ export function convertNumber(arg: SimpleEntryFunctionArgumentTypes): number | u
   return undefined;
 }
 
+/**
+ * Determines if the provided argument is a large number, which can be a number, bigint, or string representation of a number.
+ *
+ * @param arg - The argument to check, which can be of type number, bigint, or string.
+ */
 export function isLargeNumber(arg: SimpleEntryFunctionArgumentTypes): arg is number | bigint | string {
   return typeof arg === "number" || typeof arg === "bigint" || typeof arg === "string";
 }
 
+/**
+ * Checks if the provided argument is empty, meaning it is either null or undefined.
+ *
+ * @param arg - The argument to check for emptiness.
+ * @returns A boolean indicating whether the argument is empty.
+ */
 export function isEmptyOption(arg: SimpleEntryFunctionArgumentTypes): arg is null | undefined {
   return arg === null || arg === undefined;
 }
 
+/**
+ * Determines if the provided argument is a valid encoded entry function argument type.
+ * This function helps validate that the argument conforms to the expected types for entry function parameters.
+ *
+ * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+ */
 export function isEncodedEntryFunctionArgument(
   arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes,
 ): arg is EntryFunctionArgumentTypes {
   return (
+    /**
+     * Determines if the provided argument is an instance of the Bool class.
+     *
+     * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     */
     isBcsBool(arg) ||
+    /**
+     * Determines if the provided argument is an instance of U8.
+     * This function helps validate the type of the argument passed to ensure it is a U8 type.
+     *
+     * @param arg - The argument to be checked, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     */
     isBcsU8(arg) ||
+    /**
+     * Determines if the provided argument is an instance of U16.
+     *
+     * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     */
     isBcsU16(arg) ||
+    /**
+     * Determines if the provided argument is an instance of U32.
+     *
+     * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     * @returns A boolean indicating whether the argument is a U32 instance.
+     */
     isBcsU32(arg) ||
+    /**
+     * Determine if the provided argument is an instance of U64.
+     * This function helps validate that the argument conforms to the expected U64 type.
+     *
+     * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     */
     isBcsU64(arg) ||
+    /**
+     * Determines if the provided argument is an instance of U128.
+     * This function helps validate the type of the argument passed to ensure it is a U128 type.
+     *
+     * @param arg - The argument to be checked, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     */
     isBcsU128(arg) ||
+    /**
+     * Determines if the provided argument is an instance of U256.
+     *
+     * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     * @returns A boolean indicating whether the argument is a U256 instance.
+     */
     isBcsU256(arg) ||
+    /**
+     * Determines if the provided argument is an instance of AccountAddress.
+     * This function helps validate whether a given input corresponds to a valid BCS address type.
+     *
+     * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     */
     isBcsAddress(arg) ||
+    /**
+     * Determine if the provided argument is an instance of MoveString.
+     *
+     * @param arg - The argument to check, which can be of types EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     */
     isBcsString(arg) ||
+    /**
+     * Determine if the provided argument is an instance of FixedBytes.
+     * This function helps to validate the type of the argument being passed.
+     *
+     * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes.
+     */
     isBcsFixedBytes(arg) ||
     arg instanceof MoveVector ||
     arg instanceof MoveOption
@@ -104,22 +205,40 @@ export function isBcsU256(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionA
   return arg instanceof U256;
 }
 
+/**
+ * Determines if the provided argument contains script data input by checking for the presence of bytecode.
+ *
+ * @param arg - The input data to be checked, which can either be a payload with remote ABI or a standard payload.
+ * @param arg.bytecode - The bytecode of the script, present if the input is script data.
+ * @param arg.function - The function associated with the transaction, which is relevant for standard payloads.
+ * @param arg.args - The arguments for the function, applicable in the context of standard payloads.
+ */
 export function isScriptDataInput(
   arg: InputGenerateTransactionPayloadDataWithRemoteABI | InputGenerateTransactionPayloadData,
 ): arg is InputScriptData {
   return "bytecode" in arg;
 }
 
+/**
+ * Throws an error indicating a type mismatch for a specified argument position.
+ * This function helps in debugging by providing clear feedback on expected types.
+ *
+ * @param expectedType - The type that was expected for the argument.
+ * @param position - The position of the argument that caused the type mismatch.
+ */
 export function throwTypeMismatch(expectedType: string, position: number) {
   throw new Error(`Type mismatch for argument ${position}, expected '${expectedType}'`);
 }
 
 /**
- * Finds first non-signer arg.
+ * Finds the index of the first non-signer argument in the function ABI parameters.
  *
  * A function is often defined with a `signer` or `&signer` arguments at the start, which are filled in
- * by signatures, and not by the caller.
- * @param functionAbi
+ * by signatures and not by the caller. This function helps identify the position of the first argument that
+ * can be provided by the caller, allowing for easier handling of function parameters.
+ *
+ * @param functionAbi - The ABI of the function to analyze.
+ * @returns The index of the first non-signer argument, or the length of the parameters array if none are found.
  */
 export function findFirstNonSignerArg(functionAbi: MoveFunction): number {
   const index = functionAbi.params.findIndex((param) => param !== "signer" && param !== "&signer");
@@ -129,6 +248,14 @@ export function findFirstNonSignerArg(functionAbi: MoveFunction): number {
   return index;
 }
 
+/**
+ * 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.
+ */
 export function getFunctionParts(functionArg: MoveFunctionId) {
   const funcNameParts = functionArg.split("::");
   if (funcNameParts.length !== 3) {