@aptos-labs/ts-sdk 1.33.1 → 1.33.2

package/src/transactions/instances/simpleTransaction.ts

@@ -16,6 +16,8 @@ import { RawTransaction } from "./rawTransaction";
  *
  * @param rawTransaction - The Raw Transaction.
  * @param feePayerAddress - The optional sponsor Account Address.
+ * @group Implementation
+ * @category Transactions
  */
 export class SimpleTransaction extends Serializable {
   public rawTransaction: RawTransaction;
@@ -32,6 +34,8 @@ export class SimpleTransaction extends Serializable {
    *
    * @param rawTransaction The Raw Transaction.
    * @param feePayerAddress The optional sponsor Account Address to pay the gas fees.
+   * @group Implementation
+   * @category Transactions
    */
   constructor(rawTransaction: RawTransaction, feePayerAddress?: AccountAddress) {
     super();
@@ -44,6 +48,8 @@ export class SimpleTransaction extends Serializable {
    * 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.
+   * @group Implementation
+   * @category Transactions
    */
   serialize(serializer: Serializer): void {
     this.rawTransaction.serialize(serializer);
@@ -61,6 +67,8 @@ export class SimpleTransaction extends Serializable {
    * This function helps in reconstructing a SimpleTransaction object from its serialized form.
    *
    * @param deserializer - The deserializer instance used to read the serialized data.
+   * @group Implementation
+   * @category Transactions
    */
   static deserialize(deserializer: Deserializer): SimpleTransaction {
     const rawTransaction = RawTransaction.deserialize(deserializer);

package/src/transactions/instances/transactionArgument.ts

@@ -9,12 +9,16 @@ export interface TransactionArgument extends EntryFunctionArgument, ScriptFuncti
 /**
  * Represents an argument for entry functions, providing methods to serialize the argument
  * to BCS-serialized bytes and convert it to different formats.
+ * @group Implementation
+ * @category Transactions
  */
 export interface EntryFunctionArgument {
   /**
    * Serialize an argument to BCS-serialized bytes.
    *
    * @param serializer - The serializer instance used for serialization.
+   * @group Implementation
+   * @category Transactions
    */
   serialize(serializer: Serializer): void;
 
@@ -24,6 +28,8 @@ export interface EntryFunctionArgument {
    * 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.
+   * @group Implementation
+   * @category Transactions
    */
   serializeForEntryFunction(serializer: Serializer): void;
 
@@ -31,6 +37,8 @@ export interface EntryFunctionArgument {
    * Convert the argument to BCS-serialized bytes.
    *
    * @returns Uint8Array representing the BCS-serialized bytes of the argument.
+   * @group Implementation
+   * @category Transactions
    */
   bcsToBytes(): Uint8Array;
 
@@ -39,22 +47,30 @@ export interface EntryFunctionArgument {
    * 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.
+   * @group Implementation
+   * @category Transactions
    */
   bcsToHex(): Hex;
 }
 
 /**
  * Represents an argument for script functions, providing methods to serialize and convert to bytes.
+ * @group Implementation
+ * @category Transactions
  */
 export interface ScriptFunctionArgument {
   /**
    * Serialize an argument to BCS-serialized bytes.
+   * @group Implementation
+   * @category Transactions
    */
   serialize(serializer: Serializer): void;
   /**
    * Serialize an argument to BCS-serialized bytes as a type aware byte sequence.
    * The byte sequence contains an enum variant index followed by the BCS-serialized
    * bytes for a typed argument.
+   * @group Implementation
+   * @category Transactions
    */
   serializeForScriptFunction(serializer: Serializer): void;
 

package/src/transactions/instances/transactionPayload.ts

@@ -22,6 +22,8 @@ import { TypeTag } from "../typeTag";
  * @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.
+ * @group Implementation
+ * @category Transactions
  */
 export function deserializeFromScriptArgument(deserializer: Deserializer): TransactionArgument {
   // index enum variant
@@ -58,15 +60,21 @@ export function deserializeFromScriptArgument(deserializer: Deserializer): Trans
  * 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.
+ * @group Implementation
+ * @category Transactions
  */
 export abstract class TransactionPayload extends Serializable {
   /**
    * Serialize a Transaction Payload
+   * @group Implementation
+   * @category Transactions
    */
   abstract serialize(serializer: Serializer): void;
 
   /**
    * Deserialize a Transaction Payload
+   * @group Implementation
+   * @category Transactions
    */
 
   /**
@@ -74,6 +82,8 @@ export abstract class TransactionPayload extends Serializable {
    * This function enables the reconstruction of a MultiSigTransactionPayload object from its serialized form.
    *
    * @param deserializer - The deserializer instance used to read the serialized data.
+   * @group Implementation
+   * @category Transactions
    */
   static deserialize(deserializer: Deserializer): TransactionPayload {
     // index enum variant
@@ -97,6 +107,8 @@ export abstract class TransactionPayload extends Serializable {
  * This class encapsulates a script that defines the logic for a transaction payload.
  *
  * @extends TransactionPayload
+ * @group Implementation
+ * @category Transactions
  */
 export class TransactionPayloadScript extends TransactionPayload {
   public readonly script: Script;
@@ -106,6 +118,8 @@ export class TransactionPayloadScript extends TransactionPayload {
    *
    * @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.
+   * @group Implementation
+   * @category Transactions
    */
   constructor(script: Script) {
     super();
@@ -116,6 +130,8 @@ export class TransactionPayloadScript extends TransactionPayload {
    * 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.
+   * @group Implementation
+   * @category Transactions
    */
   serialize(serializer: Serializer): void {
     serializer.serializeU32AsUleb128(TransactionPayloadVariants.Script);
@@ -127,6 +143,8 @@ export class TransactionPayloadScript extends TransactionPayload {
    * This function helps in reconstructing a MultiSig transaction payload from its serialized form.
    *
    * @param deserializer - The deserializer used to read the serialized data.
+   * @group Implementation
+   * @category Transactions
    */
   static load(deserializer: Deserializer): TransactionPayloadScript {
     const script = Script.deserialize(deserializer);
@@ -138,6 +156,8 @@ export class TransactionPayloadScript extends TransactionPayload {
  * Represents a transaction payload entry function that can be serialized and deserialized.
  *
  * @extends TransactionPayload
+ * @group Implementation
+ * @category Transactions
  */
 export class TransactionPayloadEntryFunction extends TransactionPayload {
   public readonly entryFunction: EntryFunction;
@@ -160,6 +180,8 @@ export class TransactionPayloadEntryFunction extends TransactionPayload {
 
 /**
  * Represents a multi-signature transaction payload that can be serialized and deserialized.
+ * @group Implementation
+ * @category Transactions
  */
 export class TransactionPayloadMultiSig extends TransactionPayload {
   public readonly multiSig: MultiSig;
@@ -189,6 +211,8 @@ export class TransactionPayloadMultiSig extends TransactionPayload {
  * @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.
+ * @group Implementation
+ * @category Transactions
  */
 export class EntryFunction {
   public readonly module_name: ModuleId;
@@ -217,6 +241,8 @@ export class EntryFunction {
    * ```
    * public entry fun transfer<CoinType>(from: &signer, to: address, amount: u64)
    * ```
+   * @group Implementation
+   * @category Transactions
    */
   constructor(
     module_name: ModuleId,
@@ -250,6 +276,8 @@ export class EntryFunction {
    * ```
    *
    * @returns EntryFunction
+   * @group Implementation
+   * @category Transactions
    */
   static build(
     module_id: MoveModuleId,
@@ -287,6 +315,8 @@ export class EntryFunction {
    * @param deserializer
    * @returns A deserialized EntryFunction payload for a transaction.
    *
+   * @group Implementation
+   * @category Transactions
    */
   static deserialize(deserializer: Deserializer): EntryFunction {
     const module_name = ModuleId.deserialize(deserializer);
@@ -309,20 +339,28 @@ export class EntryFunction {
 /**
  * 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.
+ * @group Implementation
+ * @category Transactions
  */
 export class Script {
   /**
    * The move module bytecode
+   * @group Implementation
+   * @category Transactions
    */
   public readonly bytecode: Uint8Array;
 
   /**
    * The type arguments that the bytecode function requires.
+   * @group Implementation
+   * @category Transactions
    */
   public readonly type_args: Array<TypeTag>;
 
   /**
    * The arguments that the bytecode function requires.
+   * @group Implementation
+   * @category Transactions
    */
   public readonly args: Array<ScriptFunctionArgument>;
 
@@ -344,6 +382,8 @@ export class Script {
    * ```
    * public(script) fun transfer<CoinType>(from: &signer, to: address, amount: u64)
    * ```
+   * @group Implementation
+   * @category Transactions
    */
   constructor(bytecode: Uint8Array, type_args: Array<TypeTag>, args: Array<ScriptFunctionArgument>) {
     this.bytecode = bytecode;
@@ -381,6 +421,8 @@ export class Script {
  *
  * This class encapsulates the functionality to manage multi-signature transactions, including the address of the
  * multi-sig account and the associated transaction payload.
+ * @group Implementation
+ * @category Transactions
  */
 export class MultiSig {
   public readonly multisig_address: AccountAddress;
@@ -394,6 +436,8 @@ export class MultiSig {
    *
    * @param transaction_payload The payload of the multi-sig transaction. This is optional when executing a multi-sig
    *  transaction whose payload is already stored on chain.
+   * @group Implementation
+   * @category Transactions
    */
   constructor(multisig_address: AccountAddress, transaction_payload?: MultiSigTransactionPayload) {
     this.multisig_address = multisig_address;
@@ -428,6 +472,8 @@ export class MultiSig {
  * 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.
+ * @group Implementation
+ * @category Transactions
  */
 export class MultiSigTransactionPayload extends Serializable {
   public readonly transaction_payload: EntryFunction;
@@ -438,6 +484,8 @@ export class MultiSigTransactionPayload extends Serializable {
    * @param transaction_payload The payload of the multi-sig transaction.
    * This can only be EntryFunction for now but,
    * Script might be supported in the future.
+   * @group Implementation
+   * @category Transactions
    */
   constructor(transaction_payload: EntryFunction) {
     super();
@@ -449,6 +497,8 @@ export class MultiSigTransactionPayload extends Serializable {
      * We can support multiple types of inner transaction payload in the future.
      * For now, it's only EntryFunction but if we support more types,
      * we need to serialize with the right enum values here
+     * @group Implementation
+     * @category Transactions
      */
     serializer.serializeU32AsUleb128(0);
     this.transaction_payload.serialize(serializer);

package/src/transactions/management/accountSequenceNumber.ts

@@ -21,6 +21,8 @@
  * This only manages the distribution of sequence numbers it does not help handle transaction
  * failures.
  * If a transaction fails, you should call synchronize and wait for timeouts.
+ * @group Implementation
+ * @category Transactions
  */
 
 import { AptosConfig } from "../../api/aptosConfig";
@@ -38,6 +40,8 @@ import { nowInSeconds, sleep } from "../../utils/helpers";
  * @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.
+ * @group Implementation
+ * @category Transactions
  */
 export class AccountSequenceNumber {
   readonly aptosConfig: AptosConfig;
@@ -61,6 +65,8 @@ export class AccountSequenceNumber {
    * 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.
+   * @group Implementation
+   * @category Transactions
    */
   lock = false;
 
@@ -79,6 +85,8 @@ export class AccountSequenceNumber {
    * @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.
+   * @group Implementation
+   * @category Transactions
    */
   constructor(
     aptosConfig: AptosConfig,
@@ -99,6 +107,8 @@ export class AccountSequenceNumber {
    * This function ensures that the sequence number is updated and synchronized, handling potential delays in transaction commits.
    *
    * @returns {BigInt} The next available sequence number.
+   * @group Implementation
+   * @category Transactions
    */
   async nextSequenceNumber(): Promise<bigint | null> {
     /* eslint-disable no-await-in-loop */
@@ -146,6 +156,8 @@ export class AccountSequenceNumber {
    * @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.
+   * @group Implementation
+   * @category Transactions
    */
   async initialize(): Promise<void> {
     const { sequence_number: sequenceNumber } = await getInfo({
@@ -160,6 +172,8 @@ export class AccountSequenceNumber {
    * Updates this account's sequence number with the one on-chain.
    *
    * @returns The on-chain sequence number for this account.
+   * @group Implementation
+   * @category Transactions
    */
   async update(): Promise<bigint> {
     const { sequence_number: sequenceNumber } = await getInfo({
@@ -175,6 +189,8 @@ export class AccountSequenceNumber {
    * This function polls 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.
+   * @group Implementation
+   * @category Transactions
    */
   async synchronize(): Promise<void> {
     if (this.lastUncommintedNumber === this.currentNumber) return;

package/src/transactions/management/asyncQueue.ts

@@ -4,6 +4,8 @@
  * It allows to enqueue items and dequeue them asynchronously.
  * 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.
+ * @group Implementation
+ * @category Transactions
  */
 
 interface PendingDequeue<T> {
@@ -24,6 +26,8 @@ export class AsyncQueue<T> {
    * immediately; otherwise, it adds the item to the queue.
    *
    * @param item - The item to be added to the queue.
+   * @group Implementation
+   * @category Transactions
    */
   enqueue(item: T): void {
     this.cancelled = false;
@@ -44,6 +48,8 @@ export class AsyncQueue<T> {
    * If the queue is empty, it creates a new promise that will be resolved when an item is enqueued.
    *
    * @returns Promise<T>
+   * @group Implementation
+   * @category Transactions
    */
   async dequeue(): Promise<T> {
     if (this.queue.length > 0) {
@@ -59,6 +65,8 @@ export class AsyncQueue<T> {
    * Determine whether the queue is empty.
    *
    * @returns boolean - Returns true if the queue has no elements, otherwise false.
+   * @group Implementation
+   * @category Transactions
    */
   isEmpty(): boolean {
     return this.queue.length === 0;
@@ -69,6 +77,8 @@ export class AsyncQueue<T> {
    * This ensures that any awaiting code can handle the cancellation appropriately.
    *
    * @returns {void}
+   * @group Implementation
+   * @category Transactions
    */
   cancel(): void {
     this.cancelled = true;
@@ -86,6 +96,8 @@ export class AsyncQueue<T> {
    * Determine whether the queue has been cancelled.
    *
    * @returns boolean - Returns true if the queue is cancelled, otherwise false.
+   * @group Implementation
+   * @category Transactions
    */
   isCancelled(): boolean {
     return this.cancelled;
@@ -95,6 +107,8 @@ export class AsyncQueue<T> {
    * Retrieve the length of the pending dequeue.
    *
    * @returns number - The number of items currently in the pending dequeue.
+   * @group Implementation
+   * @category Transactions
    */
   pendingDequeueLength(): number {
     return this.pendingDequeue.length;
@@ -106,5 +120,7 @@ export class AsyncQueue<T> {
  * This error extends the built-in Error class to provide additional context for cancellation events.
  *
  * @extends Error
+ * @group Implementation
+ * @category Transactions
  */
 export class AsyncQueueCancelledError extends Error {}

package/src/transactions/management/transactionWorker.ts

@@ -11,10 +11,16 @@ import { AccountSequenceNumber } from "./accountSequenceNumber";
 import { AsyncQueue, AsyncQueueCancelledError } from "./asyncQueue";
 import { SimpleTransaction } from "../instances/simpleTransaction";
 
+/**
+ * @group Implementation
+ * @category Transactions
+ */
 export const promiseFulfilledStatus = "fulfilled";
 
 /**
  * Events emitted by the transaction worker during its operation, allowing the dapp to respond to various transaction states.
+ * @group Implementation
+ * @category Transactions
  */
 export enum TransactionWorkerEventsEnum {
   // fired after a transaction gets sent to the chain
@@ -31,11 +37,8 @@ export enum TransactionWorkerEventsEnum {
 
 /**
  * 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.
+ * @group Implementation
+ * @category Transactions
  */
 export interface TransactionWorkerEvents {
   transactionSent: (data: SuccessEventData) => void;
@@ -47,6 +50,8 @@ export interface TransactionWorkerEvents {
 
 /**
  * The payload for when the worker has finished its job.
+ * @group Implementation
+ * @category Transactions
  */
 export type ExecutionFinishEventData = {
   message: string;
@@ -54,6 +59,8 @@ export type ExecutionFinishEventData = {
 
 /**
  * The payload for a success event.
+ * @group Implementation
+ * @category Transactions
  */
 export type SuccessEventData = {
   message: string;
@@ -62,6 +69,8 @@ export type SuccessEventData = {
 
 /**
  * The payload for a failure event.
+ * @group Implementation
+ * @category Transactions
  */
 export type FailureEventData = {
   message: string;
@@ -79,6 +88,8 @@ export type FailureEventData = {
  * 1) waits for resolution of the submission process or get pre-execution validation error
  * and 2) waits for the resolution of the execution process or get an execution error.
  * The worker fires events for any submission and/or execution success and/or failure.
+ * @group Implementation
+ * @category Transactions
  */
 export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
   readonly aptosConfig: AptosConfig;
@@ -98,6 +109,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
    * transactions payloads waiting to be generated and signed
    *
    * TODO support entry function payload from ABI builder
+   * @group Implementation
+   * @category Transactions
    */
   transactionsQueue = new AsyncQueue<
     [InputGenerateTransactionPayloadData, InputGenerateTransactionOptions | undefined]
@@ -105,16 +118,22 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
 
   /**
    * signed transactions waiting to be submitted
+   * @group Implementation
+   * @category Transactions
    */
   outstandingTransactions = new AsyncQueue<[Promise<PendingTransactionResponse>, bigint]>();
 
   /**
    * transactions that have been submitted to chain
+   * @group Implementation
+   * @category Transactions
    */
   sentTransactions: Array<[string, bigint, any]> = [];
 
   /**
    * transactions that have been committed to chain
+   * @group Implementation
+   * @category Transactions
    */
   executedTransactions: Array<[string, bigint, any]> = [];
 
@@ -128,6 +147,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
    * @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.
+   * @group Implementation
+   * @category Transactions
    */
   constructor(
     aptosConfig: AptosConfig,
@@ -155,6 +176,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
    * This function continues to submit transactions until there are no more to process.
    *
    * @throws {Error} Throws an error if the transaction submission fails.
+   * @group Implementation
+   * @category Transactions
    */
   async submitNextTransaction() {
     try {
@@ -189,6 +212,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
    * @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.
+   * @group Implementation
+   * @category Transactions
    */
   async processTransactions() {
     try {
@@ -247,6 +272,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
    * 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.
+   * @group Implementation
+   * @category Transactions
    */
   async checkTransaction(sentTransaction: PromiseFulfilledResult<PendingTransactionResponse>, sequenceNumber: bigint) {
     try {
@@ -287,6 +314,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
    * @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.
+   * @group Implementation
+   * @category Transactions
    */
   async push(
     transactionData: InputGenerateTransactionPayloadData,
@@ -301,6 +330,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
    * @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.
+   * @group Implementation
+   * @category Transactions
    */
   async generateNextTransaction(account: Account, sequenceNumber: bigint): Promise<SimpleTransaction | undefined> {
     if (this.transactionsQueue.isEmpty()) return undefined;
@@ -317,6 +348,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
    * 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.
+   * @group Implementation
+   * @category Transactions
    */
   async run() {
     try {
@@ -333,6 +366,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
    * Starts the transaction management process.
    *
    * @throws {Error} Throws an error if the worker has already started.
+   * @group Implementation
+   * @category Transactions
    */
   start() {
     if (this.started) {
@@ -348,6 +383,8 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
    * Stops the transaction management process.
    *
    * @throws {Error} Throws an error if the worker has already stopped.
+   * @group Implementation
+   * @category Transactions
    */
   stop() {
     if (this.taskQueue.isCancelled()) {