@aptos-labs/ts-sdk 1.29.1 → 1.31.0

package/src/bcs/serializer.ts

@@ -13,16 +13,18 @@ import {
 import { Hex } from "../core/hex";
 import { AnyNumber, Uint16, Uint32, Uint8 } from "../types";
 
-// This class is intended to be used as a base class for all serializable types.
-// It can be used to facilitate composable serialization of a complex type and
-// in general to serialize a type to its BCS representation.
+/**
+ * This class serves as a base class for all serializable types. It facilitates
+ * composable serialization of complex types and enables the serialization of
+ * instances to their BCS (Binary Canonical Serialization) representation.
+ */
 export abstract class Serializable {
   abstract serialize(serializer: Serializer): void;
 
   /**
    * Serializes a `Serializable` value to its BCS representation.
-   * This function is the Typescript SDK equivalent of `bcs::to_bytes` in Move.
-   * @returns the BCS representation of the Serializable instance as a byte buffer
+   * This function is the TypeScript SDK equivalent of `bcs::to_bytes` in Move.
+   * @returns the BCS representation of the Serializable instance as a byte buffer.
    */
   bcsToBytes(): Uint8Array {
     const serializer = new Serializer();
@@ -31,22 +33,49 @@ export abstract class Serializable {
   }
 
   /**
-   * Helper function to get a value's BCS-serialized bytes as a Hex instance.
-   * @returns a Hex instance with the BCS-serialized bytes loaded into its underlying Uint8Array
+   * Converts the BCS-serialized bytes of a value into a Hex instance.
+   * This function provides a Hex representation of the BCS-serialized data for easier handling and manipulation.
+   * @returns A Hex instance with the BCS-serialized bytes loaded into its underlying Uint8Array.
    */
   bcsToHex(): Hex {
     const bcsBytes = this.bcsToBytes();
     return Hex.fromHexInput(bcsBytes);
   }
+
+  /**
+   * Returns the hex string representation of the `Serializable` value without the 0x prefix.
+   * @returns the hex format as a string without `0x` prefix.
+   */
+  toStringWithoutPrefix(): string {
+    return this.bcsToHex().toStringWithoutPrefix();
+  }
+
+  /**
+   * Returns the hex string representation of the `Serializable` value with the 0x prefix.
+   * @returns the hex formatas a string prefixed by `0x`.
+   */
+  toString(): string {
+    return `0x${this.toStringWithoutPrefix()}`;
+  }
 }
 
+/**
+ * A class for serializing various data types into a binary format.
+ * It provides methods to serialize strings, bytes, numbers, and other serializable objects
+ * using the Binary Coded Serialization (BCS) layout. The serialized data can be retrieved as a
+ * Uint8Array.
+ */
 export class Serializer {
   private buffer: ArrayBuffer;
 
   private offset: number;
 
-  // Constructs a serializer with a buffer of size `length` bytes, 64 bytes by default.
-  // `length` must be greater than 0.
+  /**
+   * Constructs a serializer with a buffer of size `length` bytes, 64 bytes by default.
+   * The `length` must be greater than 0.
+   *
+   * @param length - The size of the buffer in bytes.
+   */
   constructor(length: number = 64) {
     if (length <= 0) {
       throw new Error("Length needs to be greater than 0");
@@ -55,6 +84,12 @@ export class Serializer {
     this.offset = 0;
   }
 
+  /**
+   * Ensures that the internal buffer can accommodate the specified number of bytes.
+   * This function dynamically resizes the buffer if the current size is insufficient.
+   *
+   * @param bytes - The number of bytes to ensure the buffer can handle.
+   */
   private ensureBufferWillHandleSize(bytes: number) {
     while (this.buffer.byteLength < this.offset + bytes) {
       const newBuffer = new ArrayBuffer(this.buffer.byteLength * 2);
@@ -63,12 +98,26 @@ export class Serializer {
     }
   }
 
+  /**
+   * Appends the specified values to the buffer, ensuring that the buffer can accommodate the new data.
+   *
+   * @param {Uint8Array} values - The values to be appended to the buffer.
+   */
   protected appendToBuffer(values: Uint8Array) {
     this.ensureBufferWillHandleSize(values.length);
     new Uint8Array(this.buffer, this.offset).set(values);
     this.offset += values.length;
   }
 
+  /**
+   * Serializes a value into the buffer using the provided function, ensuring the buffer can accommodate the size.
+   *
+   * @param fn - The function to serialize the value, which takes a byte offset, the value to serialize, and an optional little-endian flag.
+   * @param fn.byteOffset - The byte offset at which to write the value.
+   * @param fn.value - The numeric value to serialize into the buffer.
+   * @param fn.littleEndian - Optional flag indicating whether to use little-endian byte order (defaults to true).
+   */
+  // TODO: JSDoc bytesLength and value
   private serializeWithFunction(
     fn: (byteOffset: number, value: number, littleEndian?: boolean) => void,
     bytesLength: number,
@@ -82,15 +131,16 @@ export class Serializer {
 
   /**
    * Serializes a string. UTF8 string is supported.
-   *
    * The number of bytes in the string content is serialized first, as a uleb128-encoded u32 integer.
    * Then the string content is serialized as UTF8 encoded bytes.
    *
    * BCS layout for "string": string_length | string_content
    * where string_length is a u32 integer encoded as a uleb128 integer, equal to the number of bytes in string_content.
    *
+   * @param value - The string to serialize.
+   *
    * @example
-   * ```ts
+   * ```typescript
    * const serializer = new Serializer();
    * serializer.serializeStr("1234abcd");
    * assert(serializer.toUint8Array() === new Uint8Array([8, 49, 50, 51, 52, 97, 98, 99, 100]));
@@ -104,8 +154,10 @@ export class Serializer {
   /**
    * Serializes an array of bytes.
    *
+   * This function encodes the length of the byte array as a u32 integer in uleb128 format, followed by the byte array itself.
    * BCS layout for "bytes": bytes_length | bytes
    * where bytes_length is a u32 integer encoded as a uleb128 integer, equal to the length of the bytes array.
+   * @param value - The byte array to serialize.
    */
   serializeBytes(value: Uint8Array) {
     this.serializeU32AsUleb128(value.length);
@@ -113,30 +165,41 @@ export class Serializer {
   }
 
   /**
-   * Serializes an array of bytes with known length. Therefore, length doesn't need to be
-   * serialized to help deserialization.
-   *
+   * Serializes an array of bytes with a known length, allowing for efficient deserialization without needing to serialize the
+   * length itself.
    * When deserializing, the number of bytes to deserialize needs to be passed in.
+
+   * @param value - The Uint8Array to be serialized.
    */
   serializeFixedBytes(value: Uint8Array) {
     this.appendToBuffer(value);
   }
 
   /**
-   * Serializes a boolean value.
+   * Serializes a boolean value into a byte representation.
+   *
+   * The BCS layout for a boolean uses one byte, where "0x01" represents true and "0x00" represents false.
    *
-   * BCS layout for "boolean": One byte. "0x01" for true and "0x00" for false.
+   * @param value - The boolean value to serialize.
    */
   serializeBool(value: boolean) {
+    /**
+     * Ensures that the provided value is a boolean.
+     * This function throws an error if the value is not a boolean, helping to enforce type safety in your code.
+     *
+     * @param value - The value to be checked for boolean type.
+     * @throws {Error} Throws an error if the value is not a boolean.
+     */
     ensureBoolean(value);
     const byteValue = value ? 1 : 0;
     this.appendToBuffer(new Uint8Array([byteValue]));
   }
 
   /**
-   * Serializes a uint8 number.
-   *
+   * Serializes a Uint8 value and appends it to the buffer.
    * BCS layout for "uint8": One byte. Binary format in little-endian representation.
+   *
+   * @param value - The Uint8 value to serialize.
    */
   @checkNumberRange(0, MAX_U8_NUMBER)
   serializeU8(value: Uint8) {
@@ -146,9 +209,16 @@ export class Serializer {
   /**
    * Serializes a uint16 number.
    *
+
+   */
+
+  /**
+   * Serializes a 16-bit unsigned integer value into a binary format.
    * BCS layout for "uint16": Two bytes. Binary format in little-endian representation.
+   *
+   * @param value - The 16-bit unsigned integer value to serialize.
    * @example
-   * ```ts
+   * ```typescript
    * const serializer = new Serializer();
    * serializer.serializeU16(4660);
    * assert(serializer.toUint8Array() === new Uint8Array([0x34, 0x12]));
@@ -160,15 +230,15 @@ export class Serializer {
   }
 
   /**
-   * Serializes a uint32 number.
-   *
-   * BCS layout for "uint32": Four bytes. Binary format in little-endian representation.
+   * Serializes a 32-bit unsigned integer value into a binary format.
+   * This function is useful for encoding data that needs to be stored or transmitted in a compact form.
    * @example
-   * ```ts
+   * ```typescript
    * const serializer = new Serializer();
    * serializer.serializeU32(305419896);
    * assert(serializer.toUint8Array() === new Uint8Array([0x78, 0x56, 0x34, 0x12]));
    * ```
+   * @param value - The 32-bit unsigned integer value to serialize.
    */
   @checkNumberRange(0, MAX_U32_NUMBER)
   serializeU32(value: Uint32) {
@@ -176,9 +246,10 @@ export class Serializer {
   }
 
   /**
-   * Serializes a uint64 number.
+   * Serializes a 64-bit unsigned integer into a format suitable for storage or transmission.
+   * This function breaks down the value into two 32-bit components and writes them in little-endian order.
    *
-   * BCS layout for "uint64": Eight bytes. Binary format in little-endian representation.
+   * @param value - The 64-bit unsigned integer to serialize, represented as a number.
    * @example
    * ```ts
    * const serializer = new Serializer();
@@ -197,9 +268,9 @@ export class Serializer {
   }
 
   /**
-   * Serializes a uint128 number.
+   * Serializes a U128 value into a format suitable for storage or transmission.
    *
-   * BCS layout for "uint128": Sixteen bytes. Binary format in little-endian representation.
+   * @param value - The U128 value to serialize, represented as a number.
    */
   @checkNumberRange(BigInt(0), MAX_U128_BIG_INT)
   serializeU128(value: AnyNumber) {
@@ -212,9 +283,10 @@ export class Serializer {
   }
 
   /**
-   * Serializes a uint256 number.
+   * Serializes a U256 value into a byte representation.
+   * This function is essential for encoding large numbers in a compact format suitable for transmission or storage.
    *
-   * BCS layout for "uint256": Sixteen bytes. Binary format in little-endian representation.
+   * @param value - The U256 value to serialize, represented as an AnyNumber.
    */
   @checkNumberRange(BigInt(0), MAX_U256_BIG_INT)
   serializeU256(value: AnyNumber) {
@@ -227,9 +299,10 @@ export class Serializer {
   }
 
   /**
-   * Serializes a uint32 number with uleb128.
-   *
+   * Serializes a 32-bit unsigned integer as a variable-length ULEB128 encoded byte array.
    * BCS uses uleb128 encoding in two cases: (1) lengths of variable-length sequences and (2) tags of enum values
+   *
+   * @param val - The 32-bit unsigned integer value to be serialized.
    */
   @checkNumberRange(0, MAX_U32_NUMBER)
   serializeU32AsUleb128(val: Uint32) {
@@ -244,7 +317,11 @@ export class Serializer {
   }
 
   /**
-   * Returns the buffered bytes
+   * Returns the buffered bytes as a Uint8Array.
+   *
+   * This function allows you to retrieve the byte representation of the buffer up to the current offset.
+   *
+   * @returns Uint8Array - The byte array representation of the buffer.
    */
   toUint8Array(): Uint8Array {
     return new Uint8Array(this.buffer).slice(0, this.offset);
@@ -253,35 +330,7 @@ export class Serializer {
   /**
    * Serializes a `Serializable` value, facilitating composable serialization.
    *
-   * @param value The Serializable value to serialize
-   *
-   * @example
-   * // Define the MoveStruct class that implements the Serializable interface
-   * class MoveStruct extends Serializable {
-   *     constructor(
-   *         public creatorAddress: AccountAddress, // where AccountAddress extends Serializable
-   *         public collectionName: string,
-   *         public tokenName: string
-   *     ) {}
-   *
-   *     serialize(serializer: Serializer): void {
-   *         serializer.serialize(this.creatorAddress);  // Composable serialization of another Serializable object
-   *         serializer.serializeStr(this.collectionName);
-   *         serializer.serializeStr(this.tokenName);
-   *     }
-   * }
-   *
-   * // Construct a MoveStruct
-   * const moveStruct = new MoveStruct(new AccountAddress(...), "MyCollection", "TokenA");
-   *
-   * // Serialize a string, a u64 number, and a MoveStruct instance.
-   * const serializer = new Serializer();
-   * serializer.serializeStr("ExampleString");
-   * serializer.serializeU64(12345678);
-   * serializer.serialize(moveStruct);
-   *
-   * // Get the bytes from the Serializer instance
-   * const serializedBytes = serializer.toUint8Array();
+   * @param value The Serializable value to serialize.
    *
    * @returns the serializer instance
    */
@@ -293,7 +342,7 @@ export class Serializer {
 
   /**
    * Serializes an array of BCS Serializable values to a serializer instance.
-   * Note that this does not return anything. The bytes are added to the serializer instance's byte buffer.
+   * The bytes are added to the serializer instance's byte buffer.
    *
    * @param values The array of BCS Serializable values
    * @example
@@ -318,13 +367,13 @@ export class Serializer {
   }
 
   /**
-   * Serializes a BCS Serializable values into a serializer instance or undefined.
-   * Note that this does not return anything. The bytes are added to the serializer instance's byte buffer.
+   * Serializes a BCS Serializable value into a serializer instance or handles the case when the value is undefined.
+   * This function allows you to efficiently add serialized data to the serializer's byte buffer.
    *
-   * @param values The array of BCS Serializable values
+   * @param value The BCS Serializable value to serialize, or undefined if there is no value.
    *
    * @example
-   * ```ts
+   * ```typescript
    * const serializer = new Serializer();
    * serializer.serializeOption(new AccountAddress(...));
    * const serializedBytes = serializer.toUint8Array();
@@ -344,26 +393,14 @@ export class Serializer {
   }
 
   /**
-   * Serializes an optional string. UTF8 string is supported.
-   *
-   * The existence of the string is encoded first, 0 if undefined and 1 if it exists.
-   * Them the number of bytes in the string content is serialized, as a uleb128-encoded u32 integer.
-   * Then the string content is serialized as UTF8 encoded bytes.
+   * Serializes an optional string, supporting UTF8 encoding.
+   * The function encodes the existence of the string first, followed by the length and content if it exists.
    *
    * BCS layout for optional "string": 1 | string_length | string_content
    * where string_length is a u32 integer encoded as a uleb128 integer, equal to the number of bytes in string_content.
-   *
    * BCS layout for undefined: 0
-   * @example
-   * ```ts
-   * const serializer = new Serializer();
-   * serializer.serializeOptionStr("1234abcd");
-   * assert(serializer.toUint8Array() === new Uint8Array([1, 8, 49, 50, 51, 52, 97, 98, 99, 100]));
    *
-   * const serializer = new Serializer();
-   * serializer.serializeOptionStr(undefined);
-   * assert(serializer.toUint8Array() === new Uint8Array([0]));
-   * ```
+   * @param value - The optional string to serialize. If undefined, it will serialize as 0.
    */
   serializeOptionStr(value?: string): void {
     if (value === undefined) {
@@ -384,6 +421,14 @@ export function ensureBoolean(value: unknown): asserts value is boolean {
 export const outOfRangeErrorMessage = (value: AnyNumber, min: AnyNumber, max: AnyNumber) =>
   `${value} is out of range: [${min}, ${max}]`;
 
+/**
+ * Validates that a given number is within a specified range.
+ * This function throws an error if the value is outside the defined minimum and maximum bounds.
+ *
+ * @param value - The number to validate.
+ * @param minValue - The minimum allowable value (inclusive).
+ * @param maxValue - The maximum allowable value (inclusive).
+ */
 export function validateNumberInRange<T extends AnyNumber>(value: T, minValue: T, maxValue: T) {
   const valueBigInt = BigInt(value);
   if (valueBigInt > BigInt(maxValue) || valueBigInt < BigInt(minValue)) {
@@ -392,9 +437,11 @@ export function validateNumberInRange<T extends AnyNumber>(value: T, minValue: T
 }
 
 /**
- * A decorator to ensure the input argument for a function is within a range.
- * @param minValue The input argument must be >= minValue
- * @param maxValue The input argument must be <= maxValue
+ * A decorator that validates that the input argument for a function is within a specified range.
+ * This ensures that the function is only called with valid input values, preventing potential errors.
+ *
+ * @param minValue - The input argument must be greater than or equal to this value.
+ * @param maxValue - The input argument must be less than or equal to this value.
  */
 function checkNumberRange<T extends AnyNumber>(minValue: T, maxValue: T) {
   return (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => {

package/src/cli/localNode.ts

@@ -1,23 +1,47 @@
+/* eslint-disable no-console */
+
 import { ChildProcessWithoutNullStreams, spawn } from "child_process";
 import kill from "tree-kill";
 import { platform } from "os";
 
 import { sleep } from "../utils/helpers";
 
+/**
+ * Represents a local node for running a testnet environment.
+ * This class provides methods to start, stop, and check the status of the local testnet process.
+ * It manages the lifecycle of the node process and ensures that it is operational before executing tests.
+ */
 export class LocalNode {
   readonly MAXIMUM_WAIT_TIME_SEC = 75;
 
   readonly READINESS_ENDPOINT = "http://127.0.0.1:8070/";
 
+  showStdout: boolean = true;
+
   process: ChildProcessWithoutNullStreams | null = null;
 
+  constructor(args?: { showStdout?: boolean }) {
+    this.showStdout = args?.showStdout ?? true;
+  }
+
   /**
-   * kills all the descendent processes
-   * of the node process, including the node process itself
+   * Kills the current process and all its descendant processes.
+   *
+   * @returns {Promise<void>} A promise that resolves to true if the process was successfully killed.
+   * @throws {Error} If there is an error while attempting to kill the process.
    */
-  async stop() {
+  async stop(): Promise<void> {
     await new Promise((resolve, reject) => {
       if (!this.process?.pid) return;
+
+      /**
+       * Terminates the process associated with the given process ID.
+       *
+       * @param pid - The process ID of the process to be terminated.
+       * @param callback - A function that is called after the termination attempt is complete.
+       * @param callback.err - An error object if the termination failed; otherwise, null.
+       * @param callback.resolve - A boolean indicating whether the termination was successful.
+       */
       kill(this.process.pid, (err) => {
         if (err) {
           reject(err);
@@ -29,12 +53,12 @@ export class LocalNode {
   }
 
   /**
-   * Runs a local testnet and waits for process to be up.
+   * Runs a local testnet and waits for the process to be up.
+   * If the local node process is already running, it returns without starting the process.
    *
-   * If local node process is already up it returns and does
-   * not start the process
+   * @returns {Promise<void>} A promise that resolves when the process is up.
    */
-  async run() {
+  async run(): Promise<void> {
     const nodeIsUp = await this.checkIfProcessIsUp();
     if (nodeIsUp) {
       return;
@@ -44,9 +68,13 @@ export class LocalNode {
   }
 
   /**
-   * Starts the local testnet by running the aptos node run-local-testnet command
+   * Starts the local testnet by running the Aptos node with the specified command-line arguments.
+   *
+   * @returns {void}
+   *
+   * @throws {Error} If there is an issue starting the local testnet.
    */
-  start() {
+  start(): void {
     const cliCommand = "npx";
     const cliArgs = ["aptos", "node", "run-localnet", "--force-restart", "--assume-yes", "--with-indexer-api"];
 
@@ -63,23 +91,24 @@ export class LocalNode {
 
     childProcess.stderr?.on("data", (data: any) => {
       const str = data.toString();
-      // Print local node output log
-      // eslint-disable-next-line no-console
+      // Print local node output error log
       console.log(str);
     });
 
     childProcess.stdout?.on("data", (data: any) => {
       const str = data.toString();
       // Print local node output log
-      // eslint-disable-next-line no-console
-      console.log(str);
+      if (this.showStdout) {
+        console.log(str);
+      }
     });
   }
 
   /**
-   * Waits for the local testnet process to be up
+   * Waits for the local testnet process to be operational within a specified maximum wait time.
+   * This function continuously checks if the process is up and will throw an error if it fails to start.
    *
-   * @returns Promise<boolean>
+   * @returns Promise<boolean> - Resolves to true if the process is up, otherwise throws an error.
    */
   async waitUntilProcessIsUp(): Promise<boolean> {
     let operational = await this.checkIfProcessIsUp();
@@ -104,9 +133,9 @@ export class LocalNode {
   }
 
   /**
-   * Checks if the local testnet is up
+   * Checks if the local testnet is up by querying the readiness endpoint.
    *
-   * @returns Promise<boolean>
+   * @returns Promise<boolean> - A promise that resolves to true if the testnet is up, otherwise false.
    */
   async checkIfProcessIsUp(): Promise<boolean> {
     try {