@aptos-labs/ts-sdk 0.0.0

package/src/bcs/deserializer.ts

@@ -0,0 +1,248 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+/* eslint-disable no-bitwise */
+import { MAX_U32_NUMBER } from "./consts";
+import { Uint8, Uint16, Uint32, Uint64, Uint128, Uint256 } from "../types";
+
+/**
+ * This interface exists to define Deserializable<T> inputs for functions that
+ * deserialize a byte buffer into a type T.
+ * It is not intended to be implemented or extended, because Typescript has no support
+ * for static methods in interfaces.
+ */
+export interface Deserializable<T> {
+  deserialize(deserializer: Deserializer): T;
+}
+
+export class Deserializer {
+  private buffer: ArrayBuffer;
+
+  private offset: number;
+
+  constructor(data: Uint8Array) {
+    // copies data to prevent outside mutation of buffer.
+    this.buffer = new ArrayBuffer(data.length);
+    new Uint8Array(this.buffer).set(data, 0);
+    this.offset = 0;
+  }
+
+  private read(length: number): ArrayBuffer {
+    if (this.offset + length > this.buffer.byteLength) {
+      throw new Error("Reached to the end of buffer");
+    }
+
+    const bytes = this.buffer.slice(this.offset, this.offset + length);
+    this.offset += length;
+    return bytes;
+  }
+
+  /**
+   * Deserializes a string. UTF8 string is supported. Reads the string's bytes length "l" first,
+   * and then reads "l" bytes of content. Decodes the byte array into a string.
+   *
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const deserializer = new Deserializer(new Uint8Array([8, 49, 50, 51, 52, 97, 98, 99, 100]));
+   * assert(deserializer.deserializeStr() === "1234abcd");
+   * ```
+   */
+  deserializeStr(): string {
+    const value = this.deserializeBytes();
+    const textDecoder = new TextDecoder();
+    return textDecoder.decode(value);
+  }
+
+  /**
+   * Deserializes an array of bytes.
+   *
+   * 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.
+   */
+  deserializeBytes(): Uint8Array {
+    const len = this.deserializeUleb128AsU32();
+    return new Uint8Array(this.read(len));
+  }
+
+  /**
+   * Deserializes an array of bytes. The number of bytes to read is already known.
+   *
+   */
+  deserializeFixedBytes(len: number): Uint8Array {
+    return new Uint8Array(this.read(len));
+  }
+
+  /**
+   * Deserializes a boolean value.
+   *
+   * BCS layout for "boolean": One byte. "0x01" for true and "0x00" for false.
+   */
+  deserializeBool(): boolean {
+    const bool = new Uint8Array(this.read(1))[0];
+    if (bool !== 1 && bool !== 0) {
+      throw new Error("Invalid boolean value");
+    }
+    return bool === 1;
+  }
+
+  /**
+   * Deserializes a uint8 number.
+   *
+   * BCS layout for "uint8": One byte. Binary format in little-endian representation.
+   */
+  deserializeU8(): Uint8 {
+    return new DataView(this.read(1)).getUint8(0);
+  }
+
+  /**
+   * Deserializes a uint16 number.
+   *
+   * BCS layout for "uint16": Two bytes. Binary format in little-endian representation.
+   * @example
+   * ```ts
+   * const deserializer = new Deserializer(new Uint8Array([0x34, 0x12]));
+   * assert(deserializer.deserializeU16() === 4660);
+   * ```
+   */
+  deserializeU16(): Uint16 {
+    return new DataView(this.read(2)).getUint16(0, true);
+  }
+
+  /**
+   * Deserializes a uint32 number.
+   *
+   * BCS layout for "uint32": Four bytes. Binary format in little-endian representation.
+   * @example
+   * ```ts
+   * const deserializer = new Deserializer(new Uint8Array([0x78, 0x56, 0x34, 0x12]));
+   * assert(deserializer.deserializeU32() === 305419896);
+   * ```
+   */
+  deserializeU32(): Uint32 {
+    return new DataView(this.read(4)).getUint32(0, true);
+  }
+
+  /**
+   * Deserializes a uint64 number.
+   *
+   * BCS layout for "uint64": Eight bytes. Binary format in little-endian representation.
+   * @example
+   * ```ts
+   * const deserializer = new Deserializer(new Uint8Array([0x00, 0xEF, 0xCD, 0xAB, 0x78, 0x56, 0x34, 0x12]));
+   * assert(deserializer.deserializeU64() === 1311768467750121216);
+   * ```
+   */
+  deserializeU64(): Uint64 {
+    const low = this.deserializeU32();
+    const high = this.deserializeU32();
+
+    // combine the two 32-bit values and return (little endian)
+    return BigInt((BigInt(high) << BigInt(32)) | BigInt(low));
+  }
+
+  /**
+   * Deserializes a uint128 number.
+   *
+   * BCS layout for "uint128": Sixteen bytes. Binary format in little-endian representation.
+   */
+  deserializeU128(): Uint128 {
+    const low = this.deserializeU64();
+    const high = this.deserializeU64();
+
+    // combine the two 64-bit values and return (little endian)
+    return BigInt((high << BigInt(64)) | low);
+  }
+
+  /**
+   * Deserializes a uint256 number.
+   *
+   * BCS layout for "uint256": Thirty-two bytes. Binary format in little-endian representation.
+   */
+  deserializeU256(): Uint256 {
+    const low = this.deserializeU128();
+    const high = this.deserializeU128();
+
+    // combine the two 128-bit values and return (little endian)
+    return BigInt((high << BigInt(128)) | low);
+  }
+
+  /**
+   * Deserializes a uleb128 encoded uint32 number.
+   *
+   * BCS use uleb128 encoding in two cases: (1) lengths of variable-length sequences and (2) tags of enum values
+   */
+  deserializeUleb128AsU32(): Uint32 {
+    let value: bigint = BigInt(0);
+    let shift = 0;
+
+    while (value < MAX_U32_NUMBER) {
+      const byte = this.deserializeU8();
+      value |= BigInt(byte & 0x7f) << BigInt(shift);
+
+      if ((byte & 0x80) === 0) {
+        break;
+      }
+      shift += 7;
+    }
+
+    if (value > MAX_U32_NUMBER) {
+      throw new Error("Overflow while parsing uleb128-encoded uint32 value");
+    }
+
+    return Number(value);
+  }
+
+  /**
+   * Helper function that primarily exists to support alternative syntax for deserialization.
+   * That is, if we have a `const deserializer: new Deserializer(...)`, instead of having to use
+   * `MyClass.deserialize(deserializer)`, we can call `deserializer.deserialize(MyClass)`.
+   *
+   * @example const deserializer = new Deserializer(new Uint8Array([1, 2, 3]));
+   * const value = deserializer.deserialize(MyClass); // where MyClass has a `deserialize` function
+   * // value is now an instance of MyClass
+   * // equivalent to `const value = MyClass.deserialize(deserializer)`
+   * @param cls The BCS-deserializable class to deserialize the buffered bytes into.
+   *
+   * @returns the deserialized value of class type T
+   */
+  deserialize<T>(cls: Deserializable<T>): T {
+    // NOTE: `deserialize` in `cls.deserialize(this)` here is a static method defined in `cls`,
+    // It is separate from the `deserialize` instance method defined here in Deserializer.
+    return cls.deserialize(this);
+  }
+
+  /**
+   * Deserializes an array of BCS Deserializable values given an existing Deserializer
+   * instance with a loaded byte buffer.
+   *
+   * @param cls The BCS-deserializable class to deserialize the buffered bytes into.
+   * @example
+   * // serialize a vector of addresses
+   * const addresses = new Array<AccountAddress>(
+   *   AccountAddress.fromHexInputRelaxed("0x1"),
+   *   AccountAddress.fromHexInputRelaxed("0x2"),
+   *   AccountAddress.fromHexInputRelaxed("0xa"),
+   *   AccountAddress.fromHexInputRelaxed("0xb"),
+   * );
+   * const serializer = new Serializer();
+   * serializer.serializeVector(addresses);
+   * const serializedBytes = serializer.toUint8Array();
+   *
+   * // deserialize the bytes into an array of addresses
+   * const deserializer = new Deserializer(serializedBytes);
+   * const deserializedAddresses = deserializer.deserializeVector(AccountAddress);
+   * // deserializedAddresses is now an array of AccountAddress instances
+   * @returns an array of deserialized values of type T
+   */
+  deserializeVector<T>(cls: Deserializable<T>): Array<T> {
+    const length = this.deserializeUleb128AsU32();
+    const vector = new Array<T>();
+    for (let i = 0; i < length; i += 1) {
+      vector.push(this.deserialize(cls));
+    }
+    return vector;
+  }
+}

package/src/bcs/index.ts

@@ -0,0 +1,9 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+export * from "./deserializer";
+export * from "./serializer";
+export * from "./serializable/entryFunctionBytes";
+export * from "./serializable/fixedBytes";
+export * from "./serializable/movePrimitives";
+export * from "./serializable/moveStructs";

package/src/bcs/serializable/entryFunctionBytes.ts

@@ -0,0 +1,61 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+import { Serializer, Serializable } from "../serializer";
+import { Deserializer } from "../deserializer";
+import { FixedBytes } from "./fixedBytes";
+import { EntryFunctionArgument } from "../../transactions/instances/transactionArgument";
+import { HexInput } from "../../types";
+
+/**
+ * This class exists solely to represent a sequence of fixed bytes as a serialized entry function, because
+ * serializing an entry function appends a prefix that's *only* used for entry function arguments.
+ *
+ * NOTE: Attempting to use this class for a serialized script function will result in erroneous
+ * and unexpected behavior.
+ *
+ * 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.
+ */
+export class EntryFunctionBytes extends Serializable implements EntryFunctionArgument {
+  public readonly value: FixedBytes;
+
+  private constructor(value: HexInput) {
+    super();
+    this.value = new FixedBytes(value);
+  }
+
+  // Note that to see the Move, BCS-serialized representation of the underlying fixed byte vector,
+  // we must not serialize the length prefix.
+  //
+  // In other words, this class is only used to represent a sequence of bytes that are already
+  // BCS-serialized as a type. To represent those bytes accurately, the BCS-serialized form is the same exact
+  // representation.
+  serialize(serializer: Serializer): void {
+    serializer.serialize(this.value);
+  }
+
+  // When we serialize these bytes as an entry function argument, we need to
+  // serialize the length prefix. This essentially converts the underlying fixed byte vector to a type-agnostic
+  // byte vector to an `any` type.
+  // NOTE: This, and the lack of a `serializeForScriptFunction`, is the only meaningful difference between this
+  // class and FixedBytes.
+  serializeForEntryFunction(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(this.value.value.length);
+    serializer.serialize(this);
+  }
+
+  /**
+   * The only way to create an instance of this class is to use this static method.
+   *
+   * This function should only be used when deserializing a sequence of EntryFunctionPayload arguments.
+   * @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
+   */
+  static deserialize(deserializer: Deserializer, length: number): EntryFunctionBytes {
+    const fixedBytes = FixedBytes.deserialize(deserializer, length);
+    return new EntryFunctionBytes(fixedBytes.value);
+  }
+}

package/src/bcs/serializable/fixedBytes.ts

@@ -0,0 +1,65 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+import { Serializer, Serializable } from "../serializer";
+import { Deserializer } from "../deserializer";
+import { HexInput } from "../../types";
+import { Hex } from "../../core/hex";
+import { TransactionArgument } from "../../transactions/instances/transactionArgument";
+
+/**
+ *  This class exists to represent a contiguous sequence of already serialized BCS-bytes.
+ *
+ *  It differs from most other Serializable classes in that its internal byte buffer is serialized to BCS
+ *  bytes exactly as-is, without prepending the length of the bytes.
+ *
+ *  If you want to write your own serialization function and pass the bytes as a transaction argument,
+ *  you should use this class.
+ *
+ *  This class is also more generally used to represent type-agnostic BCS bytes as a vector<u8>.
+ *
+ *  An example of this is the bytes resulting from entry function arguments that have been serialized
+ *  for an entry function.
+ *
+ *  @example
+ *  const yourCustomSerializedBytes = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+ *  const fixedBytes = new FixedBytes(yourCustomSerializedBytes);
+ *  const payload = generateTransactionPayload({
+ *    function: "0xbeefcafe::your_module::your_function_that_requires_custom_serialization",
+ *    arguments: [yourCustomBytes],
+ *  });
+ *
+ *  For example, if you store each of the 32 bytes for an address as a U8 in a MoveVector<U8>, when you
+ *  serialize that MoveVector<U8>, it will be serialized to 33 bytes. If you solely want to pass around
+ *  the 32 bytes as a Serializable class that *does not* prepend the length to the BCS-serialized representation,
+ *  use this class.
+ *
+ * @params 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
+ */
+export class FixedBytes extends Serializable implements TransactionArgument {
+  public value: Uint8Array;
+
+  constructor(value: HexInput) {
+    super();
+    this.value = Hex.fromHexInput(value).toUint8Array();
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeFixedBytes(this.value);
+  }
+
+  serializeForEntryFunction(serializer: Serializer): void {
+    serializer.serialize(this);
+  }
+
+  serializeForScriptFunction(serializer: Serializer): void {
+    serializer.serialize(this);
+  }
+
+  static deserialize(deserializer: Deserializer, length: number): FixedBytes {
+    const bytes = deserializer.deserializeFixedBytes(length);
+    return new FixedBytes(bytes);
+  }
+}

package/src/bcs/serializable/movePrimitives.ts

@@ -0,0 +1,211 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  MAX_U128_BIG_INT,
+  MAX_U16_NUMBER,
+  MAX_U32_NUMBER,
+  MAX_U64_BIG_INT,
+  MAX_U8_NUMBER,
+  MAX_U256_BIG_INT,
+} from "../consts";
+import { Deserializer } from "../deserializer";
+import { Serializable, Serializer, ensureBoolean, validateNumberInRange } from "../serializer";
+import { TransactionArgument } from "../../transactions/instances/transactionArgument";
+import { AnyNumber, Uint16, Uint32, Uint8, ScriptTransactionArgumentVariants } from "../../types";
+
+export class Bool extends Serializable implements TransactionArgument {
+  public readonly value: boolean;
+
+  constructor(value: boolean) {
+    super();
+    ensureBoolean(value);
+    this.value = value;
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeBool(this.value);
+  }
+
+  serializeForEntryFunction(serializer: Serializer): void {
+    const bcsBytes = this.bcsToBytes();
+    serializer.serializeBytes(bcsBytes);
+  }
+
+  serializeForScriptFunction(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(ScriptTransactionArgumentVariants.Bool);
+    serializer.serialize(this);
+  }
+
+  static deserialize(deserializer: Deserializer): Bool {
+    return new Bool(deserializer.deserializeBool());
+  }
+}
+
+export class U8 extends Serializable implements TransactionArgument {
+  public readonly value: Uint8;
+
+  constructor(value: Uint8) {
+    super();
+    validateNumberInRange(value, 0, MAX_U8_NUMBER);
+    this.value = value;
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeU8(this.value);
+  }
+
+  serializeForEntryFunction(serializer: Serializer): void {
+    const bcsBytes = this.bcsToBytes();
+    serializer.serializeBytes(bcsBytes);
+  }
+
+  serializeForScriptFunction(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(ScriptTransactionArgumentVariants.U8);
+    serializer.serialize(this);
+  }
+
+  static deserialize(deserializer: Deserializer): U8 {
+    return new U8(deserializer.deserializeU8());
+  }
+}
+
+export class U16 extends Serializable implements TransactionArgument {
+  public readonly value: Uint16;
+
+  constructor(value: Uint16) {
+    super();
+    validateNumberInRange(value, 0, MAX_U16_NUMBER);
+    this.value = value;
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeU16(this.value);
+  }
+
+  serializeForEntryFunction(serializer: Serializer): void {
+    const bcsBytes = this.bcsToBytes();
+    serializer.serializeBytes(bcsBytes);
+  }
+
+  serializeForScriptFunction(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(ScriptTransactionArgumentVariants.U16);
+    serializer.serialize(this);
+  }
+
+  static deserialize(deserializer: Deserializer): U16 {
+    return new U16(deserializer.deserializeU16());
+  }
+}
+
+export class U32 extends Serializable implements TransactionArgument {
+  public readonly value: Uint32;
+
+  constructor(value: Uint32) {
+    super();
+    validateNumberInRange(value, 0, MAX_U32_NUMBER);
+    this.value = value;
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeU32(this.value);
+  }
+
+  serializeForEntryFunction(serializer: Serializer): void {
+    const bcsBytes = this.bcsToBytes();
+    serializer.serializeBytes(bcsBytes);
+  }
+
+  serializeForScriptFunction(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(ScriptTransactionArgumentVariants.U32);
+    serializer.serialize(this);
+  }
+
+  static deserialize(deserializer: Deserializer): U32 {
+    return new U32(deserializer.deserializeU32());
+  }
+}
+
+export class U64 extends Serializable implements TransactionArgument {
+  public readonly value: bigint;
+
+  constructor(value: AnyNumber) {
+    super();
+    validateNumberInRange(value, BigInt(0), MAX_U64_BIG_INT);
+    this.value = BigInt(value);
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeU64(this.value);
+  }
+
+  serializeForEntryFunction(serializer: Serializer): void {
+    const bcsBytes = this.bcsToBytes();
+    serializer.serializeBytes(bcsBytes);
+  }
+
+  serializeForScriptFunction(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(ScriptTransactionArgumentVariants.U64);
+    serializer.serialize(this);
+  }
+
+  static deserialize(deserializer: Deserializer): U64 {
+    return new U64(deserializer.deserializeU64());
+  }
+}
+
+export class U128 extends Serializable implements TransactionArgument {
+  public readonly value: bigint;
+
+  constructor(value: AnyNumber) {
+    super();
+    validateNumberInRange(value, BigInt(0), MAX_U128_BIG_INT);
+    this.value = BigInt(value);
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeU128(this.value);
+  }
+
+  serializeForEntryFunction(serializer: Serializer): void {
+    const bcsBytes = this.bcsToBytes();
+    serializer.serializeBytes(bcsBytes);
+  }
+
+  serializeForScriptFunction(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(ScriptTransactionArgumentVariants.U128);
+    serializer.serialize(this);
+  }
+
+  static deserialize(deserializer: Deserializer): U128 {
+    return new U128(deserializer.deserializeU128());
+  }
+}
+
+export class U256 extends Serializable implements TransactionArgument {
+  public readonly value: bigint;
+
+  constructor(value: AnyNumber) {
+    super();
+    validateNumberInRange(value, BigInt(0), MAX_U256_BIG_INT);
+    this.value = BigInt(value);
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeU256(this.value);
+  }
+
+  serializeForEntryFunction(serializer: Serializer): void {
+    const bcsBytes = this.bcsToBytes();
+    serializer.serializeBytes(bcsBytes);
+  }
+
+  serializeForScriptFunction(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(ScriptTransactionArgumentVariants.U256);
+    serializer.serialize(this);
+  }
+
+  static deserialize(deserializer: Deserializer): U256 {
+    return new U256(deserializer.deserializeU256());
+  }
+}