@aptos-labs/ts-sdk 1.33.0 → 1.33.2-sc.0

package/src/api/transactionSubmission/sign.ts

@@ -10,6 +10,7 @@ import { AptosConfig } from "../aptosConfig";
  * A class to handle all `Sign` transaction operations.
  *
  * @param config - The configuration object for Aptos.
+ * @group Implementation
  */
 export class Sign {
   readonly config: AptosConfig;
@@ -32,6 +33,7 @@ export class Sign {
    * }
    * runExample().catch(console.error);
    * ```
+   * @group Implementation
    */
   constructor(config: AptosConfig) {
     this.config = config;
@@ -72,6 +74,7 @@ export class Sign {
    * }
    * runExample().catch(console.error);
    * ```
+   * @group Implementation
    */
   // eslint-disable-next-line class-methods-use-this
   transaction(args: { signer: Account; transaction: AnyRawTransaction }): AccountAuthenticator {
@@ -116,6 +119,7 @@ export class Sign {
    * }
    * runExample().catch(console.error);
    * ```
+   * @group Implementation
    */
   // eslint-disable-next-line class-methods-use-this
   transactionAsFeePayer(args: { signer: Account; transaction: AnyRawTransaction }): AccountAuthenticator {

package/src/api/transactionSubmission/simulate.ts

@@ -10,6 +10,7 @@ import { ValidateFeePayerDataOnSimulation } from "./helpers";
 
 /**
  * A class to handle all `Simulate` transaction operations.
+ * @group Implementation
  */
 export class Simulate {
   readonly config: AptosConfig;
@@ -37,6 +38,7 @@ export class Simulate {
    * }
    * runExample().catch(console.error);
    * ```
+   * @group Implementation
    */
   constructor(config: AptosConfig) {
     this.config = config;
@@ -97,6 +99,7 @@ export class Simulate {
    *
    * example();
    * ```
+   * @group Implementation
    */
   @ValidateFeePayerDataOnSimulation
   async simple(args: {
@@ -174,6 +177,7 @@ export class Simulate {
    *
    * example();
    * ```
+   * @group Implementation
    */
   @ValidateFeePayerDataOnSimulation
   async multiAgent(args: {

package/src/api/transactionSubmission/submit.ts

@@ -9,6 +9,7 @@ import { ValidateFeePayerDataOnSubmission } from "./helpers";
 
 /**
  * A class to handle all `Submit` transaction operations.
+ * @group Implementation
  */
 export class Submit {
   readonly config: AptosConfig;
@@ -41,6 +42,7 @@ export class Submit {
    * }
    * runExample().catch(console.error);
    * ```
+   * @group Implementation
    */
   constructor(config: AptosConfig) {
     this.config = config;
@@ -82,6 +84,7 @@ export class Submit {
    * }
    * runExample().catch(console.error);
    * ```
+   * @group Implementation
    */
   @ValidateFeePayerDataOnSubmission
   async simple(args: {
@@ -135,6 +138,7 @@ export class Submit {
    * }
    * runExample().catch(console.error);
    * ```
+   * @group Implementation
    */
   @ValidateFeePayerDataOnSubmission
   async multiAgent(args: {

package/src/api/utils.ts

@@ -31,6 +31,7 @@ import { AnyNumber } from "../types";
  * }
  * runExample().catch(console.error);
  * ```
+ * @group Implementation
  */
 export async function waitForIndexerOnVersion(args: {
   config: AptosConfig;

package/src/bcs/deserializer.ts

@@ -3,7 +3,8 @@
 
 /* eslint-disable no-bitwise */
 import { MAX_U32_NUMBER } from "./consts";
-import { Uint8, Uint16, Uint32, Uint64, Uint128, Uint256 } from "../types";
+import { Uint8, Uint16, Uint32, Uint64, Uint128, Uint256, HexInput } from "../types";
+import { Hex } from "../core/hex";
 
 /**
  * This interface exists to define Deserializable<T> inputs for functions that
@@ -12,6 +13,8 @@ import { Uint8, Uint16, Uint32, Uint64, Uint128, Uint256 } from "../types";
  * for static methods in interfaces.
  *
  * @template T - The type that this will deserialize into.
+ * @group Implementation
+ * @category BCS
  */
 export interface Deserializable<T> {
   /**
@@ -28,6 +31,8 @@ export interface Deserializable<T> {
    * // value is now an instance of MyClass
    * // equivalent to `const value = MyClass.deserialize(deserializer)`
    * ```
+   * @group Implementation
+   * @category BCS
    */
   deserialize(deserializer: Deserializer): T;
 }
@@ -35,6 +40,8 @@ export interface Deserializable<T> {
 /**
  * A class that provides methods for deserializing various data types from a byte buffer.
  * It supports deserialization of primitive types, strings, and complex objects using a BCS (Binary Common Serialization) layout.
+ * @group Implementation
+ * @category BCS
  */
 export class Deserializer {
   private buffer: ArrayBuffer;
@@ -46,6 +53,8 @@ export class Deserializer {
    * This prevents outside mutation of the buffer.
    *
    * @param data - The data to be copied into the internal buffer as a Uint8Array.
+   * @group Implementation
+   * @category BCS
    */
   constructor(data: Uint8Array) {
     // copies data to prevent outside mutation of buffer.
@@ -54,11 +63,18 @@ export class Deserializer {
     this.offset = 0;
   }
 
+  static fromHex(hex: HexInput): Deserializer {
+    const data = Hex.hexInputToUint8Array(hex);
+    return new Deserializer(data);
+  }
+
   /**
    * Reads a specified number of bytes from the buffer and advances the offset.
    *
    * @param length - The number of bytes to read from the buffer.
    * @throws Throws an error if the read operation exceeds the buffer's length.
+   * @group Implementation
+   * @category BCS
    */
   private read(length: number): ArrayBuffer {
     if (this.offset + length > this.buffer.byteLength) {
@@ -76,13 +92,14 @@ export class Deserializer {
    * This information is useful to determine if there's more data to be read.
    *
    * @returns The number of bytes remaining in the buffer.
+   * @group Implementation
+   * @category BCS
    */
   remaining(): number {
     return this.buffer.byteLength - this.offset;
   }
 
   /**
-   * @deprecated use `deserializeOption` instead.
    * Deserializes a UTF-8 encoded string from a byte array. It first reads the length of the string in bytes,
    * followed by the actual byte content, and decodes it into a string.
    *
@@ -94,6 +111,8 @@ export class Deserializer {
    * const deserializer = new Deserializer(new Uint8Array([8, 49, 50, 51, 52, 97, 98, 99, 100]));
    * assert(deserializer.deserializeStr() === "1234abcd");
    * ```
+   * @group Implementation
+   * @category BCS
    */
   deserializeStr(): string {
     const value = this.deserializeBytes();
@@ -101,6 +120,23 @@ export class Deserializer {
     return textDecoder.decode(value);
   }
 
+  /**
+   * @deprecated use `deserializeOption("string")` instead.
+   *
+   * The BCS layout for Optional<String> is 0 if none, else 1 followed by the string length and string content.
+   * @returns The deserialized string if it exists, otherwise undefined.
+   * @example
+   * ```typescript
+   * const deserializer = new Deserializer(new Uint8Array([0x00]));
+   * assert(deserializer.deserializeOptionStr() === undefined);
+   * const deserializer = new Deserializer(new Uint8Array([1, 8, 49, 50, 51, 52, 97, 98, 99, 100]));
+   * assert(deserializer.deserializeOptionStr() === "1234abcd");
+   * ```
+   */
+  deserializeOptionStr(): string | undefined {
+    return this.deserializeOption("string");
+  }
+
   /**
    * Deserializes an optional value from the buffer.
    *
@@ -136,6 +172,8 @@ export class Deserializer {
    * const optBytes = deserializer.deserializeOption("fixedBytes", 4);
    * // optBytes === Uint8Array[1, 2, 3, 4]
    * ```
+   * @group Implementation
+   * @category BCS
    */
   deserializeOption(type: "string"): string | undefined;
   deserializeOption(type: "bytes"): Uint8Array | undefined;
@@ -171,6 +209,8 @@ export class Deserializer {
    * encoded as a uleb128 integer, indicating the length of the bytes array.
    *
    * @returns {Uint8Array} The deserialized array of bytes.
+   * @group Implementation
+   * @category BCS
    */
   deserializeBytes(): Uint8Array {
     const len = this.deserializeUleb128AsU32();
@@ -181,6 +221,8 @@ export class Deserializer {
    * Deserializes an array of bytes of a specified length.
    *
    * @param len - The number of bytes to read from the source.
+   * @group Implementation
+   * @category BCS
    */
   deserializeFixedBytes(len: number): Uint8Array {
     return new Uint8Array(this.read(len));
@@ -194,6 +236,8 @@ export class Deserializer {
    *
    * @returns The deserialized boolean value.
    * @throws Throws an error if the boolean value is invalid.
+   * @group Implementation
+   * @category BCS
    */
   deserializeBool(): boolean {
     const bool = new Uint8Array(this.read(1))[0];
@@ -209,6 +253,8 @@ export class Deserializer {
    * BCS layout for "uint8": One byte. Binary format in little-endian representation.
    *
    * @returns {number} The deserialized uint8 number.
+   * @group Implementation
+   * @category BCS
    */
   deserializeU8(): Uint8 {
     return new DataView(this.read(1)).getUint8(0);
@@ -223,6 +269,8 @@ export class Deserializer {
    * const deserializer = new Deserializer(new Uint8Array([0x34, 0x12]));
    * assert(deserializer.deserializeU16() === 4660);
    * ```
+   * @group Implementation
+   * @category BCS
    */
   deserializeU16(): Uint16 {
     return new DataView(this.read(2)).getUint16(0, true);
@@ -237,6 +285,8 @@ export class Deserializer {
    * const deserializer = new Deserializer(new Uint8Array([0x78, 0x56, 0x34, 0x12]));
    * assert(deserializer.deserializeU32() === 305419896);
    * ```
+   * @group Implementation
+   * @category BCS
    */
   deserializeU32(): Uint32 {
     return new DataView(this.read(4)).getUint32(0, true);
@@ -251,6 +301,8 @@ export class Deserializer {
    * const deserializer = new Deserializer(new Uint8Array([0x00, 0xEF, 0xCD, 0xAB, 0x78, 0x56, 0x34, 0x12]));
    * assert(deserializer.deserializeU64() === 1311768467750121216);
    * ```
+   * @group Implementation
+   * @category BCS
    */
   deserializeU64(): Uint64 {
     const low = this.deserializeU32();
@@ -265,6 +317,8 @@ export class Deserializer {
    * This function combines two 64-bit values to return a single uint128 value in little-endian format.
    *
    * @returns {BigInt} The deserialized uint128 number.
+   * @group Implementation
+   * @category BCS
    */
   deserializeU128(): Uint128 {
     const low = this.deserializeU64();
@@ -280,6 +334,8 @@ export class Deserializer {
    * The BCS layout for "uint256" consists of thirty-two bytes in little-endian format.
    *
    * @returns {BigInt} The deserialized uint256 number.
+   * @group Implementation
+   * @category BCS
    */
   deserializeU256(): Uint256 {
     const low = this.deserializeU128();
@@ -296,6 +352,8 @@ export class Deserializer {
    *
    * @throws {Error} Throws an error if the parsed value exceeds the maximum uint32 number.
    * @returns {number} The deserialized uint32 value.
+   * @group Implementation
+   * @category BCS
    */
   deserializeUleb128AsU32(): Uint32 {
     let value: bigint = BigInt(0);
@@ -330,6 +388,8 @@ export class Deserializer {
    * @param cls The BCS-deserializable class to deserialize the buffered bytes into.
    *
    * @returns the deserialized value of class type T
+   * @group Implementation
+   * @category BCS
    */
   deserialize<T>(cls: Deserializable<T>): T {
     // NOTE: `deserialize` in `cls.deserialize(this)` here is a static method defined in `cls`,
@@ -358,6 +418,8 @@ export class Deserializer {
    * const deserializer = new Deserializer(serializedBytes);
    * const deserializedAddresses = deserializer.deserializeVector(AccountAddress);
    * // deserializedAddresses is now an array of AccountAddress instances
+   * @group Implementation
+   * @category BCS
    */
   deserializeVector<T>(cls: Deserializable<T>): Array<T> {
     const length = this.deserializeUleb128AsU32();

package/src/bcs/serializable/entryFunctionBytes.ts

@@ -16,6 +16,8 @@ import { HexInput } from "../../types";
  * If you wish to convert this class back to a TransactionArgument, you must know the type
  * of the argument beforehand, and use the appropriate class to deserialize the bytes within
  * an instance of this class.
+ * @group Implementation
+ * @category BCS
  */
 export class EntryFunctionBytes extends Serializable implements EntryFunctionArgument {
   public readonly value: FixedBytes;
@@ -24,6 +26,8 @@ export class EntryFunctionBytes extends Serializable implements EntryFunctionArg
    * Creates an instance of the class with a specified hexadecimal input value.
    *
    * @param value - The hexadecimal input to be converted into FixedBytes.
+   * @group Implementation
+   * @category BCS
    */
   private constructor(value: HexInput) {
     super();
@@ -45,6 +49,8 @@ export class EntryFunctionBytes extends Serializable implements EntryFunctionArg
    * we must not serialize the length prefix.
    *
    * @param serializer - The serializer instance used to perform the serialization.
+   * @group Implementation
+   * @category BCS
    */
   serialize(serializer: Serializer): void {
     serializer.serialize(this.value);
@@ -62,6 +68,8 @@ export class EntryFunctionBytes extends Serializable implements EntryFunctionArg
    * This process includes serializing the length prefix of the byte vector.
    *
    * @param serializer - The serializer instance used to perform the serialization.
+   * @group Implementation
+   * @category BCS
    */
   serializeForEntryFunction(serializer: Serializer): void {
     serializer.serializeU32AsUleb128(this.value.value.length);
@@ -74,6 +82,8 @@ export class EntryFunctionBytes extends Serializable implements EntryFunctionArg
    * @param deserializer - The deserializer instance with the buffered bytes.
    * @param length - The length of the bytes to deserialize.
    * @returns An instance of this class, which will now only be usable as an EntryFunctionArgument.
+   * @group Implementation
+   * @category BCS
    */
   static deserialize(deserializer: Deserializer, length: number): EntryFunctionBytes {
     const fixedBytes = FixedBytes.deserialize(deserializer, length);

package/src/bcs/serializable/fixedBytes.ts

@@ -36,6 +36,8 @@ import { TransactionArgument } from "../../transactions/instances/transactionArg
  * @param value - HexInput representing a sequence of Uint8 bytes.
  * @returns A Serializable FixedBytes instance, which when serialized, does not prepend the length of the bytes.
  * @see EntryFunctionBytes
+ * @group Implementation
+ * @category BCS
  */
 export class FixedBytes extends Serializable implements TransactionArgument {
   public value: Uint8Array;
@@ -45,6 +47,8 @@ export class FixedBytes extends Serializable implements TransactionArgument {
    * The value is converted from hexadecimal format to a Uint8Array.
    *
    * @param value - The hexadecimal input to be converted.
+   * @group Implementation
+   * @category BCS
    */
   constructor(value: HexInput) {
     super();
@@ -56,6 +60,8 @@ export class FixedBytes extends Serializable implements TransactionArgument {
    * This function is essential for converting the fixed bytes into a format suitable for storage or transmission.
    *
    * @param serializer - The serializer instance used for serialization.
+   * @group Implementation
+   * @category BCS
    */
   serialize(serializer: Serializer): void {
     serializer.serializeFixedBytes(this.value);
@@ -66,6 +72,8 @@ export class FixedBytes extends Serializable implements TransactionArgument {
    * This allows the instance to be converted into a format suitable for transmission or storage.
    *
    * @param serializer - The serializer used to perform the serialization.
+   * @group Implementation
+   * @category BCS
    */
   serializeForEntryFunction(serializer: Serializer): void {
     serializer.serialize(this);
@@ -76,6 +84,8 @@ export class FixedBytes extends Serializable implements TransactionArgument {
    * This function is essential for preparing data to be passed as arguments in script functions.
    *
    * @param serializer - The serializer instance used to perform the serialization.
+   * @group Implementation
+   * @category BCS
    */
   serializeForScriptFunction(serializer: Serializer): void {
     serializer.serialize(this);
@@ -87,6 +97,8 @@ export class FixedBytes extends Serializable implements TransactionArgument {
    *
    * @param deserializer - The deserializer instance used to read the byte data.
    * @param length - The length of the byte array to be deserialized.
+   * @group Implementation
+   * @category BCS
    */
   static deserialize(deserializer: Deserializer, length: number): FixedBytes {
     const bytes = deserializer.deserializeFixedBytes(length);

package/src/bcs/serializable/movePrimitives.ts

@@ -20,6 +20,8 @@ import { AnyNumber, Uint16, Uint32, Uint8, ScriptTransactionArgumentVariants } f
  * the boolean value for different contexts, such as entry functions and script functions.
  *
  * @extends Serializable
+ * @group Implementation
+ * @category BCS
  */
 export class Bool extends Serializable implements TransactionArgument {
   public readonly value: boolean;
@@ -29,6 +31,8 @@ export class Bool extends Serializable implements TransactionArgument {
    * This ensures that the value is validated to be within the acceptable range.
    *
    * @param value - The number to be validated and assigned, which must be between 0 and MAX_U256_BIG_INT.
+   * @group Implementation
+   * @category BCS
    */
   constructor(value: boolean) {
     super();
@@ -39,6 +43,8 @@ export class Bool extends Serializable implements TransactionArgument {
      *
      * @param value - The value to be checked for boolean type.
      * @throws {Error} Throws an error if the value is not a boolean.
+     * @group Implementation
+     * @category BCS
      */
     ensureBoolean(value);
     this.value = value;
@@ -49,6 +55,8 @@ export class Bool extends Serializable implements TransactionArgument {
    * This function is essential for converting the value into a format suitable for transmission or storage.
    *
    * @param serializer - The serializer instance used to perform the serialization.
+   * @group Implementation
+   * @category BCS
    */
   serialize(serializer: Serializer): void {
     serializer.serializeBool(this.value);
@@ -59,6 +67,8 @@ export class Bool extends Serializable implements TransactionArgument {
    * This allows the instance to be properly formatted for serialization in transactions.
    *
    * @param serializer - The serializer instance used to serialize the byte sequence.
+   * @group Implementation
+   * @category BCS
    */
   serializeForEntryFunction(serializer: Serializer): void {
     const bcsBytes = this.bcsToBytes();
@@ -70,6 +80,8 @@ export class Bool extends Serializable implements TransactionArgument {
    * This allows for the conversion of the instance into a format suitable for transmission or storage.
    *
    * @param serializer - The serializer used to perform the serialization.
+   * @group Implementation
+   * @category BCS
    */
   serializeForScriptFunction(serializer: Serializer): void {
     serializer.serializeU32AsUleb128(ScriptTransactionArgumentVariants.Bool);
@@ -80,6 +92,8 @@ export class Bool extends Serializable implements TransactionArgument {
    * Deserializes a U256 value from the provided deserializer.
    *
    * @param deserializer - The deserializer instance used to read the U256 data.
+   * @group Implementation
+   * @category BCS
    */
   // eslint-disable-next-line class-methods-use-this
   deserialize(deserializer: Deserializer) {
@@ -96,6 +110,8 @@ export class Bool extends Serializable implements TransactionArgument {
  * This class extends the Serializable class and provides methods for serialization and deserialization of U8 values.
  *
  * @extends Serializable
+ * @group Implementation
+ * @category BCS
  */
 export class U8 extends Serializable implements TransactionArgument {
   public readonly value: Uint8;
@@ -131,6 +147,8 @@ export class U8 extends Serializable implements TransactionArgument {
  * and deserialization of the U16 value.
  *
  * @extends Serializable
+ * @group Implementation
+ * @category BCS
  */
 export class U16 extends Serializable implements TransactionArgument {
   public readonly value: Uint16;
@@ -165,6 +183,8 @@ export class U16 extends Serializable implements TransactionArgument {
  * This class ensures that the value is within the valid range for a U32.
  *
  * @extends Serializable
+ * @group Implementation
+ * @category BCS
  */
 export class U32 extends Serializable implements TransactionArgument {
   public readonly value: Uint32;
@@ -202,6 +222,8 @@ export class U32 extends Serializable implements TransactionArgument {
  * and script functions.
  *
  * @extends Serializable
+ * @group Implementation
+ * @category BCS
  */
 export class U64 extends Serializable implements TransactionArgument {
   public readonly value: bigint;
@@ -237,6 +259,8 @@ export class U64 extends Serializable implements TransactionArgument {
  * of U128 values, ensuring that the values are within the valid range.
  *
  * @extends Serializable
+ * @group Implementation
+ * @category BCS
  */
 export class U128 extends Serializable implements TransactionArgument {
   public readonly value: bigint;
@@ -272,6 +296,8 @@ export class U128 extends Serializable implements TransactionArgument {
  * ensuring that the values are within the valid range.
  *
  * @extends Serializable
+ * @group Implementation
+ * @category BCS
  */
 export class U256 extends Serializable implements TransactionArgument {
   public readonly value: bigint;