@aptos-labs/ts-sdk 1.31.0 → 1.32.1

package/src/account/KeylessAccount.ts

@@ -1,14 +1,14 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-import { JwtPayload, jwtDecode } from "jwt-decode";
 import { HexInput } from "../types";
 import { AccountAddress } from "../core/accountAddress";
-import { KeylessPublicKey, ZeroKnowledgeSig } from "../core/crypto";
+import { getIssAudAndUidVal, Groth16VerificationKey, KeylessPublicKey, ZeroKnowledgeSig } from "../core/crypto";
 
 import { EphemeralKeyPair } from "./EphemeralKeyPair";
 import { Deserializer, Serializer } from "../bcs";
 import { AbstractKeylessAccount, ProofFetchCallback } from "./AbstractKeylessAccount";
+import { Hex } from "../core/hex";
 
 /**
  * Account implementation for the Keyless authentication scheme.
@@ -19,9 +19,6 @@ import { AbstractKeylessAccount, ProofFetchCallback } from "./AbstractKeylessAcc
  *
  * When the proof expires or the JWT becomes invalid, the KeylessAccount must be instantiated again with a new JWT,
  * EphemeralKeyPair, and corresponding proof.
- *
- * @static
- * @readonly PEPPER_LENGTH - The length of the pepper used for privacy preservation.
  */
 export class KeylessAccount extends AbstractKeylessAccount {
   /**
@@ -32,11 +29,22 @@ export class KeylessAccount extends AbstractKeylessAccount {
   // Use the static constructor 'create' instead.
 
   /**
-   * Creates an instance of the transaction with an optional proof.
+   * Use the static generator `create(...)` instead.
+   * Creates an instance of the KeylessAccount with an optional proof.
    *
-   * @param args.proof - An optional ZkProof associated with the transaction.
+   * @param args - The parameters for creating a KeylessAccount.
+   * @param args.address - Optional account address associated with the KeylessAccount.
+   * @param args.ephemeralKeyPair - The ephemeral key pair used in the account creation.
+   * @param args.iss - A JWT issuer.
+   * @param args.uidKey - The claim on the JWT to identify a user.  This is typically 'sub' or 'email'.
+   * @param args.uidVal - The unique id for this user, intended to be a stable user identifier.
+   * @param args.aud - The value of the 'aud' claim on the JWT, also known as client ID.  This is the identifier for the dApp's
+   * OIDC registration with the identity provider.
+   * @param args.pepper - A hexadecimal input used for additional security.
+   * @param args.proof - A Zero Knowledge Signature or a promise that resolves to one.
+   * @param args.proofFetchCallback - Optional callback function for fetching proof.
+   * @param args.jwt - A JSON Web Token used for authentication.
    */
-  // TODO: Document rest of parameters
   private constructor(args: {
     address?: AccountAddress;
     ephemeralKeyPair: EphemeralKeyPair;
@@ -48,6 +56,7 @@ export class KeylessAccount extends AbstractKeylessAccount {
     proof: ZeroKnowledgeSig | Promise<ZeroKnowledgeSig>;
     proofFetchCallback?: ProofFetchCallback;
     jwt: string;
+    verificationKeyHash?: HexInput;
   }) {
     const publicKey = KeylessPublicKey.create(args);
     super({ publicKey, ...args });
@@ -61,14 +70,7 @@ export class KeylessAccount extends AbstractKeylessAccount {
    * @param serializer - The serializer instance used to convert the transaction data into bytes.
    */
   serialize(serializer: Serializer): void {
-    serializer.serializeStr(this.jwt);
-    serializer.serializeStr(this.uidKey);
-    serializer.serializeFixedBytes(this.pepper);
-    this.ephemeralKeyPair.serialize(serializer);
-    if (this.proof === undefined) {
-      throw new Error("Cannot serialize - proof undefined");
-    }
-    this.proof.serialize(serializer);
+    super.serialize(serializer);
   }
 
   /**
@@ -79,27 +81,37 @@ export class KeylessAccount extends AbstractKeylessAccount {
    * @returns A KeylessAccount instance created from the deserialized data.
    */
   static deserialize(deserializer: Deserializer): KeylessAccount {
-    const jwt = deserializer.deserializeStr();
-    const uidKey = deserializer.deserializeStr();
-    const pepper = deserializer.deserializeFixedBytes(31);
-    const ephemeralKeyPair = EphemeralKeyPair.deserialize(deserializer);
-    const proof = ZeroKnowledgeSig.deserialize(deserializer);
-    return KeylessAccount.create({
+    const { address, proof, ephemeralKeyPair, jwt, uidKey, pepper, verificationKeyHash } =
+      AbstractKeylessAccount.partialDeserialize(deserializer);
+    const { iss, aud, uidVal } = getIssAudAndUidVal({ jwt, uidKey });
+    return new KeylessAccount({
+      address,
       proof,
-      pepper,
+      ephemeralKeyPair,
+      iss,
       uidKey,
+      uidVal,
+      aud,
+      pepper,
       jwt,
-      ephemeralKeyPair,
+      verificationKeyHash,
     });
   }
 
-  static fromBytes(bytes: Uint8Array): KeylessAccount {
-    return KeylessAccount.deserialize(new Deserializer(bytes));
+  /**
+   * Deserialize bytes using this account's information.
+   *
+   * @param bytes The bytes being interpreted.
+   * @returns
+   */
+  static fromBytes(bytes: HexInput): KeylessAccount {
+    return KeylessAccount.deserialize(new Deserializer(Hex.hexInputToUint8Array(bytes)));
   }
 
   /**
    * Creates a KeylessAccount instance using the provided parameters.
    * This function allows you to set up a KeylessAccount with specific attributes such as address, proof, and JWT.
+   * This is used instead of the KeylessAccount constructor.
    *
    * @param args - The parameters for creating a KeylessAccount.
    * @param args.address - Optional account address associated with the KeylessAccount.
@@ -118,28 +130,23 @@ export class KeylessAccount extends AbstractKeylessAccount {
     pepper: HexInput;
     uidKey?: string;
     proofFetchCallback?: ProofFetchCallback;
+    verificationKey?: Groth16VerificationKey;
   }): KeylessAccount {
-    const { address, proof, jwt, ephemeralKeyPair, pepper, uidKey = "sub", proofFetchCallback } = args;
+    const { address, proof, jwt, ephemeralKeyPair, pepper, uidKey = "sub", proofFetchCallback, verificationKey } = args;
 
-    const jwtPayload = jwtDecode<JwtPayload & { [key: string]: string }>(jwt);
-    if (typeof jwtPayload.iss !== "string") {
-      throw new Error("iss was not found");
-    }
-    if (typeof jwtPayload.aud !== "string") {
-      throw new Error("aud was not found or an array of values");
-    }
-    const uidVal = jwtPayload[uidKey];
+    const { iss, aud, uidVal } = getIssAudAndUidVal({ jwt, uidKey });
     return new KeylessAccount({
       address,
       proof,
       ephemeralKeyPair,
-      iss: jwtPayload.iss,
+      iss,
       uidKey,
       uidVal,
-      aud: jwtPayload.aud,
+      aud,
       pepper,
       jwt,
       proofFetchCallback,
+      verificationKeyHash: verificationKey ? verificationKey.hash() : undefined,
     });
   }
 }

package/src/account/MultiKeyAccount.ts

@@ -7,7 +7,8 @@ import { AccountAddress, AccountAddressInput } from "../core/accountAddress";
 import { HexInput, SigningScheme } from "../types";
 import { AccountAuthenticatorMultiKey } from "../transactions/authenticator/account";
 import { AnyRawTransaction } from "../transactions/types";
-import { AbstractKeylessAccount } from "./AbstractKeylessAccount";
+import { AbstractKeylessAccount, KeylessSigner } from "./AbstractKeylessAccount";
+import { AptosConfig } from "../api/aptosConfig";
 
 /**
  * Arguments required to verify a multi-key signature against a given message.
@@ -28,7 +29,7 @@ export interface VerifyMultiKeySignatureArgs {
  *
  * Note: Generating a signer instance does not create the account on-chain.
  */
-export class MultiKeyAccount implements Account {
+export class MultiKeyAccount implements Account, KeylessSigner {
   /**
    * Public key associated with the account
    */
@@ -154,9 +155,21 @@ export class MultiKeyAccount implements Account {
   }
 
   /**
-   * Sign the given data using the MultiKeyAccount's signers.
-   * @param data - The data to be signed in HexInput format.
-   * @returns MultiKeySignature - The resulting multi-key signature.
+   * Validates that the Keyless Account can be used to sign transactions.
+   * @return
+   */
+  async checkKeylessAccountValidity(aptosConfig: AptosConfig): Promise<void> {
+    const keylessSigners = this.signers.filter(
+      (signer) => signer instanceof AbstractKeylessAccount,
+    ) as AbstractKeylessAccount[];
+    const promises = keylessSigners.map((signer) => signer.checkKeylessAccountValidity(aptosConfig));
+    await Promise.all(promises);
+  }
+
+  /**
+   * Sign the given message using the MultiKeyAccount's signers
+   * @param message in HexInput format
+   * @returns MultiKeySignature
    */
   sign(data: HexInput): MultiKeySignature {
     const signatures = [];

package/src/api/keyless.ts

@@ -155,7 +155,7 @@ export class Keyless {
    * @param args.jwt - The JWT token used for deriving the account.
    * @param args.ephemeralKeyPair - The EphemeralKeyPair used to generate the nonce in the JWT token.
    * @param args.jwkAddress - The address the where the JWKs used to verify signatures are found.  Setting the value derives a
-   * FederatedKeylessAccount
+   * FederatedKeylessAccount.
    * @param args.uidKey - An optional key in the JWT token to set the uidVal in the IdCommitment.
    * @param args.pepper - An optional pepper value.
    * @param args.proofFetchCallback - An optional callback function for fetching the proof in the background, allowing for a more
@@ -201,7 +201,7 @@ export class Keyless {
   /**
    * This installs a set of FederatedJWKs at an address for a given iss.
    *
-   * It will fetch the JWK set from the well-known endpoint and update the FederatedJWKs at the sender's address
+   * It will fetch the JSON Web Keyset (JWK) set from the well-known endpoint and update the FederatedJWKs at the sender's address
    * to reflect it.
    *
    * @param args.sender The account that will install the JWKs

package/src/bcs/deserializer.ts

@@ -82,6 +82,7 @@ export class Deserializer {
   }
 
   /**
+   * @deprecated use `deserializeOption` instead.
    * Deserializes a UTF-8 encoded string from a byte array. It first reads the length of the string in bytes,
    * followed by the actual byte content, and decodes it into a string.
    *
@@ -101,44 +102,66 @@ export class Deserializer {
   }
 
   /**
-   * Deserializes an optional string.
+   * Deserializes an optional value from the buffer.
    *
-   * The BCS layout for Optional<String> is 0 if none, else 1 followed by the string length and string content.
-   * @returns The deserialized string if it exists, otherwise undefined.
-   * @example
-   * ```typescript
-   * const deserializer = new Deserializer(new Uint8Array([0x00]));
-   * assert(deserializer.deserializeOptionStr() === undefined);
-   * const deserializer = new Deserializer(new Uint8Array([1, 8, 49, 50, 51, 52, 97, 98, 99, 100]));
-   * assert(deserializer.deserializeOptionStr() === "1234abcd");
-   * ```
-   */
-  deserializeOptionStr(): string | undefined {
-    const exists = this.deserializeBool();
-    return exists ? this.deserializeStr() : undefined;
-  }
-
-  /**
-   * Deserializes an optional deserializable class.
+   * The BCS layout for Optional<T> starts with a boolean byte (0 if none, 1 if some),
+   * followed by the value if present.
+   *
+   * @template T - The type of the value to deserialize
+   * @param type - Either a Deserializable class or one of the string literals: "string", "bytes", or "fixedBytes"
+   * @param len - Required length when type is "fixedBytes", ignored otherwise
+   * @returns The deserialized value if present, undefined otherwise
    *
-   * BCS layout for Optional<T>: 0 if none, else 1 | BCS representation of class.
+   * @throws {Error} When "fixedBytes" is specified without a length
    *
    * @example
-   * const deserializer = new Deserializer(new Uint8Array([1, 2, 3]));
-   * const value = deserializer.deserializeOption(MyClass); // where MyClass has a `deserialize` function
-   * // value is now an instance of MyClass
+   * ```typescript
+   * // Deserialize an optional string
+   * const deserializer = new Deserializer(new Uint8Array([1, 3, 97, 98, 99]));
+   * const optStr = deserializer.deserializeOption("string");
+   * // optStr === "abc"
    *
+   * // Deserialize an optional custom type
    * const deserializer = new Deserializer(new Uint8Array([0]));
-   * const value = deserializer.deserializeOption(MyClass); // where MyClass has a `deserialize` function
-   * // value is undefined
-   *
-   * @param cls The BCS-deserializable class to deserialize the buffered bytes into.
-   *
-   * @returns The deserialized value of class type T or undefined if no value exists.
+   * const optValue = deserializer.deserializeOption(MyClass);
+   * // optValue === undefined
+   *
+   * // Deserialize optional bytes
+   * const deserializer = new Deserializer(new Uint8Array([1, 3, 1, 2, 3]));
+   * const optBytes = deserializer.deserializeOption("bytes");
+   * // optBytes === Uint8Array[1, 2, 3]
+   *
+   * // Deserialize optional fixed bytes
+   * const deserializer = new Deserializer(new Uint8Array([1, 1, 2, 3, 4]));
+   * const optBytes = deserializer.deserializeOption("fixedBytes", 4);
+   * // optBytes === Uint8Array[1, 2, 3, 4]
+   * ```
    */
-  deserializeOption<T>(cls: Deserializable<T>): T | undefined {
+  deserializeOption(type: "string"): string | undefined;
+  deserializeOption(type: "bytes"): Uint8Array | undefined;
+  deserializeOption(type: "fixedBytes", len: number): Uint8Array | undefined;
+  deserializeOption<T>(type: Deserializable<T>): T | undefined;
+  deserializeOption<T>(
+    type: Deserializable<T> | "string" | "bytes" | "fixedBytes",
+    len?: number,
+  ): T | string | Uint8Array | undefined {
     const exists = this.deserializeBool();
-    return exists ? this.deserialize(cls) : undefined;
+    if (!exists) return undefined;
+
+    if (type === "string") {
+      return this.deserializeStr();
+    }
+    if (type === "bytes") {
+      return this.deserializeBytes();
+    }
+    if (type === "fixedBytes") {
+      if (len === undefined) {
+        throw new Error("Fixed bytes length not provided");
+      }
+      return this.deserializeFixedBytes(len);
+    }
+
+    return this.deserialize(type);
   }
 
   /**

package/src/bcs/serializable/moveStructs.ts

@@ -42,8 +42,7 @@ import { EntryFunctionArgument, TransactionArgument } from "../../transactions/i
  * const vecOfStrings = new MoveVector([new MoveString("hello"), new MoveString("world")]);
  * const vecOfStrings2 = MoveVector.MoveString(["hello", "world"]);
  *
- * @params
- * values: an Array<T> of values where T is a class that implements Serializable
+ * @param values an Array<T> of values where T is a class that implements Serializable
  * @returns a `MoveVector<T>` with the values `values`
  */
 export class MoveVector<T extends Serializable & EntryFunctionArgument>
@@ -132,9 +131,9 @@ export class MoveVector<T extends Serializable & EntryFunctionArgument>
 
   /**
    * Factory method to generate a MoveOption<U16> from a `number` or `null`.
-   * 
-   * This method allows you to create a MoveVector that can either hold a U16 value or be empty. 
-   * 
+   *
+   * This method allows you to create a MoveVector that can either hold a U16 value or be empty.
+   *
    * @param values - The value used to fill the MoveVector. If `value` is null or undefined, the resulting MoveVector's
    * `.isSome()` method will return false.
    * @returns A MoveVector<U16> with an inner value `value`.
@@ -150,13 +149,13 @@ export class MoveVector<T extends Serializable & EntryFunctionArgument>
 
   /**
    * Factory method to generate a MoveVector<U32> from a `number` or `null`.
-   * 
-   * This method allows you to create a MoveVector that can either hold a U32 value or be empty. 
-   * 
+   *
+   * This method allows you to create a MoveVector that can either hold a U32 value or be empty.
+   *
    * @param values - The value used to fill the MoveVector. If `value` is null or undefined,
    * the resulting MoveVector's .isSome() method will return false.
    * @returns A MoveVector<U32> with an inner value `value`.
-   * 
+   *
    * @example
    * ```
    * const v = MoveVector.U32([1, 2, 3, 4]);
@@ -442,7 +441,7 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
    * MoveOption.U8(1).isSome() === true;
    * MoveOption.U8().isSome() === false;
    * MoveOption.U8(undefined).isSome() === false;
-   * @params value: the value used to fill the MoveOption. If `value` is undefined
+   * @param value the value used to fill the MoveOption. If `value` is undefined
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<U8> with an inner value `value`
    */
@@ -457,7 +456,7 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
    * MoveOption.U16(1).isSome() === true;
    * MoveOption.U16().isSome() === false;
    * MoveOption.U16(undefined).isSome() === false;
-   * @params value: the value used to fill the MoveOption. If `value` is undefined
+   * @param value the value used to fill the MoveOption. If `value` is undefined
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<U16> with an inner value `value`
    */
@@ -472,7 +471,7 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
    * MoveOption.U32(1).isSome() === true;
    * MoveOption.U32().isSome() === false;
    * MoveOption.U32(undefined).isSome() === false;
-   * @params value: the value used to fill the MoveOption. If `value` is undefined
+   * @param value the value used to fill the MoveOption. If `value` is undefined
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<U32> with an inner value `value`
    */
@@ -487,7 +486,7 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
    * MoveOption.U64(1).isSome() === true;
    * MoveOption.U64().isSome() === false;
    * MoveOption.U64(undefined).isSome() === false;
-   * @params value: the value used to fill the MoveOption. If `value` is undefined
+   * @param value the value used to fill the MoveOption. If `value` is undefined
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<U64> with an inner value `value`
    */
@@ -502,7 +501,7 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
    * MoveOption.U128(1).isSome() === true;
    * MoveOption.U128().isSome() === false;
    * MoveOption.U128(undefined).isSome() === false;
-   * @params value: the value used to fill the MoveOption. If `value` is undefined
+   * @param value the value used to fill the MoveOption. If `value` is undefined
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<U128> with an inner value `value`
    */
@@ -517,7 +516,7 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
    * MoveOption.U256(1).isSome() === true;
    * MoveOption.U256().isSome() === false;
    * MoveOption.U256(undefined).isSome() === false;
-   * @params value: the value used to fill the MoveOption. If `value` is undefined
+   * @param value the value used to fill the MoveOption. If `value` is undefined
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<U256> with an inner value `value`
    */
@@ -532,7 +531,7 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
    * MoveOption.Bool(true).isSome() === true;
    * MoveOption.Bool().isSome() === false;
    * MoveOption.Bool(undefined).isSome() === false;
-   * @params value: the value used to fill the MoveOption. If `value` is undefined
+   * @param value the value used to fill the MoveOption. If `value` is undefined
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<Bool> with an inner value `value`
    */
@@ -548,7 +547,7 @@ export class MoveOption<T extends Serializable & EntryFunctionArgument>
    * MoveOption.MoveString("").isSome() === true;
    * MoveOption.MoveString().isSome() === false;
    * MoveOption.MoveString(undefined).isSome() === false;
-   * @params value: the value used to fill the MoveOption. If `value` is undefined
+   * @param value the value used to fill the MoveOption. If `value` is undefined
    * the resulting MoveOption's .isSome() method will return false.
    * @returns a MoveOption<MoveString> with an inner value `value`
    */

package/src/bcs/serializer.ts

@@ -367,32 +367,42 @@ export class Serializer {
   }
 
   /**
-   * Serializes a BCS Serializable value into a serializer instance or handles the case when the value is undefined.
-   * This function allows you to efficiently add serialized data to the serializer's byte buffer.
+   * Serializes an optional value which can be a Serializable, string, or Uint8Array.
+   * For strings and Uint8Arrays, it uses the appropriate serialization method.
    *
-   * @param value The BCS Serializable value to serialize, or undefined if there is no value.
+   * @param value The value to serialize (Serializable, string, Uint8Array, or undefined)
+   * @param len Optional fixed length for Uint8Array serialization. If provided, uses serializeFixedBytes instead of serializeBytes
    *
    * @example
    * ```typescript
    * const serializer = new Serializer();
-   * serializer.serializeOption(new AccountAddress(...));
-   * const serializedBytes = serializer.toUint8Array();
-   * // serializedBytes is now the BCS-serialized byte representation of AccountAddress
-   *
-   * const serializer = new Serializer();
-   * serializer.serializeOption(undefined);
-   * assert(serializer.toUint8Array() === new Uint8Array([0x00]));
+   * serializer.serializeOption("hello");  // Serializes optional string
+   * serializer.serializeOption(new Uint8Array([1, 2, 3]));  // Serializes optional bytes
+   * serializer.serializeOption(new Uint8Array([1, 2, 3]), 3);  // Serializes optional fixed-length bytes
+   * serializer.serializeOption(new AccountAddress(...));  // Serializes optional Serializable
+   * serializer.serializeOption(undefined);  // Serializes none case
    * ```
    */
-  serializeOption<T extends Serializable>(value?: T): void {
+  serializeOption<T extends Serializable | string | Uint8Array>(value?: T, len?: number): void {
     const hasValue = value !== undefined;
     this.serializeBool(hasValue);
     if (hasValue) {
-      value.serialize(this);
+      if (typeof value === "string") {
+        this.serializeStr(value);
+      } else if (value instanceof Uint8Array) {
+        if (len !== undefined) {
+          this.serializeFixedBytes(value);
+        } else {
+          this.serializeBytes(value);
+        }
+      } else {
+        value.serialize(this);
+      }
     }
   }
 
   /**
+   * @deprecated use `serializeOption` instead.
    * Serializes an optional string, supporting UTF8 encoding.
    * The function encodes the existence of the string first, followed by the length and content if it exists.
    *

package/src/client/core.ts

@@ -2,10 +2,10 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { AptosConfig } from "../api/aptosConfig";
-import { AptosApiError, AptosResponse } from "./types";
 import { VERSION } from "../version";
-import { AnyNumber, AptosRequest, Client, ClientRequest, ClientResponse, MimeType } from "../types";
+import { AnyNumber, AptosRequest, AptosResponse, Client, ClientRequest, ClientResponse, MimeType } from "../types";
 import { AptosApiType } from "../utils";
+import { AptosApiError } from "../errors";
 
 /**
  * Sends a request using the specified options and returns the response.

package/src/client/get.ts

@@ -1,7 +1,6 @@
 import { AptosConfig } from "../api/aptosConfig";
 import { aptosRequest } from "./core";
-import { AptosResponse } from "./types";
-import { AnyNumber, ClientConfig, MimeType } from "../types";
+import { AptosResponse, AnyNumber, ClientConfig, MimeType } from "../types";
 import { AptosApiType } from "../utils/const";
 
 /**

package/src/client/index.ts

@@ -4,4 +4,3 @@
 export * from "./core";
 export * from "./get";
 export * from "./post";
-export * from "./types";

package/src/client/post.ts

@@ -3,8 +3,7 @@
 
 import { AptosConfig } from "../api/aptosConfig";
 import { aptosRequest } from "./core";
-import { AptosResponse } from "./types";
-import { AnyNumber, ClientConfig, MimeType } from "../types";
+import { AptosResponse, AnyNumber, ClientConfig, MimeType } from "../types";
 import { AptosApiType } from "../utils/const";
 
 /**

package/src/core/accountAddress.ts

@@ -19,6 +19,7 @@ export enum AddressInvalidReason {
   LEADING_ZERO_X_REQUIRED = "leading_zero_x_required",
   LONG_FORM_REQUIRED_UNLESS_SPECIAL = "long_form_required_unless_special",
   INVALID_PADDING_ZEROES = "INVALID_PADDING_ZEROES",
+  INVALID_PADDING_STRICTNESS = "INVALID_PADDING_STRICTNESS",
 }
 
 /**
@@ -249,7 +250,9 @@ export class AccountAddress extends Serializable implements TransactionArgument
    *
    * @throws {ParsingError} If the hex string does not start with 0x or is not in a valid format.
    *
-   * @note This function has strict parsing behavior. For relaxed behavior, please use the `fromString` function.
+   * @remarks
+   *
+   * This function has strict parsing behavior. For relaxed behavior, please use the `fromString` function.
    *
    * @see AIP-40 documentation for more details on address formats:
    * https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-40.md.
@@ -288,7 +291,7 @@ export class AccountAddress extends Serializable implements TransactionArgument
   /**
    * NOTE: This function has relaxed parsing behavior. For strict behavior, please use
    * the `fromStringStrict` function. Where possible use `fromStringStrict` rather than this
-   * function, `fromString` is only provided for backwards compatibility.
+   * function, `fromString`.
    *
    * Creates an instance of AccountAddress from a hex string.
    *
@@ -296,23 +299,24 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * following formats are accepted:
    *
    * - LONG, with or without leading 0x
-   * - SHORT, with or without leading 0x
+   * - SHORT*, with or without leading 0x
    *
    * Where:
    * - LONG is 64 hex characters.
-   * - SHORT is 1 to 63 hex characters inclusive.
+   * - SHORT* is 1 to 63 hex characters inclusive. The address can have missing values up to `maxMissingChars` before it is padded.
    * - Padding zeroes are allowed, e.g. 0x0123 is valid.
    *
    * Learn more about the different address formats by reading AIP-40:
    * https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-40.md.
    *
-   * @param input - A hex string representing an account address.
+   * @param input A hex string representing an account address.
+   * @param args.maxMissingChars The number of characters that can be missing in a padded address before it is invalid.
    *
    * @returns An instance of AccountAddress.
    *
    * @throws ParsingError if the hex string is too short, too long, or contains invalid characters.
    */
-  static fromString(input: string): AccountAddress {
+  static fromString(input: string, { maxMissingChars = 4 }: { maxMissingChars?: number } = {}): AccountAddress {
     let parsedInput = input;
     // Remove leading 0x for parsing.
     if (input.startsWith("0x")) {
@@ -335,6 +339,14 @@ export class AccountAddress extends Serializable implements TransactionArgument
       );
     }
 
+    // Ensure that the maxMissingChars is between or equal to 0 and 63.
+    if (maxMissingChars > 63 || maxMissingChars < 0) {
+      throw new ParsingError(
+        `maxMissingChars must be between or equal to 0 and 63. Received ${maxMissingChars}`,
+        AddressInvalidReason.INVALID_PADDING_STRICTNESS,
+      );
+    }
+
     let addressBytes: Uint8Array;
     try {
       // Pad the address with leading zeroes, so it is 64 chars long and then convert
@@ -347,7 +359,21 @@ export class AccountAddress extends Serializable implements TransactionArgument
       throw new ParsingError(`Hex characters are invalid: ${error?.message}`, AddressInvalidReason.INVALID_HEX_CHARS);
     }
 
-    return new AccountAddress(addressBytes);
+    const address = new AccountAddress(addressBytes);
+
+    // Cannot pad the address if it has more than maxMissingChars missing.
+    if (parsedInput.length < 64 - maxMissingChars) {
+      if (!address.isSpecial()) {
+        throw new ParsingError(
+          `Hex string is too short, must be ${64 - maxMissingChars} to 64 chars long, excluding the leading 0x. You may need to fix 
+the addresss by padding it with 0s before passing it to \`fromString\` (e.g. <addressString>.padStart(64, '0')). 
+Received ${input}`,
+          AddressInvalidReason.TOO_SHORT,
+        );
+      }
+    }
+
+    return address;
   }
 
   /**
@@ -357,10 +383,11 @@ export class AccountAddress extends Serializable implements TransactionArgument
    *
    * @param input - The input to convert into an AccountAddress. This can be a string representation of an address, a Uint8Array,
    * or an existing AccountAddress.
+   * @param args.maxMissingChars The number of characters that can be missing in a padded address before it is invalid.
    */
-  static from(input: AccountAddressInput): AccountAddress {
+  static from(input: AccountAddressInput, { maxMissingChars = 4 }: { maxMissingChars?: number } = {}): AccountAddress {
     if (typeof input === "string") {
-      return AccountAddress.fromString(input);
+      return AccountAddress.fromString(input, { maxMissingChars });
     }
     if (input instanceof Uint8Array) {
       return new AccountAddress(input);