@cofhe/sdk 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @cofhe/sdk Changelog
 
+## 0.4.0
+
+### Patch Changes
+
+- e446642: Switch `decryptForTx` to Threshold Network v2 decrypt (submit + poll)
+
 ## 0.3.2
 
 ### Patch Changes

package/core/client.ts

@@ -250,22 +250,22 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
     },
 
     // Retrieval methods (auto-fill chainId/account)
-    getPermit: async (hash: string, chainId?: number, account?: string) => {
+    getPermit: (hash: string, chainId?: number, account?: string) => {
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
       return permits.getPermit(_chainId, _account, hash);
     },
 
-    getPermits: async (chainId?: number, account?: string) => {
+    getPermits: (chainId?: number, account?: string) => {
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
       return permits.getPermits(_chainId, _account);
     },
 
-    getActivePermit: async (chainId?: number, account?: string) => {
+    getActivePermit: (chainId?: number, account?: string) => {
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
       return permits.getActivePermit(_chainId, _account);
     },
 
-    getActivePermitHash: async (chainId?: number, account?: string) => {
+    getActivePermitHash: (chainId?: number, account?: string) => {
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
       return permits.getActivePermitHash(_chainId, _account);
     },

package/core/clientTypes.ts

@@ -84,10 +84,10 @@ export type CofheClientPermits = {
   ) => Promise<RecipientPermit>;
 
   // Retrieval methods (chainId/account optional)
-  getPermit: (hash: string, chainId?: number, account?: string) => Promise<Permit | undefined>;
-  getPermits: (chainId?: number, account?: string) => Promise<Record<string, Permit>>;
-  getActivePermit: (chainId?: number, account?: string) => Promise<Permit | undefined>;
-  getActivePermitHash: (chainId?: number, account?: string) => Promise<string | undefined>;
+  getPermit: (hash: string, chainId?: number, account?: string) => Permit | undefined;
+  getPermits: (chainId?: number, account?: string) => Record<string, Permit>;
+  getActivePermit: (chainId?: number, account?: string) => Permit | undefined;
+  getActivePermitHash: (chainId?: number, account?: string) => string | undefined;
 
   // Get or create methods (get active or create new, chainId/account optional)
   getOrCreateSelfPermit: (chainId?: number, account?: string, options?: CreateSelfPermitOptions) => Promise<Permit>;

package/core/decrypt/decryptForTxBuilder.ts

@@ -2,14 +2,14 @@
 import { hardhat } from '@/chains';
 import { type Permit, type Permission, PermitUtils } from '@/permits';
 
-import { FheTypes } from '../types.js';
-import { getThresholdNetworkUrlOrThrow } from '../config.js';
-import { CofheError, CofheErrorCode } from '../error.js';
-import { permits } from '../permits.js';
-import { BaseBuilder, type BaseBuilderParams } from '../baseBuilder.js';
-import { cofheMocksDecryptForTx } from './cofheMocksDecryptForTx.js';
-import { getPublicClientChainID, sleep } from '../utils.js';
-import { tnDecrypt } from './tnDecrypt.js';
+import { FheTypes } from '../types';
+import { getThresholdNetworkUrlOrThrow } from '../config';
+import { CofheError, CofheErrorCode } from '../error';
+import { permits } from '../permits';
+import { BaseBuilder, type BaseBuilderParams } from '../baseBuilder';
+import { cofheMocksDecryptForTx } from './cofheMocksDecryptForTx';
+import { getPublicClientChainID, sleep } from '../utils';
+import { tnDecryptV2 } from './tnDecryptV2';
 
 /**
  * API
@@ -291,7 +291,7 @@ export class DecryptForTxBuilder extends BaseBuilder {
     const thresholdNetworkUrl = await this.getThresholdNetworkUrl();
 
     const permission = permit ? PermitUtils.getPermission(permit, true) : null;
-    const { decryptedValue, signature } = await tnDecrypt(this.ctHash, this.chainId, permission, thresholdNetworkUrl);
+    const { decryptedValue, signature } = await tnDecryptV2(this.ctHash, this.chainId, permission, thresholdNetworkUrl);
 
     return {
       ctHash: this.ctHash,

package/core/decrypt/tnDecryptUtils.ts

@@ -0,0 +1,65 @@
+import { CofheError, CofheErrorCode } from '../error';
+import { parseSignature, serializeSignature } from 'viem';
+
+export function normalizeTnSignature(signature: unknown): `0x${string}` {
+  if (typeof signature !== 'string') {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptReturnedNull,
+      message: 'decrypt response missing signature',
+      context: {
+        signature,
+      },
+    });
+  }
+
+  const trimmed = signature.trim();
+  if (trimmed.length === 0) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptReturnedNull,
+      message: 'decrypt response returned empty signature',
+    });
+  }
+
+  const prefixed = trimmed.startsWith('0x') ? (trimmed as `0x${string}`) : (`0x${trimmed}` as `0x${string}`);
+  const parsed = parseSignature(prefixed);
+  return serializeSignature(parsed);
+}
+
+export function parseDecryptedBytesToBigInt(decrypted: unknown): bigint {
+  if (!Array.isArray(decrypted)) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptReturnedNull,
+      message: 'decrypt response field <decrypted> must be a byte array',
+      context: {
+        decrypted,
+      },
+    });
+  }
+
+  if (decrypted.length === 0) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptReturnedNull,
+      message: 'decrypt response field <decrypted> was an empty byte array',
+      context: {
+        decrypted,
+      },
+    });
+  }
+
+  let hex = '';
+  for (const b of decrypted as unknown[]) {
+    if (typeof b !== 'number' || !Number.isInteger(b) || b < 0 || b > 255) {
+      throw new CofheError({
+        code: CofheErrorCode.DecryptReturnedNull,
+        message: 'decrypt response field <decrypted> contained a non-byte value',
+        context: {
+          badElement: b,
+          decrypted,
+        },
+      });
+    }
+    hex += b.toString(16).padStart(2, '0');
+  }
+
+  return BigInt(`0x${hex}`);
+}

package/core/decrypt/{tnDecrypt.ts → tnDecryptV1.ts}

@@ -1,9 +1,9 @@
 import { type Permission } from '@/permits';
 
-import { CofheError, CofheErrorCode } from '../error.js';
-import { parseSignature, serializeSignature } from 'viem';
+import { CofheError, CofheErrorCode } from '../error';
+import { normalizeTnSignature, parseDecryptedBytesToBigInt } from './tnDecryptUtils';
 
-type TnDecryptResponse = {
+type TnDecryptResponseV1 = {
   // TN returns bytes in big-endian order, e.g. [0,0,0,42]
   decrypted: number[];
   signature: string;
@@ -11,70 +11,7 @@ type TnDecryptResponse = {
   error_message: string | null;
 };
 
-function normalizeSignature(signature: unknown): `0x${string}` {
-  if (typeof signature !== 'string') {
-    throw new CofheError({
-      code: CofheErrorCode.DecryptReturnedNull,
-      message: 'decrypt response missing signature',
-      context: {
-        signature,
-      },
-    });
-  }
-
-  const trimmed = signature.trim();
-  if (trimmed.length === 0) {
-    throw new CofheError({
-      code: CofheErrorCode.DecryptReturnedNull,
-      message: 'decrypt response returned empty signature',
-    });
-  }
-
-  const prefixed = trimmed.startsWith('0x') ? (trimmed as `0x${string}`) : (`0x${trimmed}` as `0x${string}`);
-  const parsed = parseSignature(prefixed);
-  return serializeSignature(parsed);
-}
-
-function parseDecryptedBytesToBigInt(decrypted: unknown): bigint {
-  if (!Array.isArray(decrypted)) {
-    throw new CofheError({
-      code: CofheErrorCode.DecryptReturnedNull,
-      message: 'decrypt response field <decrypted> must be a byte array',
-      context: {
-        decrypted,
-      },
-    });
-  }
-
-  if (decrypted.length === 0) {
-    throw new CofheError({
-      code: CofheErrorCode.DecryptReturnedNull,
-      message: 'decrypt response field <decrypted> was an empty byte array',
-      context: {
-        decrypted,
-      },
-    });
-  }
-
-  let hex = '';
-  for (const b of decrypted as unknown[]) {
-    if (typeof b !== 'number' || !Number.isInteger(b) || b < 0 || b > 255) {
-      throw new CofheError({
-        code: CofheErrorCode.DecryptReturnedNull,
-        message: 'decrypt response field <decrypted> contained a non-byte value',
-        context: {
-          badElement: b,
-          decrypted,
-        },
-      });
-    }
-    hex += b.toString(16).padStart(2, '0');
-  }
-
-  return BigInt(`0x${hex}`);
-}
-
-function assertTnDecryptResponse(value: unknown): TnDecryptResponse {
+function assertTnDecryptResponseV1(value: unknown): TnDecryptResponseV1 {
   if (value == null || typeof value !== 'object') {
     throw new CofheError({
       code: CofheErrorCode.DecryptFailed,
@@ -128,7 +65,7 @@ function assertTnDecryptResponse(value: unknown): TnDecryptResponse {
   };
 }
 
-export async function tnDecrypt(
+export async function tnDecryptV1(
   ctHash: bigint | string,
   chainId: number,
   permission: Permission | null,
@@ -213,7 +150,7 @@ export async function tnDecrypt(
     });
   }
 
-  const decryptResponse = assertTnDecryptResponse(rawJson);
+  const decryptResponse = assertTnDecryptResponseV1(rawJson);
 
   if (decryptResponse.error_message) {
     throw new CofheError({
@@ -228,7 +165,7 @@ export async function tnDecrypt(
   }
 
   const decryptedValue = parseDecryptedBytesToBigInt(decryptResponse.decrypted);
-  const signature = normalizeSignature(decryptResponse.signature);
+  const signature = normalizeTnSignature(decryptResponse.signature);
 
   return { decryptedValue, signature };
 }

package/core/decrypt/tnDecryptV2.ts

@@ -0,0 +1,343 @@
+import { type Permission } from '@/permits';
+
+import { CofheError, CofheErrorCode } from '../error';
+import { normalizeTnSignature, parseDecryptedBytesToBigInt } from './tnDecryptUtils';
+
+// Polling configuration
+const POLL_INTERVAL_MS = 1000; // 1 second
+const POLL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+type DecryptSubmitResponseV2 = {
+  request_id: string;
+};
+
+type DecryptStatusResponseV2 = {
+  request_id: string;
+  status: 'PROCESSING' | 'COMPLETED';
+  submitted_at: string;
+  completed_at?: string;
+  is_succeed?: boolean;
+  decrypted?: number[];
+  signature?: string;
+  encryption_type?: number;
+  error_message?: string | null;
+};
+
+function assertDecryptSubmitResponseV2(value: unknown): DecryptSubmitResponseV2 {
+  if (value == null || typeof value !== 'object') {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: 'decrypt submit response must be a JSON object',
+      context: {
+        value,
+      },
+    });
+  }
+
+  const v = value as Record<string, unknown>;
+  if (typeof v.request_id !== 'string' || v.request_id.trim().length === 0) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: 'decrypt submit response missing request_id',
+      context: {
+        value,
+      },
+    });
+  }
+
+  return { request_id: v.request_id };
+}
+
+function assertDecryptStatusResponseV2(value: unknown): DecryptStatusResponseV2 {
+  if (value == null || typeof value !== 'object') {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: 'decrypt status response must be a JSON object',
+      context: {
+        value,
+      },
+    });
+  }
+
+  const v = value as Record<string, unknown>;
+
+  const requestId = v.request_id;
+  const status = v.status;
+  const submittedAt = v.submitted_at;
+
+  if (typeof requestId !== 'string' || requestId.trim().length === 0) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: 'decrypt status response missing request_id',
+      context: {
+        value,
+      },
+    });
+  }
+
+  if (status !== 'PROCESSING' && status !== 'COMPLETED') {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: 'decrypt status response has invalid status',
+      context: {
+        value,
+        status,
+      },
+    });
+  }
+
+  if (typeof submittedAt !== 'string' || submittedAt.trim().length === 0) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: 'decrypt status response missing submitted_at',
+      context: {
+        value,
+      },
+    });
+  }
+
+  return value as DecryptStatusResponseV2;
+}
+
+async function submitDecryptRequestV2(
+  thresholdNetworkUrl: string,
+  ctHash: bigint | string,
+  chainId: number,
+  permission: Permission | null
+): Promise<string> {
+  const body: {
+    ct_tempkey: string;
+    host_chain_id: number;
+    permit?: Permission;
+  } = {
+    ct_tempkey: BigInt(ctHash).toString(16).padStart(64, '0'),
+    host_chain_id: chainId,
+  };
+
+  if (permission) {
+    body.permit = permission;
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(`${thresholdNetworkUrl}/v2/decrypt`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (e) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: `decrypt request failed`,
+      hint: 'Ensure the threshold network URL is valid and reachable.',
+      cause: e instanceof Error ? e : undefined,
+      context: {
+        thresholdNetworkUrl,
+        body,
+      },
+    });
+  }
+
+  if (!response.ok) {
+    let errorMessage = `HTTP ${response.status}`;
+    try {
+      const errorBody = (await response.json()) as Record<string, unknown>;
+      const maybeMessage = (errorBody.error_message || errorBody.message) as unknown;
+      if (typeof maybeMessage === 'string' && maybeMessage.length > 0) errorMessage = maybeMessage;
+    } catch {
+      errorMessage = response.statusText || errorMessage;
+    }
+
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: `decrypt request failed: ${errorMessage}`,
+      hint: 'Check the threshold network URL and request parameters.',
+      context: {
+        thresholdNetworkUrl,
+        status: response.status,
+        statusText: response.statusText,
+        body,
+      },
+    });
+  }
+
+  let rawJson: unknown;
+  try {
+    rawJson = (await response.json()) as unknown;
+  } catch (e) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: `Failed to parse decrypt submit response`,
+      cause: e instanceof Error ? e : undefined,
+      context: {
+        thresholdNetworkUrl,
+        body,
+      },
+    });
+  }
+
+  const submitResponse = assertDecryptSubmitResponseV2(rawJson);
+  return submitResponse.request_id;
+}
+
+async function pollDecryptStatusV2(
+  thresholdNetworkUrl: string,
+  requestId: string
+): Promise<{ decryptedValue: bigint; signature: `0x${string}` }> {
+  const startTime = Date.now();
+  let completed = false;
+
+  while (!completed) {
+    if (Date.now() - startTime > POLL_TIMEOUT_MS) {
+      throw new CofheError({
+        code: CofheErrorCode.DecryptFailed,
+        message: `decrypt polling timed out after ${POLL_TIMEOUT_MS}ms`,
+        hint: 'The request may still be processing. Try again later.',
+        context: {
+          thresholdNetworkUrl,
+          requestId,
+          timeoutMs: POLL_TIMEOUT_MS,
+        },
+      });
+    }
+
+    let response: Response;
+    try {
+      response = await fetch(`${thresholdNetworkUrl}/v2/decrypt/${requestId}`, {
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+    } catch (e) {
+      throw new CofheError({
+        code: CofheErrorCode.DecryptFailed,
+        message: `decrypt status poll failed`,
+        hint: 'Ensure the threshold network URL is valid and reachable.',
+        cause: e instanceof Error ? e : undefined,
+        context: {
+          thresholdNetworkUrl,
+          requestId,
+        },
+      });
+    }
+
+    if (response.status === 404) {
+      throw new CofheError({
+        code: CofheErrorCode.DecryptFailed,
+        message: `decrypt request not found: ${requestId}`,
+        hint: 'The request may have expired or been invalid.',
+        context: {
+          thresholdNetworkUrl,
+          requestId,
+        },
+      });
+    }
+
+    if (!response.ok) {
+      let errorMessage = `HTTP ${response.status}`;
+      try {
+        const errorBody = (await response.json()) as Record<string, unknown>;
+        const maybeMessage = (errorBody.error_message || errorBody.message) as unknown;
+        if (typeof maybeMessage === 'string' && maybeMessage.length > 0) errorMessage = maybeMessage;
+      } catch {
+        errorMessage = response.statusText || errorMessage;
+      }
+
+      throw new CofheError({
+        code: CofheErrorCode.DecryptFailed,
+        message: `decrypt status poll failed: ${errorMessage}`,
+        context: {
+          thresholdNetworkUrl,
+          requestId,
+          status: response.status,
+          statusText: response.statusText,
+        },
+      });
+    }
+
+    let rawJson: unknown;
+    try {
+      rawJson = (await response.json()) as unknown;
+    } catch (e) {
+      throw new CofheError({
+        code: CofheErrorCode.DecryptFailed,
+        message: `Failed to parse decrypt status response`,
+        cause: e instanceof Error ? e : undefined,
+        context: {
+          thresholdNetworkUrl,
+          requestId,
+        },
+      });
+    }
+
+    const statusResponse = assertDecryptStatusResponseV2(rawJson);
+
+    if (statusResponse.status === 'COMPLETED') {
+      if (statusResponse.is_succeed === false) {
+        const errorMessage = statusResponse.error_message || 'Unknown error';
+        throw new CofheError({
+          code: CofheErrorCode.DecryptFailed,
+          message: `decrypt request failed: ${errorMessage}`,
+          context: {
+            thresholdNetworkUrl,
+            requestId,
+            statusResponse,
+          },
+        });
+      }
+
+      if (statusResponse.error_message) {
+        throw new CofheError({
+          code: CofheErrorCode.DecryptFailed,
+          message: `decrypt request failed: ${statusResponse.error_message}`,
+          context: {
+            thresholdNetworkUrl,
+            requestId,
+            statusResponse,
+          },
+        });
+      }
+
+      if (!Array.isArray(statusResponse.decrypted)) {
+        throw new CofheError({
+          code: CofheErrorCode.DecryptReturnedNull,
+          message: 'decrypt completed but response missing <decrypted> byte array',
+          context: {
+            thresholdNetworkUrl,
+            requestId,
+            statusResponse,
+          },
+        });
+      }
+
+      const decryptedValue = parseDecryptedBytesToBigInt(statusResponse.decrypted);
+      const signature = normalizeTnSignature(statusResponse.signature);
+      return { decryptedValue, signature };
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+
+  // This should never be reached, but keeps TS and linters happy.
+  throw new CofheError({
+    code: CofheErrorCode.DecryptFailed,
+    message: 'Polling loop exited unexpectedly',
+    context: {
+      thresholdNetworkUrl,
+      requestId,
+    },
+  });
+}
+
+export async function tnDecryptV2(
+  ctHash: bigint | string,
+  chainId: number,
+  permission: Permission | null,
+  thresholdNetworkUrl: string
+): Promise<{ decryptedValue: bigint; signature: `0x${string}` }> {
+  const requestId = await submitDecryptRequestV2(thresholdNetworkUrl, ctHash, chainId, permission);
+  return await pollDecryptStatusV2(thresholdNetworkUrl, requestId);
+}

package/core/permits.ts

@@ -85,15 +85,15 @@ const deserialize = (serialized: SerializedPermit) => {
 
 // GET
 
-const getPermit = async (chainId: number, account: string, hash: string): Promise<Permit | undefined> => {
+const getPermit = (chainId: number, account: string, hash: string): Permit | undefined => {
   return permitStore.getPermit(chainId, account, hash);
 };
 
-const getPermits = async (chainId: number, account: string): Promise<Record<string, Permit>> => {
+const getPermits = (chainId: number, account: string): Record<string, Permit> => {
   return permitStore.getPermits(chainId, account);
 };
 
-const getActivePermit = async (chainId: number, account: string): Promise<Permit | undefined> => {
+const getActivePermit = (chainId: number, account: string): Permit | undefined => {
   return permitStore.getActivePermit(chainId, account);
 };
 

package/core/types.ts

@@ -389,6 +389,14 @@ export type EncryptStepCallbackFunction = (state: EncryptStep, context?: Encrypt
 
 // DECRYPT
 
+/**
+ * Decrypted plaintext value returned by view-decryption helpers.
+ *
+ * This is a scalar JS value (not a wrapper object):
+ * - `boolean` for `FheTypes.Bool`
+ * - checksummed address `string` for `FheTypes.Uint160`
+ * - `bigint` for supported integer utypes
+ */
 export type UnsealedItem<U extends FheTypes> = U extends FheTypes.Bool
   ? boolean
   : U extends FheTypes.Uint160