@aptos-labs/ts-sdk 0.0.0

package/src/bcs/serializer.ts

@@ -0,0 +1,353 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+/* eslint-disable no-bitwise */
+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 { 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.
+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
+   */
+  bcsToBytes(): Uint8Array {
+    const serializer = new Serializer();
+    this.serialize(serializer);
+    return serializer.toUint8Array();
+  }
+
+  /**
+   * 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
+   */
+  bcsToHex(): Hex {
+    const bcsBytes = this.bcsToBytes();
+    return Hex.fromHexInput(bcsBytes);
+  }
+}
+
+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.
+  constructor(length: number = 64) {
+    if (length <= 0) {
+      throw new Error("Length needs to be greater than 0");
+    }
+    this.buffer = new ArrayBuffer(length);
+    this.offset = 0;
+  }
+
+  private ensureBufferWillHandleSize(bytes: number) {
+    while (this.buffer.byteLength < this.offset + bytes) {
+      const newBuffer = new ArrayBuffer(this.buffer.byteLength * 2);
+      new Uint8Array(newBuffer).set(new Uint8Array(this.buffer));
+      this.buffer = newBuffer;
+    }
+  }
+
+  protected appendToBuffer(values: Uint8Array) {
+    this.ensureBufferWillHandleSize(values.length);
+    new Uint8Array(this.buffer, this.offset).set(values);
+    this.offset += values.length;
+  }
+
+  private serializeWithFunction(
+    fn: (byteOffset: number, value: number, littleEndian?: boolean) => void,
+    bytesLength: number,
+    value: number,
+  ) {
+    this.ensureBufferWillHandleSize(bytesLength);
+    const dv = new DataView(this.buffer, this.offset);
+    fn.apply(dv, [0, value, true]);
+    this.offset += bytesLength;
+  }
+
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const serializer = new Serializer();
+   * serializer.serializeStr("1234abcd");
+   * assert(serializer.toUint8Array() === new Uint8Array([8, 49, 50, 51, 52, 97, 98, 99, 100]));
+   * ```
+   */
+  serializeStr(value: string) {
+    const textEncoder = new TextEncoder();
+    this.serializeBytes(textEncoder.encode(value));
+  }
+
+  /**
+   * Serializes 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.
+   */
+  serializeBytes(value: Uint8Array) {
+    this.serializeU32AsUleb128(value.length);
+    this.appendToBuffer(value);
+  }
+
+  /**
+   * Serializes an array of bytes with known length. Therefore, length doesn't need to be
+   * serialized to help deserialization.
+   *
+   * When deserializing, the number of bytes to deserialize needs to be passed in.
+   */
+  serializeFixedBytes(value: Uint8Array) {
+    this.appendToBuffer(value);
+  }
+
+  /**
+   * Serializes a boolean value.
+   *
+   * BCS layout for "boolean": One byte. "0x01" for true and "0x00" for false.
+   */
+  serializeBool(value: boolean) {
+    ensureBoolean(value);
+    const byteValue = value ? 1 : 0;
+    this.appendToBuffer(new Uint8Array([byteValue]));
+  }
+
+  /**
+   * Serializes a uint8 number.
+   *
+   * BCS layout for "uint8": One byte. Binary format in little-endian representation.
+   */
+  @checkNumberRange(0, MAX_U8_NUMBER)
+  serializeU8(value: Uint8) {
+    this.appendToBuffer(new Uint8Array([value]));
+  }
+
+  /**
+   * Serializes a uint16 number.
+   *
+   * BCS layout for "uint16": Two bytes. Binary format in little-endian representation.
+   * @example
+   * ```ts
+   * const serializer = new Serializer();
+   * serializer.serializeU16(4660);
+   * assert(serializer.toUint8Array() === new Uint8Array([0x34, 0x12]));
+   * ```
+   */
+  @checkNumberRange(0, MAX_U16_NUMBER)
+  serializeU16(value: Uint16) {
+    this.serializeWithFunction(DataView.prototype.setUint16, 2, value);
+  }
+
+  /**
+   * Serializes a uint32 number.
+   *
+   * BCS layout for "uint32": Four bytes. Binary format in little-endian representation.
+   * @example
+   * ```ts
+   * const serializer = new Serializer();
+   * serializer.serializeU32(305419896);
+   * assert(serializer.toUint8Array() === new Uint8Array([0x78, 0x56, 0x34, 0x12]));
+   * ```
+   */
+  @checkNumberRange(0, MAX_U32_NUMBER)
+  serializeU32(value: Uint32) {
+    this.serializeWithFunction(DataView.prototype.setUint32, 4, value);
+  }
+
+  /**
+   * Serializes a uint64 number.
+   *
+   * BCS layout for "uint64": Eight bytes. Binary format in little-endian representation.
+   * @example
+   * ```ts
+   * const serializer = new Serializer();
+   * serializer.serializeU64(1311768467750121216);
+   * assert(serializer.toUint8Array() === new Uint8Array([0x00, 0xEF, 0xCD, 0xAB, 0x78, 0x56, 0x34, 0x12]));
+   * ```
+   */
+  @checkNumberRange(BigInt(0), MAX_U64_BIG_INT)
+  serializeU64(value: AnyNumber) {
+    const low = BigInt(value) & BigInt(MAX_U32_NUMBER);
+    const high = BigInt(value) >> BigInt(32);
+
+    // write little endian number
+    this.serializeU32(Number(low));
+    this.serializeU32(Number(high));
+  }
+
+  /**
+   * Serializes a uint128 number.
+   *
+   * BCS layout for "uint128": Sixteen bytes. Binary format in little-endian representation.
+   */
+  @checkNumberRange(BigInt(0), MAX_U128_BIG_INT)
+  serializeU128(value: AnyNumber) {
+    const low = BigInt(value) & MAX_U64_BIG_INT;
+    const high = BigInt(value) >> BigInt(64);
+
+    // write little endian number
+    this.serializeU64(low);
+    this.serializeU64(high);
+  }
+
+  /**
+   * Serializes a uint256 number.
+   *
+   * BCS layout for "uint256": Sixteen bytes. Binary format in little-endian representation.
+   */
+  @checkNumberRange(BigInt(0), MAX_U256_BIG_INT)
+  serializeU256(value: AnyNumber) {
+    const low = BigInt(value) & MAX_U128_BIG_INT;
+    const high = BigInt(value) >> BigInt(128);
+
+    // write little endian number
+    this.serializeU128(low);
+    this.serializeU128(high);
+  }
+
+  /**
+   * Serializes a uint32 number with uleb128.
+   *
+   * BCS uses uleb128 encoding in two cases: (1) lengths of variable-length sequences and (2) tags of enum values
+   */
+  @checkNumberRange(0, MAX_U32_NUMBER)
+  serializeU32AsUleb128(val: Uint32) {
+    let value = val;
+    const valueArray = [];
+    while (value >>> 7 !== 0) {
+      valueArray.push((value & 0x7f) | 0x80);
+      value >>>= 7;
+    }
+    valueArray.push(value);
+    this.appendToBuffer(new Uint8Array(valueArray));
+  }
+
+  /**
+   * Returns the buffered bytes
+   */
+  toUint8Array(): Uint8Array {
+    return new Uint8Array(this.buffer).slice(0, this.offset);
+  }
+
+  /**
+   * 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();
+   *
+   * @returns the serializer instance
+   */
+  serialize<T extends Serializable>(value: T): void {
+    // NOTE: The `serialize` method called by `value` is defined in `value`'s
+    // Serializable interface, not the one defined in this class.
+    value.serialize(this);
+  }
+
+  /**
+   * 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.
+   *
+   * @param values The array of BCS Serializable values
+   * @example
+   * 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();
+   * // serializedBytes is now the BCS-serialized bytes
+   * // The equivalent value in Move would be:
+   * // `bcs::to_bytes(&vector<address> [@0x1, @0x2, @0xa, @0xb])`;
+   */
+  serializeVector<T extends Serializable>(values: Array<T>): void {
+    this.serializeU32AsUleb128(values.length);
+    values.forEach((item) => {
+      item.serialize(this);
+    });
+  }
+}
+
+export function ensureBoolean(value: unknown): asserts value is boolean {
+  if (typeof value !== "boolean") {
+    throw new Error(`${value} is not a boolean value`);
+  }
+}
+
+export const outOfRangeErrorMessage = (value: AnyNumber, min: AnyNumber, max: AnyNumber) =>
+  `${value} is out of range: [${min}, ${max}]`;
+
+export function validateNumberInRange<T extends AnyNumber>(value: T, minValue: T, maxValue: T) {
+  const valueBigInt = BigInt(value);
+  if (valueBigInt > BigInt(maxValue) || valueBigInt < BigInt(minValue)) {
+    throw new Error(outOfRangeErrorMessage(value, minValue, maxValue));
+  }
+}
+
+/**
+ * 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
+ */
+function checkNumberRange<T extends AnyNumber>(minValue: T, maxValue: T) {
+  return (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => {
+    const childFunction = descriptor.value;
+    // eslint-disable-next-line no-param-reassign
+    descriptor.value = function deco(value: AnyNumber) {
+      validateNumberInRange(value, minValue, maxValue);
+      return childFunction.apply(this, [value]);
+    };
+
+    return descriptor;
+  };
+}

package/src/client/core.ts

@@ -0,0 +1,106 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+import aptosClient from "@aptos-labs/aptos-client";
+import { AptosConfig } from "../api/aptosConfig";
+import { AptosApiError, AptosResponse } from "./types";
+import { ClientConfig, AptosRequest, MimeType } from "../types";
+import { VERSION } from "../version";
+
+/**
+ * Meaningful errors map
+ */
+const errors: Record<number, string> = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+};
+
+/**
+ * Given a url and method, sends the request with axios and
+ * returns the response.
+ */
+async function request<Req, Res>(
+  url: string,
+  method: "GET" | "POST",
+  body?: Req,
+  contentType?: string,
+  params?: any,
+  overrides?: ClientConfig,
+): Promise<any> {
+  const headers: Record<string, string | string[] | undefined> = {
+    ...overrides?.HEADERS,
+    "x-aptos-client": `aptos-ts-sdk/${VERSION}`,
+    "content-type": contentType ?? MimeType.JSON,
+  };
+
+  if (overrides?.TOKEN) {
+    headers.Authorization = `Bearer ${overrides?.TOKEN}`;
+  }
+
+  /*
+   * make a call using the @aptos-labs/aptos-client package
+   * {@link https://www.npmjs.com/package/@aptos-labs/aptos-client}
+   */
+  return aptosClient<Res>({
+    url,
+    method,
+    body,
+    params,
+    headers,
+    overrides,
+  });
+}
+
+/**
+ * The main function to use when doing an API request.
+ *
+ * @param options AptosRequest
+ * @param aptosConfig The config information for the SDK client instance
+ * @returns the response or AptosApiError
+ */
+export async function aptosRequest<Req, Res>(
+  options: AptosRequest,
+  aptosConfig: AptosConfig,
+): Promise<AptosResponse<Req, Res>> {
+  const { url, path, method, body, contentType, params, overrides } = options;
+  const fullUrl = `${url}/${path ?? ""}`;
+  const response = await request<Req, Res>(fullUrl, method, body, contentType, params, overrides);
+  const result: AptosResponse<Req, Res> = {
+    status: response.status,
+    statusText: response.statusText!,
+    data: response.data,
+    headers: response.headers,
+    config: response.config,
+    url: fullUrl,
+  };
+
+  // to support both fullnode and indexer responses,
+  // check if it is an indexer query, and adjust response.data
+  if (aptosConfig.isIndexerRequest(url)) {
+    // errors from indexer
+    if ((result.data as any).errors) {
+      throw new AptosApiError(
+        options,
+        result,
+        response.data.errors[0].message ?? `Unhandled Error ${response.status} : ${response.statusText}`,
+      );
+    }
+    result.data = (result.data as any).data as Res;
+  }
+
+  if (result.status >= 200 && result.status < 300) {
+    return result;
+  }
+  const errorMessage = errors[result.status];
+  throw new AptosApiError(
+    options,
+    result,
+    errorMessage ?? `Unhandled Error ${response.status} : ${response.statusText}`,
+  );
+}

package/src/client/get.ts

@@ -0,0 +1,109 @@
+import { AptosConfig } from "../api/aptosConfig";
+import { aptosRequest } from "./core";
+import { AptosResponse } from "./types";
+import { AnyNumber, ClientConfig, MimeType } from "../types";
+import { AptosApiType } from "../utils/const";
+
+export type GetRequestOptions = {
+  /**
+   * The config for the API client
+   */
+  aptosConfig: AptosConfig;
+  /**
+   * The type of API endpoint to call e.g. fullnode, indexer, etc
+   */
+  type: AptosApiType;
+  /**
+   * The name of the API method
+   */
+  originMethod: string;
+  /**
+   * The URL path to the API method
+   */
+  path: string;
+  /**
+   * The content type of the request body
+   */
+  contentType?: MimeType;
+  /**
+   * The accepted content type of the response of the API
+   */
+  acceptType?: MimeType;
+  /**
+   * The query parameters for the request
+   */
+  params?: Record<string, string | AnyNumber | boolean | undefined>;
+  /**
+   * Specific client overrides for this request to override aptosConfig
+   */
+  overrides?: ClientConfig;
+};
+
+export type GetAptosRequestOptions = Omit<GetRequestOptions, "type">;
+
+/**
+ * Main function to do a Get request
+ *
+ * @param options GetRequestOptions
+ * @returns
+ */
+export async function get<Req, Res>(options: GetRequestOptions): Promise<AptosResponse<Req, Res>> {
+  const { aptosConfig, overrides, params, contentType, acceptType, path, originMethod, type } = options;
+  const url = aptosConfig.getRequestUrl(type);
+
+  return aptosRequest<Req, Res>(
+    {
+      url,
+      method: "GET",
+      originMethod,
+      path,
+      contentType: contentType?.valueOf(),
+      acceptType: acceptType?.valueOf(),
+      params,
+      overrides: {
+        ...aptosConfig,
+        ...overrides,
+      },
+    },
+    aptosConfig,
+  );
+}
+
+export async function getAptosFullNode<Req, Res>(options: GetAptosRequestOptions): Promise<AptosResponse<Req, Res>> {
+  return get<Req, Res>({ ...options, type: AptosApiType.FULLNODE });
+}
+
+/// This function is a helper for paginating using a function wrapping an API
+export async function paginateWithCursor<Req extends Record<string, any>, Res extends any[]>(
+  options: GetAptosRequestOptions,
+): Promise<Res> {
+  const out = [];
+  let cursor: string | undefined;
+  const requestParams = options.params as Req & { start?: string; limit?: number };
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    requestParams.start = cursor;
+    // eslint-disable-next-line no-await-in-loop
+    const response = await getAptosFullNode<Req, Res>({
+      aptosConfig: options.aptosConfig,
+      originMethod: options.originMethod,
+      path: options.path,
+      params: requestParams,
+      overrides: options.overrides,
+    });
+    /**
+     * the cursor is a "state key" from the API perspective. Client
+     * should not need to "care" what it represents but just use it
+     * to query the next chunk of data.
+     */
+    cursor = response.headers["x-aptos-cursor"];
+    // Now that we have the cursor (if any), we remove the headers before
+    // adding these to the output of this function.
+    delete (response as any).headers;
+    out.push(...response.data);
+    if (cursor === null || cursor === undefined) {
+      break;
+    }
+  }
+  return out as any;
+}

package/src/client/index.ts

@@ -0,0 +1,7 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+export * from "./core";
+export * from "./get";
+export * from "./post";
+export * from "./types";

package/src/client/post.ts

@@ -0,0 +1,90 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+import { AptosConfig } from "../api/aptosConfig";
+import { aptosRequest } from "./core";
+import { AptosResponse } from "./types";
+import { AnyNumber, ClientConfig, MimeType } from "../types";
+import { AptosApiType } from "../utils/const";
+
+export type PostRequestOptions = {
+  /**
+   * The config for the API client
+   */
+  aptosConfig: AptosConfig;
+  /**
+   * The type of API endpoint to call e.g. fullnode, indexer, etc
+   */
+  type: AptosApiType;
+  /**
+   * The name of the API method
+   */
+  originMethod: string;
+  /**
+   * The URL path to the API method
+   */
+  path: string;
+  /**
+   * The content type of the request body
+   */
+  contentType?: MimeType;
+  /**
+   * The accepted content type of the response of the API
+   */
+  acceptType?: MimeType;
+  /**
+   * The query parameters for the request
+   */
+  params?: Record<string, string | AnyNumber | boolean | undefined>;
+  /**
+   * The body of the request, should match teh content type of the request
+   */
+  body?: any;
+  /**
+   * Specific client overrides for this request to override aptosConfig
+   */
+  overrides?: ClientConfig;
+};
+
+export type PostAptosRequestOptions = Omit<PostRequestOptions, "type">;
+
+/**
+ * Main function to do a Post request
+ *
+ * @param options PostRequestOptions
+ * @returns
+ */
+export async function post<Req, Res>(options: PostRequestOptions): Promise<AptosResponse<Req, Res>> {
+  const { type, originMethod, path, body, acceptType, contentType, params, aptosConfig, overrides } = options;
+  const url = aptosConfig.getRequestUrl(type);
+
+  return aptosRequest<Req, Res>(
+    {
+      url,
+      method: "POST",
+      originMethod,
+      path,
+      body,
+      contentType: contentType?.valueOf(),
+      acceptType: acceptType?.valueOf(),
+      params,
+      overrides: {
+        ...aptosConfig,
+        ...overrides,
+      },
+    },
+    aptosConfig,
+  );
+}
+
+export async function postAptosFullNode<Req, Res>(options: PostAptosRequestOptions): Promise<AptosResponse<Req, Res>> {
+  return post<Req, Res>({ ...options, type: AptosApiType.FULLNODE });
+}
+
+export async function postAptosIndexer<Req, Res>(options: PostAptosRequestOptions): Promise<AptosResponse<Req, Res>> {
+  return post<Req, Res>({ ...options, type: AptosApiType.INDEXER });
+}
+
+export async function postAptosFaucet<Req, Res>(options: PostAptosRequestOptions): Promise<AptosResponse<Req, Res>> {
+  return post<Req, Res>({ ...options, type: AptosApiType.FAUCET });
+}