@fhevm/sdk 1.0.0-alpha.1 → 1.0.0-alpha.2

package/core/clients/decorators/decrypt.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/unified-signatures */
 import type { Fhevm, FhevmBase, FhevmExtension, OptionalNativeClient } from '../../types/coreFhevmClient.js';
 import type { FhevmRuntime, WithDecrypt } from '../../types/coreFhevmRuntime.js';
 import type { FhevmChain } from '../../types/fhevmChain.js';
@@ -8,38 +7,29 @@ import { asFhevmClientWith, assertIsFhevmClientWith } from '../../runtime/CoreFh
 import { generateTransportKeypair } from '../../kms/TransportKeypair-p.js';
 import {
   decryptValue,
-  type DecryptSelfValueParameters,
-  type DecryptDelegatedValueParameters,
+  type DecryptValueParameters,
   type DecryptValueReturnType,
 } from '../../actions/decrypt/decryptValue.js';
 import {
   decryptValues,
-  type DecryptDelegatedValuesParameters,
-  type DecryptSelfValuesParameters,
+  type DecryptValuesParameters,
   type DecryptValuesReturnType,
 } from '../../actions/decrypt/decryptValues.js';
 import {
   decryptValuesFromPairs,
-  type DecryptSelfValuesFromPairsParameters,
-  type DecryptDelegatedValuesFromPairsParameters,
+  type DecryptValuesFromPairsParameters,
   type DecryptValuesFromPairsReturnType,
 } from '../../actions/decrypt/decryptValuesFromPairs.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
 export type DecryptActions = {
-  readonly decryptValue: {
-    (parameters: DecryptSelfValueParameters): Promise<DecryptValueReturnType>;
-    (parameters: DecryptDelegatedValueParameters): Promise<DecryptValueReturnType>;
-  };
-  readonly decryptValues: {
-    (parameters: DecryptSelfValuesParameters): Promise<DecryptValuesReturnType>;
-    (parameters: DecryptDelegatedValuesParameters): Promise<DecryptValuesReturnType>;
-  };
-  readonly decryptValuesFromPairs: {
-    (parameters: DecryptSelfValuesFromPairsParameters): Promise<DecryptValuesFromPairsReturnType>;
-    (parameters: DecryptDelegatedValuesFromPairsParameters): Promise<DecryptValuesFromPairsReturnType>;
-  };
+  readonly decryptValue: (parameters: DecryptValueParameters) => Promise<DecryptValueReturnType>;
+  readonly decryptValues: (parameters: DecryptValuesParameters) => Promise<DecryptValuesReturnType>;
+
+  readonly decryptValuesFromPairs: (
+    parameters: DecryptValuesFromPairsParameters,
+  ) => Promise<DecryptValuesFromPairsReturnType>;
   readonly generateTransportKeypair: () => Promise<GenerateTransportKeypairReturnType>;
 };
 
@@ -49,15 +39,9 @@ function _decryptActions(fhevm: Fhevm<FhevmChain, WithDecrypt>): DecryptActions
   // Preserve the original action overloads on the decorated client API.
   // Runtime behavior is unchanged: this is a direct pass-through wrapper.
   return {
-    decryptValue: ((parameters) =>
-      decryptValue(fhevm, parameters as DecryptSelfValueParameters)) as DecryptActions['decryptValue'],
-    decryptValues: ((parameters) =>
-      decryptValues(fhevm, parameters as DecryptSelfValuesParameters)) as DecryptActions['decryptValues'],
-    decryptValuesFromPairs: ((parameters) =>
-      decryptValuesFromPairs(
-        fhevm,
-        parameters as DecryptSelfValuesFromPairsParameters,
-      )) as DecryptActions['decryptValuesFromPairs'],
+    decryptValue: (parameters) => decryptValue(fhevm, parameters),
+    decryptValues: (parameters) => decryptValues(fhevm, parameters),
+    decryptValuesFromPairs: (parameters) => decryptValuesFromPairs(fhevm, parameters),
     generateTransportKeypair: () => generateTransportKeypair(fhevm),
   };
 }

package/core/coprocessor/InputProof-p.ts

@@ -208,9 +208,9 @@ export function createInputProofFromInputHandles({
   // Proof format :
   // ==============
   //
-  // <len(handles)><len(signatures)><concat(handles)><concat(signatures)>
+  // <len(handles)><len(signatures)><concat(handles)><concat(signatures)><extraData>
   //
-  // size: Byte1 + Byte1 + len(handles)*Bytes32 + len(signatures)*Bytes65
+  // size: Byte1 + Byte1 + len(handles)*Bytes32 + len(signatures)*Bytes65 + BytesN(extraData)
   //
 
   let proof: string = '';

package/core/coprocessor/ZkProof-p.ts

@@ -7,6 +7,7 @@ import type {
   Uint64,
   Bytes21Hex,
   Uint8Number,
+  BytesHex,
 } from '../types/primitives.js';
 import type { ZkProofLike, ZkProof } from '../types/zkProof-p.js';
 import type { ErrorMetadataParams } from '../base/errors/ErrorBase.js';
@@ -49,27 +50,32 @@ class ZkProofImpl implements ZkProof {
   readonly #fheTypeIds: readonly FheTypeId[]; // Can be empty
   #inputHandles: InputHandle[] | undefined;
 
+  // In theory, 'extraData' is not part of the ZkProof
+  readonly #extraData: BytesHex;
+
   constructor(
     privateToken: symbol,
-    params: {
+    parameters: {
       readonly chainId: Uint64BigInt;
       readonly aclContractAddress: ChecksummedAddress;
       readonly contractAddress: ChecksummedAddress;
       readonly userAddress: ChecksummedAddress;
       readonly ciphertextWithZkProof: Bytes;
       readonly encryptionBits: readonly EncryptionBits[];
+      readonly extraData: BytesHex;
     },
   ) {
     if (privateToken !== PRIVATE_TOKEN) {
       throw new Error('Unauthorized');
     }
-    this.#chainId = params.chainId;
-    this.#aclContractAddress = params.aclContractAddress;
-    this.#contractAddress = params.contractAddress;
-    this.#userAddress = params.userAddress;
-    this.#ciphertextWithZkProof = params.ciphertextWithZkProof;
-    this.#encryptionBits = Object.freeze([...params.encryptionBits]);
+    this.#chainId = parameters.chainId;
+    this.#aclContractAddress = parameters.aclContractAddress;
+    this.#contractAddress = parameters.contractAddress;
+    this.#userAddress = parameters.userAddress;
+    this.#ciphertextWithZkProof = parameters.ciphertextWithZkProof;
+    this.#encryptionBits = Object.freeze([...parameters.encryptionBits]);
     this.#fheTypeIds = Object.freeze(this.#encryptionBits.map(fheTypeIdFromEncryptionBits));
+    this.#extraData = parameters.extraData;
     Object.freeze(this);
   }
 
@@ -145,6 +151,10 @@ class ZkProofImpl implements ZkProof {
     return this.#inputHandles;
   }
 
+  public getExtraData(): BytesHex {
+    return this.#extraData;
+  }
+
   //////////////////////////////////////////////////////////////////////////////
   // JSON
   //////////////////////////////////////////////////////////////////////////////
@@ -218,6 +228,7 @@ export function assertIsZkProof(
  */
 export async function toZkProof(
   zkProofLike: ZkProofLike,
+  extraData: BytesHex,
   options?: {
     readonly zkProofParser?: ParseTFHEProvenCompactCiphertextListModuleFunction;
     readonly copy?: boolean;
@@ -265,8 +276,9 @@ export async function toZkProof(
     aclContractAddress,
     contractAddress,
     userAddress,
-    ciphertextWithZkProof: ciphertextWithZkProof,
+    ciphertextWithZkProof,
     encryptionBits,
+    extraData,
   });
 }
 
@@ -440,7 +452,7 @@ async function _getOrParseEncryptionBits(
  * assert_eq!(handle.len(), 32);
  * ```
  *
- * @see https://github.com/zama-ai/fhevm/blob/8ffbd5906ab3d57af178e049930e3fc065c9d4b3/coprocessor/fhevm-engine/zkproof-worker/src/verifier.rs#L431
+ * @see https://github.com/zama-ai/fhevm/blob/322748569f0b5eb100b8cc1a58f691cfe88d17c4/coprocessor/fhevm-engine/zkproof-worker/src/verifier.rs#L538
  * @internal
  */
 function _computeInputHash21(

package/core/coprocessor/ZkProofBuilder-p.ts

@@ -1,4 +1,4 @@
-import type { Bytes20, Bytes32, ChecksummedAddress, UintNumber } from '../types/primitives.js';
+import type { Bytes20, Bytes32, BytesHex, ChecksummedAddress, UintNumber } from '../types/primitives.js';
 import type { ZkProof } from '../types/zkProof-p.js';
 import type { EncryptionBits, FheType } from '../types/fheType.js';
 import type { ZkProofBuilder } from '../types/zkProofBuilder.js';
@@ -18,7 +18,7 @@ import type {
 import { assert } from '../base/errors/InternalError.js';
 import { isUint64, uint256ToBytes32 } from '../base/uint.js';
 import { isAddress } from '../base/address.js';
-import { hexToBytes20 } from '../base/bytes.js';
+import { asBytesHex, hexToBytes20 } from '../base/bytes.js';
 import { ZkProofError } from '../errors/ZkProofError.js';
 import { createTypedValue, TypedValueArrayBuilder } from '../base/typedValue.js';
 import { toZkProof } from './ZkProof-p.js';
@@ -142,9 +142,11 @@ class ZkProofBuilderImpl implements ZkProofBuilder {
     {
       contractAddress,
       userAddress,
+      extraData,
     }: {
       readonly contractAddress: string;
       readonly userAddress: string;
+      readonly extraData: string;
     },
   ): Promise<ZkProof> {
     // Fetch the FheEncryptionKey (in wasm format) from the global cache.
@@ -211,11 +213,13 @@ class ZkProofBuilderImpl implements ZkProofBuilder {
 
     assert(metaData.length - chainIdBytes32.length === 60);
 
-    const ciphertextWithZKProofBytes: Uint8Array = await context.runtime.encrypt.buildWithProofPacked({
-      typedValues: [...this.#builder.build()],
-      fheEncryptionKey: fheEncryptionKeyWasm,
-      metaData,
-    });
+    const { ciphertextWithZKProofBytes, extraData: finalExtraData } =
+      await context.runtime.encrypt.buildWithProofPacked({
+        typedValues: [...this.#builder.build()],
+        fheEncryptionKey: fheEncryptionKeyWasm,
+        metaData,
+        extraData: asBytesHex(extraData),
+      });
 
     return toZkProof(
       {
@@ -226,6 +230,7 @@ class ZkProofBuilderImpl implements ZkProofBuilder {
         ciphertextWithZkProof: ciphertextWithZKProofBytes,
         encryptionBits: this.#bits,
       },
+      finalExtraData,
       { copy: false }, // Take ownership
     );
   }
@@ -273,9 +278,10 @@ export async function createZkProof(
     readonly values: readonly TypedValue[];
     readonly contractAddress: ChecksummedAddress;
     readonly userAddress: ChecksummedAddress;
+    readonly extraData: BytesHex;
   },
 ): Promise<ZkProof> {
-  const { contractAddress, userAddress, values } = parameters;
+  const { contractAddress, userAddress, values, extraData } = parameters;
 
   const builder = new ZkProofBuilderImpl(PRIVATE_TOKEN, {
     ciphertextCapacity: TFHE_ZKPROOF_CIPHERTEXT_CAPACITY,
@@ -289,6 +295,7 @@ export async function createZkProof(
   const zkProof = await builder.build(context, {
     contractAddress,
     userAddress,
+    extraData,
   });
 
   return zkProof;

package/core/coprocessor/encrypt.ts

@@ -3,7 +3,6 @@ import type { FhevmChain } from '../types/fhevmChain.js';
 import type { BytesHex, ChecksummedAddress, TypedValue } from '../types/primitives.js';
 import type { RelayerInputProofOptions } from '../types/relayer.js';
 import type { InputHandle } from '../types/encryptedTypes-p.js';
-import { asBytesHex } from '../base/bytes.js';
 import { fetchVerifiedInputProof } from './fetchVerifiedInputProof.js';
 import { createZkProof } from './ZkProofBuilder-p.js';
 
@@ -33,11 +32,10 @@ type ReturnType = {
 export async function encrypt(context: Context, parameters: Parameters): Promise<ReturnType> {
   const hardCodedExtraData = '0x00' as BytesHex;
 
-  const zkProof = await createZkProof(context, parameters);
+  const zkProof = await createZkProof(context, { ...parameters, extraData: hardCodedExtraData });
 
   const inputProof = await fetchVerifiedInputProof(context, {
     zkProof,
-    extraData: asBytesHex(hardCodedExtraData),
     options: parameters.options,
   });
 

package/core/coprocessor/fetchVerifiedInputProof.ts

@@ -1,7 +1,6 @@
 import type { RelayerInputProofOptions } from '../types/relayer.js';
 import type { FhevmChain } from '../types/fhevmChain.js';
 import type { VerifiedInputProof } from '../types/inputProof.js';
-import type { BytesHex } from '../types/primitives.js';
 import type { ZkProof } from '../types/zkProof-p.js';
 import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
 import type { InputHandle } from '../types/encryptedTypes-p.js';
@@ -22,7 +21,6 @@ type Context = {
 
 type Parameters = {
   readonly zkProof: ZkProof;
-  readonly extraData: BytesHex;
   readonly options?: RelayerInputProofOptions | undefined;
 };
 
@@ -31,7 +29,7 @@ type ReturnType = VerifiedInputProof;
 ////////////////////////////////////////////////////////////////////////////////
 
 export async function fetchVerifiedInputProof(context: Context, parameters: Parameters): Promise<ReturnType> {
-  const { zkProof, extraData, options } = parameters;
+  const { zkProof, options } = parameters;
 
   assertIsZkProof(zkProof, {});
 
@@ -52,16 +50,12 @@ export async function fetchVerifiedInputProof(context: Context, parameters: Para
 
   // 2. Request coprocessor signatures from the relayer for the given ZK proof
   const { handles: coprocessorSignedHandles, coprocessorEip712Signatures: coprocessorSignatures } =
-    await context.runtime.relayer.fetchCoprocessorSignatures(
-      { relayerUrl: context.chain.fhevm.relayerUrl, chainId: context.chain.id },
-      {
-        payload: {
-          zkProof,
-          extraData,
-        },
-        options: relayerOptions,
+    await context.runtime.relayer.fetchCoprocessorSignatures(context, {
+      payload: {
+        zkProof,
       },
-    );
+      options: relayerOptions,
+    });
 
   // 3. Check that the handles and the one in the fetch result
   // Note: this check is theoretically unnecessary
@@ -73,7 +67,7 @@ export async function fetchVerifiedInputProof(context: Context, parameters: Para
   const inputProof = createInputProofFromInputHandles({
     coprocessorEip712Signatures: coprocessorSignatures,
     inputHandles,
-    extraData,
+    extraData: zkProof.getExtraData(),
     signedHandleAccess: {
       userAddress: zkProof.userAddress,
       contractAddress: zkProof.contractAddress,

package/core/handle/FheType.ts

@@ -418,8 +418,7 @@ function _assertMinimumEncryptionBitWidth(bw: number): void {
   );
 }
 
-export function bytesToClearValueType<etype extends FheType>(fheType: etype, bytes: Bytes): ClearValueType<etype> {
-  const bn = bytesToBigInt(bytes);
+export function bigintToClearValueType<etype extends FheType>(fheType: etype, bn: bigint): ClearValueType<etype> {
   // needed to type narrowing
   const ft: FheType = fheType;
 
@@ -455,6 +454,10 @@ export function bytesToClearValueType<etype extends FheType>(fheType: etype, byt
   }
 }
 
+export function bytesToClearValueType<etype extends FheType>(fheType: etype, bytes: Bytes): ClearValueType<etype> {
+  return bigintToClearValueType(fheType, bytesToBigInt(bytes));
+}
+
 /**
  * Asserts that `value` is already the correct JS type for the given `fheTypeName`
  * and returns it narrowed. No conversion is performed.

package/core/host-contracts/KmsSignersContext-p.ts

@@ -70,7 +70,7 @@ class KmsSignersContextImpl implements KmsSignersContext {
   }
 
   public has(signer: string): boolean {
-    return this.#kmsSignersSet.has(signer);
+    return this.#kmsSignersSet.has(signer.toLowerCase());
   }
 
   public static [VERIFY_FUNC](instance: unknown, owner: FhevmRuntime): void {

package/core/kms/fetchKmsSignedcryptedShares-p.ts

@@ -157,36 +157,28 @@ export async function fetchKmsSignedcryptedShares(context: Context, parameters:
   // Safe casts: the discriminated union on parameters guarantees
   // that options type matches signedPermit type, but TS can't prove
   // it after destructuring (nested discriminant limitation).
-  const relayerUrl = context.chain.fhevm.relayerUrl;
-
   let shares: readonly KmsSigncryptedShare[];
 
   if (signedPermit.isDelegated) {
-    shares = await context.runtime.relayer.fetchDelegatedUserDecrypt(
-      { relayerUrl, chainId: context.chain.id },
-      {
-        payload: {
-          handleContractPairs,
-          kmsDecryptEip712Signer: signerAddress,
-          kmsDecryptEip712Message: signedPermit.eip712.message,
-          kmsDecryptEip712Signature: signature,
-        },
-        options: relayerOptions as RelayerDelegatedUserDecryptOptions,
+    shares = await context.runtime.relayer.fetchDelegatedUserDecrypt(context, {
+      payload: {
+        handleContractPairs,
+        kmsDecryptEip712Signer: signerAddress,
+        kmsDecryptEip712Message: signedPermit.eip712.message,
+        kmsDecryptEip712Signature: signature,
       },
-    );
+      options: relayerOptions as RelayerDelegatedUserDecryptOptions,
+    });
   } else {
-    shares = await context.runtime.relayer.fetchUserDecrypt(
-      { relayerUrl, chainId: context.chain.id },
-      {
-        payload: {
-          handleContractPairs,
-          kmsDecryptEip712Signer: signerAddress,
-          kmsDecryptEip712Message: signedPermit.eip712.message,
-          kmsDecryptEip712Signature: signature,
-        },
-        options: relayerOptions as RelayerUserDecryptOptions,
+    shares = await context.runtime.relayer.fetchUserDecrypt(context, {
+      payload: {
+        handleContractPairs,
+        kmsDecryptEip712Signer: signerAddress,
+        kmsDecryptEip712Message: signedPermit.eip712.message,
+        kmsDecryptEip712Signature: signature,
       },
-    );
+      options: relayerOptions as RelayerUserDecryptOptions,
+    });
   }
 
   // 11. Build and verify the sealed validated `KmsSigncryptedShares` object

package/core/kms/publicDecrypt.ts

@@ -74,19 +74,13 @@ export async function publicDecrypt(context: Context, parameters: Parameters): P
     orderedAbiEncodedClearValues,
     kmsPublicDecryptEIP712Signatures,
     extraData: relayerExtraData,
-  } = await context.runtime.relayer.fetchPublicDecrypt(
-    {
-      relayerUrl: context.chain.fhevm.relayerUrl,
-      chainId: context.chain.id,
+  } = await context.runtime.relayer.fetchPublicDecrypt(context, {
+    payload: {
+      orderedHandles,
+      extraData: requestedExtraData,
     },
-    {
-      payload: {
-        orderedHandles,
-        extraData: requestedExtraData,
-      },
-      options: relayerOptions,
-    },
-  );
+    options: relayerOptions,
+  });
 
   // 6. Reconcile KMS signer context using 'loose' mode
   const reconciledKmsSignersContext: KmsSignersContext = await reconcileKmsSignersContext(context, {

package/core/modules/decrypt/mock.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/require-await */
 import type { FhevmRuntime } from '../../types/coreFhevmRuntime.js';
 import type {
   DecryptAndReconstructParameters,
@@ -16,24 +15,129 @@ import type {
   DecryptModuleFactory,
   UserDecryptModuleFactory,
 } from './types.js';
+import type { CleartextEthereumModule } from '../ethereum/types-ct.js';
+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';
+
+////////////////////////////////////////////////////////////////////////////////
+
+const PRIVATE_CLEARTEXT_TKMS_LIB_TOKEN = Symbol('CleartextTKMSLib.token');
+
+////////////////////////////////////////////////////////////////////////////////
+
+function _xorUnmaskWithPublicKey(publicKey: BytesHex, maskedCleartexts: readonly bigint[]): bigint[] {
+  const hex = remove0x(publicKey);
+  if (hex.length < 64) {
+    throw new Error(`PublicKeyTooShort: publicKey has ${hex.length / 2} bytes, need >= 32`);
+  }
+  const mask = BigInt('0x' + hex.slice(0, 64));
+  return maskedCleartexts.map((c) => c ^ mask);
+}
 
 ////////////////////////////////////////////////////////////////////////////////
 // decryptAndReconstruct
 ////////////////////////////////////////////////////////////////////////////////
 
 export async function decryptAndReconstruct(
-  _runtime: FhevmRuntime,
-  _parameters: DecryptAndReconstructParameters,
+  runtime: FhevmRuntime,
+  parameters: DecryptAndReconstructParameters,
 ): Promise<DecryptAndReconstructReturnType> {
-  throw new Error('Not yet implemented');
+  const cleartextEthereumModule = runtime.ethereum as CleartextEthereumModule;
+  const { tkmsPrivateKey, shares } = parameters;
+
+  const privateKeySecp256k1 = asBytesHex(tkmsPrivateKey as unknown);
+  const publicKeySecp256k1 = cleartextEthereumModule.getPublicKey({ privateKey: privateKeySecp256k1 });
+
+  const metadata: KmsSigncryptedSharesMetadata = getMetadata(shares);
+  const sharesArray: readonly KmsSigncryptedShare[] = getShares(shares);
+
+  const firstShare = sharesArray[0];
+  if (firstShare === undefined) {
+    throw new Error('Expected at least one signcrypted share.');
+  }
+
+  const firstExtraData = firstShare.extraData;
+  for (let i = 1; i < sharesArray.length; i++) {
+    const share = sharesArray[i];
+    if (share !== undefined && share.extraData !== firstExtraData) {
+      throw new Error(
+        `Mismatched extraData across shares: share[0]="${firstExtraData}" vs share[${i}]="${share.extraData}".`,
+      );
+    }
+  }
+
+  const extraData: BytesHex = ensure0x(firstExtraData);
+  assertIsKmsExtraData(extraData, {});
+
+  for (let i = 0; i < sharesArray.length; ++i) {
+    const s = sharesArray[i];
+    if (!s) {
+      throw new Error('Internal error');
+    }
+    const recoveredAddress = await cleartextEthereumModule.recoverAddress({
+      hash: ensure0x(s.payload),
+      signature: ensure0x(s.signature),
+    });
+    if (!metadata.kmsSignersContext.has(recoveredAddress)) {
+      throw new Error(
+        `Unknown KMS signer: recovered address ${recoveredAddress} from share[${i}] is not a registered KMS signer.`,
+      );
+    }
+  }
+
+  const decoded = cleartextEthereumModule.decode({
+    encodedData: ensure0x(firstShare.payload),
+    types: ['uint256[]', 'bytes'],
+  });
+
+  if (decoded.length !== 2) {
+    throw new Error('Invalid decrypted result.');
+  }
+
+  const maskedCleartexts = decoded[0] as bigint[];
+  const signedExtraData = decoded[1] as BytesHex;
+
+  const cleartexts: bigint[] = _xorUnmaskWithPublicKey(publicKeySecp256k1, maskedCleartexts);
+
+  if (extraData !== signedExtraData) {
+    throw new Error(
+      `extraData mismatch: share extraData="${extraData}" does not match the signed payload's extraData="${signedExtraData}".`,
+    );
+  }
+
+  // 2. Build an unforgeable structure that contains the decrypted FhevmHandles
+  const orderedClearValues: readonly ClearValue[] = cleartexts.map((plaintext: bigint, idx: number) => {
+    const fhevmHandle = metadata.handles[idx];
+    if (fhevmHandle === undefined) {
+      throw new Error('Internal error');
+    }
+    return createClearValue({
+      value: bigintToClearValueType(fhevmHandle.fheType, plaintext),
+      handle: fhevmHandle,
+      originToken: PRIVATE_CLEARTEXT_TKMS_LIB_TOKEN, // origin token for authenticity assertion
+    });
+  });
+  Object.freeze(orderedClearValues);
+
+  return orderedClearValues;
 }
 
 //////////////////////////////////////////////////////////////////////////////
 // generateTkmsPrivateKey
 //////////////////////////////////////////////////////////////////////////////
 
-export async function generateTkmsPrivateKey(_runtime: FhevmRuntime): Promise<GenerateTkmsPrivateKeyReturnType> {
-  throw new Error('Not yet implemented');
+export async function generateTkmsPrivateKey(runtime: FhevmRuntime): Promise<GenerateTkmsPrivateKeyReturnType> {
+  const cleartextEthereumModule = runtime.ethereum as CleartextEthereumModule;
+  const privateKeySecp256k1 = cleartextEthereumModule.generatePrivateKey();
+  return Promise.resolve(privateKeySecp256k1 as unknown as TkmsPrivateKey);
 }
 
 //////////////////////////////////////////////////////////////////////////////
@@ -41,10 +145,14 @@ export async function generateTkmsPrivateKey(_runtime: FhevmRuntime): Promise<Ge
 //////////////////////////////////////////////////////////////////////////////
 
 export async function getTkmsPublicKeyHex(
-  _runtime: FhevmRuntime,
-  _parameters: GetTkmsPublicKeyHexParameters,
+  runtime: FhevmRuntime,
+  parameters: GetTkmsPublicKeyHexParameters,
 ): Promise<GetTkmsPublicKeyHexReturnType> {
-  throw new Error('Not yet implemented');
+  const { tkmsPrivateKey } = parameters;
+  const privateKeySecp256k1 = asBytesHex(tkmsPrivateKey as unknown);
+  const cleartextEthereumModule = runtime.ethereum as CleartextEthereumModule;
+  const publicKeySecp256k1 = cleartextEthereumModule.getPublicKey({ privateKey: privateKeySecp256k1 });
+  return Promise.resolve(publicKeySecp256k1);
 }
 
 //////////////////////////////////////////////////////////////////////////////
@@ -53,9 +161,12 @@ export async function getTkmsPublicKeyHex(
 
 export async function serializeTkmsPrivateKey(
   _runtime: FhevmRuntime,
-  _parameters: SerializeTkmsPrivateKeyParameters,
+  parameters: SerializeTkmsPrivateKeyParameters,
 ): Promise<SerializeTkmsPrivateKeyReturnType> {
-  throw new Error('Not yet implemented');
+  const { tkmsPrivateKey } = parameters;
+  const privateKeySecp256k1 = asBytesHex(tkmsPrivateKey as unknown);
+  const privateKeySecp256k1Bytes = hexToBytes(privateKeySecp256k1);
+  return Promise.resolve(privateKeySecp256k1Bytes);
 }
 
 //////////////////////////////////////////////////////////////////////////////
@@ -64,9 +175,11 @@ export async function serializeTkmsPrivateKey(
 
 export async function deserializeTkmsPrivateKey(
   _runtime: FhevmRuntime,
-  _parameters: DeserializeTkmsPrivateKeyParameters,
+  parameters: DeserializeTkmsPrivateKeyParameters,
 ): Promise<DeserializeTkmsPrivateKeyReturnType> {
-  throw new Error('Not yet implemented');
+  const { tkmsPrivateKeyBytes } = parameters;
+  const privateKeySecp256k1 = bytesToHex(tkmsPrivateKeyBytes);
+  return Promise.resolve(privateKeySecp256k1 as unknown as TkmsPrivateKey);
 }
 
 //////////////////////////////////////////////////////////////////////////////