@fhevm/sdk 1.1.0-alpha.6 → 1.1.0-alpha.8

package/core/kms/fetchKmsSigncryptedSharesV2-p.ts

@@ -0,0 +1,176 @@
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import type { KmsSigncryptedShare, KmsSigncryptedSharesMetadata } from '../types/kms-p.js';
+import type { KmsSigncryptedShares } from '../types/kms.js';
+import type { KmsSignersContext } from '../types/kmsSignersContext.js';
+import type { ChecksummedAddress, Uint64BigInt } from '../types/primitives.js';
+import type { FhevmChain } from '../types/fhevmChain.js';
+import type { RelayerUserDecryptOptions } from '../types/relayer.js';
+import type { SignedDecryptionPermit, SignedDecryptionPermitV2 } from '../types/signedDecryptionPermit.js';
+import type { Handle } from '../types/encryptedTypes-p.js';
+import { assertHandlesBelongToSameChainId } from '../handle/FhevmHandle.js';
+import { createKmsSigncryptedShares } from './KmsSigncryptedShares-p.js';
+import { readCurrentKmsSignersContext } from '../host-contracts/readKmsSignersContext-p.js';
+import { assertIsSignedDecryptionPermit } from './SignedDecryptionPermit-p.js';
+import { assertKmsDecryptionBitLimit } from './utils.js';
+import { checkPersistAllowed } from '../host-contracts/checkPersistAllowed.js';
+import { checkDelegation } from '../host-contracts/checkDelegation.js';
+import { assertExtraDataMatchesKmsSingersContext } from '../host-contracts/KmsSignersContext-p.js';
+import { createKmsEip712Domain } from './createKmsEip712Domain.js';
+import { resolveFhevmTkmsVersion } from '../runtime/resolveFhevmVersions-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly chain: FhevmChain;
+  readonly client: NonNullable<object>;
+  readonly options: { readonly batchRpcCalls: boolean };
+};
+
+type Parameters = {
+  readonly pairs: ReadonlyArray<{
+    readonly handle: Handle;
+    readonly contractAddress: ChecksummedAddress;
+    // When omitted, defaults to userAddress (direct-access path).
+    // Provide explicitly only for delegated handles where ownerAddress !== userAddress.
+    readonly ownerAddress?: ChecksummedAddress | undefined;
+  }>;
+  readonly signedPermit: SignedDecryptionPermit;
+  readonly options?: RelayerUserDecryptOptions | undefined;
+};
+
+type ReturnType = KmsSigncryptedShares;
+
+////////////////////////////////////////////////////////////////////////////////
+// fetchKmsSigncryptedSharesV2
+////////////////////////////////////////////////////////////////////////////////
+
+export async function fetchKmsSigncryptedSharesV2(context: Context, parameters: Parameters): Promise<ReturnType> {
+  const { options, pairs } = parameters;
+  const signedPermit = parameters.signedPermit as SignedDecryptionPermitV2;
+
+  const tkmsVersion = await resolveFhevmTkmsVersion(context);
+
+  const relayerOptions = {
+    auth: context.runtime.config.auth,
+    ...options,
+  };
+
+  assertIsSignedDecryptionPermit(signedPermit, {});
+
+  const { signerAddress, signature } = signedPermit;
+  const userAddress = signedPermit.eip712.message.userAddress;
+
+  // 1. Check: At least one handle/contract pair is required
+  if (pairs.length === 0) {
+    throw Error(
+      `encrypted value/contract pairs must not be empty, at least one encrypted value/contract pair is required`,
+    );
+  }
+
+  // Resolve ownerAddress for each pair: defaults to userAddress (direct-access path)
+  // when not explicitly provided by the caller.
+  const resolvedPairs = pairs.map((p) => ({
+    handle: p.handle,
+    contractAddress: p.contractAddress,
+    ownerAddress: p.ownerAddress ?? userAddress,
+  }));
+
+  const handles = resolvedPairs.map((p) => p.handle);
+  Object.freeze(handles);
+
+  // 2. Check: All handles belong to the host chainId
+  assertHandlesBelongToSameChainId(handles, BigInt(context.chain.id) as Uint64BigInt);
+
+  // 3. Check: 2048 bits limit
+  assertKmsDecryptionBitLimit(handles);
+
+  // 4. Check: Expiration date
+  signedPermit.assertNotExpired();
+
+  // 5. Check: ACL permissions — split pairs by direct vs delegated access
+  const directPairs = resolvedPairs.filter((p) => p.ownerAddress.toLowerCase() === userAddress.toLowerCase());
+  const delegatedPairs = resolvedPairs.filter((p) => p.ownerAddress.toLowerCase() !== userAddress.toLowerCase());
+
+  if (directPairs.length > 0) {
+    await checkPersistAllowed(context, {
+      aclAddress: context.chain.fhevm.contracts.acl.address as ChecksummedAddress,
+      userAddress,
+      handleContractPairs: directPairs,
+    });
+  }
+
+  if (delegatedPairs.length > 0) {
+    // Group delegated pairs by delegator (ownerAddress): a single batch may contain
+    // handles from multiple delegators, each requiring a separate ACL delegation check.
+    const byDelegator = new Map<ChecksummedAddress, Array<(typeof delegatedPairs)[number]>>();
+    for (const pair of delegatedPairs) {
+      const group = byDelegator.get(pair.ownerAddress) ?? [];
+      group.push(pair);
+      byDelegator.set(pair.ownerAddress, group);
+    }
+    for (const [delegator, groupedPairs] of byDelegator) {
+      await checkDelegation(context, {
+        aclAddress: context.chain.fhevm.contracts.acl.address as ChecksummedAddress,
+        delegate: userAddress,
+        delegator,
+        handleContractPairs: groupedPairs,
+      });
+    }
+  }
+
+  // 6. Verify the Eip712 signature
+  // Not required because a signedPermit is guaranteed to be verified.
+
+  // 7. Fetch `KmsSignersContext` on-chain (cached)
+  // Reject the permit early if it was signed against a different KMS context.
+  //
+  // TODO: The current check is a strict byte-level comparison. A permit signed
+  // with the correct `kmsContextId` but a different `extraData` encoding format
+  // (e.g. a version change in the serialization scheme) will be rejected even
+  // though the context ID matches. Consider comparing the decoded `kmsContextId`
+  // instead of the raw `extraData` bytes.
+  const requestedKmsSignersContext: KmsSignersContext = await readCurrentKmsSignersContext(context, {
+    kmsVerifierAddress: context.chain.fhevm.contracts.kmsVerifier.address as ChecksummedAddress,
+    protocolConfigAddress: context.chain.fhevm.contracts.protocolConfig?.address as ChecksummedAddress | undefined,
+  });
+
+  assertExtraDataMatchesKmsSingersContext(
+    {
+      extraData: signedPermit.eip712.message.extraData,
+      kmsSignersContext: requestedKmsSignersContext,
+    },
+    { subject: 'Invalid permit' },
+  );
+
+  // 8. Fetch `KmsSigncryptedShares` from the relayer (unified V2 route)
+  const shares: readonly KmsSigncryptedShare[] = await context.runtime.relayer.fetchUserDecrypt(context, {
+    payload: {
+      handleContractPairs: resolvedPairs,
+      kmsDecryptEip712Message: signedPermit.eip712.message,
+      kmsDecryptEip712Signature: signature,
+    },
+    options: relayerOptions,
+  });
+
+  // 9. Build and verify the sealed validated `KmsSigncryptedShares` object
+  const sharesMetadata: KmsSigncryptedSharesMetadata = {
+    kmsSignersContext: requestedKmsSignersContext,
+    eip712Domain: createKmsEip712Domain({
+      chainId: context.chain.fhevm.gateway.id,
+      verifyingContractAddressDecryption: context.chain.fhevm.gateway.contracts.decryption.address,
+    }),
+    eip712Signature: signature,
+    eip712SignerAddress: signerAddress,
+    handles,
+    tkmsVersion,
+  };
+
+  // 10. The returned KmsSigncryptedShares is guaranteed to be fully verified:
+  // uniform extraData across shares, valid extraData format, and consistency
+  // with the KmsSignersContext (see KmsSigncryptedSharesImpl invariants).
+  return await createKmsSigncryptedShares(context, {
+    metadata: sharesMetadata,
+    shares,
+  });
+}

package/core/kms/{kmsDelegatedUserDecryptEip712Types.ts → kmsDelegatedUserDecryptEip712V1Types.ts}

@@ -1,10 +1,11 @@
-import type { KmsDelegateUserDecryptEip712Types } from '../types/kms.js';
+import type { KmsDelegatedUserDecryptEip712V1Types } from '../types/kms.js';
 
 ////////////////////////////////////////////////////////////////////////////////
-// KmsDelegateUserDecryptEIP712Types
+// KmsDelegatedUserDecryptEip712V1Types
 ////////////////////////////////////////////////////////////////////////////////
 
-export const kmsDelegatedUserDecryptEip712Types: KmsDelegateUserDecryptEip712Types = {
+// Careful: do not change any fields in this structure
+export const kmsDelegatedUserDecryptEip712V1Types: KmsDelegatedUserDecryptEip712V1Types = {
   EIP712Domain: [
     { name: 'name', type: 'string' },
     { name: 'version', type: 'string' },
@@ -24,8 +25,8 @@ export const kmsDelegatedUserDecryptEip712Types: KmsDelegateUserDecryptEip712Typ
   ] as const,
 } as const;
 
-Object.freeze(kmsDelegatedUserDecryptEip712Types);
-Object.freeze(kmsDelegatedUserDecryptEip712Types.EIP712Domain);
-Object.freeze(kmsDelegatedUserDecryptEip712Types.DelegatedUserDecryptRequestVerification);
-kmsDelegatedUserDecryptEip712Types.EIP712Domain.forEach(Object.freeze);
-kmsDelegatedUserDecryptEip712Types.DelegatedUserDecryptRequestVerification.forEach(Object.freeze);
+Object.freeze(kmsDelegatedUserDecryptEip712V1Types);
+Object.freeze(kmsDelegatedUserDecryptEip712V1Types.EIP712Domain);
+Object.freeze(kmsDelegatedUserDecryptEip712V1Types.DelegatedUserDecryptRequestVerification);
+kmsDelegatedUserDecryptEip712V1Types.EIP712Domain.forEach(Object.freeze);
+kmsDelegatedUserDecryptEip712V1Types.DelegatedUserDecryptRequestVerification.forEach(Object.freeze);

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/kmsPublicDecryptEip712Types.ts

@@ -1,7 +1,7 @@
 import type { KmsPublicDecryptEip712Types } from '../types/kms.js';
 
 ////////////////////////////////////////////////////////////////////////////////
-// KmsPublicDecryptEIP712Types
+// KmsPublicDecryptEip712Types
 ////////////////////////////////////////////////////////////////////////////////
 
 export const kmsPublicDecryptEip712Types: KmsPublicDecryptEip712Types = {

package/core/kms/{kmsUserDecryptEip712Types.ts → kmsUserDecryptEip712V1Types.ts}

@@ -1,10 +1,11 @@
-import type { KmsUserDecryptEip712Types } from '../types/kms.js';
+import type { KmsUserDecryptEip712V1Types } from '../types/kms.js';
 
 ////////////////////////////////////////////////////////////////////////////////
-// KmsUserDecryptEIP712Types
+// KmsUserDecryptEip712V1Types
 ////////////////////////////////////////////////////////////////////////////////
 
-export const kmsUserDecryptEip712Types: KmsUserDecryptEip712Types = {
+// Careful: do not change any fields in this structure
+export const kmsUserDecryptEip712V1Types: KmsUserDecryptEip712V1Types = {
   EIP712Domain: [
     { name: 'name', type: 'string' },
     { name: 'version', type: 'string' },
@@ -23,8 +24,8 @@ export const kmsUserDecryptEip712Types: KmsUserDecryptEip712Types = {
   ] as const,
 } as const;
 
-Object.freeze(kmsUserDecryptEip712Types);
-Object.freeze(kmsUserDecryptEip712Types.EIP712Domain);
-Object.freeze(kmsUserDecryptEip712Types.UserDecryptRequestVerification);
-kmsUserDecryptEip712Types.EIP712Domain.forEach(Object.freeze);
-kmsUserDecryptEip712Types.UserDecryptRequestVerification.forEach(Object.freeze);
+Object.freeze(kmsUserDecryptEip712V1Types);
+Object.freeze(kmsUserDecryptEip712V1Types.EIP712Domain);
+Object.freeze(kmsUserDecryptEip712V1Types.UserDecryptRequestVerification);
+kmsUserDecryptEip712V1Types.EIP712Domain.forEach(Object.freeze);
+kmsUserDecryptEip712V1Types.UserDecryptRequestVerification.forEach(Object.freeze);

package/core/kms/kmsUserDecryptEip712V2Types.ts

@@ -1,9 +1,10 @@
 import type { KmsUserDecryptEip712V2Types } from '../types/kms.js';
 
 ////////////////////////////////////////////////////////////////////////////////
-// KmsUserDecryptEIP712V2Types (RFC-016)
+// KmsUserDecryptEip712V2Types (RFC-016)
 ////////////////////////////////////////////////////////////////////////////////
 
+// Careful: do not change any fields in this structure
 export const kmsUserDecryptEip712V2Types: KmsUserDecryptEip712V2Types = {
   EIP712Domain: [
     { name: 'name', type: 'string' },