@aptos-labs/ts-sdk 1.8.0 → 1.9.0

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;
+}

package/src/core/crypto/secp256k1.ts

@@ -4,11 +4,13 @@
 import { sha3_256 } from "@noble/hashes/sha3";
 import { secp256k1 } from "@noble/curves/secp256k1";
 import { HDKey } from "@scure/bip32";
-import { PrivateKey, PublicKey, Signature } from "./asymmetricCrypto";
-import { Deserializer, Serializer } from "../../bcs";
+import { Serializable, Deserializer, Serializer } from "../../bcs";
 import { Hex } from "../hex";
 import { HexInput } from "../../types";
 import { isValidBIP44Path, mnemonicToSeed } from "./hdKey";
+import { PrivateKey } from "./privateKey";
+import { PublicKey, VerifySignatureArgs } from "./publicKey";
+import { Signature } from "./signature";
 
 /**
  * Represents the Secp256k1 ecdsa public key
@@ -37,38 +39,27 @@ export class Secp256k1PublicKey extends PublicKey {
     this.key = hex;
   }
 
-  /**
-   * Get the public key in bytes (Uint8Array).
-   *
-   * @returns Uint8Array representation of the public key
-   */
+  // region PublicKey
+
+  verifySignature(args: VerifySignatureArgs): boolean {
+    const { message, signature } = args;
+    if (!(signature instanceof Secp256k1Signature)) {
+      return false;
+    }
+
+    const messageBytes = Hex.fromHexInput(message).toUint8Array();
+    const messageSha3Bytes = sha3_256(messageBytes);
+    const signatureBytes = signature.toUint8Array();
+    return secp256k1.verify(signatureBytes, messageSha3Bytes, this.key.toUint8Array());
+  }
+
   toUint8Array(): Uint8Array {
     return this.key.toUint8Array();
   }
 
-  /**
-   * Get the public key as a hex string with the 0x prefix.
-   *
-   * @returns string representation of the public key
-   */
-  toString(): string {
-    return this.key.toString();
-  }
+  // endregion
 
-  /**
-   * Verifies a signed data with a public key
-   *
-   * @param args.message message
-   * @param args.signature The signature
-   * @returns true if the signature is valid
-   */
-  verifySignature(args: { message: HexInput; signature: Secp256k1Signature }): boolean {
-    const { message, signature } = args;
-    const msgHex = Hex.fromHexInput(message).toUint8Array();
-    const sha3Message = sha3_256(msgHex);
-    const rawSignature = signature.toUint8Array();
-    return secp256k1.verify(rawSignature, sha3Message, this.toUint8Array());
-  }
+  // region Serializable
 
   serialize(serializer: Serializer): void {
     serializer.serializeBytes(this.key.toUint8Array());
@@ -79,11 +70,12 @@ export class Secp256k1PublicKey extends PublicKey {
     return new Secp256k1PublicKey(bytes);
   }
 
-  static load(deserializer: Deserializer): Secp256k1PublicKey {
-    const bytes = deserializer.deserializeBytes();
-    return new Secp256k1PublicKey(bytes);
-  }
+  // endregion
 
+  /**
+   * @deprecated use `instanceof Secp256k1PublicKey` instead
+   * @param publicKey
+   */
   static isPublicKey(publicKey: PublicKey): publicKey is Secp256k1PublicKey {
     return publicKey instanceof Secp256k1PublicKey;
   }
@@ -92,7 +84,7 @@ export class Secp256k1PublicKey extends PublicKey {
 /**
  * A Secp256k1 ecdsa private key
  */
-export class Secp256k1PrivateKey extends PrivateKey {
+export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
   /**
    * Length of Secp256k1 ecdsa private key
    */
@@ -104,6 +96,8 @@ export class Secp256k1PrivateKey extends PrivateKey {
    */
   private readonly key: Hex;
 
+  // region Constructors
+
   /**
    * Create a new PrivateKey instance from a Uint8Array or String.
    *
@@ -120,46 +114,6 @@ export class Secp256k1PrivateKey extends PrivateKey {
     this.key = privateKeyHex;
   }
 
-  /**
-   * Get the private key in bytes (Uint8Array).
-   *
-   * @returns
-   */
-  toUint8Array(): Uint8Array {
-    return this.key.toUint8Array();
-  }
-
-  /**
-   * Get the private key as a hex string with the 0x prefix.
-   *
-   * @returns string representation of the private key
-   */
-  toString(): string {
-    return this.key.toString();
-  }
-
-  /**
-   * Sign the given message with the private key.
-   *
-   * @param message in HexInput format
-   * @returns Signature
-   */
-  sign(message: HexInput): Secp256k1Signature {
-    const msgHex = Hex.fromHexInput(message);
-    const sha3Message = sha3_256(msgHex.toUint8Array());
-    const signature = secp256k1.sign(sha3Message, this.key.toUint8Array());
-    return new Secp256k1Signature(signature.toCompactRawBytes());
-  }
-
-  serialize(serializer: Serializer): void {
-    serializer.serializeBytes(this.toUint8Array());
-  }
-
-  static deserialize(deserializer: Deserializer): Secp256k1PrivateKey {
-    const bytes = deserializer.deserializeBytes();
-    return new Secp256k1PrivateKey(bytes);
-  }
-
   /**
    * Generate a new random private key.
    *
@@ -170,16 +124,6 @@ export class Secp256k1PrivateKey extends PrivateKey {
     return new Secp256k1PrivateKey(hexInput);
   }
 
-  /**
-   * Derive the Secp256k1PublicKey from this private key.
-   *
-   * @returns Secp256k1PublicKey
-   */
-  publicKey(): Secp256k1PublicKey {
-    const bytes = secp256k1.getPublicKey(this.key.toUint8Array(), false);
-    return new Secp256k1PublicKey(bytes);
-  }
-
   /**
    * Derives a private key from a mnemonic seed phrase.
    *
@@ -214,13 +158,76 @@ export class Secp256k1PrivateKey extends PrivateKey {
     return new Secp256k1PrivateKey(privateKey);
   }
 
+  // endregion
+
+  // region PrivateKey
+
+  /**
+   * Sign the given message with the private key.
+   *
+   * @param message in HexInput format
+   * @returns Signature
+   */
+  sign(message: HexInput): Secp256k1Signature {
+    const messageBytes = Hex.fromHexInput(message);
+    const messageHashBytes = sha3_256(messageBytes.toUint8Array());
+    const signature = secp256k1.sign(messageHashBytes, this.key.toUint8Array());
+    return new Secp256k1Signature(signature.toCompactRawBytes());
+  }
+
+  /**
+   * Derive the Secp256k1PublicKey from this private key.
+   *
+   * @returns Secp256k1PublicKey
+   */
+  publicKey(): Secp256k1PublicKey {
+    const bytes = secp256k1.getPublicKey(this.key.toUint8Array(), false);
+    return new Secp256k1PublicKey(bytes);
+  }
+
+  /**
+   * Get the private key in bytes (Uint8Array).
+   *
+   * @returns
+   */
+  toUint8Array(): Uint8Array {
+    return this.key.toUint8Array();
+  }
+
+  /**
+   * Get the private key as a hex string with the 0x prefix.
+   *
+   * @returns string representation of the private key
+   */
+  toString(): string {
+    return this.key.toString();
+  }
+
+  // endregion
+
+  // region Serializable
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeBytes(this.toUint8Array());
+  }
+
+  static deserialize(deserializer: Deserializer): Secp256k1PrivateKey {
+    const bytes = deserializer.deserializeBytes();
+    return new Secp256k1PrivateKey(bytes);
+  }
+
+  // endregion
+
+  /**
+   * @deprecated use `instanceof Secp256k1PrivateKey` instead
+   */
   static isPrivateKey(privateKey: PrivateKey): privateKey is Secp256k1PrivateKey {
     return privateKey instanceof Secp256k1PrivateKey;
   }
 }
 
 /**
- * A signature of a message signed using an Secp256k1 ecdsa private key
+ * A signature of a message signed using a Secp256k1 ecdsa private key
  */
 export class Secp256k1Signature extends Signature {
   /**
@@ -234,6 +241,8 @@ export class Secp256k1Signature extends Signature {
    */
   private readonly data: Hex;
 
+  // region Constructors
+
   /**
    * Create a new Signature instance from a Uint8Array or String.
    *
@@ -241,31 +250,26 @@ export class Secp256k1Signature extends Signature {
    */
   constructor(hexInput: HexInput) {
     super();
-
-    const hex = Hex.fromHexInput(hexInput);
-    if (hex.toUint8Array().length !== Secp256k1Signature.LENGTH) {
-      throw new Error(`Signature length should be ${Secp256k1Signature.LENGTH}, recieved ${hex.toUint8Array().length}`);
+    const data = Hex.fromHexInput(hexInput);
+    if (data.toUint8Array().length !== Secp256k1Signature.LENGTH) {
+      throw new Error(
+        `Signature length should be ${Secp256k1Signature.LENGTH}, received ${data.toUint8Array().length}`,
+      );
     }
-    this.data = hex;
+    this.data = data;
   }
 
-  /**
-   * Get the signature in bytes (Uint8Array).
-   *
-   * @returns Uint8Array representation of the signature
-   */
+  // endregion
+
+  // region Signature
+
   toUint8Array(): Uint8Array {
     return this.data.toUint8Array();
   }
 
-  /**
-   * Get the signature as a hex string with the 0x prefix.
-   *
-   * @returns string representation of the signature
-   */
-  toString(): string {
-    return this.data.toString();
-  }
+  // endregion
+
+  // region Serializable
 
   serialize(serializer: Serializer): void {
     serializer.serializeBytes(this.data.toUint8Array());
@@ -276,12 +280,5 @@ export class Secp256k1Signature extends Signature {
     return new Secp256k1Signature(hex);
   }
 
-  static load(deserializer: Deserializer): Secp256k1Signature {
-    const bytes = deserializer.deserializeBytes();
-    return new Secp256k1Signature(bytes);
-  }
-
-  static isSignature(signature: Signature): signature is Secp256k1Signature {
-    return signature instanceof Secp256k1Signature;
-  }
+  // endregion
 }