@aptos-labs/ts-sdk 1.29.1 → 1.31.0

package/src/account/MultiKeyAccount.ts

@@ -9,6 +9,12 @@ import { AccountAuthenticatorMultiKey } from "../transactions/authenticator/acco
 import { AnyRawTransaction } from "../transactions/types";
 import { AbstractKeylessAccount } from "./AbstractKeylessAccount";
 
+/**
+ * Arguments required to verify a multi-key signature against a given message.
+ *
+ * @param message - The original message that was signed.
+ * @param signature - The multi-key signature to be verified.
+ */
 export interface VerifyMultiKeySignatureArgs {
   message: HexInput;
   signature: MultiKeySignature;
@@ -17,8 +23,8 @@ export interface VerifyMultiKeySignatureArgs {
 /**
  * Signer implementation for the MultiKey authentication scheme.
  *
- * This accounts to use a M of N signing scheme. M and N are specified in the {@link MultiKey}
- * It signs messages via the array of M number of Accounts that individually correspond to a public key in the {@link MultiKey}.
+ * This account utilizes an M of N signing scheme, where M and N are specified in the {@link MultiKey}.
+ * It signs messages using an array of M accounts, each corresponding to a public key in the {@link MultiKey}.
  *
  * Note: Generating a signer instance does not create the account on-chain.
  */
@@ -46,20 +52,21 @@ export class MultiKeyAccount implements Account {
   readonly signers: Account[];
 
   /**
-   * An array of indicies where for signer[i], signerIndicies[i] is the index of the corresponding public key in
+   * An array of indices where for signer[i], signerIndicies[i] is the index of the corresponding public key in
    * publicKey.publicKeys.  Used to derive the right public key to use for verification.
    */
+  // TODO: Rename Indicies to Indices
   readonly signerIndicies: number[];
 
   readonly signaturesBitmap: Uint8Array;
 
   /**
-   * constructor for MultiKeyAccount
+   * Constructs a MultiKeyAccount instance, which requires multiple signatures for transactions.
    *
-   * @param args.multiKey the multikey of the account which consists of N public keys and a number M which is
-   * the number of required signatures.
-   * @param args.signers an array of M signers that will be used to sign the transaction
-   * @returns MultiKeyAccount
+   * @param args - The arguments for creating a MultiKeyAccount.
+   * @param args.multiKey - The multikey of the account consisting of N public keys and a number M representing the required signatures.
+   * @param args.signers - An array of M signers that will be used to sign the transaction.
+   * @param args.address - An optional account address input. If not provided, the derived address from the public key will be used.
    */
   constructor(args: { multiKey: MultiKey; signers: Account[]; address?: AccountAddressInput }) {
     const { multiKey, signers, address } = args;
@@ -85,12 +92,13 @@ export class MultiKeyAccount implements Account {
   }
 
   /**
-   * Static constructor for MultiKeyAccount
+   * Static constructor to create a MultiKeyAccount using the provided public keys and signers.
    *
-   * @param args.publicKeys the N public keys of the MultiKeyAccount
-   * @param args.signaturesRequired the number of signatures required
-   * @param args.signers an array of M signers that will be used to sign the transaction
-   * @returns MultiKeyAccount
+   * @param args - The arguments for creating a MultiKeyAccount.
+   * @param args.publicKeys - The N public keys of the MultiKeyAccount.
+   * @param args.signaturesRequired - The number of signatures required to authorize a transaction.
+   * @param args.signers - An array of M signers that will be used to sign the transaction.
+   * @returns MultiKeyAccount - The newly created MultiKeyAccount.
    */
   static fromPublicKeysAndSigners(args: {
     publicKeys: PublicKey[];
@@ -102,34 +110,42 @@ export class MultiKeyAccount implements Account {
     return new MultiKeyAccount({ multiKey, signers });
   }
 
+  /**
+   * Determines if the provided account is a multi-key account.
+   *
+   * @param account - The account to check.
+   * @returns A boolean indicating whether the account is a multi-key account.
+   */
   static isMultiKeySigner(account: Account): account is MultiKeyAccount {
     return account instanceof MultiKeyAccount;
   }
 
   /**
-   * Sign a message using the account's signers.
-   * @param message the signing message, as binary input
-   * @return the AccountAuthenticator containing the signature, together with the account's public key
+   * Sign a message using the account's signers and return an AccountAuthenticator containing the signature along with the
+   * account's public key.
+   * @param message - The signing message, represented as binary input in hexadecimal format.
+   * @returns An instance of AccountAuthenticatorMultiKey that includes the signature and the public key.
    */
   signWithAuthenticator(message: HexInput): AccountAuthenticatorMultiKey {
     return new AccountAuthenticatorMultiKey(this.publicKey, this.sign(message));
   }
 
   /**
-   * Sign a transaction using the account's signers.
-   * @param transaction the raw transaction
-   * @return the AccountAuthenticator containing the signature of the transaction, together with the account's public key
+   * Sign a transaction using the account's signers, returning an AccountAuthenticator that contains the signature and the
+   * account's public key.
+   * @param transaction - The raw transaction to be signed.
+   * @returns An AccountAuthenticatorMultiKey containing the signature of the transaction along with the account's public key.
    */
   signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorMultiKey {
     return new AccountAuthenticatorMultiKey(this.publicKey, this.signTransaction(transaction));
   }
 
   /**
-   * Waits for any proofs on any KeylessAccount signers to be fetched. If the proof is fetched a syncronously, call this
-   * to ensure signing with the KeylessAccount does not fail as the proof must be ready.
-   * @return
+   * Waits for any proofs on KeylessAccount signers to be fetched. This ensures that signing with the KeylessAccount does not
+   * fail due to missing proofs.
+   * @return {Promise<void>} A promise that resolves when all proofs have been fetched.
    */
-  async waitForProofFetch() {
+  async waitForProofFetch(): Promise<void> {
     const keylessSigners = this.signers.filter(
       (signer) => signer instanceof AbstractKeylessAccount,
     ) as AbstractKeylessAccount[];
@@ -138,9 +154,9 @@ export class MultiKeyAccount implements Account {
   }
 
   /**
-   * Sign the given message using the MultiKeyAccount's signers
-   * @param message in HexInput format
-   * @returns MultiKeySignature
+   * Sign the given data using the MultiKeyAccount's signers.
+   * @param data - The data to be signed in HexInput format.
+   * @returns MultiKeySignature - The resulting multi-key signature.
    */
   sign(data: HexInput): MultiKeySignature {
     const signatures = [];
@@ -151,9 +167,11 @@ export class MultiKeyAccount implements Account {
   }
 
   /**
-   * Sign the given transaction using the MultiKeyAccount's signers
-   * @param transaction the transaction to be signed
-   * @returns MultiKeySignature
+   * Sign the given transaction using the MultiKeyAccount's signers.
+   * This function aggregates signatures from all signers associated with the MultiKeyAccount.
+   *
+   * @param transaction - The transaction to be signed.
+   * @returns MultiKeySignature - An object containing the aggregated signatures and a bitmap of the signatures.
    */
   signTransaction(transaction: AnyRawTransaction): MultiKeySignature {
     const signatures = [];
@@ -164,18 +182,21 @@ export class MultiKeyAccount implements Account {
   }
 
   /**
-   * Verify the given message and signature with the public key.
+   * Verify the given message and signature with the public keys.
+   *
+   * This function checks if the provided signatures are valid for the given message using the corresponding public keys.
    *
-   * @param args.message raw message data in HexInput format
-   * @param args.signatures signed message MultiKeySignature
-   * @returns boolean
+   * @param args - The arguments for verifying the signature.
+   * @param args.message - The raw message data in HexInput format.
+   * @param args.signature - The signed message MultiKeySignature containing multiple signatures.
+   * @returns A boolean indicating whether the signatures are valid for the message.
    */
   verifySignature(args: VerifyMultiKeySignatureArgs): boolean {
     const { message, signature } = args;
-    const isSignerIndiciesSorted = this.signerIndicies.every(
+    const isSignerIndicesSorted = this.signerIndicies.every(
       (value, i) => i === 0 || value >= this.signerIndicies[i - 1],
     );
-    if (!isSignerIndiciesSorted) {
+    if (!isSignerIndicesSorted) {
       return false;
     }
     for (let i = 0; i < signature.signatures.length; i += 1) {

package/src/account/SingleKeyAccount.ts

@@ -6,20 +6,40 @@ import type { Account } from "./Account";
 import { generateSigningMessageForTransaction } from "../transactions/transactionBuilder/signingMessage";
 import { AnyRawTransaction } from "../transactions/types";
 
+/**
+ * Arguments required to create a single key signer.
+ *
+ * @param privateKey - The private key used for signing.
+ * @param address - Optional account address associated with the signer.
+ */
 export interface SingleKeySignerConstructorArgs {
   privateKey: PrivateKey;
   address?: AccountAddressInput;
 }
 
+/**
+ * Arguments for generating a single key signer.
+ *
+ * @param scheme - The signing scheme to be used.
+ */
 export interface SingleKeySignerGenerateArgs {
   scheme?: SigningSchemeInput;
 }
 
+/**
+ * The arguments for generating a single key signer from a specified derivation path.
+ */
 export type SingleKeySignerFromDerivationPathArgs = SingleKeySignerGenerateArgs & {
   path: string;
   mnemonic: string;
 };
 
+/**
+ * Arguments required to verify a single key signature for a given message.
+ *
+ * @param message - The message to be verified, represented in hexadecimal format.
+ * @param signature - The signature that corresponds to the message.
+ */
 export interface VerifySingleKeySignatureArgs {
   message: HexInput;
   signature: AnySignature;
@@ -27,7 +47,7 @@ export interface VerifySingleKeySignatureArgs {
 
 /**
  * Signer implementation for the SingleKey authentication scheme.
- * This extends a SingleKeyAccount by adding signing capabilities through a valid private key.
+ * This class 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.
@@ -44,8 +64,14 @@ export class SingleKeyAccount implements Account {
 
   readonly signingScheme = SigningScheme.SingleKey;
 
-  // region Constructors
-
+  /**
+   * Creates an instance of the SingleKeySigner using the provided private key and address.
+   * This allows for signing transactions and messages with the specified private key.
+   *
+   * @param args - The constructor arguments for initializing the SingleKeySigner.
+   * @param args.privateKey - The private key used for signing.
+   * @param args.address - The optional account address; if not provided, it will derive the address from the public key.
+   */
   constructor(args: SingleKeySignerConstructorArgs) {
     const { privateKey, address } = args;
     this.privateKey = privateKey;
@@ -54,9 +80,13 @@ export class SingleKeyAccount implements Account {
   }
 
   /**
-   * Derives an account from a randomly generated private key.
-   * Default generation is using an Ed25519 key
-   * @returns Account with the given signature scheme
+   * Derives an account from a randomly generated private key based on the specified signing scheme.
+   * The default generation scheme is Ed25519, but it can also support Secp256k1Ecdsa.
+   *
+   * @param args - The arguments for generating the account.
+   * @param args.scheme - The signing scheme to use for generating the private key. Defaults to SigningSchemeInput.Ed25519.
+   * @returns An account with the generated private key based on the specified signing scheme.
+   * @throws Error if an unsupported signature scheme is provided.
    */
   static generate(args: SingleKeySignerGenerateArgs = {}) {
     const { scheme = SigningSchemeInput.Ed25519 } = args;
@@ -75,14 +105,15 @@ export class SingleKeyAccount implements Account {
   }
 
   /**
-   * Derives an account with bip44 path and mnemonics,
-   * Default to using an Ed25519 signature scheme.
+   * Derives an account using a specified BIP44 path and mnemonic seed phrase, defaulting to the Ed25519 signature scheme.
+   * This function allows you to create a single key account based on the provided derivation path and mnemonic.
    *
-   * @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
+   * @param args - The arguments for deriving the account.
+   * @param args.scheme - The signature scheme to derive the private key with. Defaults to Ed25519.
+   * @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
+   * @param args.mnemonic - The mnemonic seed phrase of the account.
    */
   static fromDerivationPath(args: SingleKeySignerFromDerivationPathArgs) {
     const { scheme = SigningSchemeInput.Ed25519, path, mnemonic } = args;
@@ -100,25 +131,23 @@ export class SingleKeyAccount implements Account {
     return new SingleKeyAccount({ privateKey });
   }
 
-  // endregion
-
-  // region Account
-
   /**
    * Verify the given message and signature with the public key.
    *
-   * @param args.message raw message data in HexInput format
-   * @param args.signature signed message Signature
-   * @returns
+   * @param args - The arguments for verifying the signature.
+   * @param args.message - The raw message data in HexInput format.
+   * @param args.signature - The signed message signature.
+   * @returns A boolean indicating whether the signature is valid.
    */
   verifySignature(args: VerifySingleKeySignatureArgs): boolean {
     return this.publicKey.verifySignature(args);
   }
 
   /**
-   * Sign a message using the account's private key.
-   * @param message the signing message, as binary input
-   * @return the AccountAuthenticator containing the signature, together with the account's public key
+   * Sign a message using the account's private key and return an AccountAuthenticator containing the signature along with the
+   * account's public key.
+   * @param message - The signing message, represented as binary input in hexadecimal format.
+   * @returns An instance of AccountAuthenticatorSingleKey containing the signature and the public key.
    */
   signWithAuthenticator(message: HexInput): AccountAuthenticatorSingleKey {
     return new AccountAuthenticatorSingleKey(this.publicKey, this.sign(message));
@@ -126,8 +155,9 @@ export class SingleKeyAccount implements Account {
 
   /**
    * Sign a transaction using the account's private key.
-   * @param transaction the raw transaction
-   * @return the AccountAuthenticator containing the signature of the transaction, together with the account's public key
+   * This function returns an AccountAuthenticator that contains the signature of the transaction along with the account's public key.
+   * @param transaction - The raw transaction to be signed.
+   * @returns An AccountAuthenticatorSingleKey containing the signature of the transaction and the account's public key.
    */
   signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorSingleKey {
     return new AccountAuthenticatorSingleKey(this.publicKey, this.signTransaction(transaction));
@@ -135,8 +165,8 @@ export class SingleKeyAccount implements Account {
 
   /**
    * Sign the given message using the account's private key.
-   * @param message in HexInput format
-   * @returns Signature
+   * @param message - The message to be signed in HexInput format.
+   * @returns A new AnySignature containing the signature of the message.
    */
   sign(message: HexInput): AnySignature {
     return new AnySignature(this.privateKey.sign(message));
@@ -144,8 +174,10 @@ export class SingleKeyAccount implements Account {
 
   /**
    * Sign the given transaction using the account's private key.
-   * @param transaction the transaction to be signed
-   * @returns Signature
+   * This function generates a signing message for the transaction and then signs it.
+   *
+   * @param transaction - The transaction to be signed.
+   * @returns Signature - The resulting signature for the signed transaction.
    */
   signTransaction(transaction: AnyRawTransaction): AnySignature {
     return this.sign(generateSigningMessageForTransaction(transaction));