@aptos-labs/ts-sdk 7.2.0 → 7.4.0

package/src/api/transactionSubmission/build.ts

@@ -1,6 +1,7 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
+import type { Account } from "../../account/index.js";
 import { AccountAddressInput } from "../../core/index.js";
 import { generateTransaction } from "../../internal/transactionSubmission.js";
 import { InputGenerateTransactionPayloadData, InputGenerateTransactionOptions } from "../../transactions/index.js";
@@ -8,6 +9,10 @@ import { MultiAgentTransaction } from "../../transactions/instances/multiAgentTr
 import { SimpleTransaction } from "../../transactions/instances/simpleTransaction.js";
 import { AptosConfig } from "../aptosConfig.js";
 
+function accountAddressInput(input: Account | AccountAddressInput): AccountAddressInput {
+  return typeof input === "object" && "accountAddress" in input ? input.accountAddress : input;
+}
+
 /**
  * A class to handle all `Build` transaction operations.
  * @group Implementation
@@ -53,7 +58,7 @@ export class Build {
    *
    * This function allows you to create a transaction with specified sender and data.
    *
-   * @param args.sender - The sender account address.
+   * @param args.sender - The sender account or account address.
    * @param args.data - The transaction data.
    * @param args.options - Optional transaction configurations.
    * @param args.withFeePayer - Whether there is a fee payer for the transaction.
@@ -62,15 +67,16 @@ export class Build {
    *
    * @example
    * ```typescript
-   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   * import { Account, Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
    * const config = new AptosConfig({ network: Network.TESTNET });
    * const aptos = new Aptos(config);
+   * const sender = Account.generate();
    *
    * async function runExample() {
    *   // Build a simple transaction
-   *   const transaction = await aptos.transaction.simple({
-   *     sender: "0x1", // replace with a real sender account address
+   *   const transaction = await aptos.transaction.build.simple({
+   *     sender,
    *     data: {
    *       function: "0x1::aptos_account::transfer",
    *       functionArguments: ["0x2", 100], // replace with a real destination account address
@@ -88,12 +94,16 @@ export class Build {
    * @group Implementation
    */
   async simple(args: {
-    sender: AccountAddressInput;
+    sender: Account | AccountAddressInput;
     data: InputGenerateTransactionPayloadData;
     options?: InputGenerateTransactionOptions;
     withFeePayer?: boolean;
   }): Promise<SimpleTransaction> {
-    return generateTransaction({ aptosConfig: this.config, ...args });
+    return generateTransaction({
+      aptosConfig: this.config,
+      ...args,
+      sender: accountAddressInput(args.sender),
+    });
   }
 
   /**

package/src/api/transactionSubmission/simulate.ts

@@ -48,8 +48,13 @@ export class Simulate {
    * Simulates a transaction based on the provided parameters and returns the result.
    * This function helps you understand the outcome of a transaction before executing it on the blockchain.
    *
+   * To pre-check a multisig proposal, build its entry function directly with the multisig address as sender and
+   * `withFeePayer: true`, then omit `signerPublicKey` and `feePayerPublicKey`. The simulation uses no-account
+   * authenticators to skip authentication-key validation, so the proposal does not need to exist on-chain.
+   *
    * @param args - The parameters for simulating the transaction.
-   * @param args.signerPublicKey - The public key of the signer for the transaction (optional).
+   * @param args.signerPublicKey - Optional public key used to validate the signer's authentication key.
+   * Omit it to simulate with the sender address already embedded in the transaction.
    * @param args.transaction - The raw transaction data to simulate.
    * @param args.feePayerPublicKey - The public key of the fee payer (optional).
    * @param args.options - Additional options for simulating the transaction (optional).
@@ -78,7 +83,7 @@ export class Simulate {
    *
    *     // 1. Build the transaction to preview the impact of it
    *     const transaction = await aptos.transaction.build.simple({
-   *         sender: sender.accountAddress,
+   *         sender,
    *         data: {
    *             // All transactions on Aptos are implemented via smart contracts.
    *             function: "0x1::aptos_account::transfer",
@@ -88,7 +93,6 @@ export class Simulate {
    *
    *     // 2. Simulate to see what would happen if we execute this transaction
    *     const [userTransactionResponse] = await aptos.transaction.simulate.simple({
-   *         signerPublicKey: sender.publicKey,
    *         transaction,
    *     });
    *     console.log(userTransactionResponse);

package/src/bcs/serializable/moveStructs.ts

@@ -6,6 +6,7 @@ import { Serializable, Serializer, serializeEntryFunctionBytesCompat } from "../
 import { Deserializable, Deserializer } from "../deserializer.js";
 import { AnyNumber, HexInput, ScriptTransactionArgumentVariants } from "../../types/index.js";
 import { Hex } from "../../core/hex.js";
+import { AccountAddress, AccountAddressInput } from "../../core/accountAddress.js";
 import { EntryFunctionArgument, TransactionArgument } from "../../transactions/instances/transactionArgument.js";
 import { TEXT_ENCODER } from "../../utils/const.js";
 
@@ -376,6 +377,23 @@ export class MoveVector<T extends Serializable & EntryFunctionArgument>
     return new MoveVector<MoveString>(values.map((v) => new MoveString(v)));
   }
 
+  /**
+   * Factory method to generate a MoveVector<AccountAddress> from an array of `AccountAddressInput` values.
+   *
+   * @param values - The values used to fill the MoveVector.
+   * @returns A MoveVector<AccountAddress> with the inner values.
+   *
+   * @example
+   * ```typescript
+   * const v = MoveVector.Address(["0x1", "0x2"]);
+   * ```
+   * @group Implementation
+   * @category BCS
+   */
+  static Address(values: Array<AccountAddressInput>): MoveVector<AccountAddress> {
+    return new MoveVector<AccountAddress>(values.map((v) => AccountAddress.from(v)));
+  }
+
   /**
    * Serializes the current object using the provided serializer.
    * This function will serialize the value if it is present.
@@ -575,13 +593,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<U8> from a `number` or `undefined`.
+   * Factory method to generate a MoveOption<U8> from a `number`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.U8(1).isSome() === true;
    * MoveOption.U8().isSome() === false;
    * MoveOption.U8(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.U8(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<U8> with an inner value `value`
    * @group Implementation
@@ -592,13 +611,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<U16> from a `number` or `undefined`.
+   * Factory method to generate a MoveOption<U16> from a `number`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.U16(1).isSome() === true;
    * MoveOption.U16().isSome() === false;
    * MoveOption.U16(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.U16(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<U16> with an inner value `value`
    * @group Implementation
@@ -609,13 +629,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<U32> from a `number` or `undefined`.
+   * Factory method to generate a MoveOption<U32> from a `number`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.U32(1).isSome() === true;
    * MoveOption.U32().isSome() === false;
    * MoveOption.U32(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.U32(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<U32> with an inner value `value`
    * @group Implementation
@@ -626,13 +647,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<U64> from a `number` or a `bigint` or `undefined`.
+   * Factory method to generate a MoveOption<U64> from a `number`, `bigint`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.U64(1).isSome() === true;
    * MoveOption.U64().isSome() === false;
    * MoveOption.U64(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.U64(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<U64> with an inner value `value`
    * @group Implementation
@@ -643,13 +665,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<U128> from a `number` or a `bigint` or `undefined`.
+   * Factory method to generate a MoveOption<U128> from a `number`, `bigint`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.U128(1).isSome() === true;
    * MoveOption.U128().isSome() === false;
    * MoveOption.U128(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.U128(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<U128> with an inner value `value`
    * @group Implementation
@@ -660,13 +683,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<U256> from a `number` or a `bigint` or `undefined`.
+   * Factory method to generate a MoveOption<U256> from a `number`, `bigint`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.U256(1).isSome() === true;
    * MoveOption.U256().isSome() === false;
    * MoveOption.U256(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.U256(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<U256> with an inner value `value`
    * @group Implementation
@@ -677,13 +701,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<Bool> from a `boolean` or `undefined`.
+   * Factory method to generate a MoveOption<Bool> from a `boolean`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.Bool(true).isSome() === true;
    * MoveOption.Bool().isSome() === false;
    * MoveOption.Bool(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.Bool(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<Bool> with an inner value `value`
    * @group Implementation
@@ -694,13 +719,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<I8> from a `number` or `undefined`.
+   * Factory method to generate a MoveOption<I8> from a `number`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.I8(1).isSome() === true;
    * MoveOption.I8().isSome() === false;
    * MoveOption.I8(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.I8(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<I8> with an inner value `value`
    * @group Implementation
@@ -711,13 +737,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<I16> from a `number` or `undefined`.
+   * Factory method to generate a MoveOption<I16> from a `number`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.I16(1).isSome() === true;
    * MoveOption.I16().isSome() === false;
    * MoveOption.I16(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.I16(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<I16> with an inner value `value`
    * @group Implementation
@@ -728,13 +755,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<I32> from a `number` or `undefined`.
+   * Factory method to generate a MoveOption<I32> from a `number`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.I32(1).isSome() === true;
    * MoveOption.I32().isSome() === false;
    * MoveOption.I32(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.I32(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<I32> with an inner value `value`
    * @group Implementation
@@ -745,13 +773,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<I64> from a `number` or a `bigint` or `undefined`.
+   * Factory method to generate a MoveOption<I64> from a `number`, `bigint`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.I64(1).isSome() === true;
    * MoveOption.I64().isSome() === false;
    * MoveOption.I64(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.I64(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<I64> with an inner value `value`
    * @group Implementation
@@ -762,13 +791,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<I128> from a `number` or a `bigint` or `undefined`.
+   * Factory method to generate a MoveOption<I128> from a `number`, `bigint`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.I128(1).isSome() === true;
    * MoveOption.I128().isSome() === false;
    * MoveOption.I128(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.I128(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<I128> with an inner value `value`
    * @group Implementation
@@ -779,13 +809,14 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<I256> from a `number` or a `bigint` or `undefined`.
+   * Factory method to generate a MoveOption<I256> from a `number`, `bigint`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.I256(1).isSome() === true;
    * MoveOption.I256().isSome() === false;
    * MoveOption.I256(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.I256(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<I256> with an inner value `value`
    * @group Implementation
@@ -796,14 +827,15 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
   }
 
   /**
-   * Factory method to generate a MoveOption<MoveString> from a `string` or `undefined`.
+   * Factory method to generate a MoveOption<MoveString> from a `string`, `undefined`, or `null`.
    *
    * @example
    * MoveOption.MoveString("hello").isSome() === true;
    * MoveOption.MoveString("").isSome() === true;
    * MoveOption.MoveString().isSome() === false;
    * MoveOption.MoveString(undefined).isSome() === false;
-   * @param value the value used to fill the MoveOption. If `value` is undefined
+   * MoveOption.MoveString(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<MoveString> with an inner value `value`
    * @group Implementation
@@ -813,6 +845,26 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
     return new MoveOption<MoveString>(value !== null && value !== undefined ? new MoveString(value) : undefined);
   }
 
+  /**
+   * Factory method to generate a MoveOption<AccountAddress> from an `AccountAddressInput`, `undefined`, or `null`.
+   *
+   * @example
+   * MoveOption.Address("0x1").isSome() === true;
+   * MoveOption.Address().isSome() === false;
+   * MoveOption.Address(undefined).isSome() === false;
+   * MoveOption.Address(null).isSome() === false;
+   * @param value the value used to fill the MoveOption. If `value` is undefined or null
+   * the resulting MoveOption's .isSome() method will return false.
+   * @returns a MoveOption<AccountAddress> with an inner value `value`
+   * @group Implementation
+   * @category BCS
+   */
+  static Address(value?: AccountAddressInput | null): MoveOption<AccountAddress> {
+    return new MoveOption<AccountAddress>(
+      value !== null && value !== undefined ? AccountAddress.from(value) : undefined,
+    );
+  }
+
   static deserialize<U extends Serializable & EntryFunctionArgument>(
     deserializer: Deserializer,
     cls: Deserializable<U>,

package/src/cli/localNode.ts

@@ -1,4 +1,6 @@
 import { ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
 import kill from "tree-kill";
 import { platform } from "node:os";
 
@@ -111,13 +113,25 @@ export class LocalNode {
 
     this.process = spawn(cliCommand, cliArgs, spawnConfig);
 
-    this.process.stdout?.on("data", (data: any) => {
+    // CI prints `${{ runner.temp }}/local-testnet-logs.txt` on failure (TMPDIR).
+    const logPath = process.env.TMPDIR ? join(process.env.TMPDIR, "local-testnet-logs.txt") : undefined;
+
+    const handleOutput = (data: any) => {
       const str = data.toString();
-      // Print local node output log
       if (this.showStdout) {
         console.log(str);
       }
-    });
+      if (logPath) {
+        try {
+          appendFileSync(logPath, str);
+        } catch {
+          // Best-effort logging only — never fail the node start on log I/O.
+        }
+      }
+    };
+
+    this.process.stdout?.on("data", handleOutput);
+    this.process.stderr?.on("data", handleOutput);
   }
 
   /**

package/src/client/core.ts

@@ -68,26 +68,107 @@ export async function request<Req, Res>(options: ClientRequest<Req>, client: Cli
   });
 }
 
+const HTTP_STATUS_GONE = 410;
+
+const CREDENTIAL_HEADERS = new Set(["authorization", "cookie", "x-api-key"]);
+
+const warnedArchivalEndpoints = new Set<string>();
+
+type ArchivalRetryTarget = {
+  url: string;
+  forwardCredentials: boolean;
+};
+
 /**
- * The main function to use when making an API request, returning the response or throwing an AptosApiError on failure.
+ * Registrable domain, approximated as the last two labels.
+ * Hosts under a multi-part suffix like `co.uk` compare equal.
+ */
+function siteOf(hostname: string): string {
+  return hostname.toLowerCase().split(".").slice(-2).join(".");
+}
+
+/**
+ * Validates the archival endpoint advertised in a pruning error, returning undefined if it is unusable.
  *
- * @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
+ * The endpoint is chosen by the node rather than the caller, so it must be an absolute http(s) URL that does
+ * not downgrade an https request, and credentials are only forwarded to it when it is same-site.
  */
-export async function aptosRequest<Req extends {}, Res extends {}>(
+function resolveArchivalRetryTarget(originalUrl: string, responseData: any): ArchivalRetryTarget | undefined {
+  const advertisedEndpoint = responseData?.archival_endpoint;
+  if (typeof advertisedEndpoint !== "string" || advertisedEndpoint.length === 0) {
+    return undefined;
+  }
+
+  let archivalUrl: URL;
+  let originUrl: URL;
+  try {
+    archivalUrl = new URL(advertisedEndpoint);
+    originUrl = new URL(originalUrl);
+  } catch {
+    return undefined;
+  }
+
+  if (archivalUrl.protocol !== "https:" && archivalUrl.protocol !== "http:") {
+    return undefined;
+  }
+  if (originUrl.protocol === "https:" && archivalUrl.protocol !== "https:") {
+    return undefined;
+  }
+
+  return {
+    url: advertisedEndpoint.replace(/\/+$/, ""),
+    forwardCredentials: siteOf(archivalUrl.hostname) === siteOf(originUrl.hostname),
+  };
+}
+
+function hasCredentials(overrides: AptosRequest["overrides"]): boolean {
+  if (!overrides) {
+    return false;
+  }
+  if (overrides.API_KEY || overrides.AUTH_TOKEN) {
+    return true;
+  }
+  return Object.keys(overrides.HEADERS ?? {}).some((name) => CREDENTIAL_HEADERS.has(name.toLowerCase()));
+}
+
+function withoutCredentials(overrides: AptosRequest["overrides"]): AptosRequest["overrides"] {
+  if (!overrides) {
+    return overrides;
+  }
+  const { API_KEY, AUTH_TOKEN, HEADERS, ...rest } = overrides;
+  if (!HEADERS) {
+    return rest;
+  }
+  return {
+    ...rest,
+    HEADERS: Object.fromEntries(
+      Object.entries(HEADERS).filter(([name]) => !CREDENTIAL_HEADERS.has(name.toLowerCase())),
+    ),
+  };
+}
+
+function warnOnceAboutDroppedCredentials(originalUrl: string, archivalUrl: string): void {
+  if (warnedArchivalEndpoints.has(archivalUrl)) {
+    return;
+  }
+  warnedArchivalEndpoints.add(archivalUrl);
+  console.warn(
+    `[Aptos SDK] ${originalUrl} reported pruned data and advertised the archival endpoint ${archivalUrl}. ` +
+      "Retrying there without credentials because it is not on the same site. If that endpoint requires " +
+      "authentication, set it as your `fullnode` URL, or disable this retry with `archivalFallback: false`.",
+  );
+}
+
+/** Sends a request and shapes the client response into an `AptosResponse`, without interpreting the status. */
+async function sendAptosRequest<Req extends {}, Res extends {}>(
   aptosRequestOpts: AptosRequest,
   aptosConfig: AptosConfig,
-  apiType: AptosApiType,
 ): Promise<AptosResponse<Req, Res>> {
   const { url, path } = aptosRequestOpts;
   const fullUrl = path ? `${url}/${path}` : url;
   const clientResponse = await request<Req, Res>({ ...aptosRequestOpts, url: fullUrl }, aptosConfig.client);
 
-  const aptosResponse: AptosResponse<Req, Res> = {
+  return {
     status: clientResponse.status,
     statusText: clientResponse.statusText ?? "No status text provided",
     data: clientResponse.data,
@@ -96,7 +177,14 @@ export async function aptosRequest<Req extends {}, Res extends {}>(
     request: clientResponse.request,
     url: fullUrl,
   };
+}
 
+/** Returns the response on success, or throws an `AptosApiError` describing the failure. */
+function handleAptosResponse<Req extends {}, Res extends {}>(
+  aptosResponse: AptosResponse<Req, Res>,
+  aptosRequestOpts: AptosRequest,
+  apiType: AptosApiType,
+): AptosResponse<Req, Res> {
   // Handle case for `Unauthorized` error (i.e. API_KEY error)
   if (aptosResponse.status === 401) {
     throw new AptosApiError({ apiType, aptosRequest: aptosRequestOpts, aptosResponse });
@@ -135,3 +223,55 @@ 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.
+ *
+ * A Node API read of pruned data answers `410 Gone` with an `archival_endpoint`. Such requests are replayed
+ * once against that endpoint and the result returned transparently. Opt out with `archivalFallback: false`.
+ *
+ * @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
+ */
+export async function aptosRequest<Req extends {}, Res extends {}>(
+  aptosRequestOpts: AptosRequest,
+  aptosConfig: AptosConfig,
+  apiType: AptosApiType,
+): Promise<AptosResponse<Req, Res>> {
+  const aptosResponse = await sendAptosRequest<Req, Res>(aptosRequestOpts, aptosConfig);
+
+  const archivalTarget =
+    apiType === AptosApiType.FULLNODE && aptosResponse.status === HTTP_STATUS_GONE && aptosConfig.archivalFallback
+      ? resolveArchivalRetryTarget(aptosResponse.url, aptosResponse.data)
+      : undefined;
+
+  if (archivalTarget === undefined) {
+    return handleAptosResponse<Req, Res>(aptosResponse, aptosRequestOpts, apiType);
+  }
+
+  if (!archivalTarget.forwardCredentials && hasCredentials(aptosRequestOpts.overrides)) {
+    warnOnceAboutDroppedCredentials(aptosResponse.url, archivalTarget.url);
+  }
+
+  const archivalRequestOpts: AptosRequest = {
+    ...aptosRequestOpts,
+    url: archivalTarget.url,
+    overrides: archivalTarget.forwardCredentials
+      ? aptosRequestOpts.overrides
+      : withoutCredentials(aptosRequestOpts.overrides),
+  };
+
+  let archivalResponse: AptosResponse<Req, Res>;
+  try {
+    archivalResponse = await sendAptosRequest<Req, Res>(archivalRequestOpts, aptosConfig);
+  } catch {
+    // Archival was unreachable, so the pruning error remains the more useful one to surface.
+    throw new AptosApiError({ apiType, aptosRequest: aptosRequestOpts, aptosResponse });
+  }
+
+  return handleAptosResponse<Req, Res>(archivalResponse, archivalRequestOpts, apiType);
+}

package/src/functions/keyless.ts

@@ -9,6 +9,7 @@
 // Standalone functions
 export {
   getPepper,
+  getPepperAndAddress,
   getProof,
   deriveKeylessAccount,
   updateFederatedKeylessJwkSetTransaction,

package/src/functions/transaction.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 export {
+  enrichTransactionWithTableItemData,
   getTransactions,
   getGasPriceEstimation,
   getTransactionByVersion,