@aptos-labs/ts-sdk 1.8.0 → 1.9.0

package/src/core/account/Account.ts

@@ -0,0 +1,245 @@
+import type { AccountAuthenticator } from "../../transactions/authenticator/account";
+import { HexInput, SigningScheme, SigningSchemeInput } from "../../types";
+import type { AccountAddress, AccountAddressInput } from "../accountAddress";
+import { AuthenticationKey } from "../authenticationKey";
+import { AccountPublicKey, Ed25519PrivateKey, PrivateKey, Signature, VerifySignatureArgs } from "../crypto";
+import { Ed25519Account } from "./Ed25519Account";
+import { SingleKeyAccount } from "./SingleKeyAccount";
+
+/**
+ * Arguments for creating an `Ed25519Account` from an `Ed25519PrivateKey`.
+ * This is the default input type when passing an `Ed25519PrivateKey`.
+ * In order to use the SingleKey authentication scheme, `legacy` needs to be explicitly set to false.
+ */
+export interface CreateEd25519AccountFromPrivateKeyArgs {
+  privateKey: Ed25519PrivateKey;
+  address?: AccountAddressInput;
+  legacy?: true;
+}
+
+/**
+ * Arguments for creating an `SingleKeyAccount` from an `Ed25519PrivateKey`.
+ * The `legacy` argument needs to be explicitly set to false in order to
+ * use the `SingleKey` authentication scheme.
+ */
+export interface CreateEd25519SingleKeyAccountFromPrivateKeyArgs {
+  privateKey: Ed25519PrivateKey;
+  address?: AccountAddressInput;
+  legacy: false;
+}
+
+/**
+ * Arguments for creating an `SingleKeyAccount` from any supported private key
+ * that is not an `Ed25519PrivateKey`.
+ * The `legacy` argument defaults to false and cannot be explicitly set to true.
+ */
+export interface CreateSingleKeyAccountFromPrivateKeyArgs {
+  privateKey: Exclude<PrivateKey, Ed25519PrivateKey>;
+  address?: AccountAddressInput;
+  legacy?: false;
+}
+
+/**
+ * Arguments for creating an opaque `Account` from any supported private key.
+ * This is used when the private key type is not known at compilation time.
+ */
+export interface CreateAccountFromPrivateKeyArgs {
+  privateKey: PrivateKey;
+  address?: AccountAddressInput;
+  legacy?: boolean;
+}
+
+/**
+ * Arguments for generating an `Ed25519Account`.
+ * This is the input type used by default.
+ */
+export interface GenerateEd25519AccountArgs {
+  scheme?: SigningSchemeInput.Ed25519;
+  legacy?: true;
+}
+
+/**
+ * Arguments for generating an `SingleKeyAccount` with ah underlying `Ed25519PrivateKey`.
+ * The `legacy` argument needs to be explicitly set to false,
+ * otherwise an `Ed25519Account` will be returned instead.
+ */
+export interface GenerateEd25519SingleKeyAccountArgs {
+  scheme?: SigningSchemeInput.Ed25519;
+  legacy: false;
+}
+
+/**
+ * Arguments for generating an `SingleKeyAccount` with any supported private key
+ * that is not an `Ed25519PrivateKey`.
+ * The `legacy` argument defaults to false and cannot be explicitly set to true.
+ */
+export interface GenerateSingleKeyAccountArgs {
+  scheme: Exclude<SigningSchemeInput, SigningSchemeInput.Ed25519>;
+  legacy?: false;
+}
+
+/**
+ * Arguments for generating an opaque `Account`.
+ * This is used when the input signature scheme is not known at compilation time.
+ */
+export interface GenerateAccountArgs {
+  scheme?: SigningSchemeInput;
+  legacy?: boolean;
+}
+
+/**
+ * Arguments for deriving a private key from a mnemonic phrase and a BIP44 path.
+ */
+export interface PrivateKeyFromDerivationPathArgs {
+  path: string;
+  mnemonic: string;
+}
+
+/**
+ * Interface for a generic Aptos account.
+ *
+ * The interface is defined as abstract class to provide a single entrypoint for account generation,
+ * either through `Account.generate()` or `Account.fromDerivationPath`.
+ * Despite this being an abstract class, it should be treated as an interface and enforced using
+ * the `implements` keyword.
+ *
+ * Note: Generating an account instance does not create the account on-chain.
+ */
+export abstract class Account {
+  /**
+   * Private key associated with the account.
+   * Note: this will be removed in the next major release,
+   *  as not all accounts have a private key.
+   */
+  abstract readonly privateKey: PrivateKey;
+
+  /**
+   * Public key associated with the account
+   */
+  abstract readonly publicKey: AccountPublicKey;
+
+  /**
+   * Account address associated with the account
+   */
+  abstract readonly accountAddress: AccountAddress;
+
+  /**
+   * Signing scheme used to sign transactions
+   */
+  abstract signingScheme: SigningScheme;
+
+  /**
+   * Derives an account from a randomly generated private key.
+   * @param args.scheme The signature scheme to use, to generate the private key
+   * @param args.legacy Whether to use a legacy authentication scheme, when applicable
+   * @returns An account compatible with the provided signature scheme
+   */
+  static generate(args?: GenerateEd25519AccountArgs): Ed25519Account;
+  static generate(args: GenerateEd25519SingleKeyAccountArgs): SingleKeyAccount;
+  static generate(args: GenerateSingleKeyAccountArgs): SingleKeyAccount;
+  static generate(args: GenerateAccountArgs): Account;
+  static generate(args: GenerateAccountArgs = {}) {
+    const { scheme = SigningSchemeInput.Ed25519, legacy = true } = args;
+    if (scheme === SigningSchemeInput.Ed25519 && legacy) {
+      return Ed25519Account.generate();
+    }
+    return SingleKeyAccount.generate({ scheme });
+  }
+
+  /**
+   * Creates an account from the provided private key.
+   *
+   * @param args.privateKey a valid private key
+   * @param args.address the account's address. If not provided, it will be derived from the public key.
+   * @param args.legacy Whether to use a legacy authentication scheme, when applicable
+   */
+  static fromPrivateKey(args: CreateEd25519AccountFromPrivateKeyArgs): Ed25519Account;
+  static fromPrivateKey(args: CreateEd25519SingleKeyAccountFromPrivateKeyArgs): SingleKeyAccount;
+  static fromPrivateKey(args: CreateSingleKeyAccountFromPrivateKeyArgs): SingleKeyAccount;
+  static fromPrivateKey(args: CreateAccountFromPrivateKeyArgs): Account;
+  static fromPrivateKey(args: CreateAccountFromPrivateKeyArgs) {
+    const { privateKey, address, legacy = true } = args;
+    if (privateKey instanceof Ed25519PrivateKey && legacy) {
+      return new Ed25519Account({
+        privateKey,
+        address,
+      });
+    }
+    return new SingleKeyAccount({ privateKey, address });
+  }
+
+  /**
+   * @deprecated use `fromPrivateKey` instead.
+   * Instantiates an account given a private key and a specified account address.
+   * This is primarily used to instantiate an `Account` that has had its authentication key rotated.
+   *
+   * @param args.privateKey PrivateKey - the underlying private key for the account
+   * @param args.address AccountAddress - The account address the `Account` will sign for
+   * @param args.legacy optional. If set to false, the keypair generated is a Unified keypair. Defaults
+   * to generating a Legacy Ed25519 keypair
+   *
+   * @returns Account
+   */
+  static fromPrivateKeyAndAddress(args: CreateAccountFromPrivateKeyArgs) {
+    return this.fromPrivateKey(args);
+  }
+
+  /**
+   * Derives an account with bip44 path and mnemonics
+   *
+   * @param args.scheme The signature scheme to derive the private key with
+   * @param args.path the BIP44 derive hardened path (e.g. m/44'/637'/0'/0'/0') for Ed25519,
+   * or non-hardened path (e.g. m/44'/637'/0'/0/0) for secp256k1
+   * Detailed description: {@link https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki}
+   * @param args.mnemonic the mnemonic seed phrase of the account
+   */
+  static fromDerivationPath(args: GenerateEd25519AccountArgs & PrivateKeyFromDerivationPathArgs): Ed25519Account;
+  static fromDerivationPath(
+    args: GenerateEd25519SingleKeyAccountArgs & PrivateKeyFromDerivationPathArgs,
+  ): SingleKeyAccount;
+  static fromDerivationPath(args: GenerateSingleKeyAccountArgs & PrivateKeyFromDerivationPathArgs): SingleKeyAccount;
+  static fromDerivationPath(args: GenerateAccountArgs & PrivateKeyFromDerivationPathArgs): Account;
+  static fromDerivationPath(args: GenerateAccountArgs & PrivateKeyFromDerivationPathArgs) {
+    const { scheme = SigningSchemeInput.Ed25519, mnemonic, path, legacy = true } = args;
+    if (scheme === SigningSchemeInput.Ed25519 && legacy) {
+      return Ed25519Account.fromDerivationPath({ mnemonic, path });
+    }
+    return SingleKeyAccount.fromDerivationPath({ scheme, mnemonic, path });
+  }
+
+  /**
+   * @deprecated use `publicKey.authKey()` instead.
+   * This key enables account owners to rotate their private key(s)
+   * associated with the account without changing the address that hosts their account.
+   * See here for more info: {@link https://aptos.dev/concepts/accounts#single-signer-authentication}
+   *
+   * @param args.publicKey PublicKey - public key of the account
+   * @returns The authentication key for the associated account
+   */
+  static authKey(args: { publicKey: AccountPublicKey }): AuthenticationKey {
+    const { publicKey } = args;
+    return publicKey.authKey();
+  }
+
+  /**
+   * Sign a message using the available signing capabilities.
+   * @param message the signing message, as binary input
+   * @return the AccountAuthenticator containing the signature, together with the account's public key
+   */
+  abstract signWithAuthenticator(message: HexInput): AccountAuthenticator;
+
+  /**
+   * Sign the given message with the private key.
+   * @param message in HexInput format
+   * @returns AccountSignature
+   */
+  abstract sign(message: HexInput): Signature;
+
+  /**
+   * @param args.message raw message data in HexInput format
+   * @param args.signature signed message signature
+   */
+  verifySignature(args: VerifySignatureArgs): boolean {
+    return this.publicKey.verifySignature(args);
+  }
+}

package/src/core/account/Ed25519Account.ts

@@ -0,0 +1,88 @@
+import { AccountAuthenticatorEd25519 } from "../../transactions/authenticator/account";
+import { HexInput, SigningScheme } from "../../types";
+import { AccountAddress, AccountAddressInput } from "../accountAddress";
+import { Ed25519PrivateKey, Ed25519PublicKey, Ed25519Signature } from "../crypto";
+import type { Account } from "./Account";
+
+export interface Ed25519SignerConstructorArgs {
+  privateKey: Ed25519PrivateKey;
+  address?: AccountAddressInput;
+}
+
+export interface Ed25519SignerFromDerivationPathArgs {
+  path: string;
+  mnemonic: string;
+}
+
+export interface VerifyEd25519SignatureArgs {
+  message: HexInput;
+  signature: Ed25519Signature;
+}
+
+/**
+ * Signer implementation for the Ed25519 authentication scheme.
+ * This extends an {@link Ed25519Account} by adding signing capabilities through an {@link Ed25519PrivateKey}.
+ *
+ * Note: Generating a signer instance does not create the account on-chain.
+ */
+export class Ed25519Account implements Account {
+  /**
+   * Private key associated with the account
+   */
+  readonly privateKey: Ed25519PrivateKey;
+
+  readonly publicKey: Ed25519PublicKey;
+
+  readonly accountAddress: AccountAddress;
+
+  readonly signingScheme = SigningScheme.Ed25519;
+
+  // region Constructors
+
+  constructor(args: Ed25519SignerConstructorArgs) {
+    const { privateKey, address } = args;
+    this.privateKey = privateKey;
+    this.publicKey = privateKey.publicKey();
+    this.accountAddress = address ? AccountAddress.from(address) : this.publicKey.authKey().derivedAddress();
+  }
+
+  /**
+   * Derives a signer from a randomly generated private key
+   */
+  static generate() {
+    const privateKey = Ed25519PrivateKey.generate();
+    return new Ed25519Account({ privateKey });
+  }
+
+  /**
+   * Derives an account with bip44 path and mnemonics
+   *
+   * @param args.path the BIP44 derive hardened path e.g. m/44'/637'/0'/0'/0'
+   * Detailed description: {@link https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki}
+   * @param args.mnemonic the mnemonic seed phrase of the account
+   */
+  static fromDerivationPath(args: Ed25519SignerFromDerivationPathArgs) {
+    const { path, mnemonic } = args;
+    const privateKey = Ed25519PrivateKey.fromDerivationPath(path, mnemonic);
+    return new Ed25519Account({ privateKey });
+  }
+
+  // endregion
+
+  // region Account
+
+  verifySignature(args: VerifyEd25519SignatureArgs): boolean {
+    return this.publicKey.verifySignature(args);
+  }
+
+  signWithAuthenticator(message: HexInput) {
+    const signature = this.privateKey.sign(message);
+    return new AccountAuthenticatorEd25519(this.publicKey, signature);
+  }
+
+  sign(message: HexInput) {
+    return this.signWithAuthenticator(message).signature;
+  }
+
+  // endregion
+}

package/src/core/account/SingleKeyAccount.ts

@@ -0,0 +1,120 @@
+import { AccountAuthenticatorSingleKey } from "../../transactions/authenticator/account";
+import { type HexInput, SigningScheme, SigningSchemeInput } from "../../types";
+import { AccountAddress, AccountAddressInput } from "../accountAddress";
+import { AnyPublicKey, AnySignature, Ed25519PrivateKey, PrivateKey, Secp256k1PrivateKey } from "../crypto";
+import type { Account } from "./Account";
+
+export interface SingleKeySignerConstructorArgs {
+  privateKey: PrivateKey;
+  address?: AccountAddressInput;
+}
+
+export interface SingleKeySignerGenerateArgs {
+  scheme?: SigningSchemeInput;
+}
+
+export type SingleKeySignerFromDerivationPathArgs = SingleKeySignerGenerateArgs & {
+  path: string;
+  mnemonic: string;
+};
+
+export interface VerifySingleKeySignatureArgs {
+  message: HexInput;
+  signature: AnySignature;
+}
+
+/**
+ * Signer implementation for the SingleKey authentication scheme.
+ * This extends a SingleKeyAccount by adding signing capabilities through a valid private key.
+ * Currently, the only supported signature schemes are Ed25519 and Secp256k1.
+ *
+ * Note: Generating a signer instance does not create the account on-chain.
+ */
+export class SingleKeyAccount implements Account {
+  /**
+   * Private key associated with the account
+   */
+  readonly privateKey: PrivateKey;
+
+  readonly publicKey: AnyPublicKey;
+
+  readonly accountAddress: AccountAddress;
+
+  readonly signingScheme = SigningScheme.SingleKey;
+
+  // region Constructors
+
+  constructor(args: SingleKeySignerConstructorArgs) {
+    const { privateKey, address } = args;
+    this.privateKey = privateKey;
+    this.publicKey = new AnyPublicKey(privateKey.publicKey());
+    this.accountAddress = address ? AccountAddress.from(address) : this.publicKey.authKey().derivedAddress();
+  }
+
+  /**
+   * Derives an account from a randomly generated private key.
+   * Default generation is using an Ed25519 key
+   * @returns Account with the given signature scheme
+   */
+  static generate(args: SingleKeySignerGenerateArgs = {}) {
+    const { scheme = SigningSchemeInput.Ed25519 } = args;
+    let privateKey: PrivateKey;
+    switch (scheme) {
+      case SigningSchemeInput.Ed25519:
+        privateKey = Ed25519PrivateKey.generate();
+        break;
+      case SigningSchemeInput.Secp256k1Ecdsa:
+        privateKey = Secp256k1PrivateKey.generate();
+        break;
+      default:
+        throw new Error(`Unsupported signature scheme ${scheme}`);
+    }
+    return new SingleKeyAccount({ privateKey });
+  }
+
+  /**
+   * Derives an account with bip44 path and mnemonics,
+   * Default to using an Ed25519 signature scheme.
+   *
+   * @param args.scheme The signature scheme to derive the private key with
+   * @param args.path the BIP44 derive hardened path (e.g. m/44'/637'/0'/0'/0') for Ed25519,
+   * or non-hardened path (e.g. m/44'/637'/0'/0/0) for secp256k1
+   * Detailed description: {@link https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki}
+   * @param args.mnemonic the mnemonic seed phrase of the account
+   */
+  static fromDerivationPath(args: SingleKeySignerFromDerivationPathArgs) {
+    const { scheme = SigningSchemeInput.Ed25519, path, mnemonic } = args;
+    let privateKey: PrivateKey;
+    switch (scheme) {
+      case SigningSchemeInput.Ed25519:
+        privateKey = Ed25519PrivateKey.fromDerivationPath(path, mnemonic);
+        break;
+      case SigningSchemeInput.Secp256k1Ecdsa:
+        privateKey = Secp256k1PrivateKey.fromDerivationPath(path, mnemonic);
+        break;
+      default:
+        throw new Error(`Unsupported signature scheme ${scheme}`);
+    }
+    return new SingleKeyAccount({ privateKey });
+  }
+
+  // endregion
+
+  // region Account
+
+  verifySignature(args: VerifySingleKeySignatureArgs): boolean {
+    return this.publicKey.verifySignature(args);
+  }
+
+  signWithAuthenticator(message: HexInput) {
+    const innerSignature = this.privateKey.sign(message);
+    const signature = new AnySignature(innerSignature);
+    return new AccountAuthenticatorSingleKey(this.publicKey, signature);
+  }
+
+  sign(message: HexInput) {
+    return this.signWithAuthenticator(message).signature;
+  }
+
+  // endregion
+}

package/src/core/account/index.ts

@@ -0,0 +1,3 @@
+export * from "./Ed25519Account";
+export * from "./Account";
+export * from "./SingleKeyAccount";

package/src/core/authenticationKey.ts

@@ -3,13 +3,9 @@
 
 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 type { AccountPublicKey } from "./crypto";
 import { Hex } from "./hex";
-import { AuthenticationKeyScheme, HexInput, SigningScheme } from "../types";
-import { AnyPublicKey } from "./crypto/anyPublicKey";
-import { MultiKey } from "./crypto/multiKey";
+import { AuthenticationKeyScheme, HexInput } from "../types";
 import { Serializable, Serializer } from "../bcs/serializer";
 import { Deserializer } from "../bcs/deserializer";
 
@@ -65,41 +61,27 @@ export class AuthenticationKey extends Serializable {
     return this.data.toUint8Array();
   }
 
+  static fromSchemeAndBytes(args: { scheme: AuthenticationKeyScheme; input: HexInput }): AuthenticationKey {
+    const { scheme, input } = args;
+    const inputBytes = Hex.fromHexInput(input).toUint8Array();
+    const hashInput = new Uint8Array([...inputBytes, scheme]);
+    const hash = sha3Hash.create();
+    hash.update(hashInput);
+    const hashDigest = hash.digest();
+    return new AuthenticationKey({ data: hashDigest });
+  }
+
   /**
+   * @deprecated Use `fromPublicKey` instead
    * Derives an AuthenticationKey from the public key seed bytes and an explicit derivation scheme.
    *
    * This facilitates targeting a specific scheme for deriving an authentication key from a public key.
    *
    * @param args - the public key and scheme to use for the derivation
    */
-  public static fromPublicKeyAndScheme(args: { publicKey: PublicKey; scheme: AuthenticationKeyScheme }) {
-    const { publicKey, scheme } = args;
-    let authKeyBytes: Uint8Array;
-
-    switch (scheme) {
-      case SigningScheme.MultiKey:
-      case SigningScheme.SingleKey: {
-        const singleKeyBytes = publicKey.bcsToBytes();
-        authKeyBytes = new Uint8Array([...singleKeyBytes, scheme]);
-        break;
-      }
-
-      case SigningScheme.Ed25519:
-      case SigningScheme.MultiEd25519: {
-        const ed25519PublicKeyBytes = publicKey.toUint8Array();
-        const inputBytes = Hex.fromHexInput(ed25519PublicKeyBytes).toUint8Array();
-        authKeyBytes = new Uint8Array([...inputBytes, scheme]);
-        break;
-      }
-
-      default:
-        throw new Error(`Scheme ${scheme} is not supported`);
-    }
-
-    const hash = sha3Hash.create();
-    hash.update(authKeyBytes);
-    const hashDigest = hash.digest();
-    return new AuthenticationKey({ data: hashDigest });
+  public static fromPublicKeyAndScheme(args: { publicKey: AccountPublicKey; scheme: AuthenticationKeyScheme }) {
+    const { publicKey } = args;
+    return publicKey.authKey();
   }
 
   /**
@@ -109,25 +91,9 @@ export class AuthenticationKey extends Serializable {
    * @param args.publicKey
    * @returns AuthenticationKey
    */
-  static fromPublicKey(args: { publicKey: PublicKey }): AuthenticationKey {
+  static fromPublicKey(args: { publicKey: AccountPublicKey }): AuthenticationKey {
     const { publicKey } = args;
-
-    let scheme: number;
-    if (publicKey instanceof Ed25519PublicKey) {
-      // for legacy support
-      scheme = SigningScheme.Ed25519.valueOf();
-    } else if (publicKey instanceof MultiEd25519PublicKey) {
-      // for legacy support
-      scheme = SigningScheme.MultiEd25519.valueOf();
-    } else if (publicKey instanceof AnyPublicKey) {
-      scheme = SigningScheme.SingleKey.valueOf();
-    } else if (publicKey instanceof MultiKey) {
-      scheme = SigningScheme.MultiKey.valueOf();
-    } else {
-      throw new Error("No supported authentication scheme for public key");
-    }
-
-    return AuthenticationKey.fromPublicKeyAndScheme({ publicKey, scheme });
+    return publicKey.authKey();
   }
 
   /**