@aptos-labs/ts-sdk 1.33.2 → 1.35.0

package/src/account/AbstractedAccount.ts

@@ -0,0 +1,111 @@
+import { sha3_256 } from "@noble/hashes/sha3";
+import { AccountAddress } from "../core";
+import { AbstractPublicKey, AbstractSignature } from "../core/crypto/abstraction";
+import { SigningScheme, HexInput } from "../types";
+import { Account } from "./Account";
+import { AnyRawTransaction } from "../transactions/types";
+import { generateSigningMessageForTransaction } from "../transactions/transactionBuilder/signingMessage";
+import { AccountAuthenticatorAbstraction } from "../transactions/authenticator/account";
+import { Ed25519Account } from "./Ed25519Account";
+import { Serializer } from "../bcs/serializer";
+import { isValidFunctionInfo } from "../utils/helpers";
+
+type AbstractedAccountConstructorArgs = {
+  /**
+   * The account address of the account.
+   */
+  accountAddress: AccountAddress;
+  /**
+   * The signer function signs transactions and returns the `authenticator` bytes in the `AbstractionAuthData`.
+   *
+   * @param digest - The SHA256 hash of the transaction signing message
+   * @returns The `authenticator` bytes that can be used to verify the signature.
+   */
+  signer: (digest: HexInput) => HexInput;
+  /**
+   * The authentication function that will be used to verify the signature.
+   *
+   * @example
+   * ```ts
+   * const authenticationFunction = `${accountAddress}::permissioned_delegation::authenticate`;
+   * ```
+   */
+  authenticationFunction: string;
+};
+
+export class AbstractedAccount extends Account {
+  public readonly publicKey: AbstractPublicKey;
+
+  readonly accountAddress: AccountAddress;
+
+  readonly authenticationFunction: string;
+
+  readonly signingScheme = SigningScheme.SingleKey;
+
+  constructor({ signer, accountAddress, authenticationFunction }: AbstractedAccountConstructorArgs) {
+    super();
+
+    if (!isValidFunctionInfo(authenticationFunction)) {
+      throw new Error(`Invalid authentication function ${authenticationFunction} passed into AbstractedAccount`);
+    }
+
+    this.authenticationFunction = authenticationFunction;
+    this.accountAddress = accountAddress;
+    this.publicKey = new AbstractPublicKey(this.accountAddress);
+    this.sign = (digest: HexInput) => new AbstractSignature(signer(digest));
+  }
+
+  /**
+   * Creates an `AbstractedAccount` from an `Ed25519Account` that has a permissioned signer function and
+   * using the `0x1::permissioned_delegation::authenticate` function to verify the signature.
+   *
+   * @param signer - The `Ed25519Account` that can be used to sign permissioned transactions.
+   * @returns The `AbstractedAccount`
+   */
+  public static fromPermissionedSigner({
+    signer,
+    accountAddress,
+  }: {
+    signer: Ed25519Account;
+    accountAddress?: AccountAddress;
+  }) {
+    return new AbstractedAccount({
+      signer: (digest: HexInput) => {
+        const serializer = new Serializer();
+        signer.publicKey.serialize(serializer);
+        signer.sign(digest).serialize(serializer);
+        return serializer.toUint8Array();
+      },
+      accountAddress: accountAddress ?? signer.accountAddress,
+      authenticationFunction: "0x1::permissioned_delegation::authenticate",
+    });
+  }
+
+  signWithAuthenticator(message: HexInput): AccountAuthenticatorAbstraction {
+    return new AccountAuthenticatorAbstraction(
+      this.authenticationFunction,
+      sha3_256(message),
+      this.sign(sha3_256(message)).toUint8Array(),
+    );
+  }
+
+  signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorAbstraction {
+    return this.signWithAuthenticator(generateSigningMessageForTransaction(transaction));
+  }
+
+  sign: (message: HexInput) => AbstractSignature;
+
+  signTransaction(transaction: AnyRawTransaction): AbstractSignature {
+    return this.sign(generateSigningMessageForTransaction(transaction));
+  }
+
+  /**
+   * Update the signer function for the account. This can be done after asynchronous operations are complete
+   * to update the context of the signer function.
+   *
+   * @param signer - The new signer function to use for the account.
+   */
+  public setSigner(signer: (digest: HexInput) => HexInput): void {
+    this.sign = (digest: HexInput) => new AbstractSignature(signer(digest));
+  }
+}

package/src/account/MultiEd25519Account.ts

@@ -0,0 +1,154 @@
+import { AccountAddress, AccountAddressInput } from "../core/accountAddress";
+import { Ed25519PrivateKey } from "../core/crypto";
+import { MultiEd25519PublicKey, MultiEd25519Signature } from "../core/crypto/multiEd25519";
+import { AccountAuthenticatorMultiEd25519 } from "../transactions/authenticator/account";
+import { generateSigningMessageForTransaction } from "../transactions/transactionBuilder/signingMessage";
+import { AnyRawTransaction } from "../transactions/types";
+import { HexInput, SigningScheme } from "../types";
+import type { Account } from "./Account";
+
+export interface MultiEd25519SignerConstructorArgs {
+  publicKey: MultiEd25519PublicKey;
+  signers: Ed25519PrivateKey[];
+  address?: AccountAddressInput;
+}
+
+export interface VerifyMultiEd25519SignatureArgs {
+  message: HexInput;
+  signature: MultiEd25519Signature;
+}
+
+/**
+ * Signer implementation for the Multi-Ed25519 authentication scheme.
+ *
+ * Note: This authentication scheme is a legacy authentication scheme.  Prefer using MultiKeyAccounts as a
+ * MultiKeyAccount can support any type of signer, not just Ed25519.  Generating a signer instance does not
+ * create the account on-chain.
+ */
+export class MultiEd25519Account implements Account {
+  readonly publicKey: MultiEd25519PublicKey;
+
+  readonly accountAddress: AccountAddress;
+
+  readonly signingScheme = SigningScheme.MultiEd25519;
+
+  /**
+   * The signers used to sign messages.  These signers should correspond to public keys in the
+   * MultiEd25519Account.  The number of signers should be equal to this.publicKey.threshold.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  readonly signers: Ed25519PrivateKey[];
+
+  /**
+   * 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.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  readonly signerIndices: number[];
+
+  readonly signaturesBitmap: Uint8Array;
+
+  // region Constructors
+
+  constructor(args: MultiEd25519SignerConstructorArgs) {
+    const { signers, publicKey, address } = args;
+    this.publicKey = publicKey;
+    this.accountAddress = address ? AccountAddress.from(address) : this.publicKey.authKey().derivedAddress();
+
+    if (publicKey.threshold > signers.length) {
+      throw new Error(
+        // eslint-disable-next-line max-len
+        `Not enough signers provided to satisfy the required signatures. Need ${publicKey.threshold} signers, but only ${signers.length} provided`,
+      );
+    } else if (publicKey.threshold < signers.length) {
+      throw new Error(
+        // eslint-disable-next-line max-len
+        `More signers provided than required. Need ${publicKey.threshold} signers, but ${signers.length} provided`,
+      );
+    }
+
+    // For each signer, find its corresponding position in the public keys array
+    const bitPositions: number[] = [];
+    for (const signer of signers) {
+      bitPositions.push(this.publicKey.getIndex(signer.publicKey()));
+    }
+
+    // Create pairs of [signer, position] and sort them by position
+    // This sorting is critical because:
+    // 1. The on-chain verification expects signatures to be in ascending order by bit position
+    // 2. The bitmap must match the order of signatures when verifying
+    const signersAndBitPosition: [Ed25519PrivateKey, number][] = signers.map((signer, index) => [
+      signer,
+      bitPositions[index],
+    ]);
+    signersAndBitPosition.sort((a, b) => a[1] - b[1]);
+
+    // Extract the sorted signers and their positions into separate arrays
+    this.signers = signersAndBitPosition.map((value) => value[0]);
+    this.signerIndices = signersAndBitPosition.map((value) => value[1]);
+
+    // Create a bitmap representing which public keys from the MultiEd25519PublicKey are being used
+    // This bitmap is used during signature verification to identify which public keys
+    // should be used to verify each signature
+    this.signaturesBitmap = this.publicKey.createBitmap({ bits: bitPositions });
+  }
+
+  // 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
+   */
+  verifySignature(args: VerifyMultiEd25519SignatureArgs): boolean {
+    return this.publicKey.verifySignature(args);
+  }
+
+  /**
+   * Sign a message using the account's Ed25519 private key.
+   * @param message the signing message, as binary input
+   * @return the AccountAuthenticator containing the signature, together with the account's public key
+   */
+  signWithAuthenticator(message: HexInput): AccountAuthenticatorMultiEd25519 {
+    return new AccountAuthenticatorMultiEd25519(this.publicKey, this.sign(message));
+  }
+
+  /**
+   * Sign a transaction using the account's Ed25519 private keys.
+   * @param transaction the raw transaction
+   * @return the AccountAuthenticator containing the signature of the transaction, together with the account's public key
+   */
+  signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorMultiEd25519 {
+    return new AccountAuthenticatorMultiEd25519(this.publicKey, this.signTransaction(transaction));
+  }
+
+  /**
+   * Sign the given message using the account's Ed25519 private keys.
+   * @param message in HexInput format
+   * @returns MultiEd25519Signature
+   */
+  sign(message: HexInput): MultiEd25519Signature {
+    const signatures = [];
+    for (const signer of this.signers) {
+      signatures.push(signer.sign(message));
+    }
+    return new MultiEd25519Signature({ signatures, bitmap: this.signaturesBitmap });
+  }
+
+  /**
+   * Sign the given transaction using the available signing capabilities.
+   * @param transaction the transaction to be signed
+   * @returns Signature
+   */
+  signTransaction(transaction: AnyRawTransaction): MultiEd25519Signature {
+    return this.sign(generateSigningMessageForTransaction(transaction));
+  }
+
+  // endregion
+}

package/src/account/MultiKeyAccount.ts

@@ -59,8 +59,7 @@ export class MultiKeyAccount implements Account, KeylessSigner {
 
   /**
    * The signers used to sign messages.  These signers should correspond to public keys in the
-   * MultiKeyAccount's public key.  The number of signers should be equal or greater
-   * than this.publicKey.signaturesRequired
+   * MultiKeyAccount's public key.  The number of signers should be equal to this.publicKey.signaturesRequired.
    * @group Implementation
    * @category Account (On-Chain Model)
    */

package/src/account/index.ts

@@ -6,4 +6,6 @@ export * from "./KeylessAccount";
 export * from "./AbstractKeylessAccount";
 export * from "./FederatedKeylessAccount";
 export * from "./MultiKeyAccount";
+export * from "./MultiEd25519Account";
 export * from "./AccountUtils";
+export * from "./AbstractedAccount";

package/src/api/account/abstraction.ts

@@ -0,0 +1,239 @@
+import { AccountAddress, AccountAddressInput } from "../../core";
+import {
+  addAuthenticationFunctionTransaction,
+  removeAuthenticationFunctionTransaction,
+  removeDispatchableAuthenticatorTransaction,
+} from "../../internal/abstraction";
+import { view } from "../../internal/view";
+import { InputGenerateTransactionOptions, TypeTagAddress } from "../../transactions";
+import { MoveFunctionId } from "../../types";
+import { getFunctionParts } from "../../utils/helpers";
+import { AptosConfig } from "../aptosConfig";
+
+export class AccountAbstraction {
+  constructor(readonly config: AptosConfig) {}
+
+  /**
+   * Adds a dispatchable authentication function to the account.
+   *
+   * @example
+   * ```ts
+   * const txn = await aptos.abstraction.addAuthenticationFunctionTransaction({
+   *   accountAddress: alice.accountAddress,
+   *   authenticationFunction: `${alice.accountAddress}::any_authenticator::authenticate`,
+   * });
+   *
+   * const txn =  await aptos.signAndSubmitTransaction({ signer: alice, transaction});
+   * await aptos.waitForTransaction({ transactionHash: txn.hash });
+   * ```
+   *
+   * @param args.accountAddress - The account to add the authentication function to.
+   * @param args.authenticationFunction - The authentication function info to add.
+   * @param args.options - The options for the transaction.
+   * @returns A transaction to add the authentication function to the account.
+   */
+  public async addAuthenticationFunctionTransaction(args: {
+    accountAddress: AccountAddressInput;
+    authenticationFunction: string;
+    options?: InputGenerateTransactionOptions;
+  }) {
+    const { accountAddress, authenticationFunction, options } = args;
+    return addAuthenticationFunctionTransaction({
+      aptosConfig: this.config,
+      authenticationFunction,
+      sender: accountAddress,
+      options,
+    });
+  }
+
+  /**
+   * Removes a dispatchable authentication function from the account.
+   *
+   * @example
+   * ```ts
+   * const txn = await aptos.abstraction.removeAuthenticationFunctionTransaction({
+   *   accountAddress: alice.accountAddress,
+   *   authenticationFunction: `${alice.accountAddress}::any_authenticator::authenticate`,
+   * });
+   *
+   * const txn = await aptos.signAndSubmitTransaction({ signer: alice, transaction: txn });
+   * await aptos.waitForTransaction({ transactionHash: txn.hash });
+   * ```
+   *
+   * @param args.accountAddress - The account to remove the authentication function from.
+   * @param args.authenticationFunction - The authentication function info to remove.
+   * @param args.options - The options for the transaction.
+   * @returns A transaction to remove the authentication function from the account.
+   */
+  public async removeAuthenticationFunctionTransaction(args: {
+    accountAddress: AccountAddressInput;
+    authenticationFunction: string;
+    options?: InputGenerateTransactionOptions;
+  }) {
+    const { accountAddress, authenticationFunction, options } = args;
+    return removeAuthenticationFunctionTransaction({
+      aptosConfig: this.config,
+      sender: accountAddress,
+      authenticationFunction,
+      options,
+    });
+  }
+
+  /**
+   * Removes a dispatchable authenticator from the account.
+   *
+   * @example
+   * ```ts
+   * const txn = await aptos.abstraction.removeDispatchableAuthenticatorTransaction({
+   *   accountAddress: alice.accountAddress,
+   * });
+   *
+   * const txn = await aptos.signAndSubmitTransaction({ signer: alice, transaction: txn });
+   * await aptos.waitForTransaction({ transactionHash: txn.hash });
+   * ```
+   *
+   * @param args.accountAddress - The account to remove the authenticator from.
+   * @param args.options - The options for the transaction.
+   * @returns A transaction to remove the authenticator from the account.
+   */
+  public async removeDispatchableAuthenticatorTransaction(args: {
+    accountAddress: AccountAddressInput;
+    options?: InputGenerateTransactionOptions;
+  }) {
+    const { accountAddress, options } = args;
+    return removeDispatchableAuthenticatorTransaction({ aptosConfig: this.config, sender: accountAddress, options });
+  }
+
+  /**
+   * Gets the dispatchable authentication function for the account.
+   *
+   * @example
+   * ```ts
+   * const functionInfos = await aptos.abstraction.getAuthenticationFunction({
+   *   accountAddress: alice.accountAddress,
+   * });
+   *
+   * if (functionInfos) {
+   *   console.log(`Account ${alice.accountAddress.toString()} is using account abstraction!`);
+   * } else {
+   *   console.log(`Account ${alice.accountAddress.toString()} is not using account abstraction.`);
+   * }
+   * ```
+   *
+   * @param args.accountAddress - The account to get the dispatchable authentication function for.
+   * @returns The dispatchable authentication function for the account.
+   */
+  public async getAuthenticationFunction(args: { accountAddress: AccountAddressInput }) {
+    const { accountAddress } = args;
+    const [{ vec: functionInfoOption }] = await view<
+      [{ vec: { function_name: string; module_name: string; module_address: string }[][] }]
+    >({
+      aptosConfig: this.config,
+      payload: {
+        function: "0x1::account_abstraction::dispatchable_authenticator",
+        functionArguments: [AccountAddress.from(accountAddress)],
+        abi: { typeParameters: [], parameters: [new TypeTagAddress()], returnTypes: [] },
+      },
+    });
+
+    if (functionInfoOption.length === 0) return undefined;
+
+    return functionInfoOption[0].map((functionInfo) => ({
+      moduleAddress: AccountAddress.fromString(functionInfo.module_address),
+      moduleName: functionInfo.module_name,
+      functionName: functionInfo.function_name,
+    }));
+  }
+
+  /**
+   * Will return true if the account is abstracted, otherwise false.
+   *
+   * @example
+   * ```ts
+   * const isAccountAbstractionEnabled = await aptos.abstraction.isAccountAbstractionEnabled({
+   *   accountAddress: alice.accountAddress,
+   *   authenticationFunction: `${alice.accountAddress}::any_authenticator::authenticate`,
+   * });
+   * if (isAccountAbstractionEnabled) {
+   *   console.log(`Account ${alice.accountAddress.toString()} is using account abstraction!`);
+   * } else {
+   *   console.log(`Account ${alice.accountAddress.toString()} is not using account abstraction.`);
+   * }
+   * ```
+   *
+   * @param args.accountAddress - The account to check.
+   * @returns Whether the account is abstracted.
+   */
+  public isAccountAbstractionEnabled = async (args: {
+    accountAddress: AccountAddressInput;
+    authenticationFunction: string;
+  }) => {
+    const functionInfos = await this.getAuthenticationFunction(args);
+    const { moduleAddress, moduleName, functionName } = getFunctionParts(args.authenticationFunction as MoveFunctionId);
+    return (
+      functionInfos?.some(
+        (functionInfo) =>
+          AccountAddress.fromString(moduleAddress).equals(functionInfo.moduleAddress) &&
+          moduleName === functionInfo.moduleName &&
+          functionName === functionInfo.functionName,
+      ) ?? false
+    );
+  };
+
+  /**
+   * Creates a transaction to enable account abstraction with the given authentication function.
+   *
+   * @example
+   * ```ts
+   * const txn = await aptos.abstraction.enableAccountAbstractionTransaction({
+   *   accountAddress: alice.accountAddress,
+   *   authenticationFunction: `{alice.accountAddress}::any_authenticator::authenticate`,
+   * });
+   *
+   * const txn = await aptos.signAndSubmitTransaction({ signer: alice, transaction: txn });
+   * await aptos.waitForTransaction({ transactionHash: txn.hash });
+   * ```
+   *
+   * @param args.accountAddress - The account to enable account abstraction for.
+   * @param args.authenticationFunction - The authentication function info to use.
+   * @param args.options - The options for the transaction.
+   * @returns A transaction to enable account abstraction for the account.
+   */
+  public enableAccountAbstractionTransaction = this.addAuthenticationFunctionTransaction;
+
+  /**
+   * Creates a transaction to disable account abstraction. If an authentication function is provided, it will specify to
+   * remove the authentication function.
+   *
+   * @example
+   * ```ts
+   * const txn = await aptos.abstraction.disableAccountAbstractionTransaction({
+   *   accountAddress: alice.accountAddress,
+   *   authenticationFunction: `${alice.accountAddress}::any_authenticator::authenticate`,
+   * });
+   *
+   * const txn = await aptos.signAndSubmitTransaction({ signer: alice, transaction: txn });
+   * await aptos.waitForTransaction({ transactionHash: txn.hash });
+   * ```
+   *
+   * @param args.accountAddress - The account to disable account abstraction for.
+   * @param args.authenticationFunction - The authentication function info to remove.
+   * @param args.options - The options for the transaction.
+   * @returns A transaction to disable account abstraction for the account.
+   */
+  public disableAccountAbstractionTransaction = async (args: {
+    accountAddress: AccountAddressInput;
+    authenticationFunction?: string;
+    options?: InputGenerateTransactionOptions;
+  }) => {
+    const { accountAddress, authenticationFunction, options } = args;
+    if (authenticationFunction) {
+      return this.removeAuthenticationFunctionTransaction({
+        accountAddress,
+        authenticationFunction,
+        options,
+      });
+    }
+    return this.removeDispatchableAuthenticatorTransaction({ accountAddress, options });
+  };
+}

package/src/api/account.ts

@@ -47,12 +47,15 @@ import { CurrentFungibleAssetBalancesBoolExp } from "../types/generated/types";
 import { view } from "../internal/view";
 import { isEncodedStruct, parseEncodedStruct } from "../utils";
 import { memoizeAsync } from "../utils/memoize";
+import { AccountAbstraction } from "./account/abstraction";
 
 /**
  * A class to query all `Account` related queries on Aptos.
  * @group Account
  */
 export class Account {
+  abstraction: AccountAbstraction;
+
   /**
    * Creates an instance of the Aptos client with the provided configuration.
    *
@@ -73,7 +76,9 @@ export class Account {
    * ```
    * @group Account
    */
-  constructor(readonly config: AptosConfig) {}
+  constructor(readonly config: AptosConfig) {
+    this.abstraction = new AccountAbstraction(config);
+  }
 
   /**
    * Queries the current state for an Aptos account given its account address.
@@ -653,7 +658,7 @@ export class Account {
   }
 
   /**
-   * Retrieves the current amount of APT for a specified account.
+   * Retrieves the current amount of APT for a specified account. If the account does not exist, it will return 0.
    *
    * @param args The arguments for the account query.
    * @param args.accountAddress The account address for which to retrieve the APT amount.

package/src/api/aptos.ts

@@ -15,6 +15,8 @@ import { Transaction } from "./transaction";
 import { Table } from "./table";
 import { Keyless } from "./keyless";
 import { AptosObject } from "./object";
+import { AccountAbstraction } from "./account/abstraction";
+import { Experimental } from "./experimental";
 
 /**
  * The main entry point for interacting with the Aptos APIs,
@@ -54,6 +56,8 @@ export class Aptos {
 
   readonly event: Event;
 
+  readonly experimental: Experimental;
+
   readonly faucet: Faucet;
 
   readonly fungibleAsset: FungibleAsset;
@@ -94,10 +98,12 @@ export class Aptos {
   constructor(settings?: AptosConfig) {
     this.config = new AptosConfig(settings);
     this.account = new Account(this.config);
+    this.abstraction = new AccountAbstraction(this.config);
     this.ans = new ANS(this.config);
     this.coin = new Coin(this.config);
     this.digitalAsset = new DigitalAsset(this.config);
     this.event = new Event(this.config);
+    this.experimental = new Experimental(this.config);
     this.faucet = new Faucet(this.config);
     this.fungibleAsset = new FungibleAsset(this.config);
     this.general = new General(this.config);
@@ -117,6 +123,7 @@ export interface Aptos
     Coin,
     DigitalAsset,
     Event,
+    Experimental,
     Faucet,
     FungibleAsset,
     General,
@@ -149,10 +156,12 @@ function applyMixin(targetClass: any, baseClass: any, baseClassProp: string) {
 }
 
 applyMixin(Aptos, Account, "account");
+applyMixin(Aptos, AccountAbstraction, "abstraction");
 applyMixin(Aptos, ANS, "ans");
 applyMixin(Aptos, Coin, "coin");
 applyMixin(Aptos, DigitalAsset, "digitalAsset");
 applyMixin(Aptos, Event, "event");
+applyMixin(Aptos, Experimental, "experimental");
 applyMixin(Aptos, Faucet, "faucet");
 applyMixin(Aptos, FungibleAsset, "fungibleAsset");
 applyMixin(Aptos, General, "general");

package/src/api/aptosConfig.ts

@@ -1,7 +1,7 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-import aptosClient from "@aptos-labs/aptos-client";
+import aptosClient, { bcsRequest } from "@aptos-labs/aptos-client";
 import { AptosSettings, ClientConfig, Client, FullNodeConfig, IndexerConfig, FaucetConfig } from "../types";
 import {
   NetworkToNodeAPI,
@@ -140,7 +140,7 @@ export class AptosConfig {
     this.pepper = settings?.pepper;
     this.prover = settings?.prover;
     this.indexer = settings?.indexer;
-    this.client = settings?.client ?? { provider: aptosClient };
+    this.client = settings?.client ?? { provider: aptosClient, binaryProvider: bcsRequest };
     this.clientConfig = settings?.clientConfig ?? {};
     this.fullnodeConfig = settings?.fullnodeConfig ?? {};
     this.indexerConfig = settings?.indexerConfig ?? {};