@aptos-labs/ts-sdk 2.0.1 → 3.0.0

package/src/transactions/instances/transactionPayload.ts

@@ -8,11 +8,19 @@ import { Serializable, Serializer } from "../../bcs/serializer";
 import { EntryFunctionBytes } from "../../bcs/serializable/entryFunctionBytes";
 import { Bool, U128, U16, U256, U32, U64, U8 } from "../../bcs/serializable/movePrimitives";
 import { MoveVector, Serialized } from "../../bcs/serializable/moveStructs";
-import { AccountAddress } from "../../core";
+import { AccountAddress, Hex } from "../../core";
 import { Identifier } from "./identifier";
 import { ModuleId } from "./moduleId";
 import type { EntryFunctionArgument, ScriptFunctionArgument, TransactionArgument } from "./transactionArgument";
-import { MoveModuleId, ScriptTransactionArgumentVariants, TransactionPayloadVariants } from "../../types";
+import {
+  AnyNumber,
+  MoveModuleId,
+  ScriptTransactionArgumentVariants,
+  TransactionExecutableVariants,
+  TransactionExtraConfigVariants,
+  TransactionInnerPayloadVariants,
+  TransactionPayloadVariants,
+} from "../../types";
 import { TypeTag } from "../typeTag";
 
 /**
@@ -95,6 +103,8 @@ export abstract class TransactionPayload extends Serializable {
         return TransactionPayloadEntryFunction.load(deserializer);
       case TransactionPayloadVariants.Multisig:
         return TransactionPayloadMultiSig.load(deserializer);
+      case TransactionPayloadVariants.Payload:
+        return TransactionInnerPayload.deserialize(deserializer);
       default:
         throw new Error(`Unknown variant index for TransactionPayload: ${index}`);
     }
@@ -511,3 +521,156 @@ export class MultiSigTransactionPayload extends Serializable {
     return new MultiSigTransactionPayload(EntryFunction.deserialize(deserializer));
   }
 }
+
+/**
+ * Represents any transaction payload that can be submitted to the Aptos chain for execution.
+ *
+ * This is specifically required for orderless transactions, but can be used for any transaction payload.
+ */
+export abstract class TransactionInnerPayload extends TransactionPayload {
+  abstract serialize(serializer: Serializer): void;
+
+  static deserialize(deserializer: Deserializer): TransactionInnerPayload {
+    // index enum variant
+    const index = deserializer.deserializeUleb128AsU32();
+    switch (index) {
+      case TransactionInnerPayloadVariants.V1:
+        return TransactionInnerPayloadV1.load(deserializer);
+      default:
+        throw new Error(`Unknown variant index for TransactionInnerPayload: ${index}`);
+    }
+  }
+}
+
+export class TransactionInnerPayloadV1 extends TransactionInnerPayload {
+  executable: TransactionExecutable;
+  extra_config: TransactionExtraConfig;
+
+  constructor(executable: TransactionExecutable, extra_config: TransactionExtraConfig) {
+    super();
+    this.executable = executable;
+    this.extra_config = extra_config;
+  }
+
+  serialize(serializer: Serializer): void {
+    // This payload must be serialized as a top level TransactionPayload, so we add that here
+    serializer.serializeU32AsUleb128(TransactionPayloadVariants.Payload);
+    // V1 is serialized as 0
+    serializer.serializeU32AsUleb128(TransactionInnerPayloadVariants.V1);
+    this.executable.serialize(serializer);
+    this.extra_config.serialize(serializer);
+  }
+
+  static load(deserializer: Deserializer): TransactionInnerPayloadV1 {
+    let executable = TransactionExecutable.deserialize(deserializer);
+    let extra_config = TransactionExtraConfig.deserialize(deserializer);
+    return new TransactionInnerPayloadV1(executable, extra_config);
+  }
+}
+
+export abstract class TransactionExecutable {
+  abstract serialize(serializer: Serializer): void;
+
+  static deserialize(deserializer: Deserializer): TransactionExecutable {
+    // index enum variant
+    const index = deserializer.deserializeUleb128AsU32();
+    switch (index) {
+      case TransactionExecutableVariants.Script:
+        return TransactionExecutableScript.load(deserializer);
+      case TransactionExecutableVariants.EntryFunction:
+        return TransactionExecutableEntryFunction.load(deserializer);
+      case TransactionExecutableVariants.Empty:
+        return TransactionExecutableEmpty.load(deserializer);
+      default:
+        throw new Error(`Unknown variant index for TransactionExecutable: ${index}`);
+    }
+  }
+}
+
+export class TransactionExecutableScript extends TransactionExecutable {
+  script: Script;
+
+  constructor(script: Script) {
+    super();
+    this.script = script;
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(TransactionExecutableVariants.Script);
+    this.script.serialize(serializer);
+  }
+
+  static load(deserializer: Deserializer): TransactionExecutableScript {
+    let script = Script.deserialize(deserializer);
+    return new TransactionExecutableScript(script);
+  }
+}
+
+export class TransactionExecutableEntryFunction extends TransactionExecutable {
+  entryFunction: EntryFunction;
+
+  constructor(entryFunction: EntryFunction) {
+    super();
+    this.entryFunction = entryFunction;
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(TransactionExecutableVariants.EntryFunction);
+    this.entryFunction.serialize(serializer);
+  }
+
+  static load(deserializer: Deserializer): TransactionExecutableEntryFunction {
+    let entryFunction = EntryFunction.deserialize(deserializer);
+    return new TransactionExecutableEntryFunction(entryFunction);
+  }
+}
+
+export class TransactionExecutableEmpty extends TransactionExecutable {
+  serialize(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(TransactionExecutableVariants.Empty);
+  }
+
+  static load(_: Deserializer): TransactionExecutableEmpty {
+    return new TransactionExecutableEmpty();
+  }
+}
+
+export abstract class TransactionExtraConfig {
+  abstract serialize(serializer: Serializer): void;
+
+  static deserialize(deserializer: Deserializer): TransactionExtraConfig {
+    // index enum variant
+    const index = deserializer.deserializeUleb128AsU32();
+    switch (index) {
+      case TransactionExtraConfigVariants.V1:
+        return TransactionExtraConfigV1.load(deserializer);
+      default:
+        throw new Error(`Unknown variant index for TransactionExtraConfig: ${index}`);
+    }
+  }
+}
+
+export class TransactionExtraConfigV1 extends TransactionExtraConfig {
+  multisigAddress?: AccountAddress;
+  replayProtectionNonce?: bigint;
+
+  constructor(multisigAddress?: AccountAddress, replayProtectionNonce?: AnyNumber) {
+    super();
+    this.multisigAddress = multisigAddress;
+    this.replayProtectionNonce = replayProtectionNonce !== undefined ? BigInt(replayProtectionNonce) : undefined;
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(TransactionExtraConfigVariants.V1);
+    serializer.serializeOption<AccountAddress>(this.multisigAddress);
+    serializer.serializeOption<U64>(
+      this.replayProtectionNonce !== undefined ? new U64(this.replayProtectionNonce) : undefined,
+    );
+  }
+
+  static load(deserializer: Deserializer): TransactionExtraConfigV1 {
+    const multisigAddress = deserializer.deserializeOption(AccountAddress);
+    const replayProtectionNonce = deserializer.deserializeOption(U64);
+    return new TransactionExtraConfigV1(multisigAddress, replayProtectionNonce?.value);
+  }
+}

package/src/transactions/management/transactionWorker.ts

@@ -340,7 +340,7 @@ export class TransactionWorker extends EventEmitter<TransactionWorkerEvents> {
       aptosConfig: this.aptosConfig,
       sender: account.accountAddress,
       data: transactionData,
-      options: { ...options, accountSequenceNumber: sequenceNumber },
+      options: { ...options, accountSequenceNumber: sequenceNumber, replayProtectionNonce: undefined },
     });
   }
 

package/src/transactions/transactionBuilder/transactionBuilder.ts

@@ -24,7 +24,6 @@ import { getInfo } from "../../internal/utils";
 import { getLedgerInfo } from "../../internal/general";
 import { getGasPriceEstimation } from "../../internal/transaction";
 import { NetworkToChainId } from "../../utils/apiEndpoints";
-import { DEFAULT_MAX_GAS_AMOUNT, DEFAULT_TXN_EXP_SEC_FROM_NOW } from "../../utils/const";
 import { normalizeBundle } from "../../utils/normalizeBundle";
 import {
   AccountAuthenticator,
@@ -51,6 +50,7 @@ import {
   MultiSigTransactionPayload,
   RawTransaction,
   Script,
+  TransactionInnerPayload,
   TransactionPayloadEntryFunction,
   TransactionPayloadMultiSig,
   TransactionPayloadScript,
@@ -83,6 +83,14 @@ import { isScriptDataInput } from "./helpers";
 import { SimpleTransaction } from "../instances/simpleTransaction";
 import { MultiAgentTransaction } from "../instances/multiAgentTransaction";
 import { getFunctionParts } from "../../utils/helpers";
+import {
+  TransactionExecutable,
+  TransactionExecutableEmpty,
+  TransactionExecutableEntryFunction,
+  TransactionExecutableScript,
+  TransactionExtraConfigV1,
+  TransactionInnerPayloadV1,
+} from "../instances/transactionPayload";
 
 /**
  * Builds a transaction payload based on the provided arguments and returns a transaction payload.
@@ -360,6 +368,10 @@ export async function generateRawTransaction(args: {
 }): Promise<RawTransaction> {
   const { aptosConfig, sender, payload, options, feePayerAddress } = args;
 
+  if (options?.replayProtectionNonce !== undefined && options?.accountSequenceNumber !== undefined) {
+    throw new Error("Cannot specify both replayProtectionNonce and accountSequenceNumber in options.");
+  }
+
   const getChainId = async () => {
     if (NetworkToChainId[aptosConfig.network]) {
       return { chainId: NetworkToChainId[aptosConfig.network] };
@@ -380,6 +392,10 @@ export async function generateRawTransaction(args: {
     const getSequenceNumber = async () => {
       if (options?.accountSequenceNumber !== undefined) {
         return options.accountSequenceNumber;
+      } else if (options?.replayProtectionNonce !== undefined) {
+        // If replay nonce is provided, use it as the sequence number
+        // This is an unused value, so it's specifically to show that the sequence number is not used
+        return 0xdeadbeefn;
       }
 
       return (await getInfo({ aptosConfig, accountAddress: sender })).sequence_number;
@@ -410,16 +426,24 @@ export async function generateRawTransaction(args: {
     getSequenceNumberForAny(),
   ]);
 
-  const { maxGasAmount, gasUnitPrice, expireTimestamp } = {
-    maxGasAmount: options?.maxGasAmount ? BigInt(options.maxGasAmount) : BigInt(DEFAULT_MAX_GAS_AMOUNT),
+  const { maxGasAmount, gasUnitPrice, expireTimestamp, replayProtectionNonce } = {
+    maxGasAmount: options?.maxGasAmount ? BigInt(options.maxGasAmount) : BigInt(aptosConfig.getDefaultMaxGasAmount()),
     gasUnitPrice: options?.gasUnitPrice ?? BigInt(gasEstimate),
-    expireTimestamp: options?.expireTimestamp ?? BigInt(Math.floor(Date.now() / 1000) + DEFAULT_TXN_EXP_SEC_FROM_NOW),
+    expireTimestamp:
+      options?.expireTimestamp ?? BigInt(Math.floor(Date.now() / 1000) + aptosConfig.getDefaultTxnExpirySecFromNow()),
+    replayProtectionNonce: options?.replayProtectionNonce ? BigInt(options.replayProtectionNonce) : undefined,
   };
 
+  // If we're using replay nonce, we must convert the original payload
+  let txnPayload = payload;
+  if (replayProtectionNonce !== undefined) {
+    txnPayload = convertPayloadToInnerPayload(payload, replayProtectionNonce);
+  }
+
   return new RawTransaction(
     AccountAddress.from(sender),
     BigInt(sequenceNumber),
-    payload,
+    txnPayload,
     BigInt(maxGasAmount),
     BigInt(gasUnitPrice),
     BigInt(expireTimestamp),
@@ -427,6 +451,41 @@ export async function generateRawTransaction(args: {
   );
 }
 
+export function convertPayloadToInnerPayload(
+  payload: AnyTransactionPayloadInstance,
+  replayProtectionNonce?: bigint,
+): TransactionInnerPayload {
+  if (payload instanceof TransactionPayloadScript) {
+    return new TransactionInnerPayloadV1(
+      new TransactionExecutableScript(payload.script),
+      new TransactionExtraConfigV1(undefined, replayProtectionNonce),
+    );
+  } else if (payload instanceof TransactionPayloadEntryFunction) {
+    return new TransactionInnerPayloadV1(
+      new TransactionExecutableEntryFunction(payload.entryFunction),
+      new TransactionExtraConfigV1(undefined, replayProtectionNonce),
+    );
+  } else if (payload instanceof TransactionPayloadMultiSig) {
+    const innerPayload = payload.multiSig.transaction_payload;
+    let executable: TransactionExecutable;
+    if (innerPayload === undefined || innerPayload?.transaction_payload === undefined) {
+      executable = new TransactionExecutableEmpty();
+    } else if (innerPayload.transaction_payload instanceof EntryFunction) {
+      executable = new TransactionExecutableEntryFunction(innerPayload.transaction_payload);
+    } else {
+      // TODO For now, scripts are not supported in multi-sig transactions, so it's always entry function
+      throw new Error("Scripts are not supported in multi-sig transactions.");
+    }
+
+    return new TransactionInnerPayloadV1(
+      executable,
+      new TransactionExtraConfigV1(payload.multiSig.multisig_address, replayProtectionNonce),
+    );
+  } else {
+    throw new Error(`Unsupported payload type: ${payload}`);
+  }
+}
+
 /**
  * Generates a transaction based on the provided arguments.
  * This function can create both simple and multi-agent transactions, allowing for flexible transaction handling.

package/src/transactions/types.ts

@@ -14,8 +14,17 @@ import {
   TransactionPayloadEntryFunction,
   TransactionPayloadMultiSig,
   TransactionPayloadScript,
+  TransactionInnerPayload,
 } from "./instances";
-import { AnyNumber, HexInput, MoveFunctionGenericTypeParam, MoveFunctionId, MoveStructId, MoveValue } from "../types";
+import {
+  AnyNumber,
+  HexInput,
+  MoveFunctionGenericTypeParam,
+  MoveFunctionId,
+  MoveStructId,
+  MoveValue,
+  TransactionSubmitter,
+} from "../types";
 import { TypeTag } from "./typeTag";
 import { AccountAuthenticator } from "./authenticator/account";
 import { SimpleTransaction } from "./instances/simpleTransaction";
@@ -113,11 +122,30 @@ export type AnyRawTransactionInstance = RawTransaction | MultiAgentRawTransactio
  * @group Implementation
  * @category Transactions
  */
-export type InputGenerateTransactionOptions = {
+export type InputGenerateTransactionOptions =
+  | InputGenerateSequenceNumberTransactionOptions
+  | InputGenerateOrderlessTransactionOptions;
+
+/**
+ * Input options for generating a transaction that requires an account sequence number, which is the default method.
+ */
+export type InputGenerateSequenceNumberTransactionOptions = {
   maxGasAmount?: number;
   gasUnitPrice?: number;
   expireTimestamp?: number;
   accountSequenceNumber?: AnyNumber;
+  replayProtectionNonce?: undefined;
+};
+
+/**
+ * Input options for generating a transaction using the orderless method, which does not require an account sequence number.
+ */
+export type InputGenerateOrderlessTransactionOptions = {
+  maxGasAmount?: number;
+  gasUnitPrice?: number;
+  expireTimestamp?: number;
+  accountSequenceNumber?: undefined;
+  replayProtectionNonce: AnyNumber;
 };
 
 /**
@@ -129,7 +157,8 @@ export type InputGenerateTransactionOptions = {
 export type AnyTransactionPayloadInstance =
   | TransactionPayloadEntryFunction
   | TransactionPayloadScript
-  | TransactionPayloadMultiSig;
+  | TransactionPayloadMultiSig
+  | TransactionInnerPayload;
 
 /**
  * The data needed to generate a transaction payload for Entry Function, Script, or Multi Sig types.
@@ -449,19 +478,41 @@ export type InputGenerateTransactionData =
   | InputGenerateSingleSignerRawTransactionData
   | InputGenerateMultiAgentRawTransactionData;
 
+interface InputSubmitTransactionDataInner {
+  transaction: AnyRawTransaction;
+  senderAuthenticator: AccountAuthenticator;
+  feePayerAuthenticator?: AccountAuthenticator;
+  additionalSignersAuthenticators?: Array<AccountAuthenticator>;
+}
+
+export interface InputTransactionPluginData {
+  /**
+   * Additional parameters that will be passed to the transaction submitter plugin if
+   * configured.
+   */
+  pluginParams?: Record<string, any>;
+
+  /**
+   * You can set this to override the configured transaction submitter (if any).
+   * Conversely you can set this to null to ignore any configured transaction submitter.
+   */
+  transactionSubmitter?: TransactionSubmitter | null;
+}
+
 /**
  * Holds user data input for submitting a transaction.
  *
  * @param transaction - The raw transaction data.
  * @param senderAuthenticator - The authenticator for the sender's account.
  * @param feePayerAuthenticator - Optional authenticator for the fee payer's account.
- * @param additionalSignersAuthenticators - Optional array of authenticators for additional signers.
+ * @param additionalSignersAuthenticators - Optional array of authenticators for
+ * additional signers.
+ * @param pluginParams - Additional parameters that will be passed to the transaction
+ * submitter plugin if configured.
+ * @param transactionSubmitter - You can set this to override the configured transaction
+ * submitter (if any). Conversely you can set this to null to ignore any configured
+ * transaction submitter.
  * @group Implementation
  * @category Transactions
  */
-export interface InputSubmitTransactionData {
-  transaction: AnyRawTransaction;
-  senderAuthenticator: AccountAuthenticator;
-  feePayerAuthenticator?: AccountAuthenticator;
-  additionalSignersAuthenticators?: Array<AccountAuthenticator>;
-}
+export type InputSubmitTransactionData = InputSubmitTransactionDataInner & InputTransactionPluginData;

package/src/types/types.ts

@@ -1,6 +1,8 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
+import type { AptosConfig } from "../api";
+import { InputSubmitTransactionData } from "../transactions";
 import { Network } from "../utils/apiEndpoints";
 import { OrderBy, TokenStandard } from "./indexer";
 
@@ -73,6 +75,35 @@ export enum TransactionPayloadVariants {
   Script = 0,
   EntryFunction = 2,
   Multisig = 3,
+  Payload = 4,
+}
+
+/**
+ * The inner payload type to support orderless transactions and all future transaction types.
+ * {@link https://github.com/aptos-labs/aptos-core/blob/main/types/src/transaction/mod.rs#L478}
+ */
+export enum TransactionInnerPayloadVariants {
+  V1 = 0,
+}
+
+/**
+ * Executable types for transactions, which can be either a script or an entry function.
+ *
+ * Empty is reserved for Multisig voting transactions, which do not have an executable payload.
+ * {@link https://github.com/aptos-labs/aptos-core/blob/main/types/src/transaction/mod.rs#L685}
+ */
+export enum TransactionExecutableVariants {
+  Script = 0,
+  EntryFunction = 1,
+  Empty = 2,
+}
+
+/**
+ * Variants of transaction extra configurations, which can include additional settings or parameters.
+ * {@link https://github.com/aptos-labs/aptos-core/blob/main/types/src/transaction/mod.rs#L737}
+ */
+export enum TransactionExtraConfigVariants {
+  V1 = 0,
 }
 
 /**
@@ -225,6 +256,10 @@ export type AptosSettings = {
   readonly indexerConfig?: IndexerConfig;
 
   readonly faucetConfig?: FaucetConfig;
+
+  readonly transactionGenerationConfig?: TransactionGenerationConfig;
+
+  readonly pluginSettings?: PluginSettings;
 };
 
 /**
@@ -293,6 +328,14 @@ export type FaucetConfig = ClientHeadersType & {
   AUTH_TOKEN?: string;
 };
 
+/**
+ * A configuration object for default parameters for transaction generation.
+ */
+export type TransactionGenerationConfig = {
+  defaultMaxGasAmount?: number;
+  defaultTxnExpirySecFromNow?: number;
+};
+
 /**
  * General type definition for client headers.
  */
@@ -300,6 +343,73 @@ export type ClientHeadersType = {
   HEADERS?: Record<string, string | number | boolean>;
 };
 
+/**
+ * Config for plugins. This can be used to override certain client behavior.
+ */
+export type PluginConfig = {
+  /**
+   * If given, this will be used for submitting transactions instead of the default
+   * implementation (which submits transactions directly via a node).
+   */
+  TRANSACTION_SUBMITTER?: TransactionSubmitter;
+
+  /**
+   * If true, we won't use the TRANSACTION_SUBMITTER if set.
+   */
+  IGNORE_TRANSACTION_SUBMITTER?: boolean;
+};
+
+export type PluginSettings = Omit<PluginConfig, "IGNORE_TRANSACTION_SUBMITTER">;
+
+/**
+ * You can implement this interface and set it in {@link PluginSettings} when building a
+ * client to override the default transaction submission behavior. This is useful if
+ * you'd like to submit transactions via a gas station for example.
+ *
+ * @example
+ * ```typescript
+ * class MyGasStationClient implements TransactionSubmitter {
+ *   async submitTransaction(
+ *     args: { aptosConfig: AptosConfig } & InputSubmitTransactionData,
+ *   ): Promise<PendingTransactionResponse> {
+ *     // TODO: Implement the logic to submit the transaction to the gas station
+ *   }
+ * }
+ *
+ * const network = Network.MAINNET;
+ * const myGasStationClient = new MyGasStationClient(network);
+ * const config = new AptosConfig({
+ *   network,
+ *   pluginConfig: {
+ *     transactionSubmitter: myGasStationClient,
+ *   },
+ * });
+ * const aptos = new Aptos(config);
+ * ```
+ */
+export interface TransactionSubmitter {
+  /**
+   * Submit a transaction to the Aptos blockchain or something that will do it on your
+   * behalf, for example a gas station. See the comments of {@link TransactionSubmitter} for more.
+   *
+   * @param args - The arguments for submitting the transaction.
+   * @param args.aptosConfig - The configuration for connecting to the Aptos network.
+   * @param args.transaction - The Aptos transaction data to be submitted.
+   * @param args.senderAuthenticator - The account authenticator of the transaction sender.
+   * @param args.secondarySignerAuthenticators - Optional. Authenticators for additional signers in a multi-signer transaction.
+   * @param args.pluginParams - Optional. Additional parameters for the plugin.
+   * @param args.transactionSubmitter - Optional. An override for the transaction submitter.
+   *
+   * @returns PendingTransactionResponse - The response containing the status of the submitted transaction.
+   * @group Implementation
+   */
+  submitTransaction(
+    args: {
+      aptosConfig: AptosConfig;
+    } & Omit<InputSubmitTransactionData, "transactionSubmitter">,
+  ): Promise<PendingTransactionResponse>;
+}
+
 /**
  * Represents a client for making requests to a service provider.
  *
@@ -593,6 +703,7 @@ export type UserTransactionResponse = {
   changes: Array<WriteSetChange>;
   sender: string;
   sequence_number: string;
+  replay_protection_nonce: string;
   max_gas_amount: string;
   gas_unit_price: string;
   expiration_timestamp_secs: string;

package/src/version.ts

@@ -6,4 +6,4 @@
  *
  * hardcoded for now, we would want to have it injected dynamically
  */
-export const VERSION = "2.0.1";
+export const VERSION = "3.0.0";