@aptos-labs/ts-sdk 1.31.0 → 1.32.0

package/src/core/crypto/privateKey.ts

@@ -1,13 +1,12 @@
-import { HexInput } from "../../types";
+/* eslint-disable max-len */
+
+import { HexInput, PrivateKeyVariants } from "../../types";
+import { Hex } from "../hex";
 import { PublicKey } from "./publicKey";
 import { Signature } from "./signature";
 
 /**
  * Represents a private key used for signing messages and deriving the associated public key.
- *
- * @method sign - Signs the given message with the private key.
- * @method publicKey - Derives the public key associated with the private key.
- * @method toUint8Array - Retrieves the private key in bytes.
  */
 export interface PrivateKey {
   /**
@@ -27,3 +26,80 @@ export interface PrivateKey {
    */
   toUint8Array(): Uint8Array;
 }
+
+export class PrivateKey {
+  /**
+   * The AIP-80 compliant prefixes for each private key type. Append this to a private key's hex representation
+   * to get an AIP-80 compliant string.
+   *
+   * [Read about AIP-80](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md)
+   */
+  public static readonly AIP80_PREFIXES = {
+    [PrivateKeyVariants.Ed25519]: "ed25519-priv-",
+    [PrivateKeyVariants.Secp256k1]: "secp256k1-priv-",
+  };
+
+  /**
+   * Format a HexInput to an AIP-80 compliant string.
+   *
+   * [Read about AIP-80](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md)
+   *
+   * @param privateKey - The HexString or Uint8Array format of the private key.
+   * @param privateKeyType - The private key type
+   */
+  public static formatPrivateKey(privateKey: HexInput, type: PrivateKeyVariants): string {
+    const aip80Prefix = PrivateKey.AIP80_PREFIXES[type];
+    return `${aip80Prefix}${Hex.fromHexInput(privateKey).toString()}`;
+  }
+
+  /**
+   * Parse a HexInput that may be a HexString, Uint8Array, or a AIP-80 compliant string to a Hex instance.
+   *
+   * [Read about AIP-80](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md)
+   *
+   * @param value - A HexString, Uint8Array, or a AIP-80 compliant string.
+   * @param privateKeyType - The private key type
+   * @param strict - If true, the value MUST be compliant with AIP-80.
+   */
+  public static parseHexInput(value: HexInput, type: PrivateKeyVariants, strict?: boolean): Hex {
+    let data: Hex;
+
+    const aip80Prefix = PrivateKey.AIP80_PREFIXES[type];
+    if (typeof value === "string") {
+      if (!strict && !value.startsWith(aip80Prefix)) {
+        // HexString input
+        data = Hex.fromHexInput(value);
+        // If the strictness is false, the user has opted into non-AIP-80 compliant private keys.
+        if (strict !== false) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            "[Aptos SDK] It is recommended that private keys are AIP-80 compliant (https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md). You can fix the private key by formatting it with `PrivateKey.formatPrivateKey(privateKey: string, type: 'ed25519' | 'secp256k1'): string`.",
+          );
+        }
+      } else if (value.startsWith(aip80Prefix)) {
+        // AIP-80 Compliant String input
+        data = Hex.fromHexString(value.split("-")[2]);
+      } else {
+        if (strict) {
+          // The value does not start with the AIP-80 prefix, and strict is true.
+          throw new Error("Invalid HexString input while parsing private key. Must AIP-80 compliant string.");
+        }
+
+        // This condition should never be reached.
+        throw new Error("Invalid HexString input while parsing private key.");
+      }
+    } else {
+      // The value is an Uint8Array
+      data = Hex.fromHexInput(value);
+      // If the strictness is false, the user has opted into non-AIP-80 compliant private keys.
+      if (strict !== false) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          "[Aptos SDK] It is recommended that private keys are parsed as AIP-80 compliant strings instead of Uint8Array (https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md). You can fix the private key by formatting it with `PrivateKey.formatPrivateKey(privateKey: Uint8Array, type: 'ed25519' | 'secp256k1'): string`.",
+        );
+      }
+    }
+
+    return data;
+  }
+}

package/src/core/crypto/secp256k1.ts

@@ -6,7 +6,7 @@ import { secp256k1 } from "@noble/curves/secp256k1";
 import { HDKey } from "@scure/bip32";
 import { Serializable, Deserializer, Serializer } from "../../bcs";
 import { Hex } from "../hex";
-import { HexInput } from "../../types";
+import { HexInput, PrivateKeyVariants } from "../../types";
 import { isValidBIP44Path, mnemonicToSeed } from "./hdKey";
 import { PrivateKey } from "./privateKey";
 import { PublicKey, VerifySignatureArgs } from "./publicKey";
@@ -17,7 +17,6 @@ import { convertSigningMessage } from "./utils";
  * Represents a Secp256k1 ECDSA public key.
  *
  * @extends PublicKey
- * @static
  * @property LENGTH - The length of the Secp256k1 public key in bytes.
  */
 export class Secp256k1PublicKey extends PublicKey {
@@ -148,12 +147,15 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
   /**
    * Create a new PrivateKey instance from a Uint8Array or String.
    *
+   * [Read about AIP-80](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md)
+   *
    * @param hexInput A HexInput (string or Uint8Array)
+   * @param strict If true, private key must AIP-80 compliant.
    */
-  constructor(hexInput: HexInput) {
+  constructor(hexInput: HexInput, strict?: boolean) {
     super();
 
-    const privateKeyHex = Hex.fromHexInput(hexInput);
+    const privateKeyHex = PrivateKey.parseHexInput(hexInput, PrivateKeyVariants.Secp256k1, strict);
     if (privateKeyHex.toUint8Array().length !== Secp256k1PrivateKey.LENGTH) {
       throw new Error(`PrivateKey length should be ${Secp256k1PrivateKey.LENGTH}`);
     }
@@ -168,7 +170,7 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    */
   static generate(): Secp256k1PrivateKey {
     const hexInput = secp256k1.utils.randomPrivateKey();
-    return new Secp256k1PrivateKey(hexInput);
+    return new Secp256k1PrivateKey(hexInput, false);
   }
 
   /**
@@ -204,7 +206,7 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
       throw new Error("Invalid key");
     }
 
-    return new Secp256k1PrivateKey(privateKey);
+    return new Secp256k1PrivateKey(privateKey, false);
   }
 
   // endregion
@@ -251,9 +253,29 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    * @returns string representation of the private key
    */
   toString(): string {
+    return this.toHexString();
+  }
+
+  /**
+   * Get the private key as a hex string with the 0x prefix.
+   *
+   * @returns string representation of the private key.
+   */
+  toHexString(): string {
     return this.key.toString();
   }
 
+  /**
+   * Get the private key as a AIP-80 compliant hex string.
+   *
+   * [Read about AIP-80](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md)
+   *
+   * @returns AIP-80 compliant string representation of the private key.
+   */
+  toAIP80String(): string {
+    return PrivateKey.formatPrivateKey(this.key.toString(), PrivateKeyVariants.Secp256k1);
+  }
+
   // endregion
 
   // region Serializable
@@ -264,7 +286,7 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
 
   static deserialize(deserializer: Deserializer): Secp256k1PrivateKey {
     const bytes = deserializer.deserializeBytes();
-    return new Secp256k1PrivateKey(bytes);
+    return new Secp256k1PrivateKey(bytes, false);
   }
 
   // endregion
@@ -284,13 +306,11 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
 /**
  * Represents a signature of a message signed using a Secp256k1 ECDSA private key.
  *
- * @static
- * @readonly
- * @length The length of Secp256k1 ECDSA signatures, which is 64 bytes.
  */
 export class Secp256k1Signature extends Signature {
   /**
-   * Secp256k1 ecdsa signatures are 256-bit.
+   * Secp256k1 ecdsa signatures are 256-bit or 64 bytes
+   * @readonly
    */
   static readonly LENGTH = 64;
 

package/src/core/hex.ts

@@ -134,6 +134,51 @@ export class Hex {
     return Hex.fromHexString(hexInput);
   }
 
+  /**
+   * Converts an instance of HexInput, which can be a string or a Uint8Array, into a Uint8Array.
+   *
+   * @param hexInput - A HexInput which can be a string or Uint8Array.
+   * @returns A Uint8Array created from the provided hexInput.
+   */
+  static hexInputToUint8Array(hexInput: HexInput): Uint8Array {
+    if (hexInput instanceof Uint8Array) return hexInput;
+    return Hex.fromHexString(hexInput).toUint8Array();
+  }
+
+  /**
+   * Converts a HexInput (string or Uint8Array) to a hex string with '0x' prefix.
+   *
+   * @param hexInput - The input to convert, either a hex string (with/without '0x' prefix) or Uint8Array
+   * @returns A hex string with '0x' prefix (e.g., "0x1234")
+   *
+   * @example
+   * ```typescript
+   * Hex.hexInputToString("1234")        // returns "0x1234"
+   * Hex.hexInputToString("0x1234")      // returns "0x1234"
+   * Hex.hexInputToString(new Uint8Array([0x12, 0x34])) // returns "0x1234"
+   * ```
+   */
+  static hexInputToString(hexInput: HexInput): string {
+    return Hex.fromHexInput(hexInput).toString();
+  }
+
+  /**
+   * Converts a HexInput (string or Uint8Array) to a hex string without '0x' prefix.
+   *
+   * @param hexInput - The input to convert, either a hex string (with/without '0x' prefix) or Uint8Array
+   * @returns A hex string without '0x' prefix (e.g., "1234")
+   *
+   * @example
+   * ```typescript
+   * Hex.hexInputToStringWithoutPrefix("1234")        // returns "1234"
+   * Hex.hexInputToStringWithoutPrefix("0x1234")      // returns "1234"
+   * Hex.hexInputToStringWithoutPrefix(new Uint8Array([0x12, 0x34])) // returns "1234"
+   * ```
+   */
+  static hexInputToStringWithoutPrefix(hexInput: HexInput): string {
+    return Hex.fromHexInput(hexInput).toStringWithoutPrefix();
+  }
+
   // ===
   // Methods for checking validity.
   // ===
@@ -172,3 +217,5 @@ export class Hex {
     return this.data.every((value, index) => value === other.data[index]);
   }
 }
+
+export const hexToAsciiString = (hex: string) => new TextDecoder().decode(Hex.fromHexInput(hex).toUint8Array());

package/src/errors/index.ts

@@ -0,0 +1,406 @@
+import { AptosApiType } from "../utils/const";
+import { getErrorMessage } from "../utils/helpers";
+import { AptosRequest, AptosResponse } from "../types";
+
+export enum KeylessErrorCategory {
+  API_ERROR,
+  EXTERNAL_API_ERROR,
+  SESSION_EXPIRED,
+  INVALID_STATE,
+  UNKNOWN,
+}
+
+export enum KeylessErrorResolutionTip {
+  REAUTHENTICATE = "Re-authentiate to continue using your keyless account",
+  // eslint-disable-next-line max-len
+  REAUTHENTICATE_UNSURE = "Try re-authentiating. If the error persists join the telegram group at https://t.me/+h5CN-W35yUFiYzkx for further support",
+  UPDATE_REQUEST_PARAMS = "Update the invalid request parameters and reauthenticate.",
+  // eslint-disable-next-line max-len
+  RATE_LIMIT_EXCEEDED = "Cache the keyless account and reuse it to avoid making too many requests.  Keyless accounts are valid until either the EphemeralKeyPair expires, when the JWK is rotated, or when the proof verifying key is changed, whichever comes soonest.",
+  // eslint-disable-next-line max-len
+  SERVER_ERROR = "Try again later.  See aptosApiError error for more context. For additional support join the telegram group at https://t.me/+h5CN-W35yUFiYzkx",
+  // eslint-disable-next-line max-len
+  CALL_PRECHECK = "Call `await account.checkKeylessAccountValidity()` to wait for asyncronous changes and check for account validity before signing or serializing.",
+  REINSTANTIATE = "Try instantiating the account again.  Avoid manipulating the account object directly",
+  JOIN_SUPPORT_GROUP = "For support join the telegram group at https://t.me/+h5CN-W35yUFiYzkx",
+  UNKNOWN = "Error unknown. For support join the telegram group at https://t.me/+h5CN-W35yUFiYzkx",
+}
+
+export enum KeylessErrorType {
+  EPHEMERAL_KEY_PAIR_EXPIRED,
+
+  PROOF_NOT_FOUND,
+
+  ASYNC_PROOF_FETCH_FAILED,
+
+  INVALID_PROOF_VERIFICATION_FAILED,
+
+  INVALID_PROOF_VERIFICATION_KEY_NOT_FOUND,
+
+  INVALID_JWT_SIG,
+
+  INVALID_JWT_JWK_NOT_FOUND,
+
+  INVALID_JWT_ISS_NOT_RECOGNIZED,
+
+  INVALID_JWT_FEDERATED_ISS_NOT_SUPPORTED,
+
+  INVALID_TW_SIG_VERIFICATION_FAILED,
+
+  INVALID_TW_SIG_PUBLIC_KEY_NOT_FOUND,
+
+  INVALID_EXPIRY_HORIZON,
+
+  JWT_PARSING_ERROR,
+
+  JWK_FETCH_FAILED,
+
+  JWK_FETCH_FAILED_FEDERATED,
+
+  RATE_LIMIT_EXCEEDED,
+
+  PEPPER_SERVICE_INTERNAL_ERROR,
+
+  PEPPER_SERVICE_BAD_REQUEST,
+
+  PEPPER_SERVICE_OTHER,
+
+  PROVER_SERVICE_INTERNAL_ERROR,
+
+  PROVER_SERVICE_BAD_REQUEST,
+
+  PROVER_SERVICE_OTHER,
+
+  FULL_NODE_CONFIG_LOOKUP_ERROR,
+
+  FULL_NODE_VERIFICATION_KEY_LOOKUP_ERROR,
+
+  FULL_NODE_JWKS_LOOKUP_ERROR,
+
+  FULL_NODE_OTHER,
+
+  UNKNOWN,
+}
+
+const KeylessErrors: { [key in KeylessErrorType]: [string, KeylessErrorCategory, KeylessErrorResolutionTip] } = {
+  [KeylessErrorType.EPHEMERAL_KEY_PAIR_EXPIRED]: [
+    "The ephemeral keypair has expired.",
+    KeylessErrorCategory.SESSION_EXPIRED,
+    KeylessErrorResolutionTip.REAUTHENTICATE,
+  ],
+  [KeylessErrorType.PROOF_NOT_FOUND]: [
+    "The required proof could not be found.",
+    KeylessErrorCategory.INVALID_STATE,
+    KeylessErrorResolutionTip.CALL_PRECHECK,
+  ],
+  [KeylessErrorType.ASYNC_PROOF_FETCH_FAILED]: [
+    "The required proof failed to fetch.",
+    KeylessErrorCategory.INVALID_STATE,
+    KeylessErrorResolutionTip.REAUTHENTICATE_UNSURE,
+  ],
+  [KeylessErrorType.INVALID_PROOF_VERIFICATION_FAILED]: [
+    "The provided proof is invalid.",
+    KeylessErrorCategory.INVALID_STATE,
+    KeylessErrorResolutionTip.REAUTHENTICATE_UNSURE,
+  ],
+  [KeylessErrorType.INVALID_PROOF_VERIFICATION_KEY_NOT_FOUND]: [
+    "The verification key used to authenticate was updated.",
+    KeylessErrorCategory.SESSION_EXPIRED,
+    KeylessErrorResolutionTip.REAUTHENTICATE,
+  ],
+  [KeylessErrorType.INVALID_JWT_SIG]: [
+    "The JWK was found, but JWT failed verification",
+    KeylessErrorCategory.INVALID_STATE,
+    KeylessErrorResolutionTip.REAUTHENTICATE_UNSURE,
+  ],
+  [KeylessErrorType.INVALID_JWT_JWK_NOT_FOUND]: [
+    "The JWK required to verify the JWT could not be found. The JWK may have been rotated out.",
+    KeylessErrorCategory.SESSION_EXPIRED,
+    KeylessErrorResolutionTip.REAUTHENTICATE,
+  ],
+  [KeylessErrorType.INVALID_JWT_ISS_NOT_RECOGNIZED]: [
+    "The JWT issuer is not recognized.",
+    KeylessErrorCategory.INVALID_STATE,
+    KeylessErrorResolutionTip.UPDATE_REQUEST_PARAMS,
+  ],
+  [KeylessErrorType.INVALID_JWT_FEDERATED_ISS_NOT_SUPPORTED]: [
+    "The JWT issuer is not supported by the Federated Keyless ",
+    KeylessErrorCategory.API_ERROR,
+    KeylessErrorResolutionTip.REAUTHENTICATE_UNSURE,
+  ],
+  [KeylessErrorType.INVALID_TW_SIG_VERIFICATION_FAILED]: [
+    "The training wheels signature is invalid.",
+    KeylessErrorCategory.INVALID_STATE,
+    KeylessErrorResolutionTip.REAUTHENTICATE_UNSURE,
+  ],
+  [KeylessErrorType.INVALID_TW_SIG_PUBLIC_KEY_NOT_FOUND]: [
+    "The public key used to verify the training wheels signature was not found.",
+    KeylessErrorCategory.SESSION_EXPIRED,
+    KeylessErrorResolutionTip.REAUTHENTICATE,
+  ],
+  [KeylessErrorType.INVALID_EXPIRY_HORIZON]: [
+    "The expiry horizon is invalid.",
+    KeylessErrorCategory.SESSION_EXPIRED,
+    KeylessErrorResolutionTip.REAUTHENTICATE,
+  ],
+  [KeylessErrorType.JWK_FETCH_FAILED]: [
+    "Failed to fetch JWKS.",
+    KeylessErrorCategory.EXTERNAL_API_ERROR,
+    KeylessErrorResolutionTip.JOIN_SUPPORT_GROUP,
+  ],
+  [KeylessErrorType.JWK_FETCH_FAILED_FEDERATED]: [
+    "Failed to fetch JWKS for Federated Keyless provider.",
+    KeylessErrorCategory.EXTERNAL_API_ERROR,
+    KeylessErrorResolutionTip.JOIN_SUPPORT_GROUP,
+  ],
+  [KeylessErrorType.RATE_LIMIT_EXCEEDED]: [
+    "Rate limit exceeded. Too many requests in a short period.",
+    KeylessErrorCategory.API_ERROR,
+    KeylessErrorResolutionTip.RATE_LIMIT_EXCEEDED,
+  ],
+  [KeylessErrorType.PEPPER_SERVICE_INTERNAL_ERROR]: [
+    "Internal error from Pepper service.",
+    KeylessErrorCategory.API_ERROR,
+    KeylessErrorResolutionTip.SERVER_ERROR,
+  ],
+  [KeylessErrorType.PEPPER_SERVICE_BAD_REQUEST]: [
+    "Bad request sent to Pepper service.",
+    KeylessErrorCategory.API_ERROR,
+    KeylessErrorResolutionTip.UPDATE_REQUEST_PARAMS,
+  ],
+  [KeylessErrorType.PEPPER_SERVICE_OTHER]: [
+    "Unknown error from Pepper service.",
+    KeylessErrorCategory.API_ERROR,
+    KeylessErrorResolutionTip.SERVER_ERROR,
+  ],
+  [KeylessErrorType.PROVER_SERVICE_INTERNAL_ERROR]: [
+    "Internal error from Prover service.",
+    KeylessErrorCategory.API_ERROR,
+    KeylessErrorResolutionTip.SERVER_ERROR,
+  ],
+  [KeylessErrorType.PROVER_SERVICE_BAD_REQUEST]: [
+    "Bad request sent to Prover service.",
+    KeylessErrorCategory.API_ERROR,
+    KeylessErrorResolutionTip.UPDATE_REQUEST_PARAMS,
+  ],
+  [KeylessErrorType.PROVER_SERVICE_OTHER]: [
+    "Unknown error from Prover service.",
+    KeylessErrorCategory.API_ERROR,
+    KeylessErrorResolutionTip.SERVER_ERROR,
+  ],
+  [KeylessErrorType.JWT_PARSING_ERROR]: [
+    "Error when parsing JWT. This should never happen. Join https://t.me/+h5CN-W35yUFiYzkx for support",
+    KeylessErrorCategory.INVALID_STATE,
+    KeylessErrorResolutionTip.REINSTANTIATE,
+  ],
+  [KeylessErrorType.FULL_NODE_CONFIG_LOOKUP_ERROR]: [
+    "Error when looking up on-chain keyless configuration.",
+    KeylessErrorCategory.API_ERROR,
+    KeylessErrorResolutionTip.SERVER_ERROR,
+  ],
+  [KeylessErrorType.FULL_NODE_VERIFICATION_KEY_LOOKUP_ERROR]: [
+    "Error when looking up on-chain verification key.",
+    KeylessErrorCategory.API_ERROR,
+    KeylessErrorResolutionTip.SERVER_ERROR,
+  ],
+  [KeylessErrorType.FULL_NODE_JWKS_LOOKUP_ERROR]: [
+    "Error when looking up on-chain JWKS.",
+    KeylessErrorCategory.API_ERROR,
+    KeylessErrorResolutionTip.SERVER_ERROR,
+  ],
+  [KeylessErrorType.FULL_NODE_OTHER]: [
+    "Unknown error from full node.",
+    KeylessErrorCategory.API_ERROR,
+    KeylessErrorResolutionTip.SERVER_ERROR,
+  ],
+  [KeylessErrorType.UNKNOWN]: [
+    "An unknown error has occurred.",
+    KeylessErrorCategory.UNKNOWN,
+    KeylessErrorResolutionTip.UNKNOWN,
+  ],
+};
+
+export class KeylessError extends Error {
+  readonly innerError?: unknown;
+
+  readonly category: KeylessErrorCategory;
+
+  readonly resolutionTip: KeylessErrorResolutionTip;
+
+  readonly type: KeylessErrorType;
+
+  readonly details?: string;
+
+  /** @internal this constructor is for sdk internal use - do not instantiate outside of the SDK codebase */
+  constructor(args: {
+    innerError?: unknown;
+    category: KeylessErrorCategory;
+    resolutionTip: KeylessErrorResolutionTip;
+    type: KeylessErrorType;
+    message?: string;
+    details?: string;
+  }) {
+    const { innerError, category, resolutionTip, type, message = KeylessErrors[type][0], details } = args;
+    super(message);
+    this.name = "KeylessError";
+    this.innerError = innerError;
+    this.category = category;
+    this.resolutionTip = resolutionTip;
+    this.type = type;
+    this.details = details;
+    this.message = KeylessError.constructMessage(message, resolutionTip, innerError, details);
+  }
+
+  static constructMessage(
+    message: string,
+    tip: KeylessErrorResolutionTip,
+    innerError?: unknown,
+    details?: string,
+  ): string {
+    let result = `\nMessage: ${message}`;
+    if (details) {
+      result += `\nDetails: ${details}`;
+    }
+    if (innerError instanceof AptosApiError) {
+      result += `\nAptosApiError: ${innerError.message}`;
+    } else if (innerError !== undefined) {
+      result += `\nError: ${getErrorMessage(innerError)}`;
+    }
+    result += `\nKeylessErrorResolutionTip: ${tip}`;
+    return result;
+  }
+
+  /**
+   * Static constructor that creates a KeylessError instance using the KeylessErrors constant
+   * @param args.type The type of KeylessError
+   * @param args.aptosApiError optional AptosApiError supplied for api errors
+   * @param args.details optional details to include in the error message
+   * @returns A new KeylessError instance
+   */
+  static fromErrorType(args: { type: KeylessErrorType; error?: unknown; details?: string }): KeylessError {
+    const { error, type, details } = args;
+
+    const [message, category, resolutionTip] = KeylessErrors[type];
+    return new KeylessError({
+      message,
+      details,
+      innerError: error,
+      category,
+      resolutionTip,
+      type,
+    });
+  }
+}
+
+/**
+ * Options for handling errors in the Aptos API.
+ */
+type AptosApiErrorOpts = {
+  apiType: AptosApiType;
+  aptosRequest: AptosRequest;
+  aptosResponse: AptosResponse<any, any>;
+};
+
+/**
+ * Represents an error returned from the Aptos API.
+ * This class encapsulates the details of the error, including the request URL, response status, and additional data.
+ *
+ * @param name - The name of the error, which is always "AptosApiError".
+ * @param url - The URL to which the request was made.
+ * @param status - The HTTP response status code (e.g., 400).
+ * @param statusText - The message associated with the response status.
+ * @param data - The response data returned from the API.
+ * @param request - The original AptosRequest that triggered the error.
+ */
+export class AptosApiError extends Error {
+  readonly url: string;
+
+  readonly status: number;
+
+  readonly statusText: string;
+
+  readonly data: any;
+
+  readonly request: AptosRequest;
+
+  /**
+   * Constructs an instance of AptosApiError with relevant error details.
+   *
+   * @param opts - The options for creating the AptosApiError.
+   * @param opts.apiType - The type of API that generated the error.
+   * @param opts.aptosRequest - The request object that caused the error.
+   * @param opts.aptosResponse - The response object containing error details.
+   *
+   * @internal This constructor is for SDK internal use - do not instantiate outside the SDK codebase.
+   */
+  constructor({ apiType, aptosRequest, aptosResponse }: AptosApiErrorOpts) {
+    super(deriveErrorMessage({ apiType, aptosRequest, aptosResponse }));
+
+    this.name = "AptosApiError";
+    this.url = aptosResponse.url;
+    this.status = aptosResponse.status;
+    this.statusText = aptosResponse.statusText;
+    this.data = aptosResponse.data;
+    this.request = aptosRequest;
+  }
+}
+
+/**
+ * Derives an error message from the Aptos API response, providing context for debugging.
+ * This function helps in understanding the nature of the error encountered during an API request.
+ *
+ * @param {AptosApiErrorOpts} opts - The options for deriving the error message.
+ * @param {AptosApiType} opts.apiType - The type of API being called.
+ * @param {AptosRequest} opts.aptosRequest - The original request made to the Aptos API.
+ * @param {AptosResponse} opts.aptosResponse - The response received from the Aptos API.
+ */
+function deriveErrorMessage({ apiType, aptosRequest, aptosResponse }: AptosApiErrorOpts): string {
+  // eslint-disable-next-line max-len
+  // extract the W3C trace_id from the response headers if it exists. Some services set this in the response, and it's useful for debugging.
+  // See https://www.w3.org/TR/trace-context/#relationship-between-the-headers .
+  const traceId = aptosResponse.headers?.traceparent?.split("-")[1];
+  const traceIdString = traceId ? `(trace_id:${traceId}) ` : "";
+
+  const errorPrelude: string = `Request to [${apiType}]: ${aptosRequest.method} ${
+    aptosResponse.url ?? aptosRequest.url
+  } ${traceIdString}failed with`;
+
+  // handle graphql responses from indexer api and extract the error message of the first error
+  if (apiType === AptosApiType.INDEXER && aptosResponse.data?.errors?.[0]?.message != null) {
+    return `${errorPrelude}: ${aptosResponse.data.errors[0].message}`;
+  }
+
+  // Received well-known structured error response body - simply serialize and return it.
+  // We don't need http status codes etc. in this case.
+  if (aptosResponse.data?.message != null && aptosResponse.data?.error_code != null) {
+    return `${errorPrelude}: ${JSON.stringify(aptosResponse.data)}`;
+  }
+
+  // This is the generic/catch-all case. We received some response from the API, but it doesn't appear to be a well-known structure.
+  // We print http status codes and the response body (after some trimming),
+  // in the hope that this gives enough context what went wrong without printing overly huge messages.
+  return `${errorPrelude} status: ${aptosResponse.statusText}(code:${
+    aptosResponse.status
+  }) and response body: ${serializeAnyPayloadForErrorMessage(aptosResponse.data)}`;
+}
+
+const SERIALIZED_PAYLOAD_TRIM_TO_MAX_LENGTH = 400;
+
+/**
+ * This function accepts a payload of any type (probably an object) and serializes it to a string
+ * Since we don't know the type or size of the payload, and we don't want to add a huge object in full to the error message
+ * we limit the to the first 200 and last 200 characters of the serialized payload and put a "..." in the middle.
+ * @param payload - The payload to serialize, which can be of any type.
+ *
+ * @returns A string representation of the serialized payload, potentially truncated.
+ */
+function serializeAnyPayloadForErrorMessage(payload: any): string {
+  const serializedPayload = JSON.stringify(payload);
+  if (serializedPayload.length <= SERIALIZED_PAYLOAD_TRIM_TO_MAX_LENGTH) {
+    return serializedPayload;
+  }
+  return `truncated(original_size:${serializedPayload.length}): ${serializedPayload.slice(
+    0,
+    SERIALIZED_PAYLOAD_TRIM_TO_MAX_LENGTH / 2,
+  )}...${serializedPayload.slice(-SERIALIZED_PAYLOAD_TRIM_TO_MAX_LENGTH / 2)}`;
+}

package/src/index.ts

@@ -6,6 +6,7 @@ export * from "./api";
 export * from "./bcs";
 export * from "./client";
 export * from "./core";
+export * from "./errors";
 export * from "./transactions";
 export * from "./transactions/management";
 export * from "./types";