@aptos-labs/ts-sdk 1.30.0 → 1.32.0

package/src/core/crypto/keyless.ts

@@ -1,11 +1,13 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
+// eslint-disable-next-line max-classes-per-file
 import { JwtPayload, jwtDecode } from "jwt-decode";
+import { sha3_256 } from "@noble/hashes/sha3";
 import { AccountPublicKey, PublicKey } from "./publicKey";
 import { Signature } from "./signature";
 import { Deserializer, Serializable, Serializer } from "../../bcs";
-import { Hex } from "../hex";
+import { Hex, hexToAsciiString } from "../hex";
 import {
   HexInput,
   EphemeralCertificateVariant,
@@ -20,11 +22,18 @@ import { bigIntToBytesLE, bytesToBigIntLE, hashStrToField, poseidonHash } from "
 import { AuthenticationKey } from "../authenticationKey";
 import { Proof } from "./proof";
 import { Ed25519PublicKey, Ed25519Signature } from "./ed25519";
-import { Groth16VerificationKeyResponse, KeylessConfigurationResponse } from "../../types/keyless";
+import {
+  Groth16VerificationKeyResponse,
+  KeylessConfigurationResponse,
+  MoveAnyStruct,
+  PatchedJWKsResponse,
+} from "../../types/keyless";
 import { AptosConfig } from "../../api/aptosConfig";
 import { getAptosFullNode } from "../../client";
 import { memoizeAsync } from "../../utils/memoize";
-import { AccountAddress } from "../accountAddress";
+import { AccountAddress, AccountAddressInput } from "../accountAddress";
+import { getErrorMessage } from "../../utils";
+import { KeylessError, KeylessErrorType } from "../../errors";
 
 export const EPK_HORIZON_SECS = 10000000;
 export const MAX_AUD_VAL_BYTES = 120;
@@ -282,6 +291,15 @@ export class KeylessSignature extends Signature {
     this.ephemeralSignature = ephemeralSignature;
   }
 
+  /**
+   * Get the kid of the JWT used to derive the Keyless Account used to sign.
+   *
+   * @returns the kid as a string
+   */
+  getJwkKid(): string {
+    return parseJwtHeader(this.jwtHeader).kid;
+  }
+
   serialize(serializer: Serializer): void {
     this.ephemeralCertificate.serialize(serializer);
     serializer.serializeStr(this.jwtHeader);
@@ -568,16 +586,16 @@ export class ZeroKnowledgeSig extends Signature {
   serialize(serializer: Serializer): void {
     this.proof.serialize(serializer);
     serializer.serializeU64(this.expHorizonSecs);
-    serializer.serializeOptionStr(this.extraField);
-    serializer.serializeOptionStr(this.overrideAudVal);
+    serializer.serializeOption(this.extraField);
+    serializer.serializeOption(this.overrideAudVal);
     serializer.serializeOption(this.trainingWheelsSignature);
   }
 
   static deserialize(deserializer: Deserializer): ZeroKnowledgeSig {
     const proof = ZkProof.deserialize(deserializer);
     const expHorizonSecs = Number(deserializer.deserializeU64());
-    const extraField = deserializer.deserializeOptionStr();
-    const overrideAudVal = deserializer.deserializeOptionStr();
+    const extraField = deserializer.deserializeOption("string");
+    const overrideAudVal = deserializer.deserializeOption("string");
     const trainingWheelsSignature = deserializer.deserializeOption(EphemeralSignature);
     return new ZeroKnowledgeSig({ proof, expHorizonSecs, trainingWheelsSignature, extraField, overrideAudVal });
   }
@@ -594,16 +612,15 @@ export class KeylessConfiguration {
   /**
    * The verification key used to verify Groth16 proofs on chain
    */
-  // TODO: Rename to verificationKey
-  readonly verficationKey: Groth16VerificationKey;
+  readonly verificationKey: Groth16VerificationKey;
 
   /**
    * The maximum lifespan of an ephemeral key pair.  This is configured on chain.
    */
   readonly maxExpHorizonSecs: number;
 
-  constructor(verficationKey: Groth16VerificationKey, maxExpHorizonSecs: number) {
-    this.verficationKey = verficationKey;
+  constructor(verificationKey: Groth16VerificationKey, maxExpHorizonSecs: number) {
+    this.verificationKey = verificationKey;
     this.maxExpHorizonSecs = maxExpHorizonSecs;
   }
 
@@ -624,7 +641,7 @@ export class KeylessConfiguration {
 /**
  * Represents the verification key stored on-chain used to verify Groth16 proofs.
  */
-class Groth16VerificationKey {
+export class Groth16VerificationKey {
   // The docstrings below are borrowed from ark-groth16
 
   /**
@@ -645,7 +662,7 @@ class Groth16VerificationKey {
   /**
    * The `gamma^{-1} * (beta * a_i + alpha * b_i + c_i) * H`, where H is the generator of G1
    */
-  readonly gammaAbcG1: G1Bytes[];
+  readonly gammaAbcG1: [G1Bytes, G1Bytes];
 
   /**
    * The `gamma * H`, where `H` is the generator of G2
@@ -667,6 +684,27 @@ class Groth16VerificationKey {
     this.gammaG2 = new G2Bytes(gammaG2);
   }
 
+  /**
+   * Calculates the hash of the serialized form of the verification key.
+   * This is useful for comparing verification keys or using them as unique identifiers.
+   *
+   * @returns The SHA3-256 hash of the serialized verification key as a Uint8Array
+   */
+  public hash(): Uint8Array {
+    const serializer = new Serializer();
+    this.serialize(serializer);
+    return sha3_256.create().update(serializer.toUint8Array()).digest();
+  }
+
+  serialize(serializer: Serializer): void {
+    this.alphaG1.serialize(serializer);
+    this.betaG2.serialize(serializer);
+    this.deltaG2.serialize(serializer);
+    this.gammaAbcG1[0].serialize(serializer);
+    this.gammaAbcG1[1].serialize(serializer);
+    this.gammaG2.serialize(serializer);
+  }
+
   /**
    * Converts a Groth16VerificationKeyResponse object into a Groth16VerificationKey instance.
    *
@@ -704,15 +742,64 @@ export async function getKeylessConfig(args: {
   options?: LedgerVersionArg;
 }): Promise<KeylessConfiguration> {
   const { aptosConfig } = args;
-  return memoizeAsync(
-    async () => {
-      const config = await getKeylessConfigurationResource(args);
-      const vk = await getGroth16VerificationKeyResource(args);
-      return KeylessConfiguration.create(vk, Number(config.max_exp_horizon_secs));
-    },
-    `keyless-configuration-${aptosConfig.network}`,
-    1000 * 60 * 5, // 5 minutes
-  )();
+  try {
+    return await memoizeAsync(
+      async () => {
+        const config = await getKeylessConfigurationResource(args);
+        const vk = await getGroth16VerificationKeyResource(args);
+        return KeylessConfiguration.create(vk, Number(config.max_exp_horizon_secs));
+      },
+      `keyless-configuration-${aptosConfig.network}`,
+      1000 * 60 * 5, // 5 minutes
+    )();
+  } catch (error) {
+    if (error instanceof KeylessError) {
+      throw error;
+    }
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.FULL_NODE_OTHER,
+      error,
+    });
+  }
+}
+
+/**
+ * Parses a JWT and returns the 'iss', 'aud', and 'uid' values.
+ *
+ * @param args - The arguments for parsing the JWT.
+ * @param args.jwt - The JWT to parse.
+ * @param args.uidKey - The key to use for the 'uid' value; defaults to 'sub'.
+ * @returns The 'iss', 'aud', and 'uid' values from the JWT.
+ */
+export function getIssAudAndUidVal(args: { jwt: string; uidKey?: string }): {
+  iss: string;
+  aud: string;
+  uidVal: string;
+} {
+  const { jwt, uidKey = "sub" } = args;
+  let jwtPayload: JwtPayload & { [key: string]: string };
+  try {
+    jwtPayload = jwtDecode<JwtPayload & { [key: string]: string }>(jwt);
+  } catch (error) {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWT_PARSING_ERROR,
+      details: `Failed to parse JWT - ${getErrorMessage(error)}`,
+    });
+  }
+  if (typeof jwtPayload.iss !== "string") {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWT_PARSING_ERROR,
+      details: "JWT is missing 'iss' in the payload. This should never happen.",
+    });
+  }
+  if (typeof jwtPayload.aud !== "string") {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.JWT_PARSING_ERROR,
+      details: "JWT is missing 'aud' in the payload or 'aud' is an array of values.",
+    });
+  }
+  const uidVal = jwtPayload[uidKey];
+  return { iss: jwtPayload.iss, aud: jwtPayload.aud, uidVal };
 }
 
 /**
@@ -730,14 +817,20 @@ async function getKeylessConfigurationResource(args: {
 }): Promise<KeylessConfigurationResponse> {
   const { aptosConfig, options } = args;
   const resourceType = "0x1::keyless_account::Configuration";
-  const { data } = await getAptosFullNode<{}, MoveResource<KeylessConfigurationResponse>>({
-    aptosConfig,
-    originMethod: "getKeylessConfigurationResource",
-    path: `accounts/${AccountAddress.from("0x1").toString()}/resource/${resourceType}`,
-    params: { ledger_version: options?.ledgerVersion },
-  });
-
-  return data.data;
+  try {
+    const { data } = await getAptosFullNode<{}, MoveResource<KeylessConfigurationResponse>>({
+      aptosConfig,
+      originMethod: "getKeylessConfigurationResource",
+      path: `accounts/${AccountAddress.from("0x1").toString()}/resource/${resourceType}`,
+      params: { ledger_version: options?.ledgerVersion },
+    });
+    return data.data;
+  } catch (error) {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.FULL_NODE_CONFIG_LOOKUP_ERROR,
+      error,
+    });
+  }
 }
 
 /**
@@ -755,12 +848,126 @@ async function getGroth16VerificationKeyResource(args: {
 }): Promise<Groth16VerificationKeyResponse> {
   const { aptosConfig, options } = args;
   const resourceType = "0x1::keyless_account::Groth16VerificationKey";
-  const { data } = await getAptosFullNode<{}, MoveResource<Groth16VerificationKeyResponse>>({
-    aptosConfig,
-    originMethod: "getGroth16VerificationKeyResource",
-    path: `accounts/${AccountAddress.from("0x1").toString()}/resource/${resourceType}`,
-    params: { ledger_version: options?.ledgerVersion },
-  });
-
-  return data.data;
+  try {
+    const { data } = await getAptosFullNode<{}, MoveResource<Groth16VerificationKeyResponse>>({
+      aptosConfig,
+      originMethod: "getGroth16VerificationKeyResource",
+      path: `accounts/${AccountAddress.from("0x1").toString()}/resource/${resourceType}`,
+      params: { ledger_version: options?.ledgerVersion },
+    });
+    return data.data;
+  } catch (error) {
+    throw KeylessError.fromErrorType({
+      type: KeylessErrorType.FULL_NODE_VERIFICATION_KEY_LOOKUP_ERROR,
+      error,
+    });
+  }
+}
+
+export async function getKeylessJWKs(args: {
+  aptosConfig: AptosConfig;
+  jwkAddr?: AccountAddressInput;
+  options?: LedgerVersionArg;
+}): Promise<Map<string, MoveJWK[]>> {
+  const { aptosConfig, jwkAddr, options } = args;
+  let resource: MoveResource<PatchedJWKsResponse>;
+  if (!jwkAddr) {
+    const resourceType = "0x1::jwks::PatchedJWKs";
+    const { data } = await getAptosFullNode<{}, MoveResource<PatchedJWKsResponse>>({
+      aptosConfig,
+      originMethod: "getKeylessJWKs",
+      path: `accounts/0x1/resource/${resourceType}`,
+      params: { ledger_version: options?.ledgerVersion },
+    });
+    resource = data;
+  } else {
+    const resourceType = "0x1::jwks::FederatedJWKs";
+    const { data } = await getAptosFullNode<{}, MoveResource<PatchedJWKsResponse>>({
+      aptosConfig,
+      originMethod: "getKeylessJWKs",
+      path: `accounts/${AccountAddress.from(jwkAddr).toString()}/resource/${resourceType}`,
+      params: { ledger_version: options?.ledgerVersion },
+    });
+    resource = data;
+  }
+
+  // Create a map of issuer to JWK arrays
+  const jwkMap = new Map<string, MoveJWK[]>();
+  for (const entry of resource.data.jwks.entries) {
+    const jwks: MoveJWK[] = [];
+    for (const jwkStruct of entry.jwks) {
+      const { data: jwkData } = jwkStruct.variant;
+      const deserializer = new Deserializer(Hex.fromHexInput(jwkData).toUint8Array());
+      const jwk = MoveJWK.deserialize(deserializer);
+      jwks.push(jwk);
+    }
+    jwkMap.set(hexToAsciiString(entry.issuer), jwks);
+  }
+
+  return jwkMap;
+}
+
+export class MoveJWK extends Serializable {
+  public kid: string;
+
+  public kty: string;
+
+  public alg: string;
+
+  public e: string;
+
+  public n: string;
+
+  constructor(args: { kid: string; kty: string; alg: string; e: string; n: string }) {
+    super();
+    const { kid, kty, alg, e, n } = args;
+    this.kid = kid;
+    this.kty = kty;
+    this.alg = alg;
+    this.e = e;
+    this.n = n;
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeStr(this.kid);
+    serializer.serializeStr(this.kty);
+    serializer.serializeStr(this.alg);
+    serializer.serializeStr(this.e);
+    serializer.serializeStr(this.n);
+  }
+
+  static fromMoveStruct(struct: MoveAnyStruct): MoveJWK {
+    const { data } = struct.variant;
+    const deserializer = new Deserializer(Hex.fromHexInput(data).toUint8Array());
+    return MoveJWK.deserialize(deserializer);
+  }
+
+  static deserialize(deserializer: Deserializer): MoveJWK {
+    const kid = deserializer.deserializeStr();
+    const kty = deserializer.deserializeStr();
+    const alg = deserializer.deserializeStr();
+    const n = deserializer.deserializeStr();
+    const e = deserializer.deserializeStr();
+    return new MoveJWK({ kid, kty, alg, n, e });
+  }
+}
+
+interface JwtHeader {
+  kid: string; // Key ID
+}
+/**
+ * Safely parses the JWT header.
+ * @param jwtHeader The JWT header string
+ * @returns Parsed JWT header as an object.
+ */
+export function parseJwtHeader(jwtHeader: string): JwtHeader {
+  try {
+    const header = JSON.parse(jwtHeader);
+    if (header.kid === undefined) {
+      throw new Error("JWT header missing kid");
+    }
+    return header;
+  } catch (error) {
+    throw new Error("Failed to parse JWT header.");
+  }
 }

package/src/core/crypto/privateKey.ts

@@ -1,13 +1,12 @@
-import { HexInput } from "../../types";
+/* eslint-disable max-len */
+
+import { HexInput, PrivateKeyVariants } from "../../types";
+import { Hex } from "../hex";
 import { PublicKey } from "./publicKey";
 import { Signature } from "./signature";
 
 /**
  * Represents a private key used for signing messages and deriving the associated public key.
- *
- * @method sign - Signs the given message with the private key.
- * @method publicKey - Derives the public key associated with the private key.
- * @method toUint8Array - Retrieves the private key in bytes.
  */
 export interface PrivateKey {
   /**
@@ -27,3 +26,80 @@ export interface PrivateKey {
    */
   toUint8Array(): Uint8Array;
 }
+
+export class PrivateKey {
+  /**
+   * The AIP-80 compliant prefixes for each private key type. Append this to a private key's hex representation
+   * to get an AIP-80 compliant string.
+   *
+   * [Read about AIP-80](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md)
+   */
+  public static readonly AIP80_PREFIXES = {
+    [PrivateKeyVariants.Ed25519]: "ed25519-priv-",
+    [PrivateKeyVariants.Secp256k1]: "secp256k1-priv-",
+  };
+
+  /**
+   * Format a HexInput to an AIP-80 compliant string.
+   *
+   * [Read about AIP-80](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md)
+   *
+   * @param privateKey - The HexString or Uint8Array format of the private key.
+   * @param privateKeyType - The private key type
+   */
+  public static formatPrivateKey(privateKey: HexInput, type: PrivateKeyVariants): string {
+    const aip80Prefix = PrivateKey.AIP80_PREFIXES[type];
+    return `${aip80Prefix}${Hex.fromHexInput(privateKey).toString()}`;
+  }
+
+  /**
+   * Parse a HexInput that may be a HexString, Uint8Array, or a AIP-80 compliant string to a Hex instance.
+   *
+   * [Read about AIP-80](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md)
+   *
+   * @param value - A HexString, Uint8Array, or a AIP-80 compliant string.
+   * @param privateKeyType - The private key type
+   * @param strict - If true, the value MUST be compliant with AIP-80.
+   */
+  public static parseHexInput(value: HexInput, type: PrivateKeyVariants, strict?: boolean): Hex {
+    let data: Hex;
+
+    const aip80Prefix = PrivateKey.AIP80_PREFIXES[type];
+    if (typeof value === "string") {
+      if (!strict && !value.startsWith(aip80Prefix)) {
+        // HexString input
+        data = Hex.fromHexInput(value);
+        // If the strictness is false, the user has opted into non-AIP-80 compliant private keys.
+        if (strict !== false) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            "[Aptos SDK] It is recommended that private keys are AIP-80 compliant (https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md). You can fix the private key by formatting it with `PrivateKey.formatPrivateKey(privateKey: string, type: 'ed25519' | 'secp256k1'): string`.",
+          );
+        }
+      } else if (value.startsWith(aip80Prefix)) {
+        // AIP-80 Compliant String input
+        data = Hex.fromHexString(value.split("-")[2]);
+      } else {
+        if (strict) {
+          // The value does not start with the AIP-80 prefix, and strict is true.
+          throw new Error("Invalid HexString input while parsing private key. Must AIP-80 compliant string.");
+        }
+
+        // This condition should never be reached.
+        throw new Error("Invalid HexString input while parsing private key.");
+      }
+    } else {
+      // The value is an Uint8Array
+      data = Hex.fromHexInput(value);
+      // If the strictness is false, the user has opted into non-AIP-80 compliant private keys.
+      if (strict !== false) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          "[Aptos SDK] It is recommended that private keys are parsed as AIP-80 compliant strings instead of Uint8Array (https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md). You can fix the private key by formatting it with `PrivateKey.formatPrivateKey(privateKey: Uint8Array, type: 'ed25519' | 'secp256k1'): string`.",
+        );
+      }
+    }
+
+    return data;
+  }
+}

package/src/core/crypto/secp256k1.ts

@@ -6,7 +6,7 @@ import { secp256k1 } from "@noble/curves/secp256k1";
 import { HDKey } from "@scure/bip32";
 import { Serializable, Deserializer, Serializer } from "../../bcs";
 import { Hex } from "../hex";
-import { HexInput } from "../../types";
+import { HexInput, PrivateKeyVariants } from "../../types";
 import { isValidBIP44Path, mnemonicToSeed } from "./hdKey";
 import { PrivateKey } from "./privateKey";
 import { PublicKey, VerifySignatureArgs } from "./publicKey";
@@ -17,7 +17,6 @@ import { convertSigningMessage } from "./utils";
  * Represents a Secp256k1 ECDSA public key.
  *
  * @extends PublicKey
- * @static
  * @property LENGTH - The length of the Secp256k1 public key in bytes.
  */
 export class Secp256k1PublicKey extends PublicKey {
@@ -148,12 +147,15 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
   /**
    * Create a new PrivateKey instance from a Uint8Array or String.
    *
+   * [Read about AIP-80](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md)
+   *
    * @param hexInput A HexInput (string or Uint8Array)
+   * @param strict If true, private key must AIP-80 compliant.
    */
-  constructor(hexInput: HexInput) {
+  constructor(hexInput: HexInput, strict?: boolean) {
     super();
 
-    const privateKeyHex = Hex.fromHexInput(hexInput);
+    const privateKeyHex = PrivateKey.parseHexInput(hexInput, PrivateKeyVariants.Secp256k1, strict);
     if (privateKeyHex.toUint8Array().length !== Secp256k1PrivateKey.LENGTH) {
       throw new Error(`PrivateKey length should be ${Secp256k1PrivateKey.LENGTH}`);
     }
@@ -168,7 +170,7 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    */
   static generate(): Secp256k1PrivateKey {
     const hexInput = secp256k1.utils.randomPrivateKey();
-    return new Secp256k1PrivateKey(hexInput);
+    return new Secp256k1PrivateKey(hexInput, false);
   }
 
   /**
@@ -204,7 +206,7 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
       throw new Error("Invalid key");
     }
 
-    return new Secp256k1PrivateKey(privateKey);
+    return new Secp256k1PrivateKey(privateKey, false);
   }
 
   // endregion
@@ -251,9 +253,29 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    * @returns string representation of the private key
    */
   toString(): string {
+    return this.toHexString();
+  }
+
+  /**
+   * Get the private key as a hex string with the 0x prefix.
+   *
+   * @returns string representation of the private key.
+   */
+  toHexString(): string {
     return this.key.toString();
   }
 
+  /**
+   * Get the private key as a AIP-80 compliant hex string.
+   *
+   * [Read about AIP-80](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-80.md)
+   *
+   * @returns AIP-80 compliant string representation of the private key.
+   */
+  toAIP80String(): string {
+    return PrivateKey.formatPrivateKey(this.key.toString(), PrivateKeyVariants.Secp256k1);
+  }
+
   // endregion
 
   // region Serializable
@@ -264,7 +286,7 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
 
   static deserialize(deserializer: Deserializer): Secp256k1PrivateKey {
     const bytes = deserializer.deserializeBytes();
-    return new Secp256k1PrivateKey(bytes);
+    return new Secp256k1PrivateKey(bytes, false);
   }
 
   // endregion
@@ -284,13 +306,11 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
 /**
  * Represents a signature of a message signed using a Secp256k1 ECDSA private key.
  *
- * @static
- * @readonly
- * @length The length of Secp256k1 ECDSA signatures, which is 64 bytes.
  */
 export class Secp256k1Signature extends Signature {
   /**
-   * Secp256k1 ecdsa signatures are 256-bit.
+   * Secp256k1 ecdsa signatures are 256-bit or 64 bytes
+   * @readonly
    */
   static readonly LENGTH = 64;
 

package/src/core/hex.ts

@@ -134,6 +134,51 @@ export class Hex {
     return Hex.fromHexString(hexInput);
   }
 
+  /**
+   * Converts an instance of HexInput, which can be a string or a Uint8Array, into a Uint8Array.
+   *
+   * @param hexInput - A HexInput which can be a string or Uint8Array.
+   * @returns A Uint8Array created from the provided hexInput.
+   */
+  static hexInputToUint8Array(hexInput: HexInput): Uint8Array {
+    if (hexInput instanceof Uint8Array) return hexInput;
+    return Hex.fromHexString(hexInput).toUint8Array();
+  }
+
+  /**
+   * Converts a HexInput (string or Uint8Array) to a hex string with '0x' prefix.
+   *
+   * @param hexInput - The input to convert, either a hex string (with/without '0x' prefix) or Uint8Array
+   * @returns A hex string with '0x' prefix (e.g., "0x1234")
+   *
+   * @example
+   * ```typescript
+   * Hex.hexInputToString("1234")        // returns "0x1234"
+   * Hex.hexInputToString("0x1234")      // returns "0x1234"
+   * Hex.hexInputToString(new Uint8Array([0x12, 0x34])) // returns "0x1234"
+   * ```
+   */
+  static hexInputToString(hexInput: HexInput): string {
+    return Hex.fromHexInput(hexInput).toString();
+  }
+
+  /**
+   * Converts a HexInput (string or Uint8Array) to a hex string without '0x' prefix.
+   *
+   * @param hexInput - The input to convert, either a hex string (with/without '0x' prefix) or Uint8Array
+   * @returns A hex string without '0x' prefix (e.g., "1234")
+   *
+   * @example
+   * ```typescript
+   * Hex.hexInputToStringWithoutPrefix("1234")        // returns "1234"
+   * Hex.hexInputToStringWithoutPrefix("0x1234")      // returns "1234"
+   * Hex.hexInputToStringWithoutPrefix(new Uint8Array([0x12, 0x34])) // returns "1234"
+   * ```
+   */
+  static hexInputToStringWithoutPrefix(hexInput: HexInput): string {
+    return Hex.fromHexInput(hexInput).toStringWithoutPrefix();
+  }
+
   // ===
   // Methods for checking validity.
   // ===
@@ -172,3 +217,5 @@ export class Hex {
     return this.data.every((value, index) => value === other.data[index]);
   }
 }
+
+export const hexToAsciiString = (hex: string) => new TextDecoder().decode(Hex.fromHexInput(hex).toUint8Array());