@moveindustries/ts-sdk 5.1.4

package/src/api/transactionSubmission/build.ts

@@ -0,0 +1,153 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+import { AccountAddressInput } from "../../core";
+import { generateTransaction } from "../../internal/transactionSubmission";
+import {
+  InputGenerateTransactionOptions,
+  InputGenerateTransactionPayloadData
+} from "../../transactions";
+import { MultiAgentTransaction } from "../../transactions/instances/multiAgentTransaction";
+import { SimpleTransaction } from "../../transactions/instances/simpleTransaction";
+import { MovementConfig } from "../movementConfig";
+
+/**
+ * A class to handle all `Build` transaction operations.
+ * @group Implementation
+ */
+export class Build {
+  readonly config: MovementConfig;
+
+  /**
+   * Initializes a new instance of the Movement client with the specified configuration.
+   * This allows you to interact with the Movement blockchain using the provided settings.
+   *
+   * @param config - The configuration settings for the Movement client.
+   * @param config.network - The network to connect to (e.g., TESTNET, MAINNET).
+   * @param config.nodeUrl - The URL of the Movement node to connect to.
+   * @param config.account - The account details for authentication.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a configuration for the Movement client
+   *     const config = new MovementConfig({
+   *         network: Network.TESTNET, // specify the network
+   *         nodeUrl: "https://testnet.movement.dev", // specify the node URL
+   *     });
+   *
+   *     // Initialize the Movement client
+   *     const movement = new Movement(config);
+   *
+   *     console.log("Movement client initialized:", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group Implementation
+   */
+  constructor(config: MovementConfig) {
+    this.config = config;
+  }
+
+  /**
+   * 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 transaction configurations.
+   * @param args.withFeePayer - Whether there is a fee payer for the transaction.
+   *
+   * @returns SimpleTransaction
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *   // Build a simple transaction
+   *   const transaction = await movement.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);
+   * ```
+   * @group Implementation
+   */
+  async simple(args: {
+    sender: AccountAddressInput;
+    data: InputGenerateTransactionPayloadData;
+    options?: InputGenerateTransactionOptions;
+    withFeePayer?: boolean;
+  }): Promise<SimpleTransaction> {
+    return generateTransaction({ movementConfig: this.config, ...args });
+  }
+
+  /**
+   * Build a multi-agent transaction that allows multiple signers to authorize a 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 { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *   // Build a multi-agent transaction
+   *   const transaction = await movement.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);
+   * ```
+   * @group Implementation
+   */
+  async multiAgent(args: {
+    sender: AccountAddressInput;
+    data: InputGenerateTransactionPayloadData;
+    secondarySignerAddresses: AccountAddressInput[];
+    options?: InputGenerateTransactionOptions;
+    withFeePayer?: boolean;
+  }): Promise<MultiAgentTransaction> {
+    return generateTransaction({ movementConfig: this.config, ...args });
+  }
+}

package/src/api/transactionSubmission/helpers.ts

@@ -0,0 +1,112 @@
+import { AccountAuthenticator, AnyRawTransaction, InputTransactionPluginData } from "../../transactions";
+import { MovementConfig } from "../movementConfig";
+
+/**
+ * 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.
+ *
+ * The validation is skipped if a custom transaction submitter is defined.
+ *
+ * @param config - The Movement configuration that may contain a transaction submitter.
+ * @param args - The method arguments containing transaction data and optional transaction submitter.
+ *
+ * @example
+ * ```typescript
+ * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+ *
+ * const config = new MovementConfig({ network: Network.TESTNET });
+ * const movement = new Movement(config);
+ *
+ * class TransactionHandler {
+ *   async submitTransaction(methodArgs: { transaction: { feePayerAddress: string }, feePayerAuthenticator?: string }) {
+ *     validateFeePayerDataOnSubmission(this.config, methodArgs);
+ *     // 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);
+ * ```
+ * @group Implementation
+ */
+export function validateFeePayerDataOnSubmission(
+  config: MovementConfig,
+  args: {
+    transaction: AnyRawTransaction;
+    senderAuthenticator: AccountAuthenticator;
+    feePayerAuthenticator?: AccountAuthenticator;
+  } & InputTransactionPluginData,
+): void {
+  // Skip validation if a transaction submitter is defined.
+  if (config.getTransactionSubmitter() !== undefined || args.transactionSubmitter !== undefined) {
+    return;
+  }
+
+  if (args.transaction.feePayerAddress && !args.feePayerAuthenticator) {
+    throw new Error("You are submitting a Fee Payer transaction but missing the feePayerAuthenticator");
+  }
+}
+
+/**
+ * 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 { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+ *
+ * const config = new MovementConfig({ network: Network.TESTNET });
+ * const movement = new Movement(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 movement.someMethod(methodArgs);
+ *   } catch (error) {
+ *     console.error(error.message); // Output the error message
+ *   }
+ * }
+ * runExample().catch(console.error);
+ * ```
+ * @group Implementation
+ */
+export function ValidateFeePayerDataOnSimulation(target: unknown, propertyKey: string, descriptor: PropertyDescriptor) {
+  const originalMethod = descriptor.value;
+  /* eslint-disable-next-line func-names, no-param-reassign */
+  descriptor.value = async function (...args: any[]) {
+    return originalMethod.apply(this, args);
+  };
+
+  return descriptor;
+}

package/src/api/transactionSubmission/management.ts

@@ -0,0 +1,211 @@
+import EventEmitter from "eventemitter3";
+import { Account } from "../../account";
+import { InputGenerateTransactionOptions, InputGenerateTransactionPayloadData } from "../../transactions";
+import { TransactionWorker, TransactionWorkerEvents, TransactionWorkerEventsEnum } from "../../transactions/management";
+import { MovementConfig } from "../movementConfig";
+
+export class TransactionManagement extends EventEmitter<TransactionWorkerEvents> {
+  account!: Account;
+
+  transactionWorker!: TransactionWorker;
+
+  readonly config: MovementConfig;
+
+  /**
+   * Initializes a new instance of the Movement client with the provided configuration settings.
+   * This allows you to interact with the Movement blockchain using the specified network and options.
+   *
+   * @param config - The configuration settings for the Movement client.
+   * @param config.network - The network to connect to (e.g., TESTNET, MAINNET).
+   * @param config.nodeUrl - The URL of the Movement node to connect to.
+   * @param config.account - Optional account settings for authentication.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a configuration for the Movement client
+   *     const config = new MovementConfig({
+   *         network: Network.TESTNET, // specify the network to use
+   *         nodeUrl: "https://testnet.movement.dev" // replace with your node URL
+   *     });
+   *
+   *     // Initialize the Movement client with the configuration
+   *     const movement = new Movement(config);
+   *
+   *     console.log("Movement client initialized successfully.");
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group Implementation
+   */
+  constructor(config: MovementConfig) {
+    super();
+    this.config = config;
+  }
+
+  /**
+   * 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 - The arguments for starting the transaction worker.
+   * @param args.sender - The sender account to sign and submit the transaction.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network, Account } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *     const sender = Account.generate(); // Generate a new account for sending transactions
+   *
+   *     // Start the transaction worker with the sender account
+   *     movement.start({ sender });
+   *
+   *     console.log("Transaction worker started with sender:", sender.accountAddress);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group Implementation
+   */
+  private start(args: { sender: Account }): void {
+    const { sender } = args;
+    this.account = sender;
+    this.transactionWorker = new TransactionWorker(this.config, sender);
+
+    this.transactionWorker.start();
+    this.registerToEvents();
+  }
+
+  /**
+   * Pushes transaction data to the transaction worker for processing.
+   *
+   * @param args.data An array of transaction payloads to be processed.
+   * @param args.options Optional. Transaction generation configurations (excluding accountSequenceNumber).
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(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
+   *   movement.push({
+   *     data: payloads,
+   *     {}, // Specify options as needed
+   *   });
+   *
+   *   console.log("Transaction data pushed successfully.");
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group Implementation
+   */
+  private push(args: {
+    data: InputGenerateTransactionPayloadData[];
+    options?: Omit<InputGenerateTransactionOptions, "accountSequenceNumber">;
+  }): void {
+    const { data, options } = args;
+
+    for (const d of data) {
+      this.transactionWorker.push(d, options);
+    }
+  }
+
+  /**
+   * 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 { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *   // Register to listen for transaction events
+   *   movement.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 movement.transaction.build.simple({
+   *     sender: sender.accountAddress,
+   *     data: {
+   *       function: "0x1::aptos_account::transfer",
+   *       functionArguments: [destination.accountAddress, 100],
+   *     },
+   *   });
+   *
+   *   await movement.transaction.send(transaction);
+   *
+   *   console.log("Transaction sent and events registered.");
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group Implementation
+   */
+  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);
+    });
+    this.transactionWorker.on(TransactionWorkerEventsEnum.TransactionSendFailed, async (data) => {
+      this.emit(TransactionWorkerEventsEnum.TransactionSendFailed, data);
+    });
+    this.transactionWorker.on(TransactionWorkerEventsEnum.TransactionExecuted, async (data) => {
+      this.emit(TransactionWorkerEventsEnum.TransactionExecuted, data);
+    });
+    this.transactionWorker.on(TransactionWorkerEventsEnum.TransactionExecutionFailed, async (data) => {
+      this.emit(TransactionWorkerEventsEnum.TransactionExecutionFailed, data);
+    });
+    this.transactionWorker.on(TransactionWorkerEventsEnum.ExecutionFinish, async (data) => {
+      this.emit(TransactionWorkerEventsEnum.ExecutionFinish, data);
+    });
+  }
+
+  /**
+   * Send batch transactions for a single account.
+   *
+   * 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
+   * don't rely on each other, i.e. batch funds, batch token mints, etc.
+   *
+   * If any worker failure, the functions throws an error.
+   *
+   * @param args.sender The sender account to sign and submit the transaction
+   * @param args.data An array of transaction payloads
+   * @param args.options optional. Transaction generation configurations (excluding accountSequenceNumber)
+   *
+   * @return void. Throws if any error
+   * @group Implementation
+   */
+  forSingleAccount(args: {
+    sender: Account;
+    data: InputGenerateTransactionPayloadData[];
+    options?: Omit<InputGenerateTransactionOptions, "accountSequenceNumber">;
+  }): void {
+    try {
+      const { sender, data, options } = args;
+      this.start({ sender });
+
+      this.push({ data, options });
+    } catch (error: any) {
+      throw new Error(`failed to submit transactions with error: ${error}`);
+    }
+  }
+}

package/src/api/transactionSubmission/sign.ts

@@ -0,0 +1,142 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+import { Account } from "../../account";
+import { signTransaction } from "../../internal/transactionSubmission";
+import { AccountAuthenticator, AnyRawTransaction } from "../../transactions";
+import { MovementConfig } from "../movementConfig";
+
+/**
+ * A class to handle all `Sign` transaction operations.
+ *
+ * @param config - The configuration object for Movement.
+ * @group Implementation
+ */
+export class Sign {
+  readonly config: MovementConfig;
+
+  /**
+   * Creates an instance of the Movement client with the specified configuration.
+   *
+   * @param config - The configuration settings for the Movement client.
+   *
+   * @example
+   * ```typescript
+   * import { Movement, MovementConfig, Network } from "@moveindustries/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a new Movement client with testnet configuration
+   *     const config = new MovementConfig({ network: Network.TESTNET });
+   *     const movement = new Movement(config);
+   *
+   *     console.log("Movement client created with config:", config);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group Implementation
+   */
+  constructor(config: MovementConfig) {
+    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 { Movement, MovementConfig, Network, Account } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *   const sender = Account.generate(); // Generate a new account for signing
+   *   const transaction = await movement.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 movement.transaction.sign({
+   *     signer: sender,
+   *     transaction: transaction,
+   *   });
+   *
+   *   console.log("Signed Transaction:", signedTransaction);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group Implementation
+   */
+  // eslint-disable-next-line class-methods-use-this
+  transaction(args: { signer: Account; transaction: AnyRawTransaction }): AccountAuthenticator {
+    return signTransaction({
+      ...args,
+    });
+  }
+
+  /**
+   * 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 { Movement, MovementConfig, Network, Account } from "@moveindustries/ts-sdk";
+   *
+   * const config = new MovementConfig({ network: Network.TESTNET });
+   * const movement = new Movement(config);
+   *
+   * async function runExample() {
+   *   const sender = Account.generate(); // Generate a new account for signing
+   *   const transaction = await movement.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 movement.transactionAsFeePayer({ signer: sender, transaction });
+   *
+   *   console.log("Signed Transaction:", signedTransaction);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group Implementation
+   */
+  // eslint-disable-next-line class-methods-use-this
+  transactionAsFeePayer(args: { signer: Account; transaction: AnyRawTransaction }): AccountAuthenticator {
+    const { signer, transaction } = args;
+
+    // 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`);
+    }
+
+    // Set the feePayerAddress to the signer account address
+    transaction.feePayerAddress = signer.accountAddress;
+
+    return signTransaction({
+      signer,
+      transaction,
+    });
+  }
+}