@aptos-labs/ts-sdk 7.2.0-beta.0 → 7.3.0

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/transactions/transactionBuilder/transactionBuilder.ts

@@ -65,6 +65,7 @@ import {
   InputGenerateSingleSignerRawTransactionArgs,
   InputGenerateTransactionOptions,
   InputScriptData,
+  InputMultiSigScriptData,
   InputSimulateTransactionData,
   InputMultiSigDataWithRemoteABI,
   InputEntryFunctionDataWithRemoteABI,
@@ -110,6 +111,11 @@ import { buildEncryptedPayload } from "./encryptPayload.js";
  * @group Implementation
  * @category Transactions
  */
+export async function generateTransactionPayload(args: InputMultiSigScriptData): Promise<TransactionPayloadMultiSig>;
+/**
+ * @group Implementation
+ * @category Transactions
+ */
 export async function generateTransactionPayload(args: InputScriptData): Promise<TransactionPayloadScript>;
 /**
  * @group Implementation

package/src/types/types.ts

@@ -346,6 +346,12 @@ export type AptosSettings = {
   readonly transactionGenerationConfig?: TransactionGenerationConfig;
 
   readonly pluginSettings?: PluginSettings;
+
+  /**
+   * Whether reads of pruned history are retried against the archival endpoint the node advertises.
+   * Defaults to `true`.
+   */
+  readonly archivalFallback?: boolean;
 };
 
 /**

package/src/version.ts

@@ -6,4 +6,4 @@
  *
  * hardcoded for now, we would want to have it injected dynamically
  */
-export const VERSION = "7.2.0-beta.0";
+export const VERSION = "7.3.0";