@cofhe/sdk 0.0.0-alpha-20260409113701

package/core/decrypt/decryptUtils.ts

@@ -0,0 +1,28 @@
+import { getAddress } from 'viem';
+import { FheTypes, FheUintUTypes, type UnsealedItem } from '../types.js';
+
+export function uint160ToAddress(uint160: bigint): string {
+  // Convert bigint to hex string and pad to 20 bytes (40 hex chars)
+  const hexStr = uint160.toString(16).padStart(40, '0');
+
+  // Add 0x prefix and convert to checksum address
+  return getAddress('0x' + hexStr);
+}
+
+export const isValidUtype = (utype: FheTypes): boolean => {
+  return (
+    utype === FheTypes.Bool || utype === FheTypes.Uint160 || utype == null || FheUintUTypes.includes(utype as number)
+  );
+};
+
+export const convertViaUtype = <U extends FheTypes>(utype: U, value: bigint): UnsealedItem<U> => {
+  if (utype === FheTypes.Bool) {
+    return !!value as UnsealedItem<U>;
+  } else if (utype === FheTypes.Uint160) {
+    return uint160ToAddress(value) as UnsealedItem<U>;
+  } else if (utype == null || FheUintUTypes.includes(utype as number)) {
+    return value as UnsealedItem<U>;
+  } else {
+    throw new Error(`convertViaUtype :: invalid utype :: ${utype}`);
+  }
+};

package/core/decrypt/pollCallbacks.test.ts

@@ -0,0 +1,194 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { tnDecryptV2 } from './tnDecryptV2.js';
+import { tnSealOutputV2 } from './tnSealOutputV2.js';
+
+const makeMockResponse = (opts: { ok: boolean; status?: number; statusText?: string; json: () => Promise<any> }) => {
+  return {
+    ok: opts.ok,
+    status: opts.status ?? (opts.ok ? 200 : 500),
+    statusText: opts.statusText ?? '',
+    json: opts.json,
+  } as unknown as Response;
+};
+
+describe('decrypt polling callbacks', () => {
+  const thresholdNetworkUrl = 'http://threshold.local';
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('tnDecryptV2 calls onPoll once per poll attempt', async () => {
+    const onPoll = vi.fn();
+
+    let decryptStatusCalls = 0;
+    const fetchMock = vi.fn(async (url: string, options?: any) => {
+      if (url === `${thresholdNetworkUrl}/v2/decrypt` && options?.method === 'POST') {
+        return makeMockResponse({
+          ok: true,
+          json: async () => ({ request_id: 'req-1' }),
+        });
+      }
+
+      if (url === `${thresholdNetworkUrl}/v2/decrypt/req-1` && options?.method === 'GET') {
+        decryptStatusCalls += 1;
+
+        if (decryptStatusCalls === 1) {
+          return makeMockResponse({
+            ok: true,
+            json: async () => ({
+              request_id: 'req-1',
+              status: 'PROCESSING',
+              submitted_at: 't',
+            }),
+          });
+        }
+
+        return makeMockResponse({
+          ok: true,
+          json: async () => ({
+            request_id: 'req-1',
+            status: 'COMPLETED',
+            submitted_at: 't',
+            is_succeed: true,
+            decrypted: [0x01],
+            signature: `0x${'01'.repeat(32)}${'02'.repeat(32)}1b`,
+          }),
+        });
+      }
+
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+
+    global.fetch = fetchMock as any;
+
+    const promise = tnDecryptV2({
+      ctHash: 1n,
+      chainId: 1,
+      permission: null,
+      thresholdNetworkUrl,
+      onPoll,
+    });
+
+    for (let i = 0; i < 25 && onPoll.mock.calls.length < 1; i += 1) {
+      await Promise.resolve();
+    }
+    expect(onPoll).toHaveBeenCalledTimes(1);
+
+    await vi.advanceTimersByTimeAsync(1000);
+    const result = await promise;
+
+    expect(result.decryptedValue).toBe(1n);
+    expect(result.signature.startsWith('0x')).toBe(true);
+
+    expect(onPoll).toHaveBeenCalledTimes(2);
+    expect(onPoll).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({
+        operation: 'decrypt',
+        requestId: 'req-1',
+        attemptIndex: 0,
+        intervalMs: 1000,
+        timeoutMs: 5 * 60 * 1000,
+      })
+    );
+    expect(onPoll).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        operation: 'decrypt',
+        requestId: 'req-1',
+        attemptIndex: 1,
+      })
+    );
+  });
+
+  it('tnSealOutputV2 calls onPoll once per poll attempt', async () => {
+    const onPoll = vi.fn();
+
+    let sealStatusCalls = 0;
+    const fetchMock = vi.fn(async (url: string, options?: any) => {
+      if (url === `${thresholdNetworkUrl}/v2/sealoutput` && options?.method === 'POST') {
+        return makeMockResponse({
+          ok: true,
+          json: async () => ({ request_id: 'req-2' }),
+        });
+      }
+
+      if (url === `${thresholdNetworkUrl}/v2/sealoutput/req-2` && options?.method === 'GET') {
+        sealStatusCalls += 1;
+
+        if (sealStatusCalls === 1) {
+          return makeMockResponse({
+            ok: true,
+            json: async () => ({
+              request_id: 'req-2',
+              status: 'PROCESSING',
+              submitted_at: 't',
+            }),
+          });
+        }
+
+        return makeMockResponse({
+          ok: true,
+          json: async () => ({
+            request_id: 'req-2',
+            status: 'COMPLETED',
+            submitted_at: 't',
+            is_succeed: true,
+            sealed: {
+              data: [1, 2, 3],
+              public_key: [4, 5],
+              nonce: [6],
+            },
+          }),
+        });
+      }
+
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+
+    global.fetch = fetchMock as any;
+
+    const promise = tnSealOutputV2({
+      ctHash: 1n,
+      chainId: 1,
+      permission: {} as any,
+      thresholdNetworkUrl,
+      onPoll,
+    });
+
+    for (let i = 0; i < 25 && onPoll.mock.calls.length < 1; i += 1) {
+      await Promise.resolve();
+    }
+    expect(onPoll).toHaveBeenCalledTimes(1);
+
+    await vi.advanceTimersByTimeAsync(1000);
+    const sealed = await promise;
+
+    expect(sealed.data).toBeInstanceOf(Uint8Array);
+    expect(Array.from(sealed.data)).toEqual([1, 2, 3]);
+
+    expect(onPoll).toHaveBeenCalledTimes(2);
+    expect(onPoll).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({
+        operation: 'sealoutput',
+        requestId: 'req-2',
+        attemptIndex: 0,
+      })
+    );
+    expect(onPoll).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        operation: 'sealoutput',
+        requestId: 'req-2',
+        attemptIndex: 1,
+      })
+    );
+  });
+});

package/core/decrypt/polling.ts

@@ -0,0 +1,14 @@
+export function computeMinuteRampPollIntervalMs(
+  elapsedMs: number,
+  params: {
+    minIntervalMs: number;
+    maxIntervalMs: number;
+  }
+): number {
+  // Increase interval by 1 second every minute: 1s, 2s, 3s... capped.
+  const elapsedSeconds = Math.floor(elapsedMs / 1000);
+  const intervalSeconds = 1 + Math.floor(elapsedSeconds / 60);
+  const intervalMs = intervalSeconds * 1000;
+
+  return Math.min(params.maxIntervalMs, Math.max(params.minIntervalMs, intervalMs));
+}

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

@@ -0,0 +1,171 @@
+import { type Permission } from '@/permits';
+
+import { CofheError, CofheErrorCode } from '../error';
+import { normalizeTnSignature, parseDecryptedBytesToBigInt } from './tnDecryptUtils';
+
+type TnDecryptResponseV1 = {
+  // TN returns bytes in big-endian order, e.g. [0,0,0,42]
+  decrypted: number[];
+  signature: string;
+  encryption_type: number;
+  error_message: string | null;
+};
+
+function assertTnDecryptResponseV1(value: unknown): TnDecryptResponseV1 {
+  if (value == null || typeof value !== 'object') {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: 'decrypt response must be a JSON object',
+      context: {
+        value,
+      },
+    });
+  }
+
+  const v = value as Record<string, unknown>;
+  const decrypted = v.decrypted;
+  const signature = v.signature;
+  const encryptionType = v.encryption_type;
+  const errorMessage = v.error_message;
+
+  if (!Array.isArray(decrypted)) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptReturnedNull,
+      message: 'decrypt response missing <decrypted> byte array',
+      context: { decryptResponse: value },
+    });
+  }
+  if (typeof signature !== 'string') {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptReturnedNull,
+      message: 'decrypt response missing <signature> string',
+      context: { decryptResponse: value },
+    });
+  }
+  if (typeof encryptionType !== 'number') {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: 'decrypt response missing <encryption_type> number',
+      context: { decryptResponse: value },
+    });
+  }
+  if (!(typeof errorMessage === 'string' || errorMessage === null)) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: 'decrypt response field <error_message> must be string or null',
+      context: { decryptResponse: value },
+    });
+  }
+
+  return {
+    decrypted: decrypted as number[],
+    signature,
+    encryption_type: encryptionType,
+    error_message: errorMessage,
+  };
+}
+
+export async function tnDecryptV1(
+  ctHash: bigint | string,
+  chainId: number,
+  permission: Permission | null,
+  thresholdNetworkUrl: string
+): Promise<{ decryptedValue: bigint; signature: `0x${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}/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,
+      },
+    });
+  }
+
+  const responseText = await response.text();
+
+  // Even on non-200 responses, TN may return JSON with { error_message }.
+  if (!response.ok) {
+    let errorMessage = response.statusText || `HTTP ${response.status}`;
+    try {
+      const errorBody = JSON.parse(responseText) as Record<string, unknown>;
+      const maybeMessage = (errorBody.error_message || errorBody.message) as unknown;
+      if (typeof maybeMessage === 'string' && maybeMessage.length > 0) errorMessage = maybeMessage;
+    } catch {
+      const trimmed = responseText.trim();
+      if (trimmed.length > 0) errorMessage = trimmed;
+    }
+
+    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,
+        responseText,
+      },
+    });
+  }
+
+  let rawJson: unknown;
+  try {
+    rawJson = JSON.parse(responseText) as unknown;
+  } catch (e) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: `Failed to parse decrypt response`,
+      cause: e instanceof Error ? e : undefined,
+      context: {
+        thresholdNetworkUrl,
+        body,
+        responseText,
+      },
+    });
+  }
+
+  const decryptResponse = assertTnDecryptResponseV1(rawJson);
+
+  if (decryptResponse.error_message) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: `decrypt request failed: ${decryptResponse.error_message}`,
+      context: {
+        thresholdNetworkUrl,
+        body,
+        decryptResponse,
+      },
+    });
+  }
+
+  const decryptedValue = parseDecryptedBytesToBigInt(decryptResponse.decrypted);
+  const signature = normalizeTnSignature(decryptResponse.signature);
+
+  return { decryptedValue, signature };
+}