Add new account derivation APIs (#635)

* Add account discovery APIs

* update

* add sindling for single sender

* remove test script

* fix lint

* remove unused func

* fmt

* Update account recovery API

* remove signatures query

* remove pubkey for account address

* Update account api options

* update CL

* lower coverage threshold for functions

* update test

* Add e2e tests and txnoptions for rotateAuthKey

* revert jest

* Add comments

* Update funcdoc

* fix origin method

* add testcases

* fmt

* fmt

* update API to have lastTxnVersion

* update error message

* reomve space

* skip tests

* use object look up to check account existance

Author: heliuchuan

CHANGELOG.md

@@ -3,6 +3,8 @@
 All notable changes to the Aptos TypeScript SDK will be captured in this file. This changelog is written by hand for now. It adheres to the format set out by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## Unreleased
+- Add account derivation APIs, `getAccountsForPublicKey` and `deriveOwnedAccountsFromSigner` which handle multi-key accounts and key rotations
+- Update the deprecated function deriveAccountFromPrivateKey to use the new account derivation API
 
 # 3.0.0 (2025-06-26)
 - Make the default max gas amount and exipry time from now values for transaction generation configurable.

src/account/FederatedKeylessAccount.ts

@@ -140,6 +140,7 @@ export class FederatedKeylessAccount extends AbstractKeylessAccount {
     uidKey?: string;
     proofFetchCallback?: ProofFetchCallback;
     verificationKey?: Groth16VerificationKey;
+    verificationKeyHash?: Uint8Array;
   }): FederatedKeylessAccount {
     const {
       address,
@@ -151,8 +152,13 @@ export class FederatedKeylessAccount extends AbstractKeylessAccount {
       uidKey = "sub",
       proofFetchCallback,
       verificationKey,
+      verificationKeyHash,
     } = args;
 
+    if (verificationKeyHash && verificationKey) {
+      throw new Error("Cannot provide both verificationKey and verificationKeyHash");
+    }
+
     const { iss, aud, uidVal } = getIssAudAndUidVal({ jwt, uidKey });
     return new FederatedKeylessAccount({
       address,
@@ -166,7 +172,7 @@ export class FederatedKeylessAccount extends AbstractKeylessAccount {
       jwkAddress: AccountAddress.from(jwkAddress),
       jwt,
       proofFetchCallback,
-      verificationKeyHash: verificationKey ? verificationKey.hash() : undefined,
+      verificationKeyHash: verificationKeyHash ?? (verificationKey ? verificationKey.hash() : undefined),
     });
   }
 }

src/account/KeylessAccount.ts

@@ -143,8 +143,23 @@ export class KeylessAccount extends AbstractKeylessAccount {
     uidKey?: string;
     proofFetchCallback?: ProofFetchCallback;
     verificationKey?: Groth16VerificationKey;
+    verificationKeyHash?: Uint8Array;
   }): KeylessAccount {
-    const { address, proof, jwt, ephemeralKeyPair, pepper, uidKey = "sub", proofFetchCallback, verificationKey } = args;
+    const {
+      address,
+      proof,
+      jwt,
+      ephemeralKeyPair,
+      pepper,
+      uidKey = "sub",
+      proofFetchCallback,
+      verificationKey,
+      verificationKeyHash,
+    } = args;
+
+    if (verificationKeyHash && verificationKey) {
+      throw new Error("Cannot provide both verificationKey and verificationKeyHash");
+    }
 
     const { iss, aud, uidVal } = getIssAudAndUidVal({ jwt, uidKey });
     return new KeylessAccount({
@@ -158,7 +173,7 @@ export class KeylessAccount extends AbstractKeylessAccount {
       pepper,
       jwt,
       proofFetchCallback,
-      verificationKeyHash: verificationKey ? verificationKey.hash() : undefined,
+      verificationKeyHash: verificationKeyHash ?? (verificationKey ? verificationKey.hash() : undefined),
     });
   }
 }

src/api/account.ts

@@ -2,7 +2,13 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { Account as AccountModule } from "../account";
-import { AccountAddress, PrivateKey, AccountAddressInput, createObjectAddress } from "../core";
+import {
+  AccountAddress,
+  AccountAddressInput,
+  createObjectAddress,
+  BaseAccountPublicKey,
+  PrivateKeyInput,
+} from "../core";
 import {
   AccountData,
   AnyNumber,
@@ -31,6 +37,7 @@ import {
   getAccountOwnedObjects,
   getAccountOwnedTokens,
   getAccountOwnedTokensFromCollectionAddress,
+  getAccountsForPublicKey,
   getAccountTokensCount,
   getAccountTransactionsCount,
   getInfo,
@@ -42,6 +49,8 @@ import {
   getResourcesPage,
   getTransactions,
   lookupOriginalAccountAddress,
+  deriveOwnedAccountsFromSigner,
+  AccountInfo,
 } from "../internal/account";
 import { APTOS_COIN, APTOS_FA, ProcessorType } from "../utils/const";
 import { AptosConfig } from "./aptosConfig";
@@ -977,7 +986,131 @@ export class Account {
    * @group Account
    * @deprecated Note that more inspection is needed by the user to determine which account exists on-chain
    */
-  async deriveAccountFromPrivateKey(args: { privateKey: PrivateKey }): Promise<AccountModule> {
+  async deriveAccountFromPrivateKey(args: {
+    privateKey: PrivateKeyInput;
+    minimumLedgerVersion?: AnyNumber;
+    options?: {
+      throwIfNoAccountFound?: boolean;
+    };
+  }): Promise<AccountModule> {
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args.minimumLedgerVersion,
+      processorType: ProcessorType.ACCOUNT_RESTORATION_PROCESSOR,
+    });
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args.minimumLedgerVersion,
+      processorType: ProcessorType.OBJECT_PROCESSOR,
+    });
     return deriveAccountFromPrivateKey({ aptosConfig: this.config, ...args });
   }
+
+  /**
+   * Derives all accounts owned by a signer. This function takes a signer (either an Account or PrivateKey)
+   * and returns all accounts that can be derived from it, ordered by the most recently used account first.
+   *
+   * Note, this function will not return accounts that require more than one signer to be used.
+   *
+   * @param args - The arguments for deriving owned accounts
+   * @param args.signer - The signer to derive accounts from (Account or PrivateKey)
+   * @param args.minimumLedgerVersion - The minimum ledger version to wait for before querying
+   * @param args.options.includeUnverified - Whether to include unverified accounts in the results. Unverified accounts
+   * are accounts that can be authenticated with the signer, but there is no history of the signer using the account.
+   * Default is false.
+   * @param args.options.noMultiKey - If true, do not include multi-key accounts in the results. Default is false.
+   * @returns Promise resolving to an array of derived Account objects
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network, Ed25519Account } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function getOwnedAccounts() {
+   *   const signer = Ed25519Account.generate();
+   *   const accounts = await aptos.deriveOwnedAccountsFromSigner({
+   *     signer
+   *   });
+   *   const account = accounts[0];
+   *   console.log(account);
+   * }
+   * ```
+   * @group Account
+   */
+  async deriveOwnedAccountsFromSigner(args: {
+    signer: AccountModule | PrivateKeyInput;
+    minimumLedgerVersion?: AnyNumber;
+    options?: { includeUnverified?: boolean; noMultiKey?: boolean };
+  }): Promise<AccountModule[]> {
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args.minimumLedgerVersion,
+      processorType: ProcessorType.ACCOUNT_RESTORATION_PROCESSOR,
+    });
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args.minimumLedgerVersion,
+      processorType: ProcessorType.OBJECT_PROCESSOR,
+    });
+    return deriveOwnedAccountsFromSigner({ aptosConfig: this.config, ...args });
+  }
+
+  /**
+   * Gets all account info (address, account public key, last transaction version) that have are associated with a public key and **related public keys**
+   *
+   * For a given public key, it will query all multikeys that the public key is part of.  Then for the provided public key and
+   * any multikeys found in the previous step, it will query for any accounts that have an auth key that matches any of the
+   * public keys.
+   *
+   * Note: If an Ed25519PublicKey or an AnyPublicKey that wraps Ed25519PublicKey is passed in, it will query for both legacy and single singer cases.
+   *
+   * @param args - The arguments for getting accounts for a public key
+   * @param args.publicKey - The public key to look up accounts for
+   * @param args.minimumLedgerVersion - The minimum ledger version to wait for before querying
+   * @param args.options.includeUnverified - Whether to include unverified accounts in the results. Unverified accounts
+   * are accounts that can be authenticated with the signer, but there is no history of the signer using the account. Default
+   * is false.
+   * @param args.options.noMultiKey - Whether to exclude multi-key accounts in the results. Default is false.
+   * @returns Promise resolving to an array of account addresses and their associated public keys
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network, Ed25519PrivateKey } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function getAccounts() {
+   *   const privateKey = Ed25519PrivateKey.generate();
+   *   const publicKey = privateKey.publicKey();
+   *   const accounts = await aptos.getAccountsForPublicKey({
+   *     publicKey
+   *   });
+   *   console.log(accounts);
+   * }
+   * ```
+   * @group Account
+   */
+  async getAccountsForPublicKey(args: {
+    publicKey: BaseAccountPublicKey;
+    minimumLedgerVersion?: AnyNumber;
+    options?: { includeUnverified?: boolean; noMultiKey?: boolean };
+  }): Promise<AccountInfo[]> {
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args.minimumLedgerVersion,
+      processorType: ProcessorType.ACCOUNT_RESTORATION_PROCESSOR,
+    });
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args.minimumLedgerVersion,
+      processorType: ProcessorType.OBJECT_PROCESSOR,
+    });
+    return getAccountsForPublicKey({
+      aptosConfig: this.config,
+      ...args,
+    });
+  }
 }

src/api/transaction.ts

@@ -523,6 +523,7 @@ export class Transaction {
   async rotateAuthKey(
     args: {
       fromAccount: Account;
+      options?: InputGenerateTransactionOptions;
     } & (
       | { toAccount: Account; dangerouslySkipVerification?: never }
       | { toNewPrivateKey: Ed25519PrivateKey; dangerouslySkipVerification?: never }

src/core/crypto/index.ts

@@ -15,4 +15,5 @@ export * from "./publicKey";
 export * from "./secp256k1";
 export * from "./signature";
 export * from "./singleKey";
+export * from "./types";
 export * from "./deserializationUtils";

src/core/crypto/multiEd25519.ts

@@ -92,6 +92,10 @@ export class MultiEd25519PublicKey extends AbstractMultiKey {
     this.threshold = threshold;
   }
 
+  getSignaturesRequired(): number {
+    return this.threshold;
+  }
+
   // region AccountPublicKey
 
   /**
@@ -217,6 +221,28 @@ export class MultiEd25519PublicKey extends AbstractMultiKey {
     return new MultiEd25519PublicKey({ publicKeys: keys, threshold });
   }
 
+  /**
+   * Deserializes a MultiEd25519Signature from the provided deserializer.
+   * This function helps in reconstructing a MultiEd25519Signature object from its serialized byte representation.
+   *
+   * @param deserializer - The deserializer instance used to read the serialized data.
+   * @group Implementation
+   * @category Serialization
+   */
+  static deserializeWithoutLength(deserializer: Deserializer): MultiEd25519PublicKey {
+    const length = deserializer.remaining();
+    const bytes = deserializer.deserializeFixedBytes(length);
+    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 });
+  }
+
   // endregion
 
   /**

src/core/crypto/multiKey.ts

@@ -96,6 +96,8 @@ export abstract class AbstractMultiKey extends AccountPublicKey {
     }
     throw new Error(`Public key ${publicKey} not found in multi key set ${this.publicKeys}`);
   }
+
+  abstract getSignaturesRequired(): number;
 }
 
 /**
@@ -175,6 +177,10 @@ export class MultiKey extends AbstractMultiKey {
     this.signaturesRequired = signaturesRequired;
   }
 
+  getSignaturesRequired(): number {
+    return this.signaturesRequired;
+  }
+
   // endregion
 
   // region AccountPublicKey

src/core/crypto/types.ts

@@ -0,0 +1,9 @@
+import { AnyPublicKey } from "./singleKey";
+import { Ed25519PublicKey } from "./ed25519";
+import { MultiKey } from "./multiKey";
+import { MultiEd25519PublicKey } from "./multiEd25519";
+
+// This type is used to represent the base from of an account's public key.
+// These are the types of public keys that can be used to derive an account's address by appending
+// the signing scheme to the public key as bytes and hashing it.
+export type BaseAccountPublicKey = Ed25519PublicKey | AnyPublicKey | MultiKey | MultiEd25519PublicKey;