@aptos-labs/ts-sdk 1.34.0 → 1.35.0-zeta.1

package/package.json

@@ -51,7 +51,7 @@
   },
   "dependencies": {
     "@aptos-labs/aptos-cli": "^1.0.2",
-    "@aptos-labs/aptos-client": "^0.1.1",
+    "@aptos-labs/aptos-client": "^1.0.0",
     "@noble/curves": "^1.4.0",
     "@noble/hashes": "^1.4.0",
     "@scure/bip32": "^1.4.0",
@@ -97,10 +97,5 @@
     "typedoc-plugin-missing-exports": "^3.0.0",
     "typescript": "^5.6.2"
   },
-  "pnpm": {
-    "overrides": {
-      "cross-spawn": ">=7.0.5"
-    }
-  },
-  "version": "1.34.0"
+  "version": "1.35.0-zeta.1"
 }

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,5 +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.ts

@@ -1,8 +1,15 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-import { Account as AccountModule } from "../account";
-import { AccountAddress, PrivateKey, AccountAddressInput, createObjectAddress } from "../core";
+import { Account as AccountModule, EphemeralKeyPair } from "../account";
+import {
+  AccountAddress,
+  PrivateKey,
+  AccountAddressInput,
+  createObjectAddress,
+  AccountPublicKey,
+  PublicKey,
+} from "../core";
 import {
   AccountData,
   AnyNumber,
@@ -30,11 +37,13 @@ import {
   getAccountOwnedObjects,
   getAccountOwnedTokens,
   getAccountOwnedTokensFromCollectionAddress,
+  getAccountsForPublicKey,
   getAccountTokensCount,
   getAccountTransactionsCount,
   getInfo,
   getModule,
   getModules,
+  getPublicKeyFromAccountAddress,
   getResource,
   getResources,
   getTransactions,
@@ -48,6 +57,7 @@ import { view } from "../internal/view";
 import { isEncodedStruct, parseEncodedStruct } from "../utils";
 import { memoizeAsync } from "../utils/memoize";
 import { AccountAbstraction } from "./account/abstraction";
+import { DeriveKeylessAccountParams } from "../internal/keyless";
 
 /**
  * A class to query all `Account` related queries on Aptos.
@@ -658,7 +668,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.
@@ -899,4 +909,48 @@ export class Account {
   async deriveAccountFromPrivateKey(args: { privateKey: PrivateKey }): Promise<AccountModule> {
     return deriveAccountFromPrivateKey({ aptosConfig: this.config, ...args });
   }
+
+  async getPublicKeyFromAccountAddress(args: {
+    accountAddress: AccountAddressInput;
+    minimumLedgerVersion?: AnyNumber;
+  }): Promise<PublicKey> {
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args.minimumLedgerVersion,
+      processorType: ProcessorType.DEFAULT,
+    });
+    return getPublicKeyFromAccountAddress({
+      aptosConfig: this.config,
+      ...args,
+    });
+  }
+
+  async getAccountsForPublicKey(args: {
+    publicKey: AccountPublicKey;
+    minimumLedgerVersion?: AnyNumber;
+    options?: { verified?: boolean };
+  }): Promise<
+    {
+      accountAddress: AccountAddress;
+      publicKey: PublicKey;
+      verified: boolean;
+      lastTransactionVersion: number;
+    }[]
+  > {
+    await waitForIndexerOnVersion({
+      config: this.config,
+      minimumLedgerVersion: args.minimumLedgerVersion,
+      processorType: ProcessorType.DEFAULT,
+    });
+    return getAccountsForPublicKey({
+      aptosConfig: this.config,
+      ...args,
+    });
+  }
+
+  // deriveAccount(args: AccountDerivationParams | AccountDerivationParams[]): Promise<Account> {
+  //   return deriveAccount({ aptosConfig: this.config, ...args });
+  // }
 }
+
+// type AccountDerivationParams = { privateKey: PrivateKey } | DeriveKeylessAccountParams;

package/src/api/aptos.ts

@@ -16,6 +16,7 @@ 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,
@@ -55,6 +56,8 @@ export class Aptos {
 
   readonly event: Event;
 
+  readonly experimental: Experimental;
+
   readonly faucet: Faucet;
 
   readonly fungibleAsset: FungibleAsset;
@@ -100,6 +103,7 @@ export class Aptos {
     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);
@@ -119,6 +123,7 @@ export interface Aptos
     Coin,
     DigitalAsset,
     Event,
+    Experimental,
     Faucet,
     FungibleAsset,
     General,
@@ -156,6 +161,7 @@ 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 ?? {};

package/src/api/experimental.ts

@@ -0,0 +1,64 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+import { LedgerVersionArg } from "../types";
+import { AptosConfig } from "./aptosConfig";
+import { InputViewFunctionData } from "../transactions";
+import { viewBinary } from "../internal/experimental";
+
+/**
+ * A class to have experimental functionality to the SDK.  Anything used here is subject to change.
+ * @group Experimental
+ * @experimental
+ */
+export class Experimental {
+  /**
+   * Initializes a new instance of the Aptos client with the provided configuration.
+   *
+   * @param config - The configuration settings for the Aptos client.
+   * @param config.network - The network to connect to (e.g., Testnet, Mainnet).
+   * @param config.nodeUrl - The URL of the Aptos node to connect to.
+   * @param config.faucetUrl - The URL of the faucet to use for funding accounts.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a new Aptos client with Testnet configuration
+   *     const config = new AptosConfig({ network: Network.TESTNET }); // Specify your own network if needed
+   *     const aptos = new Aptos(config);
+   *
+   *     console.log("Aptos client initialized:", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   * @group Experimental
+   * @experimental
+   */
+  constructor(readonly config: AptosConfig) {}
+
+  async viewBinary(args: {
+    payload: InputViewFunctionData;
+    options?: LedgerVersionArg & { convert?: undefined };
+  }): Promise<Uint8Array>;
+  async viewBinary<T extends {}>(args: {
+    payload: InputViewFunctionData;
+    options: LedgerVersionArg & { convert: (input: Uint8Array) => T };
+  }): Promise<T>;
+
+  /**
+   * Returns BCS encoded results of the view function.  It can also convert the results to a specific type, if a
+   * converter is provided.
+   *
+   * @experimental
+   * @group Experimental
+   * @param args
+   */
+  async viewBinary<T extends {} = Uint8Array>(args: {
+    payload: InputViewFunctionData;
+    options?: LedgerVersionArg & { convert?: (input: Uint8Array) => T };
+  }): Promise<Uint8Array | T> {
+    return viewBinary<T>({ ...args, aptosConfig: this.config });
+  }
+}

package/src/api/transaction.ts

@@ -25,6 +25,8 @@ import {
   getSigningMessage,
   publicPackageTransaction,
   rotateAuthKey,
+  rotateAuthKeyToMultiEd25519,
+  rotateAuthKeyWithVerificationTransaction,
   signAndSubmitAsFeePayer,
   signAndSubmitTransaction,
   signAsFeePayer,
@@ -36,13 +38,14 @@ import {
   InputGenerateTransactionOptions,
   InputGenerateTransactionPayloadData,
 } from "../transactions";
-import { AccountAddressInput, PrivateKeyInput } from "../core";
+import { AccountAddressInput, Ed25519PrivateKey } from "../core";
 import { Account } from "../account";
 import { Build } from "./transactionSubmission/build";
 import { Simulate } from "./transactionSubmission/simulate";
 import { Submit } from "./transactionSubmission/submit";
 import { TransactionManagement } from "./transactionSubmission/management";
 import { SimpleTransaction } from "../transactions/instances/simpleTransaction";
+import { MultiEd25519Account } from "../account/MultiEd25519Account";
 
 /**
  * Represents a transaction in the Aptos blockchain,
@@ -506,10 +509,27 @@ export class Transaction {
    * ```
    * @group Transaction
    */
-  async rotateAuthKey(args: { fromAccount: Account; toNewPrivateKey: PrivateKeyInput }): Promise<TransactionResponse> {
+  async rotateAuthKey(args: {
+    fromAccount: Account;
+    toNewPrivateKey: Ed25519PrivateKey;
+  }): Promise<PendingTransactionResponse> {
     return rotateAuthKey({ aptosConfig: this.config, ...args });
   }
 
+  async rotateAuthKeyToMultiEd25519(args: {
+    fromAccount: Account;
+    multiEd25519Account: MultiEd25519Account;
+  }): Promise<PendingTransactionResponse> {
+    return rotateAuthKeyToMultiEd25519({ aptosConfig: this.config, ...args });
+  }
+
+  async rotateAuthKeyWithVerificationTransaction(args: {
+    fromAccount: Account;
+    toAccount: Account;
+  }): Promise<CommittedTransactionResponse> {
+    return rotateAuthKeyWithVerificationTransaction({ aptosConfig: this.config, ...args });
+  }
+
   /**
    * Sign a transaction that can later be submitted to the chain.
    * This function is essential for ensuring the authenticity of the transaction by using the provided account's signing capabilities.

package/src/client/core.ts

@@ -15,6 +15,7 @@ import { AptosApiError } from "../errors";
  * @param options.method - The HTTP method to use for the request.
  * @param options.body - The body of the request.
  * @param options.contentType - The content type of the request.
+ * @param options.acceptType - The accept type of the request.
  * @param options.params - The query parameters to include in the request.
  * @param options.overrides - Additional overrides for the request.
  * @param options.overrides.HEADERS - Custom headers to include in the request.
@@ -57,6 +58,62 @@ export async function request<Req, Res>(options: ClientRequest<Req>, client: Cli
   });
 }
 
+/**
+ * Sends a request using the specified options and returns the response.
+ *
+ * @param options - The options for the request.
+ * @param options.url - The URL to send the request to.
+ * @param options.method - The HTTP method to use for the request.
+ * @param options.body - The body of the request.
+ * @param options.contentType - The content type of the request.
+ * @param options.acceptType - The accept type of the request.
+ * @param options.params - The query parameters to include in the request.
+ * @param options.overrides - Additional overrides for the request.
+ * @param options.overrides.HEADERS - Custom headers to include in the request.
+ * @param options.overrides.AUTH_TOKEN - The authorization token for the request.
+ * @param options.overrides.API_KEY - The API key for the request.
+ * @param options.originMethod - The origin method for the request.
+ * @param client - The client used to make the request.
+ *
+ * @returns The response from the request.
+ * @group Implementation
+ * @category Client
+ */
+export async function binaryRequest<Req>(options: ClientRequest<Req>, client: Client): Promise<ClientResponse<Buffer>> {
+  if (client.binaryProvider === undefined) {
+    throw new Error("Binary provider is not provided");
+  }
+  const { url, method, body, contentType, acceptType, params, overrides, originMethod } = options;
+  const headers: Record<string, string | AnyNumber | boolean | undefined> = {
+    ...overrides?.HEADERS,
+    "x-aptos-client": `aptos-typescript-sdk/${VERSION}`,
+    "content-type": contentType ?? MimeType.JSON,
+    accept: acceptType ?? MimeType.BCS,
+    "x-aptos-typescript-sdk-origin-method": originMethod,
+  };
+
+  if (overrides?.AUTH_TOKEN) {
+    headers.Authorization = `Bearer ${overrides?.AUTH_TOKEN}`;
+  }
+  if (overrides?.API_KEY) {
+    headers.Authorization = `Bearer ${overrides?.API_KEY}`;
+  }
+
+  /*
+   * make a call using the @aptos-labs/aptos-client package
+   * {@link https://www.npmjs.com/package/@aptos-labs/aptos-client}
+   */
+  return client.binaryProvider<Req>({
+    acceptType: MimeType.BCS,
+    url,
+    method,
+    body,
+    params,
+    headers,
+    overrides,
+  });
+}
+
 /**
  * The main function to use when making an API request, returning the response or throwing an AptosApiError on failure.
  *
@@ -118,3 +175,66 @@ export async function aptosRequest<Req extends {}, Res extends {}>(
   // comes from an indexer request (e.g. 404), we'll need to mention it appropriately
   throw new AptosApiError({ apiType, aptosRequest: aptosRequestOpts, aptosResponse });
 }
+
+/**
+ * The main function to use when making an API request, returning the response or throwing an AptosApiError on failure.
+ *
+ * @param aptosRequestOpts - Options for the Aptos request, including the URL and path.
+ * @param aptosConfig - The configuration information for the SDK client instance.
+ * @param apiType - The type of API being accessed, which determines how the response is handled.
+ * @returns The response from the API request or throws an AptosApiError if the request fails.
+ * @group Implementation
+ * @category Client
+ * @experimental
+ */
+export async function aptosBinaryRequest<Req extends {}>(
+  aptosRequestOpts: AptosRequest,
+  aptosConfig: AptosConfig,
+  apiType: AptosApiType,
+): Promise<AptosResponse<Req, Buffer>> {
+  const { url, path } = aptosRequestOpts;
+  const fullUrl = path ? `${url}/${path}` : url;
+  const clientResponse = await binaryRequest<Req>({ ...aptosRequestOpts, url: fullUrl }, aptosConfig.client);
+
+  const aptosResponse: AptosResponse<Req, Buffer> = {
+    status: clientResponse.status,
+    statusText: clientResponse.statusText ?? "No status text provided",
+    data: clientResponse.data,
+    headers: clientResponse.headers,
+    config: clientResponse.config,
+    request: clientResponse.request,
+    url: fullUrl,
+  };
+
+  // Handle case for `Unauthorized` error (i.e. API_KEY error)
+  if (aptosResponse.status === 401) {
+    throw new AptosApiError({ apiType, aptosRequest: aptosRequestOpts, aptosResponse });
+  }
+
+  // to support both fullnode and indexer responses,
+  // check if it is an indexer query, and adjust response.data
+  if (apiType === AptosApiType.INDEXER) {
+    const indexerResponse = aptosResponse.data as any;
+    // Handle Indexer general errors
+    if (indexerResponse.errors) {
+      throw new AptosApiError({
+        apiType,
+        aptosRequest: aptosRequestOpts,
+        aptosResponse,
+      });
+    }
+    aptosResponse.data = indexerResponse.data as Buffer;
+  } else if (apiType === AptosApiType.PEPPER || apiType === AptosApiType.PROVER) {
+    if (aptosResponse.status >= 400) {
+      throw new AptosApiError({ apiType, aptosRequest: aptosRequestOpts, aptosResponse });
+    }
+  }
+
+  if (aptosResponse.status >= 200 && aptosResponse.status < 300) {
+    return aptosResponse;
+  }
+
+  // We have to explicitly check for all request types, because if the error is a non-indexer error, but
+  // comes from an indexer request (e.g. 404), we'll need to mention it appropriately
+  throw new AptosApiError({ apiType, aptosRequest: aptosRequestOpts, aptosResponse });
+}