@fhevm/sdk 1.1.0-alpha.7 → 1.1.0-alpha.9

package/core/kms/kmsExtraData-p.ts

@@ -0,0 +1,374 @@
+import type { Bytes32Hex, BytesHex, Uint256BigInt, Uint8Number } from '../types/primitives.js';
+import type { ErrorMetadataParams } from '../base/errors/ErrorBase.js';
+import type { HostContractVersion } from '../types/hostContract.js';
+import type { KmsExtraData } from '../types/kms-p.js';
+import { asUint256BigInt, asUint8Number } from '../base/uint.js';
+import { asBytes32Hex, assertIsBytesHex } from '../base/bytes.js';
+import { isVersionEqual, isVersionStrictlyBefore } from '../host-contracts/HostContractVersion-p.js';
+import { InvalidTypeError } from '../base/errors/InvalidTypeError.js';
+
+export const EXTRA_DATA_V0: Uint8Number = 0x00 as Uint8Number; // 0x00
+export const EXTRA_DATA_V1: Uint8Number = 0x01 as Uint8Number; // 1 version byte + 32-byte big-endian context ID = 33 bytes
+export const EXTRA_DATA_V2: Uint8Number = 0x02 as Uint8Number; // 1 version byte + 32-byte big-endian context ID + 32-byte big-endian epoch ID = 65 bytes
+
+//////////////////////////////////////////////////////////////////////////////
+
+const PRIVATE_TOKEN = Symbol('KmsExtraData.token');
+
+//////////////////////////////////////////////////////////////////////////////
+// ExtraDataImpl class
+//////////////////////////////////////////////////////////////////////////////
+
+/**
+ * @internal
+ */
+export class KmsExtraDataImpl implements KmsExtraData {
+  readonly #version: Uint8Number;
+  readonly #kmsContextId: Uint256BigInt;
+  readonly #kmsEpochId: Uint256BigInt;
+
+  constructor(
+    privateToken: symbol,
+    parameters: {
+      readonly version: Uint8Number;
+      readonly kmsContextId: Uint256BigInt;
+      readonly kmsEpochId: Uint256BigInt;
+    },
+  ) {
+    if (privateToken !== PRIVATE_TOKEN) {
+      throw new Error('Unauthorized');
+    }
+
+    this.#kmsContextId = asUint256BigInt(parameters.kmsContextId);
+    this.#kmsEpochId = asUint256BigInt(parameters.kmsEpochId);
+    this.#version = asUint8Number(parameters.version);
+
+    this.#validate();
+  }
+
+  #validate(): void {
+    switch (this.#version) {
+      case EXTRA_DATA_V0: {
+        if (this.#kmsContextId !== 0n) {
+          throw new Error('kmsContextId must be 0 for v0 kms extraData');
+        }
+        if (this.#kmsEpochId !== 0n) {
+          throw new Error('kmsEpochId must be 0 for v0 kms extraData');
+        }
+        return;
+      }
+      case EXTRA_DATA_V1: {
+        if (this.#kmsContextId === 0n) {
+          throw new Error('kmsContextId cannot be 0 for v1 kms extraData');
+        }
+        if (this.#kmsEpochId !== 0n) {
+          throw new Error('kmsEpochId must be 0 for v1 kms extraData');
+        }
+        return;
+      }
+      case EXTRA_DATA_V2: {
+        if (this.#kmsContextId === 0n) {
+          throw new Error('kmsContextId cannot be 0 for v2 kms extraData');
+        }
+        if (this.#kmsEpochId === 0n) {
+          throw new Error('kmsEpochId cannot be 0 for v2 kms extraData');
+        }
+        return;
+      }
+      default:
+        throw new Error(`Unsupported kms extraData version ${this.#version}`);
+    }
+  }
+
+  public get version(): Uint8Number {
+    return this.#version;
+  }
+
+  public get kmsContextId(): Uint256BigInt {
+    return this.#kmsContextId;
+  }
+
+  public get kmsEpochId(): Uint256BigInt {
+    return this.#kmsEpochId;
+  }
+
+  /**
+   * Encodes a KMS context into an extraData format.
+   * v0: `0x00`
+   * v1: `0x01` + 32-byte big-endian context ID.
+   * v2: `0x02` + 32-byte big-endian context ID + 32-byte big-endian epoch ID.
+   */
+  public toBytesHex(): BytesHex {
+    const v = this.#version.toString(16).padStart(2, '0');
+
+    switch (this.#version) {
+      case EXTRA_DATA_V0: {
+        return `0x${v}` as BytesHex;
+      }
+      case EXTRA_DATA_V1: {
+        const contextId = this.#kmsContextId.toString(16).padStart(64, '0');
+        return `0x${v}${contextId}` as BytesHex;
+      }
+      case EXTRA_DATA_V2: {
+        const contextId = this.#kmsContextId.toString(16).padStart(64, '0');
+        const epochId = this.#kmsEpochId.toString(16).padStart(64, '0');
+        return `0x${v}${contextId}${epochId}` as BytesHex;
+      }
+      default:
+        throw new Error(`Unsupported kms extraData version ${this.#version}`);
+    }
+  }
+}
+
+//////////////////////////////////////////////////////////////////////////////
+
+export function fromKmsExtraDataBytesHex(extraDataBytesHex: BytesHex): KmsExtraData {
+  if ((extraDataBytesHex as string) === '0x00' || (extraDataBytesHex as string) === '0x') {
+    return new KmsExtraDataImpl(PRIVATE_TOKEN, {
+      version: EXTRA_DATA_V0,
+      kmsContextId: 0n as Uint256BigInt,
+      kmsEpochId: 0n as Uint256BigInt,
+    });
+  }
+
+  if (extraDataBytesHex.length <= 4) {
+    throw new Error(`Unsupported kms extraData length ${extraDataBytesHex.length}: must be more than 4 bytes`);
+  }
+
+  // First byte = version (characters 2-3 after '0x')
+  const version = asUint8Number(Number('0x' + extraDataBytesHex.slice(2, 4)));
+
+  if (version === EXTRA_DATA_V1) {
+    // ExtraData v1 format: 1 version byte + 32-byte big-endian context ID = 33 bytes = 66 hex chars + 2 for '0x' = 68
+    // 0x01aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    // ↑   ↑                                                               ↑
+    // 0   4                                                               68
+    // 0         1         2         3         4         5         6
+    // 01234567890123456789012345678901234567890123456789012345678901234567
+
+    if (extraDataBytesHex.length != 68) {
+      throw new Error(`Invalid kms extraData length for v1: expected 68, got ${extraDataBytesHex.length}`);
+    }
+
+    // 32-byte contextId starts at byte 1 (hex chars 4..67)
+    const contextIdBytes32Hex: Bytes32Hex = asBytes32Hex(`0x${extraDataBytesHex.slice(4, 68)}`);
+    const kmsContextId = asUint256BigInt(BigInt(contextIdBytes32Hex));
+
+    return new KmsExtraDataImpl(PRIVATE_TOKEN, {
+      version: EXTRA_DATA_V1,
+      kmsContextId,
+      kmsEpochId: 0n as Uint256BigInt,
+    });
+  }
+
+  if (version === EXTRA_DATA_V2) {
+    // ExtraData v2 format: 1 version byte + 32-byte big-endian context ID + 32-byte big-endian epoch ID = 65 bytes = 130 hex chars + 2 for '0x' = 132
+    // 0x01aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+    // ↑   ↑                                                               ↑                                                               ↑
+    // 0   4                                                               68                                                              132
+    // 0         1         2         3         4         5         6         7         8         9         0         1         2         3
+    // 012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901
+
+    if (extraDataBytesHex.length != 132) {
+      throw new Error(`Invalid extraData length for v2: expected 132, got ${extraDataBytesHex.length}`);
+    }
+
+    // 32-byte contextId starts at byte 1 (hex chars 4..67)
+    const contextIdBytes32Hex: Bytes32Hex = asBytes32Hex(`0x${extraDataBytesHex.slice(4, 68)}`);
+    const kmsContextId = asUint256BigInt(BigInt(contextIdBytes32Hex));
+
+    // 32-byte epochId starts at byte 33 (hex chars 68..131)
+    const epochIdBytes32Hex: Bytes32Hex = asBytes32Hex(`0x${extraDataBytesHex.slice(68, 132)}`);
+    const kmsEpochId = asUint256BigInt(BigInt(epochIdBytes32Hex));
+
+    return new KmsExtraDataImpl(PRIVATE_TOKEN, {
+      version: EXTRA_DATA_V2,
+      kmsContextId,
+      kmsEpochId: kmsEpochId,
+    });
+  }
+
+  throw new Error(`Unsupported kms extraData version ${version}`);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createKmsExtraDataV0(): KmsExtraData {
+  return new KmsExtraDataImpl(PRIVATE_TOKEN, {
+    version: EXTRA_DATA_V0,
+    kmsContextId: 0n as Uint256BigInt,
+    kmsEpochId: 0n as Uint256BigInt,
+  });
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createKmsExtraDataV1(parameters: { readonly kmsContextId: Uint256BigInt }): KmsExtraData {
+  return new KmsExtraDataImpl(PRIVATE_TOKEN, {
+    version: EXTRA_DATA_V1,
+    kmsContextId: parameters.kmsContextId,
+    kmsEpochId: 0n as Uint256BigInt,
+  });
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createKmsExtraDataV2(parameters: {
+  readonly kmsContextId: Uint256BigInt;
+  readonly kmsEpochId: Uint256BigInt;
+}): KmsExtraData {
+  return new KmsExtraDataImpl(PRIVATE_TOKEN, {
+    version: EXTRA_DATA_V2,
+    kmsContextId: parameters.kmsContextId,
+    kmsEpochId: parameters.kmsEpochId,
+  });
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function validateKmsExtraDataParams(parameters: {
+  readonly kmsContextId: Uint256BigInt;
+  readonly kmsEpochId: Uint256BigInt;
+}): void {
+  if (parameters.kmsEpochId !== 0n && parameters.kmsContextId === 0n) {
+    throw new Error('kmsContextId cannot be 0 if kmsEpochId is not 0');
+  }
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createKmsExtraData(parameters: {
+  readonly kmsContextId: Uint256BigInt;
+  readonly kmsEpochId: Uint256BigInt;
+}): KmsExtraData {
+  validateKmsExtraDataParams(parameters);
+
+  if (parameters.kmsEpochId === 0n) {
+    if (parameters.kmsContextId === 0n) {
+      return createKmsExtraDataV0();
+    }
+    return createKmsExtraDataV1({
+      kmsContextId: parameters.kmsContextId,
+    });
+  }
+
+  return createKmsExtraDataV2({
+    kmsContextId: parameters.kmsContextId,
+    kmsEpochId: parameters.kmsEpochId,
+  });
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function equalsKmsExtraData(a: KmsExtraData, b: KmsExtraData): boolean {
+  assertIsKmsExtraData(a, {});
+  assertIsKmsExtraData(b, {});
+  return a.version === b.version && a.kmsContextId === b.kmsContextId && a.kmsEpochId === b.kmsEpochId;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Module-only helper. Narrows an unknown value to the concrete
+ * {@link KmsExtraDataImpl} class by verifying it via {@link assertIsKmsExtraData}
+ * and returning it typed as the implementation class, so other functions in this
+ * module can reach class-only members. Prefer this over a bare cast.
+ *
+ * Must never be exported: `Impl` classes are internal to the SDK and never leave
+ * the module, so a function that hands one back must stay module-private too.
+ * The public surface exposes only the {@link KmsExtraData} interface.
+ *
+ * @param value - The value to narrow.
+ * @returns The same value typed as {@link KmsExtraDataImpl}.
+ * @throws {InvalidTypeError} If `value` is not a {@link KmsExtraDataImpl} instance.
+ */
+function _asKmsExtraDataImpl(value: unknown): KmsExtraDataImpl {
+  assertIsKmsExtraData(value, {});
+  return value as KmsExtraDataImpl;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function isKmsExtraData(value: unknown): value is KmsExtraData {
+  return value instanceof KmsExtraDataImpl;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function assertIsKmsExtraData(
+  value: unknown,
+  options: { readonly subject?: string } & ErrorMetadataParams,
+): asserts value is KmsExtraData {
+  if (!isKmsExtraData(value)) {
+    throw new InvalidTypeError(
+      {
+        subject: options.subject,
+        type: typeof value,
+        expectedType: 'KmsExtraData',
+      },
+      options,
+    );
+  }
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function assertIsKmsExtraDataBytesHex(
+  value: unknown,
+  options: { subject?: string } & ErrorMetadataParams,
+): asserts value is BytesHex {
+  if (value === '0x00' || value === '0x') {
+    return;
+  }
+
+  assertIsBytesHex(value, options);
+
+  // Will valid extraData length too
+  fromKmsExtraDataBytesHex(value);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Returns `true` if `kmsExtraData`'s version is accepted by the given
+ * KMSVerifier contract version.
+ *
+ * | KMSVerifier version | protocol        | max extraData version |
+ * | ------------------- | --------------- | --------------------- |
+ * | < 0.2.0             | v0.11.0         | v0                    |
+ * | 0.2.0 – 0.3.x       | v0.12.0/v0.13.0 | v1                    |
+ * | 0.4.0               | v0.14.0         | v2                    |
+ * | > 0.4.0             | v0.14.1+        | not checked (`true`)  |
+ */
+export function isKmsExtraDataCompatibleWithKmsVerifier(
+  kmsExtraData: KmsExtraData,
+  kmsVerifierVersion: HostContractVersion,
+): boolean {
+  const ed = _asKmsExtraDataImpl(kmsExtraData);
+
+  // Protocol v0.11.0
+  if (isVersionStrictlyBefore(kmsVerifierVersion, { major: 0, minor: 2 })) {
+    return ed.version <= EXTRA_DATA_V0;
+  }
+
+  // Protocol v0.12.0/v0.13.0
+  if (isVersionStrictlyBefore(kmsVerifierVersion, { major: 0, minor: 4 })) {
+    return ed.version <= EXTRA_DATA_V1;
+  }
+
+  // Protocol v0.14.0
+  if (isVersionEqual(kmsVerifierVersion, { major: 0, minor: 4, patch: 0 })) {
+    return ed.version <= EXTRA_DATA_V2;
+  }
+
+  // Protocol v0.14.1+ (beyond the versions this SDK release knows about).
+  //
+  // We deliberately return `true` (compatible) instead of guessing an upper
+  // bound on `extraData.version`. On v0.14.0 the KMSVerifier reverts for
+  // `extraData.version > 2`, but we cannot know the accepted range of future
+  // contract versions. Pre-validating here would risk rejecting extraData that
+  // a newer contract actually supports. If the on-chain contract does reject it,
+  // the call reverts — and surfacing that revert is the source of truth, not a
+  // speculative client-side check.
+  return true;
+}

package/core/kms/publicDecrypt.ts

@@ -1,13 +1,14 @@
 import type { RelayerPublicDecryptOptions } from '../types/relayer.js';
 import type { FhevmChain } from '../types/fhevmChain.js';
-import type { BytesHex, ChecksummedAddress, Uint64BigInt } from '../types/primitives.js';
+import type { ChecksummedAddress, Uint64BigInt } from '../types/primitives.js';
 import type { PublicDecryptionProof } from '../types/publicDecryptionProof-p.js';
 import type { KmsSignersContext } from '../types/kmsSignersContext.js';
 import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
 import type { Handle } from '../types/encryptedTypes-p.js';
+import type { KmsExtraData } from '../types/kms-p.js';
 import { assertHandlesBelongToSameChainId } from '../handle/FhevmHandle.js';
 import { assertKmsDecryptionBitLimit } from '../kms/utils.js';
-import { readKmsSignersContext, reconcileKmsSignersContext } from '../host-contracts/readKmsSignersContext-p.js';
+import { readCurrentKmsSignersContext, reconcileKmsSignersContext } from '../host-contracts/readKmsSignersContext-p.js';
 import { kmsSignersContextToExtraData } from '../host-contracts/KmsSignersContext-p.js';
 import { createPublicDecryptionProof } from '../kms/PublicDecryptionProof-p.js';
 import { checkAllowedForDecryption } from '../host-contracts/checkAllowedForDecryption.js';
@@ -38,12 +39,12 @@ export async function publicDecrypt(context: Context, parameters: Parameters): P
   // Contrary to the userDecrypt flow, the publicDecrypt doesn't require for an
   // EIP-712 signature from the user, so the SDK can safely fetch the current
   // context ID and build the extraData transparently to the user.
-  const requestedKmsSignersContext = await readKmsSignersContext(context, {
+  const requestedKmsSignersContext = await readCurrentKmsSignersContext(context, {
     kmsVerifierAddress: context.chain.fhevm.contracts.kmsVerifier.address as ChecksummedAddress,
     protocolConfigAddress: context.chain.fhevm.contracts.protocolConfig?.address as ChecksummedAddress | undefined,
   });
 
-  const requestedExtraData: BytesHex = kmsSignersContextToExtraData(requestedKmsSignersContext);
+  const requestedExtraData: KmsExtraData = kmsSignersContextToExtraData(requestedKmsSignersContext);
 
   const orderedHandles = handles;
 
@@ -74,11 +75,11 @@ export async function publicDecrypt(context: Context, parameters: Parameters): P
   const {
     orderedAbiEncodedClearValues,
     kmsPublicDecryptEip712Signatures,
-    extraData: relayerExtraData,
+    extraData: relayerExtraDataBytesHex,
   } = await context.runtime.relayer.fetchPublicDecrypt(context, {
     payload: {
       orderedHandles,
-      extraData: requestedExtraData,
+      extraData: requestedExtraData.toBytesHex(),
     },
     options: relayerOptions,
   });
@@ -87,7 +88,7 @@ export async function publicDecrypt(context: Context, parameters: Parameters): P
   const reconciledKmsSignersContext: KmsSignersContext = await reconcileKmsSignersContext(context, {
     kmsVerifierAddress: context.chain.fhevm.contracts.kmsVerifier.address as ChecksummedAddress,
     protocolConfigAddress: context.chain.fhevm.contracts.protocolConfig?.address as ChecksummedAddress | undefined,
-    relayerExtraData,
+    relayerKmsExtraDataBytesHex: relayerExtraDataBytesHex,
     requestedKmsSignersContext: requestedKmsSignersContext,
     mode: 'loose',
   });

package/core/kms/verifyKmsPublicDecryptEip712-p.ts

@@ -4,10 +4,12 @@ import type { KmsPublicDecryptEip712Message } from '../types/kms.js';
 import type { KmsSignersContext } from '../types/kmsSignersContext.js';
 import type { Bytes32Hex, Bytes65Hex, BytesHex } from '../types/primitives.js';
 import type { Handle } from '../types/encryptedTypes-p.js';
+import type { KmsExtraData } from '../types/kms-p.js';
 import { recoverSigners } from '../utils-p/runtime/recoverSigners.js';
 import { assertKmsSignerThreshold, kmsSignersContextToExtraData } from '../host-contracts/KmsSignersContext-p.js';
 import { createKmsEip712Domain } from './createKmsEip712Domain.js';
 import { kmsPublicDecryptEip712Types } from './kmsPublicDecryptEip712Types.js';
+import { EXTRA_DATA_V0 } from './kmsExtraData-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
@@ -30,16 +32,16 @@ export async function verifyKmsPublicDecryptEip712(context: Context, parameters:
 
   // TODO:  use createKmsPublicDecryptEip712 instead!
 
-  const extraData: BytesHex = kmsSignersContextToExtraData(kmsSignersContext);
+  const extraData: KmsExtraData = kmsSignersContextToExtraData(kmsSignersContext);
 
   ////////////////////////////////////////////////////////////////////////////
   //
   // Warning!!!! Do not use '0x00' here!! Only '0x' is permitted!
   //
   ////////////////////////////////////////////////////////////////////////////
-  let signedExtraData: BytesHex = extraData;
-  if (extraData === ('0x00' as BytesHex)) {
-    signedExtraData = '0x' as BytesHex;
+  let signedExtraDataBytesHex: BytesHex = extraData.toBytesHex();
+  if (extraData.version === EXTRA_DATA_V0) {
+    signedExtraDataBytesHex = '0x' as BytesHex;
   }
 
   const handlesBytes32Hex: readonly Bytes32Hex[] = orderedEncryptedValues.map((h) => h.bytes32Hex);
@@ -47,7 +49,7 @@ export async function verifyKmsPublicDecryptEip712(context: Context, parameters:
   const message: KmsPublicDecryptEip712Message = {
     ctHandles: handlesBytes32Hex,
     decryptedResult: orderedAbiEncodedClearValues,
-    extraData: signedExtraData,
+    extraData: signedExtraDataBytesHex,
   };
 
   //////////////////////////////////////////////////////////////////////////////

package/core/modules/decrypt/mock.ts

@@ -17,12 +17,12 @@ import type { TkmsPrivateKey } from '../../types/tkms-p.js';
 import type { BytesHex } from '../../types/primitives.js';
 import type { KmsSigncryptedShare, KmsSigncryptedSharesMetadata } from '../../types/kms-p.js';
 import type { ClearValue } from '../../types/encryptedTypes-p.js';
-import { assertIsKmsExtraData } from '../../kms/kmsExtraData.js';
 import { ensure0x, remove0x } from '../../base/string.js';
 import { getMetadata, getShares } from '../../kms/KmsSigncryptedShares-p.js';
 import { asBytesHex, bytesToHex, hexToBytes } from '../../base/bytes.js';
 import { bigintToClearValueType } from '../../handle/FheType.js';
 import { createClearValue } from '../../handle/ClearValue.js';
+import { assertIsKmsExtraDataBytesHex } from '../../kms/kmsExtraData-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
@@ -71,8 +71,8 @@ export async function decryptAndReconstruct(
     }
   }
 
-  const extraData: BytesHex = ensure0x(firstExtraData);
-  assertIsKmsExtraData(extraData, {});
+  const extraDataBytesHex: BytesHex = ensure0x(firstExtraData);
+  assertIsKmsExtraDataBytesHex(extraDataBytesHex, {});
 
   for (let i = 0; i < sharesArray.length; ++i) {
     const s = sharesArray[i];
@@ -100,13 +100,13 @@ export async function decryptAndReconstruct(
   }
 
   const maskedCleartexts = decoded[0] as bigint[];
-  const signedExtraData = decoded[1] as BytesHex;
+  const signedExtraDataBytesHex = decoded[1] as BytesHex;
 
   const cleartexts: bigint[] = _xorUnmaskWithPublicKey(publicKeySecp256k1, maskedCleartexts);
 
-  if (extraData !== signedExtraData) {
+  if (extraDataBytesHex !== signedExtraDataBytesHex) {
     throw new Error(
-      `extraData mismatch: share extraData="${extraData}" does not match the signed payload's extraData="${signedExtraData}".`,
+      `extraData mismatch: share extraData="${extraDataBytesHex}" does not match the signed payload's extraData="${signedExtraDataBytesHex}".`,
     );
   }
 

package/core/modules/decrypt/module/api-p.ts

@@ -31,10 +31,10 @@ import { uint32ToBytes32 } from '../../../base/uint.js';
 import { createClearValue } from '../../../handle/ClearValue.js';
 import { bytesToClearValueType } from '../../../handle/FheType.js';
 import { ensure0x, remove0x } from '../../../base/string.js';
-import { assertIsKmsExtraData } from '../../../kms/kmsExtraData.js';
 import { bytesToHexLarge } from '../../../base/bytes.js';
 import { initTkmsModule } from './init-p.js';
 import { getMetadata, getShares } from '../../../kms/KmsSigncryptedShares-p.js';
+import { assertIsKmsExtraDataBytesHex } from '../../../kms/kmsExtraData-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
@@ -256,18 +256,18 @@ export async function decryptAndReconstruct(
     throw new Error('Expected at least one signcrypted share.');
   }
 
-  const firstExtraData = firstShare.extraData;
+  const firstExtraDataBytesHex = firstShare.extraData;
   for (let i = 1; i < sharesArray.length; i++) {
     const share = sharesArray[i];
-    if (share !== undefined && share.extraData !== firstExtraData) {
+    if (share !== undefined && share.extraData !== firstExtraDataBytesHex) {
       throw new Error(
-        `Mismatched extraData across shares: share[0]="${firstExtraData}" vs share[${i}]="${share.extraData}".`,
+        `Mismatched extraData across shares: share[0]="${firstExtraDataBytesHex}" vs share[${i}]="${share.extraData}".`,
       );
     }
   }
 
-  const extraData: BytesHex = ensure0x(firstExtraData);
-  assertIsKmsExtraData(extraData, {});
+  const extraDataBytesHex: BytesHex = ensure0x(firstExtraDataBytesHex);
+  assertIsKmsExtraDataBytesHex(extraDataBytesHex, {});
 
   const aggRespWasmArg: ReadonlyArray<Omit<KmsSigncryptedShare, 'extraData'> & { extra_data: BytesHexNo0x }> =
     sharesArray.map((s) => {
@@ -333,7 +333,7 @@ export async function decryptAndReconstruct(
     enc_key: remove0x(publicEncKeyMlKem512WasmBytesHex),
     ciphertext_handles: metadata.handles.map((h) => h.bytes32HexNo0x),
     eip712_verifying_contract: metadata.eip712Domain.verifyingContract,
-    extra_data: remove0x(extraData),
+    extra_data: remove0x(extraDataBytesHex),
   };
 
   //

package/core/modules/ethereum/types-ct.ts

@@ -1,4 +1,4 @@
-import type { Bytes65Hex, BytesHex, ChecksummedAddress } from '../../types/primitives.js';
+import type { Bytes32Hex, Bytes65Hex, BytesHex, ChecksummedAddress, Uint256 } from '../../types/primitives.js';
 import type { Prettify } from '../../types/utils.js';
 import type { EthereumModule } from './types.js';
 
@@ -32,6 +32,28 @@ export type SignModuleFunction = {
   sign(parameters: SignParameters): Promise<SignReturnType>;
 };
 
+////////////////////////////////////////////////////////////////////////////////
+// hashTypedData
+////////////////////////////////////////////////////////////////////////////////
+
+export type HashTypedDataParameters = Readonly<{
+  domain: {
+    readonly chainId: Uint256;
+    readonly name: string;
+    readonly verifyingContract: ChecksummedAddress;
+    readonly version: string;
+  };
+  types: Readonly<Record<string, ReadonlyArray<{ name: string; type: string }>>>;
+  primaryType: string;
+  message: Readonly<Record<string, unknown>>;
+}>;
+
+export type HashTypedDataReturnType = Bytes32Hex;
+
+export type HashTypedDataModuleFunction = {
+  hashTypedData(parameters: HashTypedDataParameters): HashTypedDataReturnType;
+};
+
 ////////////////////////////////////////////////////////////////////////////////
 // generatePrivateKey
 ////////////////////////////////////////////////////////////////////////////////
@@ -81,7 +103,8 @@ export type CleartextEthereumModule = EthereumModule &
       SignModuleFunction &
       GeneratePrivateKeyModuleFunction &
       GetPublicKeyModuleFunction &
-      RecoverAddressModuleFunction
+      RecoverAddressModuleFunction &
+      HashTypedDataModuleFunction
   >;
 
 export type CleartextEthereumModuleFactory = () => {