@moveindustries/ts-sdk 5.1.4

package/src/core/crypto/singleKey.ts

@@ -0,0 +1,351 @@
+import type { MovementConfig } from "../../api";
+import { Deserializer, Serializer } from "../../bcs";
+import {
+  AnyPublicKeyVariant,
+  AnySignatureVariant,
+  SigningScheme as AuthenticationKeyScheme,
+  HexInput,
+} from "../../types";
+import { AuthenticationKey } from "../authenticationKey";
+import { Ed25519PrivateKey, Ed25519PublicKey, Ed25519Signature } from "./ed25519";
+import { FederatedKeylessPublicKey } from "./federatedKeyless";
+import { KeylessPublicKey, KeylessSignature } from "./keyless";
+import { AccountPublicKey, PublicKey } from "./publicKey";
+import { Secp256k1PrivateKey, Secp256k1PublicKey, Secp256k1Signature } from "./secp256k1";
+import { Secp256r1PublicKey, WebAuthnSignature } from "./secp256r1";
+import { Signature } from "./signature";
+
+export type PrivateKeyInput = Ed25519PrivateKey | Secp256k1PrivateKey;
+
+/**
+ * Represents any public key supported by Movement.
+ *
+ * Since [AIP-55](https://github.com/aptos-foundation/AIPs/pull/263) Movement supports
+ * `Legacy` and `Unified` authentication keys.
+ *
+ * Any unified authentication key is represented in the SDK as `AnyPublicKey`.
+ * @group Implementation
+ * @category Serialization
+ */
+export class AnyPublicKey extends AccountPublicKey {
+  /**
+   * Reference to the inner public key
+   * @group Implementation
+   * @category Serialization
+   */
+  public readonly publicKey: PublicKey;
+
+  /**
+   * Index of the underlying enum variant
+   * @group Implementation
+   * @category Serialization
+   */
+  public readonly variant: AnyPublicKeyVariant;
+
+  // region Constructors
+
+  /**
+   * Creates an instance of the signature class based on the provided signature type.
+   * This allows for the handling of different signature variants such as Ed25519, Secp256k1, and Keyless.
+   *
+   * @param publicKey - The publicKey object which determines the variant to be used.
+   * @throws Error if the provided signature type is unsupported.
+   * @group Implementation
+   * @category Serialization
+   */
+  constructor(publicKey: PublicKey) {
+    super();
+    this.publicKey = publicKey;
+    if (publicKey instanceof Ed25519PublicKey) {
+      this.variant = AnyPublicKeyVariant.Ed25519;
+    } else if (publicKey instanceof Secp256k1PublicKey) {
+      this.variant = AnyPublicKeyVariant.Secp256k1;
+    } else if (publicKey instanceof Secp256r1PublicKey) {
+      this.variant = AnyPublicKeyVariant.Secp256r1;
+    } else if (publicKey instanceof KeylessPublicKey) {
+      this.variant = AnyPublicKeyVariant.Keyless;
+    } else if (publicKey instanceof FederatedKeylessPublicKey) {
+      this.variant = AnyPublicKeyVariant.FederatedKeyless;
+    } else {
+      throw new Error("Unsupported public key type");
+    }
+  }
+
+  // endregion
+
+  // region AccountPublicKey
+
+  /**
+   * Verifies the provided signature against the given message.
+   * This function helps ensure the integrity and authenticity of the message by confirming that the signature is valid.
+   *
+   * @param args - The arguments for signature verification.
+   * @param args.message - The message that was signed.
+   * @param args.signature - The signature to verify, which must be an instance of AnySignature.
+   * @returns A boolean indicating whether the signature is valid for the given message.
+   * @group Implementation
+   * @category Serialization
+   */
+  verifySignature(args: { message: HexInput; signature: AnySignature }): boolean {
+    const { message, signature } = args;
+    if (this.publicKey instanceof KeylessPublicKey) {
+      throw new Error("Use verifySignatureAsync to verify Keyless signatures");
+    }
+    return this.publicKey.verifySignature({
+      message,
+      signature: signature.signature,
+    });
+  }
+
+  /**
+   * Verifies the provided signature against the given message.
+   * This function helps ensure the integrity and authenticity of the message by confirming that the signature is valid.
+   *
+   * @param args - The arguments for signature verification.
+   * @param args.movementConfig - The configuration object for connecting to the Movement network
+   * @param args.message - The message that was signed.
+   * @param args.signature - The signature to verify, which must be an instance of AnySignature.
+   * @returns A boolean indicating whether the signature is valid for the given message.
+   * @group Implementation
+   * @category Serialization
+   */
+  async verifySignatureAsync(args: {
+    movementConfig: MovementConfig;
+    message: HexInput;
+    signature: Signature;
+    options?: { throwErrorWithReason?: boolean };
+  }): Promise<boolean> {
+    if (!(args.signature instanceof AnySignature)) {
+      if (args.options?.throwErrorWithReason) {
+        throw new Error("Signature must be an instance of AnySignature");
+      }
+      return false;
+    }
+    return await this.publicKey.verifySignatureAsync({
+      ...args,
+      signature: args.signature.signature,
+    });
+  }
+
+  /**
+   * Generates an authentication key from the current instance's byte representation.
+   * This function is essential for creating a unique identifier for authentication purposes.
+   *
+   * @returns {AuthenticationKey} The generated authentication key.
+   * @group Implementation
+   * @category Serialization
+   */
+  authKey(): AuthenticationKey {
+    return AuthenticationKey.fromSchemeAndBytes({
+      scheme: AuthenticationKeyScheme.SingleKey,
+      input: this.toUint8Array(),
+    });
+  }
+
+  /**
+   * Get the signature in bytes (Uint8Array).
+   *
+   * This function is a warning that it will soon return the underlying signature bytes directly.
+   * Use AnySignature.bcsToBytes() instead.
+   *
+   * @returns Uint8Array representation of the signature.
+   * @group Implementation
+   * @category Serialization
+   */
+  toUint8Array(): Uint8Array {
+    return this.bcsToBytes();
+  }
+
+  // endregion
+
+  // region Serializable
+
+  /**
+   * Serializes the current object using the provided serializer.
+   * This function helps in converting the object into a format suitable for transmission or storage.
+   *
+   * @param serializer - The serializer instance used to perform the serialization.
+   * @group Implementation
+   * @category Serialization
+   */
+  serialize(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(this.variant);
+    this.publicKey.serialize(serializer);
+  }
+
+  /**
+   * Deserializes an AnySignature from the provided deserializer.
+   * This function helps in reconstructing the AnySignature object from its serialized form, allowing for further processing or validation.
+   *
+   * @param deserializer - The deserializer instance used to read the serialized data.
+   * @group Implementation
+   * @category Serialization
+   */
+  static deserialize(deserializer: Deserializer): AnyPublicKey {
+    const variantIndex = deserializer.deserializeUleb128AsU32();
+    let publicKey: PublicKey;
+    switch (variantIndex) {
+      case AnyPublicKeyVariant.Ed25519:
+        publicKey = Ed25519PublicKey.deserialize(deserializer);
+        break;
+      case AnyPublicKeyVariant.Secp256k1:
+        publicKey = Secp256k1PublicKey.deserialize(deserializer);
+        break;
+      case AnyPublicKeyVariant.Secp256r1:
+        publicKey = Secp256r1PublicKey.deserialize(deserializer);
+        break;
+      case AnyPublicKeyVariant.Keyless:
+        publicKey = KeylessPublicKey.deserialize(deserializer);
+        break;
+      case AnyPublicKeyVariant.FederatedKeyless:
+        publicKey = FederatedKeylessPublicKey.deserialize(deserializer);
+        break;
+      default:
+        throw new Error(`Unknown variant index for AnyPublicKey: ${variantIndex}`);
+    }
+    return new AnyPublicKey(publicKey);
+  }
+  // endregion
+
+  /**
+   * Determines if the provided public key is an instance of AnyPublicKey.
+   *
+   * @param publicKey - The public key to check.
+   * @deprecated Use `instanceof AnyPublicKey` instead.
+   * @group Implementation
+   * @category Serialization
+   */
+  static isPublicKey(publicKey: AccountPublicKey): publicKey is AnyPublicKey {
+    return publicKey instanceof AnyPublicKey;
+  }
+
+  /**
+   * Determines if the current public key is an instance of Ed25519PublicKey.
+   *
+   * @deprecated use `publicKey instanceof Ed25519PublicKey` instead.
+   * @group Implementation
+   * @category Serialization
+   */
+  isEd25519(): boolean {
+    return this.publicKey instanceof Ed25519PublicKey;
+  }
+
+  /**
+   * Checks if the public key is an instance of Secp256k1PublicKey.
+   *
+   * @deprecated use `publicKey instanceof Secp256k1PublicKey` instead.
+   * @group Implementation
+   * @category Serialization
+   */
+  isSecp256k1PublicKey(): boolean {
+    return this.publicKey instanceof Secp256k1PublicKey;
+  }
+
+  /**
+   * Determines if the provided publicKey is an instance of a valid PublicKey object.
+   *
+   * @param publicKey - The publicKey to be checked for validity.
+   * @param publicKey.publicKey - The actual publicKey object that needs to be validated.
+   * @returns True if the signature is a valid instance; otherwise, false.
+   * @group Implementation
+   * @category Serialization
+   */
+  static isInstance(publicKey: PublicKey): publicKey is AnyPublicKey {
+    return "publicKey" in publicKey && "variant" in publicKey;
+  }
+}
+
+/**
+ * Represents a signature that utilizes the SingleKey authentication scheme.
+ * This class is designed to encapsulate various types of signatures, which can
+ * only be generated by a `SingleKeySigner` due to the shared authentication mechanism.
+ *
+ * @extends Signature
+ * @group Implementation
+ * @category Serialization
+ */
+export class AnySignature extends Signature {
+  public readonly signature: Signature;
+
+  /**
+   * Index of the underlying enum variant
+   * @group Implementation
+   * @category Serialization
+   */
+  private readonly variant: AnySignatureVariant;
+
+  // region Constructors
+
+  constructor(signature: Signature) {
+    super();
+    this.signature = signature;
+
+    if (signature instanceof Ed25519Signature) {
+      this.variant = AnySignatureVariant.Ed25519;
+    } else if (signature instanceof Secp256k1Signature) {
+      this.variant = AnySignatureVariant.Secp256k1;
+    } else if (signature instanceof WebAuthnSignature) {
+      this.variant = AnySignatureVariant.WebAuthn;
+    } else if (signature instanceof KeylessSignature) {
+      this.variant = AnySignatureVariant.Keyless;
+    } else {
+      throw new Error("Unsupported signature type");
+    }
+  }
+
+  // endregion
+
+  // region AccountSignature
+
+  toUint8Array(): Uint8Array {
+    // TODO: keep this warning around for a bit, and eventually change this to return `this.signature.toUint8Array()`.
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[Aptos SDK] Calls to AnySignature.toUint8Array() will soon return the underlying signature bytes. " +
+      "Use AnySignature.bcsToBytes() instead.",
+    );
+    return this.bcsToBytes();
+  }
+
+  // endregion
+
+  // region Serializable
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(this.variant);
+    this.signature.serialize(serializer);
+  }
+
+  static deserialize(deserializer: Deserializer): AnySignature {
+    const variantIndex = deserializer.deserializeUleb128AsU32();
+    let signature: Signature;
+    switch (variantIndex) {
+      case AnySignatureVariant.Ed25519:
+        signature = Ed25519Signature.deserialize(deserializer);
+        break;
+      case AnySignatureVariant.Secp256k1:
+        signature = Secp256k1Signature.deserialize(deserializer);
+        break;
+      case AnySignatureVariant.WebAuthn:
+        signature = WebAuthnSignature.deserialize(deserializer);
+        break;
+      case AnySignatureVariant.Keyless:
+        signature = KeylessSignature.deserialize(deserializer);
+        break;
+      default:
+        throw new Error(`Unknown variant index for AnySignature: ${variantIndex}`);
+    }
+    return new AnySignature(signature);
+  }
+
+  // endregion
+
+  static isInstance(signature: Signature): signature is AnySignature {
+    return (
+      "signature" in signature &&
+      typeof signature.signature === "object" &&
+      signature.signature !== null &&
+      "toUint8Array" in signature.signature
+    );
+  }
+}

package/src/core/crypto/types.ts

@@ -0,0 +1,9 @@
+import { AnyPublicKey } from "./singleKey";
+import { Ed25519PublicKey } from "./ed25519";
+import { MultiKey } from "./multiKey";
+import { MultiEd25519PublicKey } from "./multiEd25519";
+
+// This type is used to represent the base from of an account's public key.
+// These are the types of public keys that can be used to derive an account's address by appending
+// the signing scheme to the public key as bytes and hashing it.
+export type BaseAccountPublicKey = Ed25519PublicKey | AnyPublicKey | MultiKey | MultiEd25519PublicKey;

package/src/core/crypto/utils.ts

@@ -0,0 +1,63 @@
+import { HexInput, SigningScheme } from "../../types";
+import { Hex } from "../hex";
+import { Ed25519PublicKey } from "./ed25519";
+import { FederatedKeylessPublicKey } from "./federatedKeyless";
+import { KeylessPublicKey } from "./keyless";
+import { MultiEd25519PublicKey } from "./multiEd25519";
+import { MultiKey } from "./multiKey";
+import { AccountPublicKey } from "./publicKey";
+import { AnyPublicKey } from "./singleKey";
+import { BaseAccountPublicKey } from "./types";
+
+/**
+ * Helper function to convert a message to sign or to verify to a valid message input
+ *
+ * @param message a message as a string or Uint8Array
+ *
+ * @returns a valid HexInput - string or Uint8Array
+ * @group Implementation
+ * @category Serialization
+ */
+export const convertSigningMessage = (message: HexInput): HexInput => {
+  // if message is of type string, verify it is a valid Hex string
+  if (typeof message === "string") {
+    const isValid = Hex.isValid(message);
+    // If message is not a valid Hex string, convert it
+    if (!isValid.valid) {
+      return new TextEncoder().encode(message);
+    }
+    // If message is a valid Hex string, return it
+    return message;
+  }
+  // message is a Uint8Array
+  return message;
+};
+
+export const accountPublicKeyToBaseAccountPublicKey = (publicKey: AccountPublicKey): BaseAccountPublicKey => {
+  if (
+    publicKey instanceof Ed25519PublicKey ||
+    publicKey instanceof AnyPublicKey ||
+    publicKey instanceof MultiEd25519PublicKey ||
+    publicKey instanceof MultiKey
+  ) {
+    return publicKey;
+  }
+  if (publicKey instanceof KeylessPublicKey || publicKey instanceof FederatedKeylessPublicKey) {
+    return new AnyPublicKey(publicKey);
+  }
+  throw new Error(`Unknown account public key: ${publicKey}`);
+};
+
+export const accountPublicKeyToSigningScheme = (publicKey: AccountPublicKey): SigningScheme => {
+  const baseAccountPublicKey = accountPublicKeyToBaseAccountPublicKey(publicKey);
+  if (baseAccountPublicKey instanceof Ed25519PublicKey) {
+    return SigningScheme.Ed25519;
+  } else if (baseAccountPublicKey instanceof AnyPublicKey) {
+    return SigningScheme.SingleKey;
+  } else if (baseAccountPublicKey instanceof MultiEd25519PublicKey) {
+    return SigningScheme.MultiEd25519;
+  } else if (baseAccountPublicKey instanceof MultiKey) {
+    return SigningScheme.MultiKey;
+  }
+  throw new Error(`Unknown signing scheme: ${baseAccountPublicKey}`);
+};

package/src/core/hex.ts

@@ -0,0 +1,241 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils";
+import { HexInput } from "../types";
+import { ParsingError, ParsingResult } from "./common";
+
+/**
+ * Provides reasons for parsing failures related to hexadecimal values.
+ * @group Implementation
+ * @category Serialization
+ */
+export enum HexInvalidReason {
+  TOO_SHORT = "too_short",
+  INVALID_LENGTH = "invalid_length",
+  INVALID_HEX_CHARS = "invalid_hex_chars",
+}
+
+/**
+ * NOTE: Do not use this class when working with account addresses; use AccountAddress instead.
+ * When accepting hex data as input to a function, prefer to accept HexInput and
+ *
+ * A helper class for working with hex data. Hex data, when represented as a string,
+ * generally looks like this, for example: 0xaabbcc, 45cd32, etc.
+ *
+ * then use the static helper methods of this class to convert it into the desired
+ * format. This enables the greatest flexibility for the developer.
+ *
+ * Example usage:
+ * ```typescript
+ * getTransactionByHash(txnHash: HexInput): Promise<Transaction> {
+ *   const txnHashString = Hex.fromHexInput(txnHash).toString();
+ *   return await getTransactionByHashInner(txnHashString);
+ * }
+ * ```
+ * This call to `Hex.fromHexInput().toString()` converts the HexInput to a hex string
+ * with a leading 0x prefix, regardless of what the input format was.
+ *
+ * Other ways to chain the functions together:
+ * - `Hex.fromHexString({ hexInput: "0x1f" }).toUint8Array()`
+ * - `new Hex([1, 3]).toStringWithoutPrefix()`
+ * @group Implementation
+ * @category Serialization
+ */
+export class Hex {
+  private readonly data: Uint8Array;
+
+  /**
+   * Create a new Hex instance from a Uint8Array.
+   *
+   * @param data - The Uint8Array containing the data to initialize the Hex instance.
+   * @group Implementation
+   * @category Serialization
+   */
+  constructor(data: Uint8Array) {
+    this.data = data;
+  }
+
+  // ===
+  // Methods for representing an instance of Hex as other types.
+  // ===
+
+  /**
+   * Get the inner hex data as a Uint8Array. The inner data is already a Uint8Array, so no conversion takes place.
+   *
+   * @returns Hex data as Uint8Array
+   * @group Implementation
+   * @category Serialization
+   */
+  toUint8Array(): Uint8Array {
+    return this.data;
+  }
+
+  /**
+   * Get the hex data as a string without the 0x prefix.
+   *
+   * @returns Hex string without 0x prefix
+   * @group Implementation
+   * @category Serialization
+   */
+  toStringWithoutPrefix(): string {
+    return bytesToHex(this.data);
+  }
+
+  /**
+   * Get the hex data as a string with the 0x prefix.
+   *
+   * @returns Hex string with 0x prefix
+   * @group Implementation
+   * @category Serialization
+   */
+  toString(): string {
+    return `0x${this.toStringWithoutPrefix()}`;
+  }
+
+  // ===
+  // Methods for creating an instance of Hex from other types.
+  // ===
+
+  /**
+   * Converts a hex string into a Hex instance, allowing for both prefixed and non-prefixed formats.
+   *
+   * @param str - A hex string, with or without the 0x prefix.
+   *
+   * @throws ParsingError - If the hex string is too short, has an odd number of characters, or contains invalid hex characters.
+   *
+   * @returns Hex - The resulting Hex instance created from the provided string.
+   * @group Implementation
+   * @category Serialization
+   */
+  static fromHexString(str: string): Hex {
+    let input = str;
+
+    if (input.startsWith("0x")) {
+      input = input.slice(2);
+    }
+
+    if (input.length === 0) {
+      throw new ParsingError(
+        "Hex string is too short, must be at least 1 char long, excluding the optional leading 0x.",
+        HexInvalidReason.TOO_SHORT,
+      );
+    }
+
+    if (input.length % 2 !== 0) {
+      throw new ParsingError("Hex string must be an even number of hex characters.", HexInvalidReason.INVALID_LENGTH);
+    }
+
+    try {
+      return new Hex(hexToBytes(input));
+    } catch (error: any) {
+      throw new ParsingError(
+        `Hex string contains invalid hex characters: ${error?.message}`,
+        HexInvalidReason.INVALID_HEX_CHARS,
+      );
+    }
+  }
+
+  /**
+   * Converts an instance of HexInput, which can be a string or a Uint8Array, into a Hex instance.
+   * This function is useful for transforming hexadecimal representations into a structured Hex object for further manipulation.
+   *
+   * @param hexInput - A HexInput which can be a string or Uint8Array.
+   * @returns A Hex instance created from the provided hexInput.
+   * @group Implementation
+   * @category Serialization
+   */
+  static fromHexInput(hexInput: HexInput): Hex {
+    if (hexInput instanceof Uint8Array) return new Hex(hexInput);
+    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.
+  // ===
+
+  /**
+   * Check if the provided string is a valid hexadecimal representation.
+   *
+   * @param str - A hex string representing byte data.
+   *
+   * @returns An object containing:
+   *  - valid: A boolean indicating whether the string is valid.
+   *  - invalidReason: The reason for invalidity if the string is not valid.
+   *  - invalidReasonMessage: A message explaining why the string is invalid.
+   * @group Implementation
+   * @category Serialization
+   */
+  static isValid(str: string): ParsingResult<HexInvalidReason> {
+    try {
+      Hex.fromHexString(str);
+      return { valid: true };
+    } catch (error: any) {
+      return {
+        valid: false,
+        invalidReason: error?.invalidReason,
+        invalidReasonMessage: error?.message,
+      };
+    }
+  }
+
+  /**
+   * Determine if two Hex instances are equal by comparing their underlying byte data.
+   *
+   * @param other The Hex instance to compare to.
+   * @returns true if the Hex instances are equal, false if not.
+   * @group Implementation
+   * @category Serialization
+   */
+  equals(other: Hex): boolean {
+    if (this.data.length !== other.data.length) return false;
+    return this.data.every((value, index) => value === other.data[index]);
+  }
+}
+
+export const hexToAsciiString = (hex: string) => new TextDecoder().decode(Hex.fromHexInput(hex).toUint8Array());

package/src/core/index.ts

@@ -0,0 +1,10 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+export * from "./account";
+export * from "./accountAddress";
+export * from "./authenticationKey";
+export * from "./common";
+export * from "./crypto";
+export * from "./hex";
+