@aptos-labs/ts-sdk 7.0.0 → 7.1.0

package/src/internal/account.ts

@@ -83,6 +83,7 @@ import { Hex } from "../core/hex.js";
 import { CurrentFungibleAssetBalancesBoolExp } from "../types/generated/types.js";
 import { getTableItem } from "./table.js";
 import { APTOS_COIN } from "../utils/index.js";
+import { memoizeAsync } from "../utils/memoize.js";
 import { AptosApiError } from "../errors/index.js";
 import { Deserializer, U8, MoveVector } from "../bcs/index.js";
 import { generateTransaction } from "./transactionSubmission.js";
@@ -381,6 +382,45 @@ export async function lookupOriginalAccountAddress(args: {
   }
 }
 
+/**
+ * Fetches the on-chain `authentication_key` for an account address and memoizes it for ~1 hour,
+ * keyed by `(network or fullnode URL, address)`. Used by the encrypted-transaction builder to
+ * derive auth keys when the caller does not pass them explicitly. Callers that just rotated their
+ * key and need an immediate fresh read should pass the auth key explicitly instead of relying on
+ * this cache.
+ *
+ * If the address has no `0x1::account::Account` resource on chain (a brand-new account, or a light
+ * account with balance/objects but no explicit resource), returns the address bytes as the
+ * authentication key — matching the chain's account-creation convention (see
+ * [`doesAccountExistAtAddress`]). This makes encrypted-transaction builds work for not-yet-created
+ * signers (e.g., fee-payer sponsorship of an uncreated sender).
+ */
+export async function fetchAndCacheAuthKeyForAddress(args: {
+  aptosConfig: AptosConfig;
+  accountAddress: AccountAddressInput;
+}): Promise<AuthenticationKey> {
+  const { aptosConfig, accountAddress } = args;
+  const address = AccountAddress.from(accountAddress);
+  const addr = address.toString();
+  const cacheKey = `auth-key-${aptosConfig.fullnode ?? aptosConfig.network}-${addr}`;
+  return memoizeAsync(
+    async () => {
+      try {
+        const info = await getInfoUtil({ aptosConfig, accountAddress: addr });
+        return new AuthenticationKey({ data: info.authentication_key });
+      } catch (err) {
+        if (err instanceof AptosApiError && err.data?.error_code === "account_not_found") {
+          // Chain convention: with no Account resource the auth key is the address itself.
+          return new AuthenticationKey({ data: address.toUint8Array() });
+        }
+        throw err;
+      }
+    },
+    cacheKey,
+    60 * 60 * 1000,
+  )();
+}
+
 /**
  * Retrieves the count of tokens owned by a specific account address.
  *
@@ -958,17 +998,27 @@ async function doesAccountExistAtAddress(args: {
   }
 }
 
-const rotateAuthKeyAbi: EntryFunctionABI = {
-  typeParameters: [],
-  parameters: [
-    new TypeTagU8(),
-    TypeTagVector.u8(),
-    new TypeTagU8(),
-    TypeTagVector.u8(),
-    TypeTagVector.u8(),
-    TypeTagVector.u8(),
-  ],
-};
+// Lazy: instantiating TypeTagU8 at module-init time creates an ESM circular
+// import (structEnumParser → internal/account → transactions/index → typeTag)
+// where TypeTagU8 may not yet be a constructor when this file evaluates.
+// Building the ABI on first use sidesteps the order dependency.
+let _rotateAuthKeyAbi: EntryFunctionABI | undefined;
+function rotateAuthKeyAbi(): EntryFunctionABI {
+  if (!_rotateAuthKeyAbi) {
+    _rotateAuthKeyAbi = {
+      typeParameters: [],
+      parameters: [
+        new TypeTagU8(),
+        TypeTagVector.u8(),
+        new TypeTagU8(),
+        TypeTagVector.u8(),
+        TypeTagVector.u8(),
+        TypeTagVector.u8(),
+      ],
+    };
+  }
+  return _rotateAuthKeyAbi;
+}
 
 /**
  * Rotates the authentication key for a given account.
@@ -1065,16 +1115,22 @@ async function rotateAuthKeyWithChallenge(
         MoveVector.U8(proofSignedByCurrentKey.toUint8Array()),
         MoveVector.U8(proofSignedByNewKey.toUint8Array()),
       ],
-      abi: rotateAuthKeyAbi,
+      abi: rotateAuthKeyAbi(),
     },
     options,
   });
 }
 
-const rotateAuthKeyUnverifiedAbi: EntryFunctionABI = {
-  typeParameters: [],
-  parameters: [new TypeTagU8(), TypeTagVector.u8()],
-};
+let _rotateAuthKeyUnverifiedAbi: EntryFunctionABI | undefined;
+function rotateAuthKeyUnverifiedAbi(): EntryFunctionABI {
+  if (!_rotateAuthKeyUnverifiedAbi) {
+    _rotateAuthKeyUnverifiedAbi = {
+      typeParameters: [],
+      parameters: [new TypeTagU8(), TypeTagVector.u8()],
+    };
+  }
+  return _rotateAuthKeyUnverifiedAbi;
+}
 
 /**
  * Rotates the authentication key for a given account without verifying the new key.
@@ -1105,7 +1161,7 @@ export async function rotateAuthKeyUnverified(args: {
         new U8(accountPublicKeyToSigningScheme(toNewPublicKey)), // to scheme
         MoveVector.U8(accountPublicKeyToBaseAccountPublicKey(toNewPublicKey).toUint8Array()),
       ],
-      abi: rotateAuthKeyUnverifiedAbi,
+      abi: rotateAuthKeyUnverifiedAbi(),
     },
     options,
   });

package/src/internal/keyless.ts

@@ -108,6 +108,12 @@ export async function getProof(args: {
   if (Hex.fromHexInput(pepper).toUint8Array().length !== KeylessAccount.PEPPER_LENGTH) {
     throw new Error(`Pepper needs to be ${KeylessAccount.PEPPER_LENGTH} bytes`);
   }
+  // SECURITY: jwtDecode does NOT verify the JWT signature. The prover service
+  // is the next hop and will reject a tampered JWT, and the on-chain keyless
+  // verifier validates the signature against the JWK set published on-chain.
+  // Callers must still source `jwt` from a trusted IdP redirect flow — accepting
+  // a user-supplied JWT here will produce a useless proof, not a forged one,
+  // but it also leaks the (unverified) claims to the prover.
   const decodedJwt = jwtDecode<JwtPayload>(jwt);
   if (typeof decodedJwt.iat !== "number") {
     throw new Error("iat was not found");
@@ -261,6 +267,28 @@ export async function updateFederatedKeylessJwkSetTransaction(args: {
     }
   }
 
+  // SSRF guard: require HTTPS. Without this check a caller-supplied `iss` or
+  // `jwksUrl` could redirect the fetch to plaintext HTTP, cloud-metadata
+  // endpoints (e.g., `http://169.254.169.254/...`), internal services, or
+  // non-network schemes like `file:` / `data:`. The on-chain JWKS update is
+  // a privileged operation, so we refuse to source key material over an
+  // untrusted transport.
+  let parsedJwksUrl: URL;
+  try {
+    parsedJwksUrl = new URL(jwksUrl);
+  } catch {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+      details: "JWKS URL is not a valid URL",
+    });
+  }
+  if (parsedJwksUrl.protocol !== "https:") {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+      details: `JWKS URL must use https: (got ${parsedJwksUrl.protocol})`,
+    });
+  }
+
   let response: Response;
 
   try {
@@ -275,13 +303,19 @@ export async function updateFederatedKeylessJwkSetTransaction(args: {
     } else {
       errorMessage = `error unknown - ${error}`;
     }
+    // Surface only the origin (scheme + host + port) of the JWKS URL in the
+    // user-facing error. The full URL, which may include `iss`-derived path
+    // segments or tenant identifiers from enterprise IdPs, is intentionally
+    // omitted to avoid leaking infrastructure details into logs / crash
+    // reporters.
     throw KeylessError.fromErrorType({
       type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
-      details: `Failed to fetch JWKS at ${jwksUrl}: ${errorMessage}`,
+      details: `Failed to fetch JWKS from ${parsedJwksUrl.origin}: ${errorMessage}`,
     });
   }
 
-  const jwks = (await response.json()) as JWKS;
+  const rawJwks: unknown = await response.json();
+  const jwks = validateJwksResponse(rawJwks, parsedJwksUrl.origin);
   return generateTransaction({
     aptosConfig,
     sender: sender.accountAddress,
@@ -298,3 +332,55 @@ export async function updateFederatedKeylessJwkSetTransaction(args: {
     options,
   });
 }
+
+/**
+ * Caller can supply any IdP URL, so the JWKS response is untrusted. The shape
+ * isn't enforced by the TS cast above, and `jwks.keys.map(...)` would throw a
+ * confusing `TypeError: Cannot read properties of ... 'map'` on malformed
+ * payloads. Worse, a hostile/buggy IdP could return an unboundedly large
+ * `keys` array and we'd pack the whole thing into the on-chain transaction.
+ *
+ * Validate the four fields we actually use (kid, alg, e, n), cap the key
+ * count, and surface a single descriptive error when anything is off.
+ */
+const MAX_FEDERATED_JWKS_KEYS = 32;
+
+function validateJwksResponse(raw: unknown, originForError: string): JWKS {
+  if (raw === null || typeof raw !== "object" || !Array.isArray((raw as { keys?: unknown }).keys)) {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+      details: `JWKS response from ${originForError} is missing a 'keys' array`,
+    });
+  }
+  const keys = (raw as { keys: unknown[] }).keys;
+  if (keys.length === 0) {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+      details: `JWKS response from ${originForError} has an empty 'keys' array`,
+    });
+  }
+  if (keys.length > MAX_FEDERATED_JWKS_KEYS) {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+      details: `JWKS response from ${originForError} has ${keys.length} keys (max ${MAX_FEDERATED_JWKS_KEYS})`,
+    });
+  }
+  for (let i = 0; i < keys.length; i += 1) {
+    const key = keys[i];
+    if (key === null || typeof key !== "object") {
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+        details: `JWKS response from ${originForError}: key at index ${i} is not an object`,
+      });
+    }
+    for (const field of ["kid", "alg", "e", "n"] as const) {
+      if (typeof (key as Record<string, unknown>)[field] !== "string") {
+        throw KeylessError.fromErrorType({
+          type: KeylessErrorType.JWK_FETCH_FAILED_FEDERATED,
+          details: `JWKS response from ${originForError}: key at index ${i} is missing string field '${field}'`,
+        });
+      }
+    }
+  }
+  return raw as JWKS;
+}

package/src/internal/transaction.ts

@@ -200,6 +200,16 @@ export async function waitForTransaction(args: {
   let backoffIntervalMs = 200;
   const backoffMultiplier = 1.5;
 
+  // A response is "settled" when the fullnode has populated the execution result.
+  // There is a window where `type` flips to a committed variant (e.g. User) before
+  // `success`/`vm_status` are filled in — during that window we must keep polling,
+  // not treat the partial response as a failure.
+  function isUnsettled(txn: TransactionResponse | undefined): boolean {
+    if (txn === undefined) return true;
+    if (txn.type === TransactionResponseType.Pending) return true;
+    return (txn as { success?: boolean }).success === undefined;
+  }
+
   /**
    * Handles API errors by throwing the last error or a timeout error for a failed transaction.
    *
@@ -223,7 +233,7 @@ export async function waitForTransaction(args: {
   // check to see if the txn is already on the blockchain
   try {
     lastTxn = await getTransactionByHash({ aptosConfig, transactionHash });
-    isPending = lastTxn.type === TransactionResponseType.Pending;
+    isPending = isUnsettled(lastTxn);
   } catch (e) {
     handleAPIError(e);
   }
@@ -233,7 +243,7 @@ export async function waitForTransaction(args: {
     const startTime = Date.now();
     try {
       lastTxn = await longWaitForTransaction({ aptosConfig, transactionHash });
-      isPending = lastTxn.type === TransactionResponseType.Pending;
+      isPending = isUnsettled(lastTxn);
     } catch (e) {
       handleAPIError(e);
     }
@@ -248,7 +258,7 @@ export async function waitForTransaction(args: {
     try {
       lastTxn = await getTransactionByHash({ aptosConfig, transactionHash });
 
-      isPending = lastTxn.type === TransactionResponseType.Pending;
+      isPending = isUnsettled(lastTxn);
 
       if (!isPending) {
         break;
@@ -280,6 +290,15 @@ export async function waitForTransaction(args: {
       lastTxn,
     );
   }
+  // If we exited the loop with a committed-shaped response that hasn't been
+  // fully populated yet (success/vm_status still undefined), this is the
+  // indexer-lag race — surface it as a timeout, not as a failed transaction.
+  if ((lastTxn as { success?: boolean }).success === undefined) {
+    throw new WaitForTransactionError(
+      `Transaction ${transactionHash} did not finish indexing within ${timeoutSecs} seconds`,
+      lastTxn,
+    );
+  }
   if (!checkSuccess) {
     return lastTxn;
   }

package/src/transactions/transactionBuilder/encryptPayload.ts

@@ -4,7 +4,7 @@
 import { AptosConfig } from "../../api/aptosConfig.js";
 import { AccountAddress, AccountAddressInput } from "../../core/index.js";
 import { AuthenticationKey } from "../../core/authenticationKey.js";
-import { AccountPublicKey } from "../../core/crypto/index.js";
+import { fetchAndCacheAuthKeyForAddress } from "../../internal/account.js";
 import { fetchAndCacheEncryptionKey } from "../../internal/encryptionKey.js";
 import {
   ClaimedEntryFunction,
@@ -83,10 +83,11 @@ function resolveClaimedEntryFun(args: {
   options: InputGenerateTransactionOptions;
 }): ClaimedEntryFunction | undefined {
   const { payload, feePayerAddress, options } = args;
-  // Match `buildSignerAuthKeys`: a zero-address fee payer is not a real sponsor, so it should not
-  // force a `claimed_entry_fun` to be exposed/validated.
-  const hasFeePayer =
-    feePayerAddress !== undefined && !AccountAddress.from(feePayerAddress).equals(AccountAddress.ZERO);
+  // Unlike buildSignerAuthKeys, we treat a zero feePayerAddress (deferred gas-station sponsor) the
+  // same as a real one: a fee payer *will* sign, so include claimed_entry_fun so they can inspect
+  // the payload without decrypting it. The zero check in buildSignerAuthKeys is different — adding
+  // a placeholder zero auth key to the cryptographic AAD would corrupt it.
+  const hasFeePayer = feePayerAddress !== undefined;
   if (!hasFeePayer && !payloadHasMultisigAddress(payload)) {
     return undefined;
   }
@@ -102,76 +103,81 @@ function resolveClaimedEntryFun(args: {
   return undefined;
 }
 
-function resolveAuthKey(input: HexInput | AccountPublicKey): AuthenticationKey {
-  if (input instanceof AccountPublicKey) {
-    return input.authKey();
+function resolveAuthKey(input: AuthenticationKey | HexInput): AuthenticationKey {
+  if (input instanceof AuthenticationKey) {
+    return input;
   }
   return new AuthenticationKey({ data: input });
 }
 
 /**
- * Validates auth-key options and assembles `(address, authenticationKey)` pairs in
- * `TransactionAuthenticator::all_signer_auth_keys` order: sender, secondaries, fee payer last.
+ * Assembles `(address, authenticationKey)` pairs in `TransactionAuthenticator::all_signer_auth_keys` order
+ * (sender, secondaries, fee payer last). Auth keys not supplied in `options` are fetched from chain via
+ * `fetchAndCacheAuthKeyForAddress`, which caches per `(network, address)` for ~1 hour.
  */
-function buildSignerAuthKeys(args: {
+async function buildSignerAuthKeys(args: {
+  aptosConfig: AptosConfig;
   sender: AccountAddress;
   options: InputGenerateTransactionOptions;
   feePayerAddress?: AccountAddressInput;
   secondarySignerAddresses?: AccountAddressInput[];
-}): { sender: SignerAuthKeyPair; additional: SignerAuthKeyPair[] | undefined } {
-  const { sender, options, feePayerAddress, secondarySignerAddresses } = args;
+}): Promise<{ sender: SignerAuthKeyPair; additional: SignerAuthKeyPair[] | undefined }> {
+  const { aptosConfig, sender, options, feePayerAddress, secondarySignerAddresses } = args;
 
-  if (options.authenticationKey === undefined) {
+  const secondaryAddrs = secondarySignerAddresses ?? [];
+  const secondaryAuthInputs = options.secondarySignerAuthenticationKeys;
+  if (secondaryAddrs.length === 0 && secondaryAuthInputs !== undefined && secondaryAuthInputs.length > 0) {
     throw new Error(
-      "options.authenticationKey is required when options.encrypted is true. " +
-        "Pass the sender's AccountPublicKey or a raw 32-byte auth key hex string.",
+      "options.secondarySignerAuthenticationKeys was set but no secondarySignerAddresses were provided to generateRawTransaction.",
     );
   }
-  const secondaryAddrs = secondarySignerAddresses ?? [];
-  const secondaryAuthHex = options.secondarySignerAuthenticationKeys;
-  if (secondaryAddrs.length > 0) {
-    if (!secondaryAuthHex || secondaryAuthHex.length !== secondaryAddrs.length) {
-      throw new Error(
-        "Encrypted multi-agent transactions require options.secondarySignerAuthenticationKeys with one entry per secondarySignerAddresses entry, in the same order. " +
-          "Each entry may be an AccountPublicKey or a raw 32-byte auth key hex string.",
-      );
-    }
-  } else if (secondaryAuthHex !== undefined && secondaryAuthHex.length > 0) {
+  if (
+    secondaryAddrs.length > 0 &&
+    secondaryAuthInputs !== undefined &&
+    secondaryAuthInputs.length !== secondaryAddrs.length
+  ) {
     throw new Error(
-      "options.secondarySignerAuthenticationKeys was set but no secondarySignerAddresses were provided to generateRawTransaction.",
+      "Encrypted multi-agent transactions require options.secondarySignerAuthenticationKeys (when provided) to have one entry per secondarySignerAddresses entry, in the same order. " +
+        "Leave individual entries undefined to fetch them from chain.",
     );
   }
 
   const feePayerAddr = feePayerAddress !== undefined ? AccountAddress.from(feePayerAddress) : undefined;
   const hasNonZeroFeePayer = feePayerAddr !== undefined && !feePayerAddr.equals(AccountAddress.ZERO);
-  if (hasNonZeroFeePayer && options.feePayerAuthenticationKey === undefined) {
-    throw new Error(
-      "options.feePayerAuthenticationKey is required when options.encrypted is true and feePayerAddress is a non-zero sponsor. " +
-        "Must match the fee payer authenticator; AAD order is sender, then secondaries, then fee payer (aptos-core `all_signer_auth_keys`).",
-    );
-  }
   if (options.feePayerAuthenticationKey !== undefined && !hasNonZeroFeePayer) {
     throw new Error(
       "options.feePayerAuthenticationKey was set but feePayerAddress is missing or the zero address (no on-chain fee payer for AAD).",
     );
   }
 
-  const senderPair: SignerAuthKeyPair = {
-    address: sender,
-    authenticationKey: resolveAuthKey(options.authenticationKey),
+  const resolveFor = async (
+    address: AccountAddress,
+    input: AuthenticationKey | HexInput | undefined,
+  ): Promise<AuthenticationKey> => {
+    if (input !== undefined) {
+      return resolveAuthKey(input);
+    }
+    return fetchAndCacheAuthKeyForAddress({ aptosConfig, accountAddress: address });
   };
-  const additional: SignerAuthKeyPair[] =
-    secondaryAddrs.length > 0 && secondaryAuthHex
-      ? secondaryAddrs.map((addr, i) => ({
-          address: AccountAddress.from(addr),
-          authenticationKey: resolveAuthKey(secondaryAuthHex[i]!),
-        }))
-      : [];
-  if (hasNonZeroFeePayer && options.feePayerAuthenticationKey !== undefined) {
-    additional.push({
-      address: feePayerAddr,
-      authenticationKey: resolveAuthKey(options.feePayerAuthenticationKey),
-    });
+
+  const secondaryPairsPromise = Promise.all(
+    secondaryAddrs.map(async (addr, i) => {
+      const address = AccountAddress.from(addr);
+      const authenticationKey = await resolveFor(address, secondaryAuthInputs?.[i]);
+      return { address, authenticationKey };
+    }),
+  );
+
+  const [senderAuthKey, secondaryPairs, feePayerAuthKey] = await Promise.all([
+    resolveFor(sender, options.senderAuthenticationKey),
+    secondaryPairsPromise,
+    hasNonZeroFeePayer ? resolveFor(feePayerAddr, options.feePayerAuthenticationKey) : Promise.resolve(undefined),
+  ]);
+
+  const senderPair: SignerAuthKeyPair = { address: sender, authenticationKey: senderAuthKey };
+  const additional: SignerAuthKeyPair[] = [...secondaryPairs];
+  if (hasNonZeroFeePayer && feePayerAuthKey !== undefined) {
+    additional.push({ address: feePayerAddr, authenticationKey: feePayerAuthKey });
   }
   return { sender: senderPair, additional: additional.length > 0 ? additional : undefined };
 }
@@ -196,7 +202,8 @@ export async function buildEncryptedPayload(args: {
     args;
 
   const senderAddr = AccountAddress.from(sender);
-  const { sender: senderPair, additional } = buildSignerAuthKeys({
+  const { sender: senderPair, additional } = await buildSignerAuthKeys({
+    aptosConfig,
     sender: senderAddr,
     options,
     feePayerAddress,

package/src/transactions/types.ts

@@ -19,8 +19,8 @@ import {
   U8,
 } from "../bcs/serializable/movePrimitives.js";
 import { FixedBytes } from "../bcs/serializable/fixedBytes.js";
-import { AccountAddress, AccountAddressInput } from "../core/index.js";
-import { AccountPublicKey, PublicKey } from "../core/crypto/index.js";
+import { AccountAddress, AccountAddressInput, AuthenticationKey } from "../core/index.js";
+import { PublicKey } from "../core/crypto/index.js";
 import {
   MultiAgentRawTransaction,
   FeePayerRawTransaction,
@@ -182,23 +182,27 @@ export type InputEncryptedTransactionBuildOptions = {
    */
   encrypted?: boolean;
   /**
-   * Authentication key for the primary sender. Required when `encrypted` is true.
-   * Accept either an `AccountPublicKey` (auth key is derived automatically via `.authKey()`) or a raw 32-byte hex
-   * string. Must match the on-chain authenticator identity (aptos-core `PayloadAssociatedData::V1.signer_auth_keys`).
+   * Authentication key for the primary sender. Optional: when omitted (and `encrypted` is true), the SDK fetches
+   * the sender's `authentication_key` from the fullnode and caches it for ~1 hour. Pass it explicitly to skip the
+   * lookup (useful right after a key rotation). Accepts an `AuthenticationKey` or a raw 32-byte hex string /
+   * `Uint8Array`. Must match the on-chain authenticator identity (aptos-core
+   * `PayloadAssociatedData::V1.signer_auth_keys`).
    */
-  authenticationKey?: HexInput | AccountPublicKey;
+  senderAuthenticationKey?: AuthenticationKey | HexInput;
   /**
    * For encrypted **multi-agent** transactions: each secondary signer's authentication key, in the same order
-   * as `secondarySignerAddresses` on the transaction build input. Accepts `AccountPublicKey` or raw 32-byte hex.
+   * as `secondarySignerAddresses` on the transaction build input. Any entry left undefined (or the entire array
+   * omitted) will be fetched from chain and cached. Accepts `AuthenticationKey` or a raw 32-byte hex string /
+   * `Uint8Array`.
    */
-  secondarySignerAuthenticationKeys?: (HexInput | AccountPublicKey)[];
+  secondarySignerAuthenticationKeys?: (AuthenticationKey | HexInput | undefined)[];
   /**
-   * For encrypted **fee-payer** transactions: the fee payer's authentication key. Required when `encrypted` is true
-   * and `feePayerAddress` is set to a **non-zero** sponsor address. Appended **last** in AAD `signer_auth_keys`,
-   * matching aptos-core `TransactionAuthenticator::all_signer_auth_keys` (after sender and secondaries).
-   * Accepts `AccountPublicKey` or raw 32-byte hex.
+   * For encrypted **fee-payer** transactions: the fee payer's authentication key. Optional when `feePayerAddress`
+   * is a **non-zero** sponsor — omitted values are fetched from chain and cached. Appended **last** in AAD
+   * `signer_auth_keys`, matching aptos-core `TransactionAuthenticator::all_signer_auth_keys` (after sender and
+   * secondaries). Accepts `AuthenticationKey` or a raw 32-byte hex string / `Uint8Array`.
    */
-  feePayerAuthenticationKey?: HexInput | AccountPublicKey;
+  feePayerAuthenticationKey?: AuthenticationKey | HexInput;
   /**
    * Overrides `claimed_entry_fun` for encrypted transactions when a fee payer is set, the payload is multisig, or the
    * payload is `TransactionInnerPayload` with a multisig address in `TransactionExtraConfigV1`.

package/src/utils/helpers.ts

@@ -6,6 +6,39 @@ import { AccountAddress } from "../core/accountAddress.js";
 import { createObjectAddress } from "../core/account/utils/address.js";
 import { TEXT_ENCODER } from "./const.js";
 
+/**
+ * Maximum bigint value that can be losslessly converted to a JS `number`.
+ * Equal to `BigInt(Number.MAX_SAFE_INTEGER)` (2^53 - 1).
+ */
+const MAX_SAFE_U64 = BigInt(Number.MAX_SAFE_INTEGER);
+
+/**
+ * Narrows a u64 (`bigint`) into a JS `number` with an explicit safety check.
+ *
+ * The `deserializeU64` reader returns `bigint`, but several keyless code
+ * paths historically narrowed the value with `Number(value)` to fit existing
+ * `number`-typed fields (expiry timestamps, expiry horizons). For values
+ * larger than `Number.MAX_SAFE_INTEGER` (~9 × 10^15), `Number(bigint)`
+ * silently loses precision — comparisons against `Date.now() / 1000` then
+ * return wrong results.
+ *
+ * Real-world expiry values are far below the unsafe range (year ~285 million
+ * AD as a Unix timestamp), so this check is effectively a guard against
+ * corrupted or malicious BCS data rather than a precision concern in normal
+ * operation. Throwing is correct behavior at the BCS/JSON boundary.
+ */
+export function u64ToNumberSafe(value: bigint, fieldName: string): number {
+  if (value < 0n) {
+    throw new RangeError(`${fieldName} is negative (${value}); expected an unsigned u64`);
+  }
+  if (value > MAX_SAFE_U64) {
+    throw new RangeError(
+      `${fieldName} (${value}) exceeds Number.MAX_SAFE_INTEGER (${MAX_SAFE_U64}); refusing to silently lose precision`,
+    );
+  }
+  return Number(value);
+}
+
 /**
  * Checks if the current runtime environment is Bun.
  * This is useful for detecting Bun-specific compatibility issues.

package/src/version.ts

@@ -6,4 +6,4 @@
  *
  * hardcoded for now, we would want to have it injected dynamically
  */
-export const VERSION = "7.0.0";
+export const VERSION = "7.1.0";