@aptos-labs/ts-sdk 1.29.0-zeta.0 → 1.29.0-zeta.2

package/src/transactions/instances/signedTransaction.ts

@@ -8,20 +8,30 @@ import { Deserializer } from "../../bcs/deserializer";
 import { Serializable, Serializer } from "../../bcs/serializer";
 import { RawTransaction } from "./rawTransaction";
 
+/**
+ * Represents a signed transaction that includes a raw transaction and an authenticator.
+ * The authenticator contains a client's public key and the signature of the raw transaction.
+ *
+ * @see {@link https://aptos.dev/integration/creating-a-signed-transaction | Creating a Signed Transaction}
+ * @param raw_txn - The raw transaction to be signed.
+ * @param authenticator - Contains a client's public key and the signature of the raw transaction.
+ * Authenticator can have three variations: single signature, multi-signature, and multi-agent.
+ * @see {@link https://github.com/aptos-labs/aptos-core/blob/main/types/src/transaction/authenticator.rs} for details.
+ */
 export class SignedTransaction extends Serializable {
   public readonly raw_txn: RawTransaction;
 
   public readonly authenticator: TransactionAuthenticator;
 
   /**
-   * A SignedTransaction consists of a raw transaction and an authenticator. The authenticator
-   * contains a client's public key and the signature of the raw transaction.
+   * Represents a signed transaction that includes a raw transaction and an authenticator.
+   * The authenticator contains a client's public key and the signature of the raw transaction,
+   * which can be of three types: single signature, multi-signature, and multi-agent.
    *
+   * @param raw_txn The raw transaction to be signed.
+   * @param authenticator Contains a client's public key and the signature of the raw transaction. The authenticator has 3
+   * flavors: single signature, multi-signature and multi-agent.
    * @see {@link https://aptos.dev/integration/creating-a-signed-transaction | Creating a Signed Transaction}
-   *
-   * @param raw_txn
-   * @param authenticator Contains a client's public key and the signature of the raw transaction.
-   * Authenticator has 3 flavors: single signature, multi-signature and multi-agent.
    * @see {@link https://github.com/aptos-labs/aptos-core/blob/main/types/src/transaction/authenticator.rs} for details.
    */
   constructor(raw_txn: RawTransaction, authenticator: TransactionAuthenticator) {
@@ -30,11 +40,23 @@ export class SignedTransaction extends Serializable {
     this.authenticator = authenticator;
   }
 
+  /**
+   * Serializes the raw transaction and its authenticator using the provided serializer.
+   * This function is essential for preparing the transaction data for transmission or storage.
+   *
+   * @param serializer - The serializer instance used to serialize the transaction and authenticator.
+   */
   serialize(serializer: Serializer): void {
     this.raw_txn.serialize(serializer);
     this.authenticator.serialize(serializer);
   }
 
+  /**
+   * Deserializes a signed transaction from the provided deserializer.
+   * This function allows you to reconstruct a SignedTransaction object from its serialized form, enabling further processing or validation.
+   *
+   * @param deserializer - The deserializer instance used to read the serialized data.
+   */
   static deserialize(deserializer: Deserializer): SignedTransaction {
     const raw_txn = RawTransaction.deserialize(deserializer);
     const authenticator = TransactionAuthenticator.deserialize(deserializer);

package/src/transactions/instances/simpleTransaction.ts

@@ -9,26 +9,29 @@ import { AccountAddress } from "../../core";
 import { RawTransaction } from "./rawTransaction";
 
 /**
- * Representation of a SimpleTransaction that can serialized and deserialized
+ * Represents a simple transaction type that can be submitted to the Aptos chain for execution.
+ *
+ * This transaction type is designed for a single signer and includes metadata such as the Raw Transaction
+ * and an optional sponsor Account Address to cover gas fees.
+ *
+ * @param rawTransaction - The Raw Transaction.
+ * @param feePayerAddress - The optional sponsor Account Address.
  */
 export class SimpleTransaction extends Serializable {
   public rawTransaction: RawTransaction;
 
   public feePayerAddress?: AccountAddress | undefined;
 
-  // We dont really need it, we add it for type checkings we do
+  // We don't really need it, we add it for type checking we do
   // throughout the SDK
   public readonly secondarySignerAddresses: undefined;
 
   /**
-   * SimpleTransaction represents a simple transaction type of a single signer that
-   * can be submitted to Aptos chain for execution.
+   * SimpleTransaction represents a transaction signed by a single account that
+   * can be submitted to the Aptos chain for execution.
    *
-   * SimpleTransaction metadata contains the Raw Transaction and an optional
-   * sponsor Account Address to pay the gas fees.
-   *
-   * @param rawTransaction The Raw Tranasaction
-   * @param feePayerAddress The sponsor Account Address
+   * @param rawTransaction The Raw Transaction.
+   * @param feePayerAddress The optional sponsor Account Address to pay the gas fees.
    */
   constructor(rawTransaction: RawTransaction, feePayerAddress?: AccountAddress) {
     super();
@@ -36,6 +39,12 @@ export class SimpleTransaction extends Serializable {
     this.feePayerAddress = feePayerAddress;
   }
 
+  /**
+   * Serializes the transaction data using the provided serializer.
+   * This function ensures that the raw transaction and fee payer address are properly serialized for further processing.
+   *
+   * @param serializer - The serializer instance used to serialize the transaction data.
+   */
   serialize(serializer: Serializer): void {
     this.rawTransaction.serialize(serializer);
 
@@ -47,11 +56,17 @@ export class SimpleTransaction extends Serializable {
     }
   }
 
+  /**
+   * Deserializes a SimpleTransaction from the given deserializer.
+   * This function helps in reconstructing a SimpleTransaction object from its serialized form.
+   *
+   * @param deserializer - The deserializer instance used to read the serialized data.
+   */
   static deserialize(deserializer: Deserializer): SimpleTransaction {
     const rawTransaction = RawTransaction.deserialize(deserializer);
-    const feepayerPresent = deserializer.deserializeBool();
+    const feePayerPresent = deserializer.deserializeBool();
     let feePayerAddress;
-    if (feepayerPresent) {
+    if (feePayerPresent) {
       feePayerAddress = AccountAddress.deserialize(deserializer);
     }
 

package/src/transactions/instances/transactionArgument.ts

@@ -6,20 +6,46 @@ import { Hex } from "../../core/hex";
 
 export interface TransactionArgument extends EntryFunctionArgument, ScriptFunctionArgument {}
 
+/**
+ * Represents an argument for entry functions, providing methods to serialize the argument
+ * to BCS-serialized bytes and convert it to different formats.
+ */
 export interface EntryFunctionArgument {
   /**
    * Serialize an argument to BCS-serialized bytes.
+   *
+   * @param serializer - The serializer instance used for serialization.
    */
   serialize(serializer: Serializer): void;
+
   /**
+   * Serialize an argument to BCS-serialized bytes.
    * Serialize an argument as a type-agnostic, fixed byte sequence. The byte sequence contains
    * the number of the following bytes followed by the BCS-serialized bytes for a typed argument.
+   *
+   * @param serializer - The serializer used to convert the argument.
    */
   serializeForEntryFunction(serializer: Serializer): void;
 
+  /**
+   * Convert the argument to BCS-serialized bytes.
+   *
+   * @returns Uint8Array representing the BCS-serialized bytes of the argument.
+   */
   bcsToBytes(): Uint8Array;
+
+  /**
+   * Converts the BCS-serialized bytes of an argument into a hexadecimal representation.
+   * This function is useful for obtaining a Hex instance that encapsulates the BCS-serialized bytes,
+   * allowing for easier manipulation and representation of the data.
+   * @returns A Hex instance containing the BCS-serialized bytes.
+   */
   bcsToHex(): Hex;
 }
+
+/**
+ * Represents an argument for script functions, providing methods to serialize and convert to bytes.
+ */
 export interface ScriptFunctionArgument {
   /**
    * Serialize an argument to BCS-serialized bytes.

package/src/transactions/instances/transactionPayload.ts

@@ -16,7 +16,12 @@ import { MoveModuleId, ScriptTransactionArgumentVariants, TransactionPayloadVari
 import { TypeTag } from "../typeTag";
 
 /**
- * Deserialize a Script Transaction Argument
+ * Deserialize a Script Transaction Argument.
+ * This function retrieves and deserializes various types of script transaction arguments based on the provided deserializer.
+ *
+ * @param deserializer - The deserializer used to read the script transaction argument.
+ * @returns The deserialized script transaction argument.
+ * @throws Error if the variant index is unknown.
  */
 export function deserializeFromScriptArgument(deserializer: Deserializer): TransactionArgument {
   // index enum variant
@@ -48,8 +53,11 @@ export function deserializeFromScriptArgument(deserializer: Deserializer): Trans
 }
 
 /**
- * Representation of the supported Transaction Payload
- * that can serialized and deserialized
+ * Represents a supported Transaction Payload that can be serialized and deserialized.
+ *
+ * This class serves as a base for different types of transaction payloads, allowing for
+ * their serialization into a format suitable for transmission and deserialization back
+ * into their original form.
  */
 export abstract class TransactionPayload extends Serializable {
   /**
@@ -60,6 +68,13 @@ export abstract class TransactionPayload extends Serializable {
   /**
    * Deserialize a Transaction Payload
    */
+
+  /**
+   * Deserializes a multisig transaction payload from the provided deserializer.
+   * This function enables the reconstruction of a MultiSigTransactionPayload object from its serialized form.
+   *
+   * @param deserializer - The deserializer instance used to read the serialized data.
+   */
   static deserialize(deserializer: Deserializer): TransactionPayload {
     // index enum variant
     const index = deserializer.deserializeUleb128AsU32();
@@ -77,21 +92,42 @@ export abstract class TransactionPayload extends Serializable {
 }
 
 /**
- * Representation of a Transaction Payload Script that can serialized and deserialized
+ * Represents a transaction payload script that can be serialized and deserialized.
+ *
+ * This class encapsulates a script that defines the logic for a transaction payload.
+ *
+ * @extends TransactionPayload
  */
 export class TransactionPayloadScript extends TransactionPayload {
   public readonly script: Script;
 
+  /**
+   * Initializes a multi-sig account transaction with the provided payload.
+   *
+   * @param script - The payload of the multi-sig transaction. This can only be an EntryFunction for now, but Script might be
+   * supported in the future.
+   */
   constructor(script: Script) {
     super();
     this.script = script;
   }
 
+  /**
+   * Serializes the transaction payload, enabling future support for multiple types of inner transaction payloads.
+   *
+   * @param serializer - The serializer instance used to serialize the transaction data.
+   */
   serialize(serializer: Serializer): void {
     serializer.serializeU32AsUleb128(TransactionPayloadVariants.Script);
     this.script.serialize(serializer);
   }
 
+  /**
+   * Loads a MultiSig transaction payload from the provided deserializer.
+   * This function helps in reconstructing a MultiSig transaction payload from its serialized form.
+   *
+   * @param deserializer - The deserializer used to read the serialized data.
+   */
   static load(deserializer: Deserializer): TransactionPayloadScript {
     const script = Script.deserialize(deserializer);
     return new TransactionPayloadScript(script);
@@ -99,7 +135,9 @@ export class TransactionPayloadScript extends TransactionPayload {
 }
 
 /**
- * Representation of a Transaction Payload Entry Function that can serialized and deserialized
+ * Represents a transaction payload entry function that can be serialized and deserialized.
+ *
+ * @extends TransactionPayload
  */
 export class TransactionPayloadEntryFunction extends TransactionPayload {
   public readonly entryFunction: EntryFunction;
@@ -121,7 +159,7 @@ export class TransactionPayloadEntryFunction extends TransactionPayload {
 }
 
 /**
- * Representation of a Transaction Payload Multi-sig that can serialized and deserialized
+ * Represents a multi-signature transaction payload that can be serialized and deserialized.
  */
 export class TransactionPayloadMultiSig extends TransactionPayload {
   public readonly multiSig: MultiSig;
@@ -143,7 +181,14 @@ export class TransactionPayloadMultiSig extends TransactionPayload {
 }
 
 /**
- * Representation of a EntryFunction that can serialized and deserialized
+ * Represents an entry function that can be serialized and deserialized.
+ * This class encapsulates the details required to invoke a function within a module,
+ * including the module name, function name, type arguments, and function arguments.
+ *
+ * @param module_name - Fully qualified module name in the format "account_address::module_name" (e.g., "0x1::coin").
+ * @param function_name - The name of the function (e.g., "transfer").
+ * @param type_args - Type arguments required by the Move function.
+ * @param args - Arguments to the Move function.
  */
 export class EntryFunction {
   public readonly module_name: ModuleId;
@@ -186,24 +231,24 @@ export class EntryFunction {
   }
 
   /**
-   * A helper function to build a EntryFunction payload from raw primitive values
+   * Build an EntryFunction payload from raw primitive values.
    *
-   * @param module_id Fully qualified module name in format "AccountAddress::module_id" e.g. "0x1::coin"
-   * @param function_name Function name
-   * @param type_args Type arguments that move function requires.
+   * @param module_id - Fully qualified module name in the format "AccountAddress::module_id", e.g., "0x1::coin".
+   * @param function_name - The name of the function to be called.
+   * @param type_args - Type arguments that the Move function requires.
+   * @param args - Arguments to the Move function.
    *
    * @example
    * A coin transfer function has one type argument "CoinType".
    * ```
-   * public(script) fun transfer<CoinType>(from: &signer, to: address, amount: u64,)
+   * public(script) fun transfer<CoinType>(from: &signer, to: address, amount: u64)
    * ```
-   * @param args Arguments to the move function.
    *
-   * @example
-   * A coin transfer function has three arguments "from", "to" and "amount".
+   * A coin transfer function has three arguments "from", "to", and "amount".
    * ```
-   * public(script) fun transfer<CoinType>(from: &signer, to: address, amount: u64,)
+   * public(script) fun transfer<CoinType>(from: &signer, to: address, amount: u64)
    * ```
+   *
    * @returns EntryFunction
    */
   static build(
@@ -262,7 +307,8 @@ export class EntryFunction {
 }
 
 /**
- * Representation of a Script that can serialized and deserialized
+ * Represents a Script that can be serialized and deserialized.
+ * Scripts contain the Move bytecode payload that can be submitted to the Aptos chain for execution.
  */
 export class Script {
   /**
@@ -289,14 +335,14 @@ export class Script {
    * @example
    * A coin transfer function has one type argument "CoinType".
    * ```
-   * public(script) fun transfer<CoinType>(from: &signer, to: address, amount: u64,)
+   * public(script) fun transfer<CoinType>(from: &signer, to: address, amount: u64)
    * ```
    * @param args The arguments that the bytecode function requires.
    *
    * @example
    * A coin transfer function has three arguments "from", "to" and "amount".
    * ```
-   * public(script) fun transfer<CoinType>(from: &signer, to: address, amount: u64,)
+   * public(script) fun transfer<CoinType>(from: &signer, to: address, amount: u64)
    * ```
    */
   constructor(bytecode: Uint8Array, type_args: Array<TypeTag>, args: Array<ScriptFunctionArgument>) {
@@ -331,7 +377,10 @@ export class Script {
 }
 
 /**
- * Representation of a MultiSig that can serialized and deserialized
+ * Represents a MultiSig account that can be serialized and deserialized.
+ *
+ * This class encapsulates the functionality to manage multi-signature transactions, including the address of the
+ * multi-sig account and the associated transaction payload.
  */
 export class MultiSig {
   public readonly multisig_address: AccountAddress;
@@ -375,12 +424,10 @@ export class MultiSig {
 }
 
 /**
- * Representation of a MultiSig Transaction Payload from `multisig_account.move`
- * that can be serialized and deserialized
-
- * This class exists right now to represent an extensible transaction payload class for
- * transactions used in `multisig_account.move`. Eventually, this class will be able to
- * support script payloads when the `multisig_account.move` module supports them.
+ * Represents a multi-signature transaction payload that can be serialized and deserialized.
+ * This class is designed to encapsulate the transaction payload for multi-sig account transactions
+ * as defined in the `multisig_account.move` module. Future enhancements may allow support for script
+ * payloads as the `multisig_account.move` module evolves.
  */
 export class MultiSigTransactionPayload extends Serializable {
   public readonly transaction_payload: EntryFunction;

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