@aptos-labs/ts-sdk 1.7.0 → 1.9.0

package/src/core/crypto/multiEd25519.ts

@@ -1,17 +1,17 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-import { PublicKey, Signature } from "./asymmetricCrypto";
-import { Deserializer } from "../../bcs/deserializer";
-import { Serializer } from "../../bcs/serializer";
+import { Deserializer, Serializer } from "../../bcs";
+import { SigningScheme as AuthenticationKeyScheme } from "../../types";
+import { AuthenticationKey } from "../authenticationKey";
 import { Ed25519PublicKey, Ed25519Signature } from "./ed25519";
-import { Hex } from "../hex";
-import { HexInput } from "../../types";
+import { AccountPublicKey, VerifySignatureArgs } from "./publicKey";
+import { Signature } from "./signature";
 
 /**
  * Represents the public key of a K-of-N Ed25519 multi-sig transaction.
  */
-export class MultiEd25519PublicKey extends PublicKey {
+export class MultiEd25519PublicKey extends AccountPublicKey {
   /**
    * Maximum number of public keys supported
    */
@@ -28,7 +28,7 @@ export class MultiEd25519PublicKey extends PublicKey {
   static readonly MIN_THRESHOLD = 1;
 
   /**
-   * List of Ed25519 public keys for this MultiEd25519PublicKey
+   * List of Ed25519 public keys for this LegacyMultiEd25519PublicKey
    */
   public readonly publicKeys: Ed25519PublicKey[];
 
@@ -50,13 +50,13 @@ export class MultiEd25519PublicKey extends PublicKey {
    */
   constructor(args: { publicKeys: Ed25519PublicKey[]; threshold: number }) {
     super();
-
     const { publicKeys, threshold } = args;
 
     // Validate number of public keys
     if (publicKeys.length > MultiEd25519PublicKey.MAX_KEYS || publicKeys.length < MultiEd25519PublicKey.MIN_KEYS) {
       throw new Error(
-        `Must have between ${MultiEd25519PublicKey.MIN_KEYS} and ${MultiEd25519PublicKey.MAX_KEYS} public keys, inclusive`,
+        `Must have between ${MultiEd25519PublicKey.MIN_KEYS} and ` +
+          `${MultiEd25519PublicKey.MAX_KEYS} public keys, inclusive`,
       );
     }
 
@@ -71,6 +71,50 @@ export class MultiEd25519PublicKey extends PublicKey {
     this.threshold = threshold;
   }
 
+  // region AccountPublicKey
+
+  verifySignature(args: VerifySignatureArgs): boolean {
+    const { message, signature } = args;
+    if (!(signature instanceof MultiEd25519Signature)) {
+      return false;
+    }
+
+    const indices: number[] = [];
+    for (let i = 0; i < 4; i += 1) {
+      for (let j = 0; j < 8; j += 1) {
+        // eslint-disable-next-line no-bitwise
+        const bitIsSet = (signature.bitmap[i] & (1 << (7 - j))) !== 0;
+        if (bitIsSet) {
+          const index = i * 8 + j;
+          indices.push(index);
+        }
+      }
+    }
+
+    if (indices.length !== signature.signatures.length) {
+      throw new Error("Bitmap and signatures length mismatch");
+    }
+
+    if (indices.length < this.threshold) {
+      throw new Error("Not enough signatures");
+    }
+
+    for (let i = 0; i < indices.length; i += 1) {
+      const publicKey = this.publicKeys[indices[i]];
+      if (!publicKey.verifySignature({ message, signature: signature.signatures[i] })) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  authKey(): AuthenticationKey {
+    return AuthenticationKey.fromSchemeAndBytes({
+      scheme: AuthenticationKeyScheme.MultiEd25519,
+      input: this.toUint8Array(),
+    });
+  }
+
   /**
    * Converts a PublicKeys into Uint8Array (bytes) with: bytes = p1_bytes | ... | pn_bytes | threshold
    */
@@ -85,14 +129,9 @@ export class MultiEd25519PublicKey extends PublicKey {
     return bytes;
   }
 
-  toString(): string {
-    return Hex.fromHexInput(this.toUint8Array()).toString();
-  }
+  // endregion
 
-  // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
-  verifySignature(args: { message: HexInput; signature: MultiEd25519Signature }): boolean {
-    throw new Error("TODO - Method not implemented.");
-  }
+  // region Serializable
 
   serialize(serializer: Serializer): void {
     serializer.serializeBytes(this.toUint8Array());
@@ -110,6 +149,8 @@ export class MultiEd25519PublicKey extends PublicKey {
     }
     return new MultiEd25519PublicKey({ publicKeys: keys, threshold });
   }
+
+  // endregion
 }
 
 /**
@@ -146,26 +187,33 @@ export class MultiEd25519Signature extends Signature {
    *
    * @param args.signatures A list of signatures
    * @param args.bitmap 4 bytes, at most 32 signatures are supported. If Nth bit value is `1`, the Nth
-   * signature should be provided in `signatures`. Bits are read from left to right
+   * signature should be provided in `signatures`. Bits are read from left to right.
+   * Alternatively, you can specify an array of bitmap positions.
+   * Valid position should range between 0 and 31.
+   * @see MultiEd25519Signature.createBitmap
    */
-  constructor(args: { signatures: Ed25519Signature[]; bitmap: Uint8Array }) {
+  constructor(args: { signatures: Ed25519Signature[]; bitmap: Uint8Array | number[] }) {
     super();
-
     const { signatures, bitmap } = args;
-    if (bitmap.length !== MultiEd25519Signature.BITMAP_LEN) {
-      throw new Error(`"bitmap" length should be ${MultiEd25519Signature.BITMAP_LEN}`);
-    }
 
     if (signatures.length > MultiEd25519Signature.MAX_SIGNATURES_SUPPORTED) {
       throw new Error(
         `The number of signatures cannot be greater than ${MultiEd25519Signature.MAX_SIGNATURES_SUPPORTED}`,
       );
     }
-
     this.signatures = signatures;
-    this.bitmap = bitmap;
+
+    if (!(bitmap instanceof Uint8Array)) {
+      this.bitmap = MultiEd25519Signature.createBitmap({ bits: bitmap });
+    } else if (bitmap.length !== MultiEd25519Signature.BITMAP_LEN) {
+      throw new Error(`"bitmap" length should be ${MultiEd25519Signature.BITMAP_LEN}`);
+    } else {
+      this.bitmap = bitmap;
+    }
   }
 
+  // region AccountSignature
+
   /**
    * Converts a MultiSignature into Uint8Array (bytes) with `bytes = s1_bytes | ... | sn_bytes | bitmap`
    */
@@ -180,10 +228,29 @@ export class MultiEd25519Signature extends Signature {
     return bytes;
   }
 
-  toString(): string {
-    return Hex.fromHexInput(this.toUint8Array()).toString();
+  // endregion
+
+  // region Serializable
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeBytes(this.toUint8Array());
   }
 
+  static deserialize(deserializer: Deserializer): MultiEd25519Signature {
+    const bytes = deserializer.deserializeBytes();
+    const bitmap = bytes.subarray(bytes.length - 4);
+
+    const signatures: Ed25519Signature[] = [];
+
+    for (let i = 0; i < bytes.length - bitmap.length; i += Ed25519Signature.LENGTH) {
+      const begin = i;
+      signatures.push(new Ed25519Signature(bytes.subarray(begin, begin + Ed25519Signature.LENGTH)));
+    }
+    return new MultiEd25519Signature({ signatures, bitmap });
+  }
+
+  // endregion
+
   /**
    * Helper method to create a bitmap out of the specified bit positions
    * @param args.bits The bitmap positions that should be set. A position starts at index 0.
@@ -208,7 +275,7 @@ export class MultiEd25519Signature extends Signature {
     // Check if duplicates exist in bits
     const dupCheckSet = new Set();
 
-    bits.forEach((bit: number) => {
+    bits.forEach((bit: number, index) => {
       if (bit >= MultiEd25519Signature.MAX_SIGNATURES_SUPPORTED) {
         throw new Error(`Cannot have a signature larger than ${MultiEd25519Signature.MAX_SIGNATURES_SUPPORTED - 1}.`);
       }
@@ -217,6 +284,10 @@ export class MultiEd25519Signature extends Signature {
         throw new Error("Duplicate bits detected.");
       }
 
+      if (index > 0 && bit <= bits[index - 1]) {
+        throw new Error("The bits need to be sorted in ascending order.");
+      }
+
       dupCheckSet.add(bit);
 
       const byteOffset = Math.floor(bit / 8);
@@ -231,21 +302,4 @@ export class MultiEd25519Signature extends Signature {
 
     return bitmap;
   }
-
-  serialize(serializer: Serializer): void {
-    serializer.serializeBytes(this.toUint8Array());
-  }
-
-  static deserialize(deserializer: Deserializer): MultiEd25519Signature {
-    const bytes = deserializer.deserializeBytes();
-    const bitmap = bytes.subarray(bytes.length - 4);
-
-    const signatures: Ed25519Signature[] = [];
-
-    for (let i = 0; i < bytes.length - bitmap.length; i += Ed25519Signature.LENGTH) {
-      const begin = i;
-      signatures.push(new Ed25519Signature(bytes.subarray(begin, begin + Ed25519Signature.LENGTH)));
-    }
-    return new MultiEd25519Signature({ signatures, bitmap });
-  }
 }

package/src/core/crypto/multiKey.ts

@@ -1,12 +1,30 @@
-import { Hex } from "../hex";
-import { HexInput } from "../../types";
+import { SigningScheme as AuthenticationKeyScheme } from "../../types";
 import { Deserializer } from "../../bcs/deserializer";
 import { Serializer } from "../../bcs/serializer";
-import { AnyPublicKey } from "./anyPublicKey";
-import { AnySignature } from "./anySignature";
-import { PublicKey } from "./asymmetricCrypto";
+import { AuthenticationKey } from "../authenticationKey";
+import { AccountPublicKey, PublicKey, VerifySignatureArgs } from "./publicKey";
+import { Signature } from "./signature";
+import { AnyPublicKey, AnySignature } from "./singleKey";
 
-export class MultiKey extends PublicKey {
+/* eslint-disable no-bitwise */
+
+function bitCount(byte: number) {
+  let n = byte;
+  n -= (n >> 1) & 0x55555555;
+  n = (n & 0x33333333) + ((n >> 2) & 0x33333333);
+  return (((n + (n >> 4)) & 0xf0f0f0f) * 0x1010101) >> 24;
+}
+
+/* eslint-enable no-bitwise */
+
+/**
+ * Represents the public key of a multi-agent account.
+ *
+ * The public keys of each individual agent can be any type of public key supported by Aptos.
+ * Since [AIP-55](https://github.com/aptos-foundation/AIPs/pull/263) Aptos supports
+ * `Legacy` and `Unified` authentication keys.
+ */
+export class MultiKey extends AccountPublicKey {
   /**
    * List of any public keys
    */
@@ -17,13 +35,15 @@ export class MultiKey extends PublicKey {
    */
   public readonly signaturesRequired: number;
 
-  constructor(args: { publicKeys: PublicKey[]; signaturesRequired: number }) {
+  // region Constructors
+
+  constructor(args: { publicKeys: Array<PublicKey>; signaturesRequired: number }) {
     super();
     const { publicKeys, signaturesRequired } = args;
 
     // Validate number of public keys is greater than signature required
     if (signaturesRequired < 1) {
-      throw new Error("The number of required signatures needs to be greater then 0");
+      throw new Error("The number of required signatures needs to be greater than 0");
     }
 
     // Validate number of public keys is greater than signature required
@@ -33,25 +53,52 @@ export class MultiKey extends PublicKey {
       );
     }
 
-    const keys: AnyPublicKey[] = [];
-    publicKeys.forEach((publicKey) => {
-      if (publicKey instanceof AnyPublicKey) {
-        keys.push(publicKey);
-      } else {
-        // if public key is instance of a legacy authentication key, i.e
-        // Legacy Ed25519, convert it into AnyPublicKey
-        keys.push(new AnyPublicKey(publicKey));
-      }
-    });
+    // Make sure that all keys are normalized to the SingleKey authentication scheme
+    this.publicKeys = publicKeys.map((publicKey) =>
+      publicKey instanceof AnyPublicKey ? publicKey : new AnyPublicKey(publicKey),
+    );
 
-    this.publicKeys = keys;
     this.signaturesRequired = signaturesRequired;
   }
 
+  // endregion
+
+  // region AccountPublicKey
+
+  // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
+  verifySignature(args: VerifySignatureArgs): boolean {
+    throw new Error("not implemented");
+  }
+
+  authKey(): AuthenticationKey {
+    return AuthenticationKey.fromSchemeAndBytes({
+      scheme: AuthenticationKeyScheme.MultiKey,
+      input: this.toUint8Array(),
+    });
+  }
+
   toUint8Array(): Uint8Array {
     return this.bcsToBytes();
   }
 
+  // endregion
+
+  // region Serializable
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeVector(this.publicKeys);
+    serializer.serializeU8(this.signaturesRequired);
+  }
+
+  static deserialize(deserializer: Deserializer): MultiKey {
+    const keys = deserializer.deserializeVector(AnyPublicKey);
+    const signaturesRequired = deserializer.deserializeU8();
+
+    return new MultiKey({ publicKeys: keys, signaturesRequired });
+  }
+
+  // endregion
+
   /**
    * Create a bitmap that holds the mapping from the original public keys
    * to the signatures passed in
@@ -92,31 +139,142 @@ export class MultiKey extends PublicKey {
 
     return bitmap;
   }
+}
+
+export class MultiKeySignature extends Signature {
+  /**
+   * Number of bytes in the bitmap representing who signed the transaction (32-bits)
+   */
+  static BITMAP_LEN: number = 4;
+
+  /**
+   * Maximum number of Ed25519 signatures supported
+   */
+  static MAX_SIGNATURES_SUPPORTED = MultiKeySignature.BITMAP_LEN * 8;
+
+  /**
+   * The list of underlying Ed25519 signatures
+   */
+  public readonly signatures: AnySignature[];
+
+  /**
+   * 32-bit Bitmap representing who signed the transaction
+   *
+   * This is represented where each public key can be masked to determine whether the message was signed by that key.
+   */
+  public readonly bitmap: Uint8Array;
+
+  /**
+   * Signature for a K-of-N multi-sig transaction.
+   *
+   * @see {@link
+   * https://aptos.dev/integration/creating-a-signed-transaction/#multisignature-transactions | Creating a Signed Transaction}
+   *
+   * @param args.signatures A list of signatures
+   * @param args.bitmap 4 bytes, at most 32 signatures are supported. If Nth bit value is `1`, the Nth
+   * signature should be provided in `signatures`. Bits are read from left to right
+   */
+  constructor(args: { signatures: Array<Signature | AnySignature>; bitmap: Uint8Array | number[] }) {
+    super();
+    const { signatures, bitmap } = args;
+
+    if (signatures.length > MultiKeySignature.MAX_SIGNATURES_SUPPORTED) {
+      throw new Error(`The number of signatures cannot be greater than ${MultiKeySignature.MAX_SIGNATURES_SUPPORTED}`);
+    }
+
+    // Make sure that all signatures are normalized to the SingleKey authentication scheme
+    this.signatures = signatures.map((signature) =>
+      signature instanceof AnySignature ? signature : new AnySignature(signature),
+    );
+
+    if (!(bitmap instanceof Uint8Array)) {
+      this.bitmap = MultiKeySignature.createBitmap({ bits: bitmap });
+    } else if (bitmap.length !== MultiKeySignature.BITMAP_LEN) {
+      throw new Error(`"bitmap" length should be ${MultiKeySignature.BITMAP_LEN}`);
+    } else {
+      this.bitmap = bitmap;
+    }
+
+    const nSignatures = this.bitmap.reduce((acc, byte) => acc + bitCount(byte), 0);
+    if (nSignatures !== this.signatures.length) {
+      throw new Error(`Expecting ${nSignatures} signatures from the bitmap, but got ${this.signatures.length}`);
+    }
+  }
 
   /**
-   * Hex string representation the multi key bytes
+   * Helper method to create a bitmap out of the specified bit positions
+   * @param args.bits The bitmap positions that should be set. A position starts at index 0.
+   * Valid position should range between 0 and 31.
+   * @example
+   * Here's an example of valid `bits`
+   * ```
+   * [0, 2, 31]
+   * ```
+   * `[0, 2, 31]` means the 1st, 3rd and 32nd bits should be set in the bitmap.
+   * The result bitmap should be 0b1010000000000000000000000000001
    *
-   * @returns string
+   * @returns bitmap that is 32bit long
    */
-  toString(): string {
-    return Hex.fromHexInput(this.toUint8Array()).toString();
+  static createBitmap(args: { bits: number[] }): Uint8Array {
+    const { bits } = args;
+    // Bits are read from left to right. e.g. 0b10000000 represents the first bit is set in one byte.
+    // The decimal value of 0b10000000 is 128.
+    const firstBitInByte = 128;
+    const bitmap = new Uint8Array([0, 0, 0, 0]);
+
+    // Check if duplicates exist in bits
+    const dupCheckSet = new Set();
+
+    bits.forEach((bit: number) => {
+      if (bit >= MultiKeySignature.MAX_SIGNATURES_SUPPORTED) {
+        throw new Error(`Cannot have a signature larger than ${MultiKeySignature.MAX_SIGNATURES_SUPPORTED - 1}.`);
+      }
+
+      if (dupCheckSet.has(bit)) {
+        throw new Error("Duplicate bits detected.");
+      }
+
+      dupCheckSet.add(bit);
+
+      const byteOffset = Math.floor(bit / 8);
+
+      let byte = bitmap[byteOffset];
+
+      // eslint-disable-next-line no-bitwise
+      byte |= firstBitInByte >> bit % 8;
+
+      bitmap[byteOffset] = byte;
+    });
+
+    return bitmap;
   }
 
-  // TODO
-  // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
-  verifySignature(args: { message: HexInput; signature: AnySignature }): boolean {
-    throw new Error("not implemented");
+  // region Signature
+
+  toUint8Array(): Uint8Array {
+    return this.bcsToBytes();
   }
 
+  // endregion
+
+  // region Serializable
+
   serialize(serializer: Serializer): void {
-    serializer.serializeVector(this.publicKeys);
-    serializer.serializeU8(this.signaturesRequired);
+    // Note: we should not need to serialize the vector length, as it can be derived from the bitmap
+    serializer.serializeVector(this.signatures);
+    serializer.serializeBytes(this.bitmap);
   }
 
-  static deserialize(deserializer: Deserializer): MultiKey {
-    const keys = deserializer.deserializeVector(AnyPublicKey);
-    const signaturesRequired = deserializer.deserializeU8();
-
-    return new MultiKey({ publicKeys: keys, signaturesRequired });
+  static deserialize(deserializer: Deserializer): MultiKeySignature {
+    const bitmap = deserializer.deserializeBytes();
+    const nSignatures = bitmap.reduce((acc, byte) => acc + bitCount(byte), 0);
+    const signatures: AnySignature[] = [];
+    for (let i = 0; i < nSignatures; i += 1) {
+      const signature = AnySignature.deserialize(deserializer);
+      signatures.push(signature);
+    }
+    return new MultiKeySignature({ signatures, bitmap });
   }
+
+  // endregion
 }

package/src/core/crypto/privateKey.ts

@@ -0,0 +1,25 @@
+import { HexInput } from "../../types";
+import { PublicKey } from "./publicKey";
+import { Signature } from "./signature";
+
+/**
+ * An abstract representation of a private key.
+ * It is associated to a signature scheme and provides signing capabilities.
+ */
+export interface PrivateKey {
+  /**
+   * Sign the given message with the private key.
+   * @param message in HexInput format
+   */
+  sign(message: HexInput): Signature;
+
+  /**
+   * Derive the public key associated with the private key
+   */
+  publicKey(): PublicKey;
+
+  /**
+   * Get the private key in bytes (Uint8Array).
+   */
+  toUint8Array(): Uint8Array;
+}

package/src/core/crypto/publicKey.ts

@@ -0,0 +1,52 @@
+import { Serializable } from "../../bcs";
+import { HexInput } from "../../types";
+import { AuthenticationKey } from "../authenticationKey";
+import { Hex } from "../hex";
+import { Signature } from "./signature";
+
+/**
+ * Arguments for verifying a signature
+ */
+export interface VerifySignatureArgs {
+  message: HexInput;
+  signature: Signature;
+}
+
+/**
+ * An abstract representation of a public key.
+ *
+ * Provides a common interface for verifying any signature.
+ */
+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
+   */
+  abstract verifySignature(args: VerifySignatureArgs): boolean;
+
+  /**
+   * Get the raw public key bytes
+   */
+  abstract toUint8Array(): Uint8Array;
+
+  /**
+   * Get the public key as a hex string with a 0x prefix e.g. 0x123456...
+   */
+  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.
+ */
+export abstract class AccountPublicKey extends PublicKey {
+  /**
+   * Get the authentication key associated with this public key
+   */
+  abstract authKey(): AuthenticationKey;
+}