@aptos-labs/ts-sdk 0.0.0

package/src/core/authenticationKey.ts

@@ -0,0 +1,102 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+import { sha3_256 as sha3Hash } from "@noble/hashes/sha3";
+import { AccountAddress } from "./accountAddress";
+import { PublicKey } from "./crypto/asymmetricCrypto";
+import { Ed25519PublicKey } from "./crypto/ed25519";
+import { MultiEd25519PublicKey } from "./crypto/multiEd25519";
+import { Secp256k1PublicKey } from "./crypto/secp256k1";
+import { Hex } from "./hex";
+import { AuthenticationKeyScheme, HexInput, SigningScheme } from "../types";
+
+/**
+ * Each account stores an authentication key. Authentication key enables account owners to rotate
+ * their private key(s) associated with the account without changing the address that hosts their account.
+ * @see {@link https://aptos.dev/concepts/accounts | Account Basics}
+ *
+ * Note: AuthenticationKey only supports Ed25519 and MultiEd25519 public keys for now.
+ *
+ * Account addresses can be derived from AuthenticationKey
+ */
+export class AuthenticationKey {
+  /**
+   * An authentication key is always a SHA3-256 hash of data, and is always 32 bytes.
+   */
+  static readonly LENGTH: number = 32;
+
+  /**
+   * The raw bytes of the authentication key.
+   */
+  public readonly data: Hex;
+
+  constructor(args: { data: HexInput }) {
+    const { data } = args;
+    const hex = Hex.fromHexInput(data);
+    if (hex.toUint8Array().length !== AuthenticationKey.LENGTH) {
+      throw new Error(`Authentication Key length should be ${AuthenticationKey.LENGTH}`);
+    }
+    this.data = hex;
+  }
+
+  toString(): string {
+    return this.data.toString();
+  }
+
+  toUint8Array(): Uint8Array {
+    return this.data.toUint8Array();
+  }
+
+  /**
+   * Creates an AuthenticationKey from seed bytes and a scheme
+   *
+   * This allows for the creation of AuthenticationKeys that are not derived from Public Keys directly
+   * @param args
+   */
+  private static fromBytesAndScheme(args: { bytes: HexInput; scheme: AuthenticationKeyScheme }) {
+    const { bytes, scheme } = args;
+    const inputBytes = Hex.fromHexInput(bytes).toUint8Array();
+    const authKeyBytes = new Uint8Array(inputBytes.length + 1);
+    authKeyBytes.set(inputBytes);
+    authKeyBytes.set([scheme], inputBytes.length);
+
+    const hash = sha3Hash.create();
+    hash.update(authKeyBytes);
+
+    return new AuthenticationKey({ data: hash.digest() });
+  }
+
+  /**
+   * Converts a PublicKey(s) to AuthenticationKey
+   *
+   * @param args.publicKey
+   * @returns AuthenticationKey
+   */
+  static fromPublicKey(args: { publicKey: PublicKey }): AuthenticationKey {
+    const { publicKey } = args;
+
+    let scheme: number;
+    if (publicKey instanceof Ed25519PublicKey) {
+      scheme = SigningScheme.Ed25519.valueOf();
+    } else if (publicKey instanceof MultiEd25519PublicKey) {
+      scheme = SigningScheme.MultiEd25519.valueOf();
+    } else if (publicKey instanceof Secp256k1PublicKey) {
+      scheme = SigningScheme.Secp256k1Ecdsa.valueOf();
+    } else {
+      throw new Error("No supported authentication scheme for public key");
+    }
+
+    const pubKeyBytes = publicKey.toUint8Array();
+    return AuthenticationKey.fromBytesAndScheme({ bytes: pubKeyBytes, scheme });
+  }
+
+  /**
+   * Derives an account address from AuthenticationKey. Since current AccountAddress is 32 bytes,
+   * AuthenticationKey bytes are directly translated to AccountAddress.
+   *
+   * @returns AccountAddress
+   */
+  derivedAddress(): AccountAddress {
+    return new AccountAddress({ data: this.data.toUint8Array() });
+  }
+}

package/src/core/common.ts

@@ -0,0 +1,40 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * This error is used to explain why parsing failed.
+ */
+export class ParsingError<T> extends Error {
+  /**
+   * This provides a programmatic way to access why parsing failed. Downstream devs
+   * might want to use this to build their own error messages if the default error
+   * messages are not suitable for their use case. This should be an enum.
+   */
+  public invalidReason: T;
+
+  constructor(message: string, invalidReason: T) {
+    super(message);
+    this.invalidReason = invalidReason;
+  }
+}
+
+/**
+ * Whereas ParsingError is thrown when parsing fails, e.g. in a fromString function,
+ * this type is returned from "defensive" functions like isValid.
+ */
+export type ParsingResult<T> = {
+  /**
+   * True if valid, false otherwise.
+   */
+  valid: boolean;
+
+  /**
+   * If valid is false, this will be a code explaining why parsing failed.
+   */
+  invalidReason?: T;
+
+  /**
+   * If valid is false, this will be a string explaining why parsing failed.
+   */
+  invalidReasonMessage?: string;
+};

package/src/core/crypto/asymmetricCrypto.ts

@@ -0,0 +1,77 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+import { Serializable, Serializer } from "../../bcs";
+import { HexInput } from "../../types";
+
+/**
+ * An abstract representation of a public key.  All Asymmetric key pairs will use this to
+ * verify signatures and for authentication keys.
+ */
+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: { message: HexInput; signature: Signature }): 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...
+   */
+  abstract toString(): string;
+
+  abstract serialize(serializer: Serializer): void;
+}
+
+/**
+ * An abstract representation of a private key.  This is used to sign transactions and
+ * derive the public key associated.
+ */
+export abstract class PrivateKey extends Serializable {
+  /**
+   * Sign a message with the key
+   * @param message The message to sign
+   */
+  abstract sign(message: HexInput): Signature;
+
+  /**
+   * Get the raw private key bytes
+   */
+  abstract toUint8Array(): Uint8Array;
+
+  /**
+   * Get the private key as a hex string with a 0x prefix e.g. 0x123456...
+   */
+  abstract toString(): string;
+
+  abstract serialize(serializer: Serializer): void;
+
+  /**
+   * Derives the public key associated with the private key
+   */
+  abstract publicKey(): PublicKey;
+}
+
+/**
+ * An abstract representation of a signature.  This is the product of signing a
+ * message and can be used with the PublicKey to verify the signature.
+ */
+export abstract class Signature extends Serializable {
+  /**
+   * Get the raw signature bytes
+   */
+  abstract toUint8Array(): Uint8Array;
+
+  /**
+   * Get the signature as a hex string with a 0x prefix e.g. 0x123456...
+   */
+  abstract toString(): string;
+
+  abstract serialize(serializer: Serializer): void;
+}

package/src/core/crypto/ed25519.ts

@@ -0,0 +1,224 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+import nacl from "tweetnacl";
+import { PublicKey, PrivateKey, Signature } from "./asymmetricCrypto";
+import { Deserializer } from "../../bcs/deserializer";
+import { Serializer } from "../../bcs/serializer";
+import { Hex } from "../hex";
+import { HexInput } from "../../types";
+
+/**
+ * Represents the public key of an Ed25519 key pair.
+ */
+export class Ed25519PublicKey extends PublicKey {
+  /**
+   * Length of an Ed25519 public key
+   */
+  static readonly LENGTH: number = 32;
+
+  /**
+   * Bytes of the public key
+   * @private
+   */
+  private readonly key: Hex;
+
+  /**
+   * Create a new PublicKey instance from a Uint8Array or String.
+   *
+   * @param hexInput A HexInput (string or Uint8Array)
+   */
+  constructor(hexInput: HexInput) {
+    super();
+
+    const hex = Hex.fromHexInput(hexInput);
+    if (hex.toUint8Array().length !== Ed25519PublicKey.LENGTH) {
+      throw new Error(`PublicKey length should be ${Ed25519PublicKey.LENGTH}`);
+    }
+    this.key = hex;
+  }
+
+  /**
+   * Get the public key in bytes (Uint8Array).
+   *
+   * @returns Uint8Array representation of the public key
+   */
+  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();
+  }
+
+  /**
+   * Verifies a signed data with a public key
+   * @param args.message a signed message
+   * @param args.signature the signature of the message
+   */
+  verifySignature(args: { message: HexInput; signature: Ed25519Signature }): boolean {
+    const { message, signature } = args;
+    const rawMessage = Hex.fromHexInput(message).toUint8Array();
+    const rawSignature = Hex.fromHexInput(signature.toUint8Array()).toUint8Array();
+    return nacl.sign.detached.verify(rawMessage, rawSignature, this.key.toUint8Array());
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeBytes(this.key.toUint8Array());
+  }
+
+  static deserialize(deserializer: Deserializer): Ed25519PublicKey {
+    const bytes = deserializer.deserializeBytes();
+    return new Ed25519PublicKey(bytes);
+  }
+}
+
+/**
+ * Represents the private key of an Ed25519 key pair.
+ */
+export class Ed25519PrivateKey extends PrivateKey {
+  /**
+   * Length of an Ed25519 private key
+   */
+  static readonly LENGTH: number = 32;
+
+  /**
+   * The Ed25519 signing key
+   * @private
+   */
+  private readonly signingKeyPair: nacl.SignKeyPair;
+
+  /**
+   * Create a new PrivateKey instance from a Uint8Array or String.
+   *
+   * @param hexInput HexInput (string or Uint8Array)
+   */
+  constructor(hexInput: HexInput) {
+    super();
+
+    const privateKeyHex = Hex.fromHexInput(hexInput);
+    if (privateKeyHex.toUint8Array().length !== Ed25519PrivateKey.LENGTH) {
+      throw new Error(`PrivateKey length should be ${Ed25519PrivateKey.LENGTH}`);
+    }
+
+    // Create keyPair from Private key in Uint8Array format
+    this.signingKeyPair = nacl.sign.keyPair.fromSeed(privateKeyHex.toUint8Array().slice(0, Ed25519PrivateKey.LENGTH));
+  }
+
+  /**
+   * Get the private key in bytes (Uint8Array).
+   *
+   * @returns Uint8Array representation of the private key
+   */
+  toUint8Array(): Uint8Array {
+    return this.signingKeyPair.secretKey.slice(0, Ed25519PrivateKey.LENGTH);
+  }
+
+  /**
+   * Get the private key as a hex string with the 0x prefix.
+   *
+   * @returns string representation of the private key
+   */
+  toString(): string {
+    return Hex.fromHexInput(this.toUint8Array()).toString();
+  }
+
+  /**
+   * Sign the given message with the private key.
+   *
+   * @param message in HexInput format
+   * @returns Signature
+   */
+  sign(message: HexInput): Ed25519Signature {
+    const hex = Hex.fromHexInput(message);
+    const signature = nacl.sign.detached(hex.toUint8Array(), this.signingKeyPair.secretKey);
+    return new Ed25519Signature(signature);
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeBytes(this.toUint8Array());
+  }
+
+  static deserialize(deserializer: Deserializer): Ed25519PrivateKey {
+    const bytes = deserializer.deserializeBytes();
+    return new Ed25519PrivateKey(bytes);
+  }
+
+  /**
+   * Generate a new random private key.
+   *
+   * @returns Ed25519PrivateKey
+   */
+  static generate(): Ed25519PrivateKey {
+    const keyPair = nacl.sign.keyPair();
+    return new Ed25519PrivateKey(keyPair.secretKey.slice(0, Ed25519PrivateKey.LENGTH));
+  }
+
+  /**
+   * Derive the Ed25519PublicKey for this private key.
+   *
+   * @returns Ed25519PublicKey
+   */
+  publicKey(): Ed25519PublicKey {
+    const bytes = this.signingKeyPair.publicKey;
+    return new Ed25519PublicKey(bytes);
+  }
+}
+
+/**
+ * A signature of a message signed using an Ed25519 private key
+ */
+export class Ed25519Signature extends Signature {
+  /**
+   * Length of an Ed25519 signature
+   */
+  static readonly LENGTH = 64;
+
+  /**
+   * The signature bytes
+   * @private
+   */
+  private readonly data: Hex;
+
+  constructor(hexInput: HexInput) {
+    super();
+    const hex = Hex.fromHexInput(hexInput);
+    if (hex.toUint8Array().length !== Ed25519Signature.LENGTH) {
+      throw new Error(`Signature length should be ${Ed25519Signature.LENGTH}`);
+    }
+
+    this.data = hex;
+  }
+
+  /**
+   * Get the signature in bytes (Uint8Array).
+   *
+   * @returns Uint8Array representation of the 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();
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeBytes(this.data.toUint8Array());
+  }
+
+  static deserialize(deserializer: Deserializer): Ed25519Signature {
+    const bytes = deserializer.deserializeBytes();
+    return new Ed25519Signature(bytes);
+  }
+}

package/src/core/crypto/index.ts

@@ -0,0 +1,7 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+export * from "./asymmetricCrypto";
+export * from "./ed25519";
+export * from "./multiEd25519";
+export * from "./secp256k1";

package/src/core/crypto/multiEd25519.ts

@@ -0,0 +1,251 @@
+// 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 { Ed25519PublicKey, Ed25519Signature } from "./ed25519";
+import { Hex } from "../hex";
+import { HexInput } from "../../types";
+
+/**
+ * Represents the public key of a K-of-N Ed25519 multi-sig transaction.
+ */
+export class MultiEd25519PublicKey extends PublicKey {
+  /**
+   * Maximum number of public keys supported
+   */
+  static readonly MAX_KEYS = 32;
+
+  /**
+   * Minimum number of public keys needed
+   */
+  static readonly MIN_KEYS = 2;
+
+  /**
+   * Minimum threshold for the number of valid signatures required
+   */
+  static readonly MIN_THRESHOLD = 1;
+
+  /**
+   * List of Ed25519 public keys for this MultiEd25519PublicKey
+   */
+  public readonly publicKeys: Ed25519PublicKey[];
+
+  /**
+   * The minimum number of valid signatures required, for the number of public keys specified
+   */
+  public readonly threshold: number;
+
+  /**
+   * Public key for a K-of-N multi-sig transaction. A K-of-N multi-sig transaction means that for such a
+   * transaction to be executed, at least K out of the N authorized signers have signed the transaction
+   * and passed the check conducted by the chain.
+   *
+   * @see {@link
+   * https://aptos.dev/integration/creating-a-signed-transaction/ | Creating a Signed Transaction}
+   *
+   * @param args.publicKeys A list of public keys
+   * @param args.threshold At least "threshold" signatures must be valid
+   */
+  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`,
+      );
+    }
+
+    // Validate threshold: must be between 1 and the number of public keys, inclusive
+    if (threshold < MultiEd25519PublicKey.MIN_THRESHOLD || threshold > publicKeys.length) {
+      throw new Error(
+        `Threshold must be between ${MultiEd25519PublicKey.MIN_THRESHOLD} and ${publicKeys.length}, inclusive`,
+      );
+    }
+
+    this.publicKeys = publicKeys;
+    this.threshold = threshold;
+  }
+
+  /**
+   * Converts a PublicKeys into Uint8Array (bytes) with: bytes = p1_bytes | ... | pn_bytes | threshold
+   */
+  toUint8Array(): Uint8Array {
+    const bytes = new Uint8Array(this.publicKeys.length * Ed25519PublicKey.LENGTH + 1);
+    this.publicKeys.forEach((k: Ed25519PublicKey, i: number) => {
+      bytes.set(k.toUint8Array(), i * Ed25519PublicKey.LENGTH);
+    });
+
+    bytes[this.publicKeys.length * Ed25519PublicKey.LENGTH] = this.threshold;
+
+    return bytes;
+  }
+
+  toString(): string {
+    return Hex.fromHexInput(this.toUint8Array()).toString();
+  }
+
+  // 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.");
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeBytes(this.toUint8Array());
+  }
+
+  static deserialize(deserializer: Deserializer): MultiEd25519PublicKey {
+    const bytes = deserializer.deserializeBytes();
+    const threshold = bytes[bytes.length - 1];
+
+    const keys: Ed25519PublicKey[] = [];
+
+    for (let i = 0; i < bytes.length - 1; i += Ed25519PublicKey.LENGTH) {
+      const begin = i;
+      keys.push(new Ed25519PublicKey(bytes.subarray(begin, begin + Ed25519PublicKey.LENGTH)));
+    }
+    return new MultiEd25519PublicKey({ publicKeys: keys, threshold });
+  }
+}
+
+/**
+ * Represents the signature of a K-of-N Ed25519 multi-sig transaction.
+ */
+export class MultiEd25519Signature extends Signature {
+  /**
+   * Maximum number of Ed25519 signatures supported
+   */
+  static MAX_SIGNATURES_SUPPORTED = 32;
+
+  /**
+   * Number of bytes in the bitmap representing who signed the transaction (32-bits)
+   */
+  static BITMAP_LEN: number = 4;
+
+  /**
+   * The list of underlying Ed25519 signatures
+   */
+  public readonly signatures: Ed25519Signature[];
+
+  /**
+   * 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: Ed25519Signature[]; bitmap: Uint8Array }) {
+    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;
+  }
+
+  /**
+   * Converts a MultiSignature into Uint8Array (bytes) with `bytes = s1_bytes | ... | sn_bytes | bitmap`
+   */
+  toUint8Array(): Uint8Array {
+    const bytes = new Uint8Array(this.signatures.length * Ed25519Signature.LENGTH + MultiEd25519Signature.BITMAP_LEN);
+    this.signatures.forEach((k: Ed25519Signature, i: number) => {
+      bytes.set(k.toUint8Array(), i * Ed25519Signature.LENGTH);
+    });
+
+    bytes.set(this.bitmap, this.signatures.length * Ed25519Signature.LENGTH);
+
+    return bytes;
+  }
+
+  toString(): string {
+    return Hex.fromHexInput(this.toUint8Array()).toString();
+  }
+
+  /**
+   * 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 bitmap that is 32bit long
+   */
+  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 >= MultiEd25519Signature.MAX_SIGNATURES_SUPPORTED) {
+        throw new Error(`Cannot have a signature larger than ${MultiEd25519Signature.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;
+  }
+
+  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 });
+  }
+}