@moveindustries/ts-sdk 5.1.4

package/src/core/crypto/poseidon.ts

@@ -0,0 +1,231 @@
+/* eslint-disable no-bitwise */
+import {
+  poseidon1,
+  poseidon2,
+  poseidon3,
+  poseidon4,
+  poseidon5,
+  poseidon6,
+  poseidon7,
+  poseidon8,
+  poseidon9,
+  poseidon10,
+  poseidon11,
+  poseidon12,
+  poseidon13,
+  poseidon14,
+  poseidon15,
+  poseidon16,
+} from "poseidon-lite";
+
+const numInputsToPoseidonFunc = [
+  poseidon1,
+  poseidon2,
+  poseidon3,
+  poseidon4,
+  poseidon5,
+  poseidon6,
+  poseidon7,
+  poseidon8,
+  poseidon9,
+  poseidon10,
+  poseidon11,
+  poseidon12,
+  poseidon13,
+  poseidon14,
+  poseidon15,
+  poseidon16,
+];
+
+const BYTES_PACKED_PER_SCALAR = 31;
+const MAX_NUM_INPUT_SCALARS = 16;
+const MAX_NUM_INPUT_BYTES = (MAX_NUM_INPUT_SCALARS - 1) * BYTES_PACKED_PER_SCALAR;
+
+/**
+ * Hashes a string to a field element via Poseidon hashing.
+ * This function is useful for converting a string into a fixed-size hash that can be used in cryptographic applications.
+ *
+ * @param str - The string to be hashed.
+ * @param maxSizeBytes - The maximum size in bytes for the resulting hash.
+ * @returns bigint - The result of the hash.
+ * @group Implementation
+ * @category Serialization
+ */
+export function hashStrToField(str: string, maxSizeBytes: number): bigint {
+  const textEncoder = new TextEncoder();
+  const strBytes = textEncoder.encode(str);
+  return hashBytesWithLen(strBytes, maxSizeBytes);
+}
+
+/**
+ * Computes a Poseidon hash of the provided byte array, ensuring that the byte array does not exceed the specified maximum size.
+ * This function is useful for generating a hash from a byte array while enforcing size constraints.
+ *
+ * @param bytes - The byte array to be hashed.
+ * @param maxSizeBytes - The maximum allowed size for the byte array.
+ * @throws Error if the length of the inputted bytes exceeds the specified maximum size.
+ * @group Implementation
+ * @category Serialization
+ */
+function hashBytesWithLen(bytes: Uint8Array, maxSizeBytes: number): bigint {
+  if (bytes.length > maxSizeBytes) {
+    throw new Error(`Inputted bytes of length ${bytes} is longer than ${maxSizeBytes}`);
+  }
+  const packed = padAndPackBytesWithLen(bytes, maxSizeBytes);
+  return poseidonHash(packed);
+}
+
+/**
+ * Pads the input byte array with zeros to a specified maximum size and then packs the bytes.
+ * This function ensures that the byte array does not exceed the specified maximum size, throwing an error if it does.
+ *
+ * @param bytes - The byte array to be padded and packed.
+ * @param maxSizeBytes - The maximum size in bytes that the input array can have.
+ * @throws Error if the input byte array exceeds the specified maximum size.
+ * @group Implementation
+ * @category Serialization
+ */
+function padAndPackBytesNoLen(bytes: Uint8Array, maxSizeBytes: number): bigint[] {
+  if (bytes.length > maxSizeBytes) {
+    throw new Error(`Input bytes of length ${bytes} is longer than ${maxSizeBytes}`);
+  }
+  const paddedStrBytes = padUint8ArrayWithZeros(bytes, maxSizeBytes);
+  return packBytes(paddedStrBytes);
+}
+
+/**
+ * Pads and packs the given byte array to a specified maximum size and appends its length.
+ * This function ensures that the byte array does not exceed the maximum size, throwing an error if it does.
+ * It is useful for preparing byte data for further processing or transmission by ensuring a consistent format.
+ *
+ * @param bytes - The byte array to be padded and packed.
+ * @param maxSizeBytes - The maximum allowed size for the byte array.
+ * @throws Error if the length of the input bytes exceeds the maximum size.
+ * @returns A new Uint8Array that contains the padded and packed bytes along with the length of the original byte array.
+ * @group Implementation
+ * @category Serialization
+ */
+export function padAndPackBytesWithLen(bytes: Uint8Array, maxSizeBytes: number): bigint[] {
+  if (bytes.length > maxSizeBytes) {
+    throw new Error(`Input bytes of length ${bytes} is longer than ${maxSizeBytes}`);
+  }
+  return padAndPackBytesNoLen(bytes, maxSizeBytes).concat([BigInt(bytes.length)]);
+}
+
+/**
+ * Packs a Uint8Array into an array of BigInts, ensuring the input does not exceed the maximum allowed bytes.
+ * @param bytes - The Uint8Array to be packed.
+ * @throws {Error} Throws an error if the input exceeds the maximum number of bytes allowed.
+ * @group Implementation
+ * @category Serialization
+ */
+function packBytes(bytes: Uint8Array): bigint[] {
+  if (bytes.length > MAX_NUM_INPUT_BYTES) {
+    throw new Error(`Can't pack more than ${MAX_NUM_INPUT_BYTES}.  Was given ${bytes.length} bytes`);
+  }
+  return chunkUint8Array(bytes, BYTES_PACKED_PER_SCALAR).map((chunk) => bytesToBigIntLE(chunk));
+}
+
+/**
+ * Splits a Uint8Array into smaller chunks of the specified size.
+ * This function is useful for processing large arrays in manageable segments.
+ *
+ * @param array - The Uint8Array to be split into chunks.
+ * @param chunkSize - The size of each chunk.
+ * @returns An array of Uint8Array chunks.
+ * @group Implementation
+ * @category Serialization
+ */
+function chunkUint8Array(array: Uint8Array, chunkSize: number): Uint8Array[] {
+  const result: Uint8Array[] = [];
+  for (let i = 0; i < array.length; i += chunkSize) {
+    result.push(array.subarray(i, i + chunkSize));
+  }
+  return result;
+}
+
+/**
+ * Converts a little-endian byte array into a BigInt.
+ * This function is useful for interpreting byte data as a numerical value in a way that respects the little-endian format.
+ *
+ * @param bytes - The byte array to convert.
+ * @returns The resulting BigInt representation of the byte array.
+ * @group Implementation
+ * @category Serialization
+ */
+export function bytesToBigIntLE(bytes: Uint8Array): bigint {
+  let result = BigInt(0);
+  for (let i = bytes.length - 1; i >= 0; i -= 1) {
+    result = (result << BigInt(8)) | BigInt(bytes[i]);
+  }
+  return result;
+}
+
+/**
+ * Converts a bigint value into a little-endian byte array of a specified length.
+ * This function is useful for representing large integers in a byte format, which is often required for cryptographic operations
+ * or binary data manipulation.
+ *
+ * @param value - The number to convert into bytes.
+ * @param length - The desired length of the resulting byte array.
+ * @returns A Uint8Array containing the little-endian representation of the bigint value.
+ * @group Implementation
+ * @category Serialization
+ */
+export function bigIntToBytesLE(value: bigint | number, length: number): Uint8Array {
+  let val = BigInt(value);
+  const bytes = new Uint8Array(length);
+  for (let i = 0; i < length; i += 1) {
+    bytes[i] = Number(val & BigInt(0xff));
+    val >>= BigInt(8);
+  }
+  return bytes;
+}
+
+/**
+ * Pads the input Uint8Array with zeros to achieve the specified size.
+ * This function is useful for ensuring that a byte array meets a required length for further processing.
+ *
+ * @param inputArray - The Uint8Array to be padded.
+ * @param paddedSize - The desired size of the padded array, which must be greater than or equal to the input array size.
+ * @throws Error if paddedSize is less than the length of inputArray.
+ * @group Implementation
+ * @category Serialization
+ */
+function padUint8ArrayWithZeros(inputArray: Uint8Array, paddedSize: number): Uint8Array {
+  if (paddedSize < inputArray.length) {
+    throw new Error("Padded size must be greater than or equal to the input array size.");
+  }
+
+  // Create a new Uint8Array with the padded size
+  const paddedArray = new Uint8Array(paddedSize);
+
+  // Copy the content of the input array to the new array
+  paddedArray.set(inputArray);
+
+  // Fill the remaining space with zeros
+  for (let i = inputArray.length; i < paddedSize; i += 1) {
+    paddedArray[i] = 0;
+  }
+
+  return paddedArray;
+}
+
+/**
+ * Hashes up to 16 scalar elements via the Poseidon hashing algorithm.
+ * Each element must be scalar fields of the BN254 elliptic curve group.
+ *
+ * @param inputs - An array of elements to be hashed, which can be of type number, bigint, or string.
+ * @returns bigint - The result of the hash.
+ * @throws Error - Throws an error if the input length exceeds the maximum allowed.
+ * @group Implementation
+ * @category Serialization
+ */
+export function poseidonHash(inputs: (number | bigint | string)[]): bigint {
+  if (inputs.length > numInputsToPoseidonFunc.length) {
+    throw new Error(
+      `Unable to hash input of length ${inputs.length}.  Max input length is ${numInputsToPoseidonFunc.length}`,
+    );
+  }
+  return numInputsToPoseidonFunc[inputs.length - 1](inputs);
+}

package/src/core/crypto/privateKey.ts

@@ -0,0 +1,115 @@
+/* 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.
+ * @group Implementation
+ * @category Serialization
+ */
+export interface PrivateKey {
+  /**
+   * Sign the given message with the private key to create a signature.
+   * @param message - The message to be signed, provided in HexInput format.
+   * @returns A Signature object representing the signed message.
+   * @group Implementation
+   * @category Serialization
+   */
+  sign(message: HexInput): Signature;
+
+  /**
+   * Derive the public key associated with the private key.
+   * @group Implementation
+   * @category Serialization
+   */
+  publicKey(): PublicKey;
+
+  /**
+   * Get the private key in bytes (Uint8Array).
+   * @group Implementation
+   * @category Serialization
+   */
+  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-",
+    [PrivateKeyVariants.Secp256r1]: "secp256r1-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];
+
+    // Remove the prefix if it exists
+    let formattedPrivateKey = privateKey;
+    if (typeof formattedPrivateKey === "string" && formattedPrivateKey.startsWith(aip80Prefix)) {
+      // eslint-disable-next-line prefer-destructuring
+      formattedPrivateKey = formattedPrivateKey.split("-")[2];
+    }
+
+    return `${aip80Prefix}${Hex.fromHexInput(formattedPrivateKey).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);
+    }
+
+    return data;
+  }
+}

package/src/core/crypto/proof.ts

@@ -0,0 +1,9 @@
+import { Serializable } from "../../bcs";
+
+/**
+ * An abstract representation of a cryptographic proof associated with specific
+ * zero-knowledge proof schemes, such as Groth16 and PLONK.
+ * @group Implementation
+ * @category Serialization
+ */
+export abstract class Proof extends Serializable {}

package/src/core/crypto/publicKey.ts

@@ -0,0 +1,106 @@
+import type { MovementConfig } from "../../api";
+import { Serializable } from "../../bcs";
+import { HexInput } from "../../types";
+import { AuthenticationKey } from "../authenticationKey";
+import { Hex } from "../hex";
+import { Signature } from "./signature";
+
+/**
+ * Represents the arguments required to verify a digital signature.
+ *
+ * @param message - The original message that was signed.
+ * @param signature - The signature to be verified against the message.
+ * @group Implementation
+ * @category Serialization
+ */
+export interface VerifySignatureArgs {
+  message: HexInput;
+  signature: Signature;
+}
+
+/**
+ * Represents the arguments required to verify a digital signature asynchronously.
+ *
+ * The validity of certain types of signatures are dependent on network state.  This is the case for
+ * Keyless signatures which need to lookup the verification key and keyless configuration.
+ *
+ * @param movementConfig - The Movement configuration to use
+ * @param message - The original message that was signed.
+ * @param signature - The signature to be verified against the message.
+ * @group Implementation
+ * @category Serialization
+ */
+export type VerifySignatureAsyncArgs = VerifySignatureArgs & {
+  movementConfig: MovementConfig;
+  options?: any;
+};
+
+/**
+ * Represents an abstract public key.
+ *
+ * This class provides a common interface for verifying signatures associated with the public key.
+ * It allows for the retrieval of the raw public key bytes and the public key in a hexadecimal string format.
+ * @group Implementation
+ * @category Serialization
+ */
+export abstract class PublicKey extends Serializable {
+  /**
+   * Verifies that the private key associated with this public key signed the message with the given signature.
+   * @param args.message The message that was signed
+   * @param args.signature The signature to verify
+   * @group Implementation
+   * @category Serialization
+   */
+  abstract verifySignature(args: VerifySignatureArgs): boolean;
+
+  /**
+   * Verifies signature with the public key and makes any network calls required to get state required to verify the signature.
+   * @param args.movementConfig The Movement configuration
+   * @param args.message The message that was signed
+   * @param args.signature The signature to verify
+   * @group Implementation
+   * @category Serialization
+   */
+  async verifySignatureAsync(args: VerifySignatureAsyncArgs): Promise<boolean> {
+    return this.verifySignature(args);
+  }
+
+  /**
+   * Get the raw public key bytes
+   * @group Implementation
+   * @category Serialization
+   */
+  toUint8Array(): Uint8Array {
+    return this.bcsToBytes();
+  }
+
+  /**
+   * Get the public key as a hex string with a 0x prefix.
+   *
+   * @returns The public key in hex format.
+   * @group Implementation
+   * @category Serialization
+   */
+  toString(): string {
+    const bytes = this.toUint8Array();
+    return Hex.fromHexInput(bytes).toString();
+  }
+}
+
+/**
+ * An abstract representation of an account public key.
+ *
+ * Provides a common interface for deriving an authentication key.
+ *
+ * @abstract
+ * @group Implementation
+ * @category Serialization
+ */
+export abstract class AccountPublicKey extends PublicKey {
+  /**
+   * Get the authentication key associated with this public key
+   * @group Implementation
+   * @category Serialization
+   */
+  abstract authKey(): AuthenticationKey;
+}