@fhevm/sdk 0.0.1 → 1.0.0-alpha.1

package/core/modules/relayer/module/fetchCoprocessorSignatures.ts

@@ -0,0 +1,45 @@
+import type { FetchInputProofPayload } from '../../../types/relayer-p.js';
+import type { FetchInputProofResult } from '../../../types/relayer.js';
+import type {
+  FetchCoprocessorSignaturesParameters,
+  FetchCoprocessorSignaturesReturnType,
+  RelayerClient,
+} from '../types.js';
+import { bytesToHexNo0x } from '../../../base/bytes.js';
+import { removeSuffix } from '../../../base/string.js';
+import { uintToHex0x } from '../../../base/uint.js';
+import { RelayerAsyncRequest } from './RelayerAsyncRequest.js';
+
+////////////////////////////////////////////////////////////////////////////////
+// fetchCoprocessorSignatures
+////////////////////////////////////////////////////////////////////////////////
+
+export async function fetchCoprocessorSignatures(
+  relayerClient: RelayerClient,
+  parameters: FetchCoprocessorSignaturesParameters,
+): Promise<FetchCoprocessorSignaturesReturnType> {
+  const { options, payload } = parameters;
+
+  const inputProofPayload: FetchInputProofPayload = {
+    ciphertextWithInputVerification: bytesToHexNo0x(payload.zkProof.ciphertextWithZkProof),
+    contractAddress: payload.zkProof.contractAddress,
+    contractChainId: uintToHex0x(payload.zkProof.chainId),
+    extraData: payload.extraData,
+    userAddress: payload.zkProof.userAddress,
+  };
+
+  const request = new RelayerAsyncRequest({
+    relayerOperation: 'INPUT_PROOF',
+    url: `${removeSuffix(relayerClient.relayerUrl, '/')}/v2/input-proof`,
+    payload: inputProofPayload,
+    options,
+  });
+
+  const result = (await request.run()) as FetchInputProofResult;
+
+  return {
+    handles: result.handles,
+    coprocessorEip712Signatures: result.signatures,
+    extraData: result.extraData,
+  };
+}

package/core/modules/relayer/module/fetchDelegatedUserDecrypt.ts

@@ -0,0 +1,67 @@
+import type { FetchDelegatedUserDecryptPayload } from '../../../types/relayer-p.js';
+import type { FetchDelegatedUserDecryptResult } from '../../../types/relayer.js';
+import type {
+  FetchDelegatedUserDecryptParameters,
+  FetchDelegatedUserDecryptReturnType,
+  RelayerClient,
+} from '../types.js';
+import type { KmsSigncryptedShare } from '../../../types/kms-p.js';
+import { remove0x, removeSuffix } from '../../../base/string.js';
+import { RelayerAsyncRequest } from './RelayerAsyncRequest.js';
+
+//////////////////////////////////////////////////////////////////////////////
+// fetchDelegatedUserDecrypt
+//////////////////////////////////////////////////////////////////////////////
+
+export async function fetchDelegatedUserDecrypt(
+  relayerClient: RelayerClient,
+  parameters: FetchDelegatedUserDecryptParameters,
+): Promise<FetchDelegatedUserDecryptReturnType> {
+  const { options, payload } = parameters;
+
+  const firstHandleContractPair = payload.handleContractPairs[0];
+  if (firstHandleContractPair === undefined) {
+    throw new Error('Empty handle contract pairs');
+  }
+
+  // retrieve chainId using handles
+  const contractsChainId = firstHandleContractPair.handle.chainId.toString();
+
+  const relayerPayload: FetchDelegatedUserDecryptPayload = {
+    handleContractPairs: payload.handleContractPairs.map((pair) => {
+      return {
+        handle: pair.handle.bytes32Hex,
+        contractAddress: pair.contractAddress,
+      };
+    }),
+    startTimestamp: payload.kmsDecryptEip712Message.startTimestamp,
+    durationDays: payload.kmsDecryptEip712Message.durationDays,
+    contractsChainId,
+    contractAddresses: payload.kmsDecryptEip712Message.contractAddresses,
+    delegatorAddress: payload.kmsDecryptEip712Message.delegatorAddress,
+    delegateAddress: payload.kmsDecryptEip712Signer,
+    signature: remove0x(payload.kmsDecryptEip712Signature),
+    extraData: payload.kmsDecryptEip712Message.extraData,
+    publicKey: remove0x(payload.kmsDecryptEip712Message.publicKey),
+  };
+
+  const request = new RelayerAsyncRequest({
+    relayerOperation: 'DELEGATED_USER_DECRYPT',
+    url: `${removeSuffix(relayerClient.relayerUrl, '/')}/v2/delegated-user-decrypt`,
+    payload: relayerPayload,
+    options,
+  });
+
+  const result: FetchDelegatedUserDecryptResult = (await request.run()) as FetchDelegatedUserDecryptResult;
+
+  const shares: KmsSigncryptedShare[] = result.map((r) => {
+    const share: KmsSigncryptedShare = {
+      signature: r.signature,
+      payload: r.payload,
+      extraData: remove0x(r.extraData),
+    };
+    return share;
+  });
+
+  return shares;
+}

package/core/modules/relayer/module/fetchFheEncryptionKeyBytes.ts

@@ -0,0 +1,34 @@
+import type {
+  FetchFheEncryptionKeyBytesParameters,
+  FetchFheEncryptionKeyBytesReturnType,
+  RelayerClient,
+} from '../types.js';
+import { fetchFheEncryptionKeySource } from './fetchFheEncryptionKeySource.js';
+import { fetchFheEncryptionKeyBytesWithSource as fetchFheEncryptionKeyBytesWithSource_ } from '../../../key/fetchFheEncryptionKeyBytesWithSource.js';
+
+////////////////////////////////////////////////////////////////////////////////
+// fetchFheEncryptionKeyBytes
+////////////////////////////////////////////////////////////////////////////////
+
+export async function fetchFheEncryptionKeyBytes(
+  relayerClient: RelayerClient,
+  parameters: FetchFheEncryptionKeyBytesParameters,
+): Promise<FetchFheEncryptionKeyBytesReturnType> {
+  const { options } = parameters;
+
+  // 1. Ask the relayer for the URLs where the keys are hosted
+  const source = await fetchFheEncryptionKeySource(relayerClient, {
+    options,
+  });
+
+  const init: RequestInit | undefined = options?.signal !== undefined ? { signal: options.signal } : undefined;
+
+  // 2. Download the actual keys from those URLs
+  const paramsBytes = await fetchFheEncryptionKeyBytesWithSource_(source, {
+    retries: options?.fetchRetries,
+    retryDelayMs: options?.fetchRetryDelayInMilliseconds,
+    init,
+  });
+
+  return paramsBytes;
+}

package/core/modules/relayer/module/fetchFheEncryptionKeySource.ts

@@ -0,0 +1,166 @@
+import type {
+  FetchFheEncryptionKeySourceParameters,
+  FetchFheEncryptionKeySourceReturnType,
+  RelayerClient,
+} from '../types.js';
+import type { FetchKeyUrlResult } from '../../../types/relayer-p.js';
+import { setAuth } from '../../../base/auth.js';
+import { RelayerFetchError } from '../../../errors/RelayerFetchError.js';
+import { assertRecordArrayProperty, assertRecordNonNullableProperty } from '../../../base/record.js';
+import { fetchWithRetry } from '../../../base/fetch.js';
+import { sdkName, version } from '../../../_version.js';
+import { assertRecordStringArrayProperty, assertRecordStringProperty, removeSuffix } from '../../../base/string.js';
+
+////////////////////////////////////////////////////////////////////////////////
+// fetchFheEncryptionKeySource
+////////////////////////////////////////////////////////////////////////////////
+
+export async function fetchFheEncryptionKeySource(
+  relayerClient: RelayerClient,
+  parameters: FetchFheEncryptionKeySourceParameters,
+): Promise<FetchFheEncryptionKeySourceReturnType> {
+  const { options } = parameters;
+  const relayerUrl = relayerClient.relayerUrl;
+  const init = setAuth(
+    {
+      method: 'GET',
+      headers: {
+        'ZAMA-SDK-VERSION': version,
+        'ZAMA-SDK-NAME': sdkName,
+      },
+    } satisfies RequestInit,
+    options?.auth,
+  );
+
+  const url = `${removeSuffix(relayerUrl, '/')}/v2/keyurl`;
+
+  let response;
+  try {
+    response = await fetchWithRetry({
+      url,
+      init,
+      retries: options?.fetchRetries,
+      retryDelayMs: options?.fetchRetryDelayInMilliseconds,
+    });
+  } catch (cause) {
+    if ((cause as { name: string }).name === 'AbortError') {
+      throw cause;
+    }
+    _throwFetchError({
+      url,
+      message: `Fetch ${url} failed!`,
+      cause,
+    });
+  }
+
+  if (!response.ok) {
+    _throwFetchError({
+      url,
+      message: `HTTP error! status: ${response.status} on ${response.url}`,
+    });
+  }
+
+  let json;
+  try {
+    json = (await response.json()) as unknown;
+  } catch (e) {
+    _throwFetchError({
+      url,
+      message: 'JSON parsing failed.',
+      cause: e,
+    });
+  }
+
+  _assertIsRelayerFetchResponseJson(url, json);
+
+  const result = json.response;
+  _assertIsFetchKeyUrlResult(result, 'response');
+
+  return {
+    publicKeySource: {
+      id: result.fheKeyInfo[0].fhePublicKey.dataId,
+      url: result.fheKeyInfo[0].fhePublicKey.urls[0],
+    },
+    crsSource: {
+      id: result.crs[2048].dataId,
+      url: result.crs[2048].urls[0],
+      capacity: 2048,
+    },
+    metadata: {
+      relayerUrl,
+      chainId: relayerClient.chainId,
+    },
+  };
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+function _throwFetchError(params: { url: string; message: string; cause?: unknown }): never {
+  throw new RelayerFetchError({
+    url: params.url,
+    fetchMethod: 'GET',
+    operation: 'KEY_URL',
+    retryCount: 0,
+    elapsed: 0,
+    message: params.message,
+    cause: params.cause,
+  });
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// Asserts
+////////////////////////////////////////////////////////////////////////////////
+
+function _assertIsRelayerFetchResponseJson(url: string, json: unknown): asserts json is { response: unknown } {
+  if (json === undefined || json === null || typeof json !== 'object') {
+    _throwFetchError({
+      url,
+      message: 'Unexpected response JSON.',
+    });
+  }
+  if (!('response' in json && json.response !== null && json.response !== undefined)) {
+    _throwFetchError({
+      url,
+      message: "Unexpected response JSON format: missing 'response' property.",
+    });
+  }
+}
+
+function _assertIsFetchKeyUrlResult(value: unknown, valueName: string): asserts value is FetchKeyUrlResult {
+  // value.fheKeyInfo (array)
+  assertRecordArrayProperty(value, 'fheKeyInfo', valueName, {});
+  if (value.fheKeyInfo.length !== 1) {
+    throw new Error(`Unexpected 'fheKeyInfo' array length.`);
+  }
+
+  const fheKeyInfo = value.fheKeyInfo[0];
+  const fheKeyInfoName = `${valueName}.fheKeyInfo[0]`;
+
+  // value.fheKeyInfo[0].fhePublicKey (record)
+  assertRecordNonNullableProperty(fheKeyInfo, 'fhePublicKey', fheKeyInfoName, {});
+
+  const fhePublicKey = fheKeyInfo.fhePublicKey;
+  const fhePublicKeyName = `${fheKeyInfoName}.fhePublicKey`;
+
+  // value.fheKeyInfo[0].fhePublicKey.dataId (string)
+  assertRecordStringProperty(fhePublicKey, 'dataId', fhePublicKeyName, {});
+  // value.fheKeyInfo[0].fhePublicKey.urls (string[])
+  assertRecordStringArrayProperty(fhePublicKey, 'urls', fhePublicKeyName, {});
+  if (fhePublicKey.urls.length !== 1) {
+    throw new Error(`Unexpected '${fhePublicKeyName}.urls' array length.`);
+  }
+
+  // value.crs (record)
+  assertRecordNonNullableProperty(value, 'crs', valueName, {});
+  // value.crs[2048] (record)
+  assertRecordNonNullableProperty(value.crs, '2048', `${valueName}.crs`, {});
+  // value.crs[2048].dataId (record)
+  assertRecordStringProperty(value.crs[2048], 'dataId', `${valueName}.crs[2048]`, {});
+  // value.crs[2048].urls (string[])
+  assertRecordStringArrayProperty(value.crs[2048], 'urls', `${valueName}.crs[2048]`, {});
+  if (value.crs[2048].urls.length !== 1) {
+    throw new Error(`Unexpected '${valueName}.crs[2048].urls' array length.`);
+  }
+}
+
+////////////////////////////////////////////////////////////////////////////////

package/core/modules/relayer/module/fetchPublicDecrypt.ts

@@ -0,0 +1,40 @@
+import type { Bytes65Hex, BytesHex } from '../../../types/primitives.js';
+import type { RelayerFetchPublicDecryptPayload } from '../../../types/relayer-p.js';
+import type { FetchPublicDecryptResult } from '../../../types/relayer.js';
+import type { FetchPublicDecryptParameters, FetchPublicDecryptReturnType, RelayerClient } from '../types.js';
+import { ensure0x, removeSuffix } from '../../../base/string.js';
+import { RelayerAsyncRequest } from './RelayerAsyncRequest.js';
+
+//////////////////////////////////////////////////////////////////////////////
+// fetchPublicDecrypt
+//////////////////////////////////////////////////////////////////////////////
+
+export async function fetchPublicDecrypt(
+  relayerClient: RelayerClient,
+  parameters: FetchPublicDecryptParameters,
+): Promise<FetchPublicDecryptReturnType> {
+  const { options, payload } = parameters;
+
+  // Convert payload argument to relayer payload
+  const p: RelayerFetchPublicDecryptPayload = {
+    ciphertextHandles: payload.orderedHandles.map((h) => {
+      return h.bytes32Hex;
+    }),
+    extraData: payload.extraData,
+  };
+
+  const request = new RelayerAsyncRequest({
+    relayerOperation: 'PUBLIC_DECRYPT',
+    url: `${removeSuffix(relayerClient.relayerUrl, '/')}/v2/public-decrypt`,
+    payload: p,
+    options,
+  });
+
+  const result = (await request.run()) as FetchPublicDecryptResult;
+
+  return {
+    orderedAbiEncodedClearValues: ensure0x(result.decryptedValue) as BytesHex,
+    kmsPublicDecryptEIP712Signatures: result.signatures.map(ensure0x) as Bytes65Hex[],
+    extraData: result.extraData,
+  };
+}

package/core/modules/relayer/module/fetchUserDecrypt.ts

@@ -0,0 +1,65 @@
+import type { KmsSigncryptedShare } from '../../../types/kms-p.js';
+import type { Bytes65HexNo0x } from '../../../types/primitives.js';
+import type { FetchUserDecryptPayload } from '../../../types/relayer-p.js';
+import type { FetchUserDecryptResult } from '../../../types/relayer.js';
+import type { FetchUserDecryptParameters, FetchUserDecryptReturnType, RelayerClient } from '../types.js';
+import { remove0x, removeSuffix } from '../../../base/string.js';
+import { RelayerAsyncRequest } from './RelayerAsyncRequest.js';
+
+//////////////////////////////////////////////////////////////////////////////
+// fetchUserDecrypt
+//////////////////////////////////////////////////////////////////////////////
+
+export async function fetchUserDecrypt(
+  relayerClient: RelayerClient,
+  parameters: FetchUserDecryptParameters,
+): Promise<FetchUserDecryptReturnType> {
+  const { options, payload } = parameters;
+
+  const firstHandleContractPair = payload.handleContractPairs[0];
+  if (firstHandleContractPair === undefined) {
+    throw new Error('Empty handle contract pairs');
+  }
+
+  // retrieve chainId using handles
+  const contractsChainId = firstHandleContractPair.handle.chainId.toString();
+
+  const relayerPayload: FetchUserDecryptPayload = {
+    handleContractPairs: payload.handleContractPairs.map((pair) => {
+      return {
+        handle: pair.handle.bytes32Hex,
+        contractAddress: pair.contractAddress,
+      };
+    }),
+    requestValidity: {
+      startTimestamp: payload.kmsDecryptEip712Message.startTimestamp,
+      durationDays: payload.kmsDecryptEip712Message.durationDays,
+    },
+    contractsChainId,
+    contractAddresses: payload.kmsDecryptEip712Message.contractAddresses,
+    userAddress: payload.kmsDecryptEip712Signer,
+    signature: remove0x(payload.kmsDecryptEip712Signature) as Bytes65HexNo0x,
+    extraData: payload.kmsDecryptEip712Message.extraData,
+    publicKey: remove0x(payload.kmsDecryptEip712Message.publicKey),
+  };
+
+  const request = new RelayerAsyncRequest({
+    relayerOperation: 'USER_DECRYPT',
+    url: `${removeSuffix(relayerClient.relayerUrl, '/')}/v2/user-decrypt`,
+    payload: relayerPayload,
+    options,
+  });
+
+  const result = (await request.run()) as FetchUserDecryptResult;
+
+  const shares: KmsSigncryptedShare[] = result.map((r) => {
+    const share: KmsSigncryptedShare = {
+      signature: r.signature,
+      payload: r.payload,
+      extraData: remove0x(r.extraData),
+    };
+    return share;
+  });
+
+  return shares;
+}

package/core/modules/relayer/module/guards/RelayerInputProofSucceeded.ts

@@ -0,0 +1,106 @@
+import type {
+  RelayerInputProofSucceeded,
+  RelayerResult200InputProofAccepted,
+  RelayerResult200InputProofRejected,
+} from '../../../../types/relayer-p.js';
+import type { ErrorMetadataParams } from '../../../../base/errors/ErrorBase.js';
+import { assertRecordNonNullableProperty } from '../../../../base/record.js';
+import { assertRecordStringProperty } from '../../../../base/string.js';
+import { assertRecordBooleanProperty } from '../../../../base/record.js';
+import {
+  assertRecordBytes32HexArrayProperty,
+  assertRecordBytesHexArrayProperty,
+  assertRecordBytesHexProperty,
+} from '../../../../base/bytes.js';
+
+/**
+ * Asserts that `value` matches the {@link RelayerInputProofSucceeded} schema:
+ * ```json
+ * {
+ *   "status": "succeeded",
+ *   "requestId": "string",
+ *   "result": {
+ *     "accepted": true,
+ *     "extraData": "0x...",
+ *     "handles": ["0x..."],
+ *     "signatures": ["0x..."]
+ *   } | {
+ *     "accepted": false,
+ *     "extraData": "0x..."
+ *   }
+ * }
+ * ```
+ */
+export function assertIsRelayerInputProofSucceeded(
+  value: unknown,
+  name: string,
+  options: ErrorMetadataParams,
+): asserts value is RelayerInputProofSucceeded {
+  type T = RelayerInputProofSucceeded;
+  assertRecordStringProperty(value, 'status' satisfies keyof T, name, {
+    expectedValue: 'succeeded' satisfies T['status'],
+    ...options,
+  });
+  assertRecordStringProperty(value, 'requestId' satisfies keyof T, name, options);
+  assertRecordNonNullableProperty(value, 'result' satisfies keyof T, name, options);
+
+  type R = RelayerInputProofSucceeded['result'];
+
+  assertRecordBooleanProperty(value.result, 'accepted' satisfies keyof R, `${name}.result`, options);
+
+  if (value.result.accepted) {
+    _assertIsRelayerResult200InputProofAccepted(value.result, `${name}.result`, options);
+  } else {
+    _assertIsRelayerResult200InputProofRejected(value.result, `${name}.result`, options);
+  }
+}
+
+/**
+ * Asserts that `value` matches the {@link RelayerResult200InputProofAccepted} schema:
+ * ```json
+ * {
+ *   "accepted": true,
+ *   "extraData": "0x...",
+ *   "handles": ["0x..."],
+ *   "signatures": ["0x..."]
+ * }
+ * ```
+ */
+function _assertIsRelayerResult200InputProofAccepted(
+  value: unknown,
+  name: string,
+  options: ErrorMetadataParams,
+): asserts value is RelayerResult200InputProofAccepted {
+  type T = RelayerResult200InputProofAccepted;
+
+  assertRecordBooleanProperty(value, 'accepted' satisfies keyof T, name, {
+    expectedValue: true,
+    ...options,
+  });
+  assertRecordBytesHexProperty(value, 'extraData' satisfies keyof T, name, options);
+  assertRecordBytes32HexArrayProperty(value, 'handles' satisfies keyof T, name, options);
+  assertRecordBytesHexArrayProperty(value, 'signatures' satisfies keyof T, name, options);
+}
+
+/**
+ * Asserts that `value` matches the {@link RelayerResult200InputProofAccepted} schema:
+ * ```json
+ * {
+ *   "accepted": false,
+ *   "extraData": "0x...",
+ * }
+ * ```
+ */
+function _assertIsRelayerResult200InputProofRejected(
+  value: unknown,
+  name: string,
+  options: ErrorMetadataParams,
+): asserts value is RelayerResult200InputProofRejected {
+  type T = RelayerResult200InputProofRejected;
+
+  assertRecordBooleanProperty(value, 'accepted' satisfies keyof T, name, {
+    expectedValue: false,
+    ...options,
+  });
+  assertRecordBytesHexProperty(value, 'extraData' satisfies keyof T, name, options);
+}

package/core/modules/relayer/module/guards/RelayerPublicDecryptSucceeded.ts

@@ -0,0 +1,59 @@
+import type { RelayerPublicDecryptSucceeded, RelayerResult200PublicDecrypt } from '../../../../types/relayer-p.js';
+import type { ErrorMetadataParams } from '../../../../base/errors/ErrorBase.js';
+import { assertRecordNonNullableProperty } from '../../../../base/record.js';
+import { assertRecordStringProperty } from '../../../../base/string.js';
+import {
+  assertRecordBytesHexNo0xArrayProperty,
+  assertRecordBytesHexNo0xProperty,
+  assertRecordBytesHexProperty,
+} from '../../../../base/bytes.js';
+
+/**
+ * Asserts that `value` matches the {@link RelayerPublicDecryptSucceeded} schema:
+ * ```json
+ * {
+ *   "status": "succeeded",
+ *   "requestId": "string",
+ *   "result": {
+ *     "signatures": ["hexNo0x..."],
+ *     "decryptedValue": "hexNo0x...",
+ *     "extraData": "0x..."
+ *   }
+ * }
+ * ```
+ */
+export function assertIsRelayerPublicDecryptSucceeded(
+  value: unknown,
+  name: string,
+  options: ErrorMetadataParams,
+): asserts value is RelayerPublicDecryptSucceeded {
+  type T = RelayerPublicDecryptSucceeded;
+  assertRecordStringProperty(value, 'status' satisfies keyof T, name, {
+    expectedValue: 'succeeded' satisfies T['status'],
+    ...options,
+  });
+  assertRecordStringProperty(value, 'requestId' satisfies keyof T, name, options);
+  assertRecordNonNullableProperty(value, 'result' satisfies keyof T, name, options);
+  _assertIsRelayerResult200PublicDecrypt(value.result, `${name}.result`, options);
+}
+
+/**
+ * Asserts that `value` matches the {@link RelayerResult200PublicDecrypt} schema:
+ * ```json
+ * {
+ *   "signatures": ["hexNo0x..."],
+ *   "decryptedValue": "hexNo0x...",
+ *   "extraData": "0x..."
+ * }
+ * ```
+ */
+function _assertIsRelayerResult200PublicDecrypt(
+  value: unknown,
+  name: string,
+  options: ErrorMetadataParams,
+): asserts value is RelayerResult200PublicDecrypt {
+  type T = RelayerResult200PublicDecrypt;
+  assertRecordBytesHexNo0xArrayProperty(value, 'signatures' satisfies keyof T, name, options);
+  assertRecordBytesHexNo0xProperty(value, 'decryptedValue' satisfies keyof T, name, options);
+  assertRecordBytesHexProperty(value, 'extraData' satisfies keyof T, name, options);
+}