@aptos-labs/ts-sdk 1.29.1 → 1.31.0

package/src/api/transactionSubmission/build.ts

@@ -9,24 +9,80 @@ import { SimpleTransaction } from "../../transactions/instances/simpleTransactio
 import { AptosConfig } from "../aptosConfig";
 
 /**
- * A class to handle all `Build` transaction operations
+ * A class to handle all `Build` transaction operations.
  */
 export class Build {
   readonly config: AptosConfig;
 
+  /**
+   * Initializes a new instance of the Aptos client with the specified configuration.
+   * This allows you to interact with the Aptos blockchain using the provided settings.
+   *
+   * @param config - The configuration settings for the Aptos client.
+   * @param config.network - The network to connect to (e.g., TESTNET, MAINNET).
+   * @param config.nodeUrl - The URL of the Aptos node to connect to.
+   * @param config.account - The account details for authentication.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a configuration for the Aptos client
+   *     const config = new AptosConfig({
+   *         network: Network.TESTNET, // specify the network
+   *         nodeUrl: "https://testnet.aptos.dev", // specify the node URL
+   *     });
+   *
+   *     // Initialize the Aptos client
+   *     const aptos = new Aptos(config);
+   *
+   *     console.log("Aptos client initialized:", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   constructor(config: AptosConfig) {
     this.config = config;
   }
 
   /**
-   * Build a simple transaction
+   * Build a simple transaction.
+   *
+   * This function allows you to create a transaction with specified sender and data.
    *
-   * @param args.sender The sender account address
-   * @param args.data The transaction data
-   * @param args.options optional. Optional transaction configurations
-   * @param args.withFeePayer optional. Whether there is a fee payer for the transaction
+   * @param args.sender - The sender account address.
+   * @param args.data - The transaction data.
+   * @param args.options - Optional transaction configurations.
+   * @param args.withFeePayer - Whether there is a fee payer for the transaction.
    *
    * @returns SimpleTransaction
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Build a simple transaction
+   *   const transaction = await aptos.transaction.simple({
+   *     sender: "0x1", // replace with a real sender account address
+   *     data: {
+   *       function: "0x1::aptos_account::transfer",
+   *       functionArguments: ["0x2", 100], // replace with a real destination account address
+   *     },
+   *     options: {
+   *       gasUnitPrice: 100, // specify your own gas unit price if needed
+   *       maxGasAmount: 1000, // specify your own max gas amount if needed
+   *     },
+   *   });
+   *
+   *   console.log(transaction);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async simple(args: {
     sender: AccountAddressInput;
@@ -38,15 +94,45 @@ export class Build {
   }
 
   /**
-   * Build a multi agent transaction
+   * Build a multi-agent transaction that allows multiple signers to authorize a transaction.
    *
-   * @param args.sender The sender account address
-   * @param args.data The transaction data
-   * @param args.secondarySignerAddresses An array of the secondary signers account addresses
-   * @param args.options optional. Optional transaction configurations
-   * @param args.withFeePayer optional. Whether there is a fee payer for the transaction
+   * @param args - The parameters for creating the multi-agent transaction.
+   * @param args.sender - The sender account address.
+   * @param args.data - The transaction data.
+   * @param args.secondarySignerAddresses - An array of the secondary signers' account addresses.
+   * @param args.options - Optional transaction configurations.
+   * @param args.withFeePayer - Whether there is a fee payer for the transaction.
    *
    * @returns MultiAgentTransaction
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Build a multi-agent transaction
+   *   const transaction = await aptos.multiAgent({
+   *     sender: "0x1", // replace with a real sender account address
+   *     data: {
+   *       // Transaction data structure
+   *       function: "0x1::aptos_account::transfer",
+   *       functionArguments: ["0x2", 100], // replace with a real destination account address and amount
+   *     },
+   *     secondarySignerAddresses: ["0x3", "0x4"], // replace with real secondary signer addresses
+   *     options: {
+   *       // Optional transaction configurations
+   *       maxGasAmount: "1000",
+   *       gasUnitPrice: "1",
+   *     },
+   *   });
+   *
+   *   console.log(transaction);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async multiAgent(args: {
     sender: AccountAddressInput;

package/src/api/transactionSubmission/helpers.ts

@@ -1,3 +1,49 @@
+/**
+ * Validates the fee payer data when submitting a transaction to ensure that the fee payer authenticator is provided if a fee
+ * payer address is specified.
+ * This helps prevent errors in transaction submission related to fee payer authentication.
+ *
+ * @param target - The target object where the method is defined.
+ * @param propertyKey - The name of the method being decorated.
+ * @param descriptor - The property descriptor for the method.
+ *
+ * @example
+ * ```typescript
+ * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+ *
+ * const config = new AptosConfig({ network: Network.TESTNET });
+ * const aptos = new Aptos(config);
+ *
+ * class TransactionHandler {
+ *   @ValidateFeePayerDataOnSubmission
+ *   async submitTransaction(methodArgs: { transaction: { feePayerAddress: string }, feePayerAuthenticator?: string }) {
+ *     // Logic to submit the transaction
+ *   }
+ * }
+ *
+ * async function runExample() {
+ *   const handler = new TransactionHandler();
+ *
+ *   // Attempt to submit a transaction without a fee payer authenticator
+ *   try {
+ *     await handler.submitTransaction({
+ *       transaction: { feePayerAddress: "0x1" }, // replace with a real fee payer address
+ *     });
+ *   } catch (error) {
+ *     console.error(error.message); // Should log the error message
+ *   }
+ *
+ *   // Submit a transaction with a fee payer authenticator
+ *   await handler.submitTransaction({
+ *     transaction: { feePayerAddress: "0x1" }, // replace with a real fee payer address
+ *     feePayerAuthenticator: "authenticatorValue", // replace with a real authenticator
+ *   });
+ *
+ *   console.log("Transaction submitted successfully.");
+ * }
+ * runExample().catch(console.error);
+ * ```
+ */
 export function ValidateFeePayerDataOnSubmission(target: unknown, propertyKey: string, descriptor: PropertyDescriptor) {
   const originalMethod = descriptor.value;
   /* eslint-disable-next-line func-names, no-param-reassign */
@@ -14,6 +60,39 @@ export function ValidateFeePayerDataOnSubmission(target: unknown, propertyKey: s
   return descriptor;
 }
 
+/**
+ * Validates that the fee payer public key is provided when simulating a Fee Payer transaction.
+ * This ensures that all necessary data is present for the simulation to proceed correctly.
+ *
+ * @param target - The target object where the method is defined.
+ * @param propertyKey - The name of the method being decorated.
+ * @param descriptor - The property descriptor for the method.
+ *
+ * @example
+ * ```typescript
+ * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+ *
+ * const config = new AptosConfig({ network: Network.TESTNET });
+ * const aptos = new Aptos(config);
+ *
+ * async function runExample() {
+ *   const methodArgs = {
+ *     transaction: {
+ *       feePayerAddress: "0x1", // replace with a real fee payer address
+ *     },
+ *     feePayerPublicKey: undefined, // missing fee payer public key
+ *   };
+ *
+ *   try {
+ *     // This will throw an error due to missing feePayerPublicKey
+ *     await aptos.someMethod(methodArgs);
+ *   } catch (error) {
+ *     console.error(error.message); // Output the error message
+ *   }
+ * }
+ * runExample().catch(console.error);
+ * ```
+ */
 export function ValidateFeePayerDataOnSimulation(target: unknown, propertyKey: string, descriptor: PropertyDescriptor) {
   const originalMethod = descriptor.value;
   /* eslint-disable-next-line func-names, no-param-reassign */

package/src/api/transactionSubmission/management.ts

@@ -11,16 +11,63 @@ export class TransactionManagement extends EventEmitter<TransactionWorkerEvents>
 
   readonly config: AptosConfig;
 
+  /**
+   * Initializes a new instance of the Aptos client with the provided configuration settings.
+   * This allows you to interact with the Aptos blockchain using the specified network and options.
+   *
+   * @param config - The configuration settings for the Aptos client.
+   * @param config.network - The network to connect to (e.g., TESTNET, MAINNET).
+   * @param config.nodeUrl - The URL of the Aptos node to connect to.
+   * @param config.account - Optional account settings for authentication.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a configuration for the Aptos client
+   *     const config = new AptosConfig({
+   *         network: Network.TESTNET, // specify the network to use
+   *         nodeUrl: "https://testnet.aptos.dev" // replace with your node URL
+   *     });
+   *
+   *     // Initialize the Aptos client with the configuration
+   *     const aptos = new Aptos(config);
+   *
+   *     console.log("Aptos client initialized successfully.");
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   constructor(config: AptosConfig) {
     super();
     this.config = config;
   }
 
   /**
-   * Internal function to start the transaction worker and
-   * listen to worker events
+   * Initializes the transaction worker using the provided sender account and begins listening for events.
+   * This function is essential for setting up the transaction processing environment.
    *
-   * @param args.sender The sender account to sign and submit the transaction
+   * @param args - The arguments for starting the transaction worker.
+   * @param args.sender - The sender account to sign and submit the transaction.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network, Account } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *     const sender = Account.generate(); // Generate a new account for sending transactions
+   *
+   *     // Start the transaction worker with the sender account
+   *     aptos.start({ sender });
+   *
+   *     console.log("Transaction worker started with sender:", sender.accountAddress);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   private start(args: { sender: Account }): void {
     const { sender } = args;
@@ -32,12 +79,35 @@ export class TransactionManagement extends EventEmitter<TransactionWorkerEvents>
   }
 
   /**
-   * Internal function to push transaction data to the transaction worker.
+   * Pushes transaction data to the transaction worker for processing.
    *
-   * @param args.data An array of transaction payloads
-   * @param args.options optional. Transaction generation configurations (excluding accountSequenceNumber)
+   * @param args.data An array of transaction payloads to be processed.
+   * @param args.options Optional. Transaction generation configurations (excluding accountSequenceNumber).
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Prepare transaction payloads
+   *   const payloads = [
+   *      {}, // Build your first transaction payload
+   *      {}, // Build your second transaction payload
+   *   ];
+   *
+   *   // Push transaction data to the worker
+   *   aptos.push({
+   *     data: payloads,
+   *     {}, // Specify options as needed
+   *   });
    *
-   * TODO - make this public once worker supports adding transactions to existing queue
+   *   console.log("Transaction data pushed successfully.");
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   private push(args: {
     data: InputGenerateTransactionPayloadData[];
@@ -51,11 +121,41 @@ export class TransactionManagement extends EventEmitter<TransactionWorkerEvents>
   }
 
   /**
-   * Internal function to start listening to transaction worker events
+   * Starts listening to transaction worker events, allowing the application to respond to transaction status changes.
+   * This function enables the application to handle events such as transaction sent, execution success, or failure.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Register to listen for transaction events
+   *   aptos.registerToEvents();
+   *
+   *   // You can send a transaction here to see the events in action
+   *   const sender = Account.generate(); // replace with a real account
+   *   const destination = Account.generate(); // replace with a real account
+   *
+   *   const transaction = await aptos.transaction.build.simple({
+   *     sender: sender.accountAddress,
+   *     data: {
+   *       function: "0x1::aptos_account::transfer",
+   *       functionArguments: [destination.accountAddress, 100],
+   *     },
+   *   });
+   *
+   *   await aptos.transaction.send(transaction);
    *
-   * TODO - should we ask events to listen to as an input?
+   *   console.log("Transaction sent and events registered.");
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   private registerToEvents() {
+    // TODO - Should we ask events to listen to this as an input?
     this.transactionWorker.on(TransactionWorkerEventsEnum.TransactionSent, async (data) => {
       this.emit(TransactionWorkerEventsEnum.TransactionSent, data);
     });
@@ -79,7 +179,7 @@ export class TransactionManagement extends EventEmitter<TransactionWorkerEvents>
    * This function uses a transaction worker that receives payloads to be processed
    * and submitted to chain.
    * Note that this process is best for submitting multiple transactions that
-   * dont rely on each other, i.e batch funds, batch token mints, etc.
+   * don't rely on each other, i.e. batch funds, batch token mints, etc.
    *
    * If any worker failure, the functions throws an error.
    *

package/src/api/transactionSubmission/sign.ts

@@ -7,15 +7,72 @@ import { AccountAuthenticator, AnyRawTransaction } from "../../transactions";
 import { AptosConfig } from "../aptosConfig";
 
 /**
- * A class to handle all `Sign` transaction operations
+ * A class to handle all `Sign` transaction operations.
+ *
+ * @param config - The configuration object for Aptos.
  */
 export class Sign {
   readonly config: AptosConfig;
 
+  /**
+   * Creates an instance of the Aptos client with the specified configuration.
+   *
+   * @param config - The configuration settings for the Aptos client.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a new Aptos client with testnet configuration
+   *     const config = new AptosConfig({ network: Network.TESTNET });
+   *     const aptos = new Aptos(config);
+   *
+   *     console.log("Aptos client created with config:", config);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   constructor(config: AptosConfig) {
     this.config = config;
   }
 
+  /**
+   * Signs a transaction using the provided account signer. This function is essential for ensuring that transactions are properly
+   * authenticated before being sent to the network.
+   *
+   * @param args - The arguments for signing the transaction.
+   * @param args.signer - The account that will sign the transaction.
+   * @param args.transaction - The raw transaction data to be signed.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network, Account } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   const sender = Account.generate(); // Generate a new account for signing
+   *   const transaction = await aptos.transaction.build.simple({
+   *     sender: sender.accountAddress,
+   *     data: {
+   *       function: "0x1::aptos_account::transfer",
+   *       functionArguments: [ "0x1", 100 ], // replace with a real account address and amount
+   *     },
+   *   });
+   *
+   *   // Sign the transaction
+   *   const signedTransaction = await aptos.transaction.sign({
+   *     signer: sender,
+   *     transaction: transaction,
+   *   });
+   *
+   *   console.log("Signed Transaction:", signedTransaction);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   // eslint-disable-next-line class-methods-use-this
   transaction(args: { signer: Account; transaction: AnyRawTransaction }): AccountAuthenticator {
     return signTransaction({
@@ -23,11 +80,48 @@ export class Sign {
     });
   }
 
+  /**
+   * Sets the fee payer address for a transaction and signs it with the provided account.
+   * This function is essential for transactions that require a designated fee payer.
+   *
+   * @param args - The arguments for the function.
+   * @param args.signer - The account that will sign the transaction.
+   * @param args.transaction - The transaction object that requires a fee payer address.
+   *
+   * @throws Error if the transaction does not have a feePayerAddress property.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network, Account } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   const sender = Account.generate(); // Generate a new account for signing
+   *   const transaction = await aptos.transaction.build.simple({
+   *     sender: sender.accountAddress,
+   *     data: {
+   *       function: "0x1::aptos_account::transfer",
+   *       functionArguments: ["0x1", 100], // replace with a real recipient address
+   *     },
+   *   });
+   *
+   *   // Set the fee payer for the transaction
+   *   transaction.feePayerAddress = "0x1"; // replace with a real fee payer address
+   *
+   *   const signedTransaction = await aptos.transactionAsFeePayer({ signer: sender, transaction });
+   *
+   *   console.log("Signed Transaction:", signedTransaction);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   // eslint-disable-next-line class-methods-use-this
   transactionAsFeePayer(args: { signer: Account; transaction: AnyRawTransaction }): AccountAuthenticator {
     const { signer, transaction } = args;
 
-    // if transaction doesnt hold a "feePayerAddress" prop it means
+    // if transaction doesn't hold a "feePayerAddress" prop it means
     // this is not a fee payer transaction
     if (!transaction.feePayerAddress) {
       throw new Error(`Transaction ${transaction} is not a Fee Payer transaction`);

package/src/api/transactionSubmission/simulate.ts

@@ -9,24 +9,94 @@ import { AptosConfig } from "../aptosConfig";
 import { ValidateFeePayerDataOnSimulation } from "./helpers";
 
 /**
- * A class to handle all `Simulate` transaction operations
+ * A class to handle all `Simulate` transaction operations.
  */
 export class Simulate {
   readonly config: AptosConfig;
 
+  /**
+   * Initializes a new instance of the Aptos client with the specified configuration.
+   * This allows you to interact with the Aptos blockchain using the provided settings.
+   *
+   * @param config - The configuration settings for the Aptos client.
+   * @param config.network - The network to connect to (e.g., TESTNET, MAINNET).
+   * @param config.nodeUrl - The URL of the Aptos node to connect to.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a configuration for the Aptos client
+   *     const config = new AptosConfig({ network: Network.TESTNET }); // Specify your desired network
+   *
+   *     // Initialize the Aptos client with the configuration
+   *     const aptos = new Aptos(config);
+   *
+   *     console.log("Aptos client initialized:", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   constructor(config: AptosConfig) {
     this.config = config;
   }
 
   /**
-   * Simulate a simple transaction
+   * Simulates a transaction based on the provided parameters and returns the result.
+   * This function helps you understand the outcome of a transaction before executing it on the blockchain.
+   *
+   * @param args - The parameters for simulating the transaction.
+   * @param args.signerPublicKey - The public key of the signer for the transaction.
+   * @param args.transaction - The raw transaction data to simulate.
+   * @param args.feePayerPublicKey - The public key of the fee payer (optional).
+   * @param args.options - Additional options for simulating the transaction (optional).
+   *
+   * @example
+   * ```typescript
+   * import {
+   *     Account,
+   *     Aptos,
+   *     AptosConfig,
+   *     Network,
+   * } from "@aptos-labs/ts-sdk";
+   *
+   * async function example() {
+   *     let sender = Account.generate();
+   *     let receiver = Account.generate();
+   *
+   *     // 0. Set up the client and test accounts
+   *     const config = new AptosConfig({ network: Network.DEVNET });
+   *     const aptos = new Aptos(config);
    *
-   * @param args.signerPublicKey The signer public key
-   * @param args.transaction An instance of a raw transaction
-   * @param args.options optional. Optional transaction configurations
-   * @param args.feePayerPublicKey optional. The fee payer public key if it is a fee payer transaction
+   *     await aptos.fundAccount({
+   *         accountAddress: sender.accountAddress,
+   *         amount: 100_000_000,
+   *     });
    *
-   * @returns Array<UserTransactionResponse>
+   *     // 1. Build the transaction to preview the impact of it
+   *     const transaction = await aptos.transaction.build.simple({
+   *         sender: sender.accountAddress,
+   *         data: {
+   *             // All transactions on Aptos are implemented via smart contracts.
+   *             function: "0x1::aptos_account::transfer",
+   *             functionArguments: [receiver.accountAddress, 100],
+   *         },
+   *     });
+   *
+   *     // 2. Simulate to see what would happen if we execute this transaction
+   *     const [userTransactionResponse] = await aptos.transaction.simulate.simple({
+   *         signerPublicKey: sender.publicKey,
+   *         transaction,
+   *     });
+   *     console.log(userTransactionResponse);
+   *
+   *     // If the fee looks ok, continue to signing!
+   *     // ...
+   * }
+   *
+   * example();
+   * ```
    */
   @ValidateFeePayerDataOnSimulation
   async simple(args: {
@@ -39,15 +109,70 @@ export class Simulate {
   }
 
   /**
-   * Simulate a multi agent transaction
+   * Simulates a multi-agent transaction by generating a signed transaction and posting it to the Aptos full node.
+   * This function helps in understanding the outcome of a transaction involving multiple signers before it is executed.
+   *
+   * @param args - The parameters for simulating the transaction.
+   * @param args.signerPublicKey - The public key of the primary signer.
+   * @param args.transaction - The raw transaction to be simulated.
+   * @param args.secondarySignersPublicKeys - An array of public keys for secondary signers.
+   * @param args.feePayerPublicKey - (Optional) The public key of the fee payer.
+   * @param args.options - (Optional) Options for simulating the transaction.
+   *
+   * @example
+   * ```typescript
+   * import {
+   *     Account,
+   *     Aptos,
+   *     AptosConfig,
+   *     Network,
+   * } from "@aptos-labs/ts-sdk";
+   *
+   * async function example() {
+   *     let sender1 = Account.generate();
+   *     let sender2 = Account.generate();
+   *     let receiver = Account.generate();
+   *
+   *     // 0. Set up the client and test accounts
+   *     const config = new AptosConfig({ network: Network.DEVNET });
+   *     const aptos = new Aptos(config);
+   *
+   *     await aptos.fundAccount({
+   *         accountAddress: sender.accountAddress,
+   *         amount: 100_000_000,
+   *     });
+   *
+   *     // 1. Build
+   *     console.log("\n=== 1. Building the transaction ===\n");
+   *     const transaction = await aptos.transaction.build.multiAgent({
+   *     sender: sender1.accountAddress,
+   *     secondarySignerAddresses: [sender2.accountAddress],
+   *     data: {
+   *        // REPLACE WITH YOUR MULTI-AGENT FUNCTION HERE
+   *        function:
+   *          "<REPLACE WITH YOUR MULTI AGENT MOVE ENTRY FUNCTION> (Syntax {address}::{module}::{function})",
+   *          functionArguments: [],
+   *        },
+   *      });
+   *      console.log("Transaction:", transaction);
+   *
+   *      // 2. Simulate (Optional)
+   *      console.log("\n === 2. Simulating Response (Optional) === \n");
+   *      const [userTransactionResponse] = await aptos.transaction.simulate.multiAgent(
+   *        {
+   *          signerPublicKey: sender1.publicKey,
+   *          secondarySignersPublicKeys: [sender2.publicKey],
+   *          transaction,
+   *        },
+   *      );
+   *      console.log(userTransactionResponse);
    *
-   * @param args.signerPublicKey The signer public key
-   * @param args.transaction An instance of a raw transaction
-   * @param args.secondarySignersPublicKeys An array of the secondary signers public keys
-   * @param args.options optional. Optional transaction configurations
-   * @param args.feePayerPublicKey optional. The fee payer public key if it is a fee payer transaction
+   *      // If the fee looks ok, continue to signing!
+   *      // ...
+   * }
    *
-   * @returns Array<UserTransactionResponse>
+   * example();
+   * ```
    */
   @ValidateFeePayerDataOnSimulation
   async multiAgent(args: {