@cofhe/abi 0.0.0-alpha-20260409113701

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# @cofhe/abi Changelog
+
+## 0.0.0-alpha-20260409113701
+
+### Patch Changes
+
+- Updated dependencies [788a6e2]
+- Updated dependencies [9a06012]
+- Updated dependencies [503536a]
+  - @cofhe/sdk@0.0.0-alpha-20260409113701
+
+## 0.4.0
+
+### Patch Changes
+
+- Updated dependencies [e446642]
+  - @cofhe/sdk@0.4.0
+
+## 0.3.2
+
+### Patch Changes
+
+- d4e86ea: Aligns with CTA encrypted variables bytes32 representation.
+
+  - **@cofhe/hardhat-plugin**: `hre.cofhe.mocks.getTestBed()`, `getMockTaskManager()`, `getMockACL()`, `getMockThresholdNetwork()`, and `getMockZkVerifier()` now return typed contracts (typechain interfaces) instead of untyped `Contract`. `getPlaintext(ctHash)` and `expectPlaintext(ctHash, value)` now accept bytes32 ctHashes as `string` support cofhe-contracts 0.1.0 CTA changes.
+  - **@cofhe/mock-contracts**: Export typechain-generated contract types (`TestBed`, `MockACL`, `MockTaskManager`, `MockZkVerifier`, `MockThresholdNetwork`) for use with the hardhat plugin. Typechain is run from artifact ABIs only; factory files are not generated.
+  - **@cofhe/abi**: CTA-related types use `bytes32` (string) instead of `uint256`. Decryption and return-type helpers aligned with cofhe-contracts 0.1.0.
+  - **@cofhe/sdk**: Decryption APIs (`decryptForTx`, `decryptForView`, and related builders) now also accept `string` for ciphertext hashes (bytes32) as well as `bigint`.
+
+- Updated dependencies [d4e86ea]
+- Updated dependencies [0feaf3f]
+  - @cofhe/sdk@0.3.2
+
+## 0.3.1
+
+### Patch Changes
+
+- 370f0c7: no-op
+- Updated dependencies [370f0c7]
+  - @cofhe/sdk@0.3.1
+
+## 0.3.0
+
+### Patch Changes
+
+- Updated dependencies [35024b6]
+- Updated dependencies [5467d77]
+- Updated dependencies [73b1502]
+- Updated dependencies [29c2401]
+- Updated dependencies [650ea48]
+  - @cofhe/sdk@0.3.0
+
+## 0.2.1
+
+### Patch Changes
+
+- be9bfd9: Fix deployment include `dist` folder.
+- Updated dependencies [409bfdf]
+- Updated dependencies [ac47e2f]
+- Updated dependencies [8af1b70]
+  - @cofhe/sdk@0.2.1
+
+## 0.2.0
+
+### Patch Changes
+
+- Updated dependencies [8fda09a]
+- Updated dependencies [4057a76]
+- Updated dependencies [dba2759]
+- Updated dependencies [e0caeca]
+- Updated dependencies [7c861af]
+- Updated dependencies [2a9d6c5]
+  - @cofhe/sdk@0.2.0

package/README.md

@@ -0,0 +1,184 @@
+# @cofhe/abi
+
+Type-safe ABI utilities for Fhenix fully homomorphic encryption (FHE) smart contracts. Provides type-safe transformations between encrypted input/output types and their underlying primitive values.
+
+## Overview
+
+Fhenix contracts use encrypted types (e.g., `euint32`, `ebool`) that are represented as structs in ABIs. This package bridges the gap between:
+
+- **Encrypted types** (`struct InEuint32`, `euint32`) - the ABI representation
+- **Primitive types** (`bigint`, `boolean`, `string`) - developer-friendly values
+- **Encryptable types** (`EncryptableItem`) - intermediate encryption format
+
+The package provides compile-time type safety through TypeScript generics, ensuring encrypted values are correctly extracted, transformed, and inserted based on ABI definitions.
+
+## Installation
+
+```bash
+npm install @cofhe/abi
+# or
+pnpm add @cofhe/abi
+# or
+yarn add @cofhe/abi
+```
+
+**Peer Dependencies:**
+
+- `@cofhe/sdk` - Core encryption types and utilities
+- `abitype` - ABI type utilities
+
+## Quick Start
+
+```typescript
+import { extractEncryptableValues, insertEncryptedValues, transformEncryptedReturnTypes } from '@cofhe/abi';
+import type { CofheInputArgs, CofheInputArgsPreTransform, CofheReturnType } from '@cofhe/abi';
+import { encrypt } from '@cofhe/sdk';
+
+const abi = [
+  {
+    type: 'function',
+    name: 'add',
+    inputs: [
+      { name: 'a', type: 'uint256', internalType: 'uint256' },
+      { name: 'b', type: 'tuple', internalType: 'struct InEuint32', components: [...] }
+    ],
+    outputs: [{ name: '', type: 'uint256', internalType: 'euint32' }],
+    stateMutability: 'nonpayable'
+  }
+] as const;
+
+// 1. Prepare arguments with primitive values
+const args: CofheInputArgsPreTransform<typeof abi, 'add'> = [100n, 200n];
+
+// 2. Extract encryptable values
+const encryptables = extractEncryptableValues(abi, 'add', args);
+//    ^? [Encryptable.uint32(200n)]
+
+// 3. Encrypt the values
+const encrypted = await encrypt(encryptables);
+//    ^? [EncryptedUint32Input]
+
+// 4. Insert encrypted values back into arguments
+const encryptedArgs: CofheInputArgs<typeof abi, 'add'> = insertEncryptedValues(abi, 'add', args, encrypted);
+//    ^? [100n, EncryptedUint32Input]
+
+// 5. Call contract and transform return value
+const result = await contract.add(...encryptedArgs);
+//    ^? bigint
+
+// 6. Transform raw return value into correct encrypted value type
+const transformed: CofheReturnType<typeof abi, 'add'> = transformEncryptedReturnTypes(abi, 'add', result);
+//    ^? Euint32
+```
+
+## Public API Reference
+
+### Return Types
+
+#### `CofheReturnType<abi, functionName, args?>`
+
+Type-level utility that infers the return type of a function, transforming encrypted return types to their typed representations.
+
+**Type Parameters:**
+
+- `abi` - Contract ABI (must be `const`-asserted for type inference)
+- `functionName` - Function name (string literal)
+- `args` - Optional function arguments for overload disambiguation
+
+**Returns:**
+
+- Transformed return type where encrypted types (`euint32`, `ebool`, etc.) are converted to typed objects (`{ ctHash: bigint, utype: FheTypes }`)
+- Non-encrypted types remain unchanged
+- Supports single values, tuples, arrays, and nested structures
+
+**Supported Encrypted Return Types:**
+
+- `ebool` → `{ ctHash: bigint; utype: FheTypes.Bool }`
+- `euint8` → `{ ctHash: bigint; utype: FheTypes.Uint8 }`
+- `euint16` → `{ ctHash: bigint; utype: FheTypes.Uint16 }`
+- `euint32` → `{ ctHash: bigint; utype: FheTypes.Uint32 }`
+- `euint64` → `{ ctHash: bigint; utype: FheTypes.Uint64 }`
+- `euint128` → `{ ctHash: bigint; utype: FheTypes.Uint128 }`
+- `eaddress` → `{ ctHash: bigint; utype: FheTypes.Uint160 }`
+
+#### `transformEncryptedReturnTypes(abi, functionName, data)`
+
+Runtime function that transforms contract return values from `bigint` ciphertext hashes to typed encrypted return objects.
+
+**Parameters:**
+
+- `abi` - Contract ABI
+- `functionName` - Function name
+- `data` - Raw return value(s) from contract call (single value or array)
+
+**Returns:**
+Transformed return value matching `CofheReturnType<abi, functionName>`
+Works with multiple return values, nested structures and arrays.
+
+### Encrypted Inputs
+
+#### `CofheInputArgs<abi, functionName>`
+
+Type-level utility that infers function input arguments with encrypted types represented as encrypted input structs.
+
+**Type Parameters:**
+
+- `abi` - Contract ABI (must be `const`-asserted for type inference)
+- `functionName` - Function name (string literal)
+
+**Returns:**
+
+- Tuple type where encrypted inputs are represented as encrypted input structs (`EncryptedUint32Input`, `EncryptedBoolInput`, etc.)
+- Non-encrypted types use their primitive representations
+
+#### `CofheInputArgsPreTransform<abi, functionName>`
+
+Type-level utility that infers function input arguments with encrypted types represented as their underlying primitive values (before encryption).
+
+**Type Parameters:**
+
+- `abi` - Contract ABI (must be `const`-asserted for type inference)
+- `functionName` - Function name (string literal)
+
+**Returns:**
+
+- Tuple type where encrypted inputs use primitive types (`bigint` for uints, `boolean` for bool, `string` for address)
+- This is the format you provide to `extractEncryptableValues`
+
+**Supported Encrypted Input Types:**
+
+- `struct InEbool` → `boolean` (pre-transform) → `EncryptedBoolInput` (post-transform)
+- `struct InEuint8` → `bigint | string` → `EncryptedUint8Input`
+- `struct InEuint16` → `bigint | string` → `EncryptedUint16Input`
+- `struct InEuint32` → `bigint | string` → `EncryptedUint32Input`
+- `struct InEuint64` → `bigint | string` → `EncryptedUint64Input`
+- `struct InEuint128` → `bigint | string` → `EncryptedUint128Input`
+- `struct InEaddress` → `string | bigint` → `EncryptedAddressInput`
+
+#### `extractEncryptableValues(abi, functionName, args)`
+
+Extracts encryptable values from function arguments, converting primitive values to `EncryptableItem` objects ready for encryption.
+
+**Parameters:**
+
+- `abi` - Contract ABI
+- `functionName` - Function name
+- `args` - Function arguments in `CofheInputArgsPreTransform` format (primitives)
+
+**Returns:**
+Flat array of `EncryptableItem` objects in the order they appear in the ABI (depth-first traversal).
+Works with arrays (fixed length or unbounded) and nested structures.
+
+#### `insertEncryptedValues(abi, functionName, args, encryptedValues)`
+
+Re-inserts encrypted values back into function arguments, replacing primitive values with encrypted input structs.
+
+**Parameters:**
+
+- `abi` - Contract ABI
+- `functionName` - Function name
+- `args` - Original function arguments in `CofheInputArgsPreTransform` format
+- `encryptedValues` - Array of encrypted values in the same order as returned by `extractEncryptableValues`
+
+**Returns:**
+Function arguments in `CofheInputArgs` format (ready for contract calls)

package/dist/index.cjs

@@ -0,0 +1,331 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  extractEncryptableValues: () => extractEncryptableValues,
+  insertEncryptedValues: () => insertEncryptedValues,
+  transformEncryptedReturnTypes: () => transformEncryptedReturnTypes
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/encryptedInputs.ts
+var import_sdk = require("@cofhe/sdk");
+
+// src/utils.ts
+function extractArrayParameterType(type) {
+  if (type == null) return [type, void 0];
+  const match = type.match(/^(.+)\[(\d*)\]$/);
+  if (!match) {
+    return [type, void 0];
+  }
+  const head = match[1];
+  const size = match[2];
+  return [head, size === "" ? "" : size];
+}
+function isAbiFunction(item) {
+  if (typeof item !== "object" || item === null) return false;
+  return "type" in item && item.type === "function" && "name" in item && "outputs" in item;
+}
+function getAbiFunction(abi, functionName) {
+  return abi.find((item) => {
+    const isFunction = isAbiFunction(item);
+    if (!isFunction) return false;
+    return item.name === functionName;
+  });
+}
+
+// src/encryptedInputs.ts
+var ENCRYPTED_INPUT_INTERNAL_TYPES = [
+  "struct InEbool",
+  "struct InEuint8",
+  "struct InEuint16",
+  "struct InEuint32",
+  "struct InEuint64",
+  "struct InEuint128",
+  "struct InEaddress"
+];
+function transformSingleEncryptedInputToEncryptable(internalType, data) {
+  switch (internalType) {
+    case "struct InEbool":
+      return import_sdk.Encryptable.bool(data);
+    case "struct InEuint8":
+      return import_sdk.Encryptable.uint8(data);
+    case "struct InEuint16":
+      return import_sdk.Encryptable.uint16(data);
+    case "struct InEuint32":
+      return import_sdk.Encryptable.uint32(data);
+    case "struct InEuint64":
+      return import_sdk.Encryptable.uint64(data);
+    case "struct InEuint128":
+      return import_sdk.Encryptable.uint128(data);
+    case "struct InEaddress":
+      return import_sdk.Encryptable.address(data);
+    default:
+      throw new Error(`Unknown encrypted input type: ${internalType}`);
+  }
+}
+function transformArrayOfEncryptedInputsToEncryptables(internalType, size, data) {
+  if (!Array.isArray(data)) {
+    throw new Error("Data must be an array");
+  }
+  if (size != null && size !== "" && parseInt(size) !== data.length) {
+    throw new Error(`Array size mismatch: ${size} !== ${data.length}`);
+  }
+  return data.map((item) => transformSingleEncryptedInputToEncryptable(internalType, item));
+}
+function internalTypeIsEncryptedInput(internalType) {
+  return ENCRYPTED_INPUT_INTERNAL_TYPES.includes(internalType);
+}
+function extractEncryptableValues(abi, functionName, args) {
+  const abiFunction = getAbiFunction(abi, functionName);
+  const inputs = abiFunction?.inputs;
+  if (abiFunction == null || inputs == null) {
+    throw new Error(`Function ${functionName} not found in ABI`);
+  }
+  if (!Array.isArray(args)) {
+    throw new Error("Arguments must be an array");
+  }
+  const encryptableItems = [];
+  function processParameter(param, value) {
+    const [typeHead, typeSize] = extractArrayParameterType(param.type);
+    const [internalTypeHead, internalTypeSize] = extractArrayParameterType(param.internalType);
+    if (typeHead === "tuple" && typeSize == null && internalTypeHead != null && internalTypeIsEncryptedInput(internalTypeHead)) {
+      const encryptable = transformSingleEncryptedInputToEncryptable(internalTypeHead, value);
+      encryptableItems.push(encryptable);
+      return;
+    }
+    if (typeHead === "tuple" && typeSize != null && internalTypeHead != null && internalTypeIsEncryptedInput(internalTypeHead)) {
+      const encryptables = transformArrayOfEncryptedInputsToEncryptables(internalTypeHead, typeSize, value);
+      encryptableItems.push(...encryptables);
+      return;
+    }
+    if (typeHead === "tuple" && (internalTypeHead == null || !internalTypeIsEncryptedInput(internalTypeHead))) {
+      if ("components" in param && Array.isArray(param.components)) {
+        param.components.forEach((component) => {
+          processParameter(component, value[component.name]);
+        });
+      }
+      return;
+    }
+    return;
+  }
+  inputs.forEach((input, index) => {
+    const arg = args[index];
+    if (arg == null) {
+      throw new Error(`Argument ${index} is undefined`);
+    }
+    processParameter(input, arg);
+  });
+  return encryptableItems;
+}
+function insertEncryptedValues(abi, functionName, args, encryptedValues) {
+  const abiFunction = getAbiFunction(abi, functionName);
+  const inputs = abiFunction?.inputs;
+  if (abiFunction == null || inputs == null) {
+    throw new Error(`Function ${functionName} not found in ABI`);
+  }
+  if (!Array.isArray(args)) {
+    throw new Error("Arguments must be an array");
+  }
+  let encryptedIndex = 0;
+  function processParameter(param, value) {
+    const [typeHead, typeSize] = extractArrayParameterType(param.type);
+    const [internalTypeHead, internalTypeSize] = extractArrayParameterType(param.internalType);
+    if (typeHead === "tuple" && typeSize == null && internalTypeHead != null && internalTypeIsEncryptedInput(internalTypeHead)) {
+      if (encryptedIndex >= encryptedValues.length) {
+        throw new Error(
+          `Not enough encrypted values: expected at least ${encryptedIndex + 1}, got ${encryptedValues.length}`
+        );
+      }
+      const encryptedValue = encryptedValues[encryptedIndex];
+      encryptedIndex++;
+      return encryptedValue;
+    }
+    if (typeHead === "tuple" && typeSize != null && internalTypeHead != null && internalTypeIsEncryptedInput(internalTypeHead)) {
+      const arrayLength = Array.isArray(value) ? value.length : 0;
+      if (arrayLength === 0) {
+        return [];
+      }
+      if (encryptedIndex + arrayLength > encryptedValues.length) {
+        throw new Error(
+          `Not enough encrypted values: expected at least ${encryptedIndex + arrayLength}, got ${encryptedValues.length}`
+        );
+      }
+      const encryptedArray = encryptedValues.slice(encryptedIndex, encryptedIndex + arrayLength);
+      encryptedIndex += arrayLength;
+      return encryptedArray;
+    }
+    if (typeHead === "tuple" && (internalTypeHead == null || !internalTypeIsEncryptedInput(internalTypeHead))) {
+      if ("components" in param && Array.isArray(param.components)) {
+        const valueObj = value;
+        const result2 = {};
+        param.components.forEach((component) => {
+          const componentName = component.name;
+          if (componentName) {
+            const componentValue = valueObj[componentName];
+            if (componentValue !== void 0) {
+              result2[componentName] = processParameter(component, componentValue);
+            }
+          }
+        });
+        return result2;
+      }
+      return value;
+    }
+    return value;
+  }
+  const result = inputs.map((input, index) => {
+    const arg = args[index];
+    if (arg == null) {
+      throw new Error(`Argument ${index} is undefined`);
+    }
+    return processParameter(input, arg);
+  });
+  if (encryptedIndex !== encryptedValues.length) {
+    throw new Error(
+      `Mismatch in encrypted values count: used ${encryptedIndex}, but provided ${encryptedValues.length}`
+    );
+  }
+  return result;
+}
+
+// src/encryptedReturnTypes.ts
+var import_sdk2 = require("@cofhe/sdk");
+var ENCRYPTED_RETURN_TYPE_INTERNAL_TYPES = [
+  "ebool",
+  "euint8",
+  "euint16",
+  "euint32",
+  "euint64",
+  "euint128",
+  "eaddress"
+];
+function transformSingleEncryptedReturnTypeToReturnType(internalType, data) {
+  switch (internalType) {
+    case "ebool":
+      return {
+        ctHash: data,
+        utype: import_sdk2.FheTypes.Bool
+      };
+    case "euint8":
+      return {
+        ctHash: data,
+        utype: import_sdk2.FheTypes.Uint8
+      };
+    case "euint16":
+      return {
+        ctHash: data,
+        utype: import_sdk2.FheTypes.Uint16
+      };
+    case "euint32":
+      return {
+        ctHash: data,
+        utype: import_sdk2.FheTypes.Uint32
+      };
+    case "euint64":
+      return {
+        ctHash: data,
+        utype: import_sdk2.FheTypes.Uint64
+      };
+    case "euint128":
+      return {
+        ctHash: data,
+        utype: import_sdk2.FheTypes.Uint128
+      };
+    case "eaddress":
+      return {
+        ctHash: data,
+        utype: import_sdk2.FheTypes.Uint160
+      };
+    default:
+      throw new Error(`Unknown encrypted return type: ${internalType}`);
+  }
+}
+function transformArrayOfEncryptedReturnTypesToReturnTypes(internalType, size, data) {
+  if (!Array.isArray(data)) {
+    throw new Error("Data must be an array");
+  }
+  if (size != null && size !== "" && parseInt(size) !== data.length) {
+    throw new Error(`Array size mismatch: ${size} !== ${data.length}`);
+  }
+  return data.map((item) => transformSingleEncryptedReturnTypeToReturnType(internalType, item));
+}
+function internalTypeIsEncryptedReturnType(internalType) {
+  return ENCRYPTED_RETURN_TYPE_INTERNAL_TYPES.includes(internalType);
+}
+function transformEncryptedReturnTypes(abi, functionName, data) {
+  const abiFunction = getAbiFunction(abi, functionName);
+  const outputs = abiFunction?.outputs;
+  if (abiFunction == null || outputs == null) {
+    throw new Error(`Function ${functionName} not found in ABI`);
+  }
+  const outputsLength = outputs.length;
+  function processParameter(param, value) {
+    const [typeHead, typeSize] = extractArrayParameterType(param.type);
+    const [internalTypeHead, internalTypeSize] = extractArrayParameterType(param.internalType);
+    if (internalTypeHead != null && internalTypeIsEncryptedReturnType(internalTypeHead)) {
+      if (internalTypeSize == null) {
+        return transformSingleEncryptedReturnTypeToReturnType(internalTypeHead, value);
+      }
+      if (internalTypeSize != null) {
+        console.log("array of encrypted return types", internalTypeHead, internalTypeSize, value);
+        return transformArrayOfEncryptedReturnTypesToReturnTypes(internalTypeHead, internalTypeSize, value);
+      }
+    }
+    if (typeHead === "tuple") {
+      if ("components" in param && Array.isArray(param.components)) {
+        const valueObj = value;
+        const result = {};
+        param.components.forEach((component) => {
+          const componentName = component.name;
+          if (componentName) {
+            const componentValue = valueObj[componentName];
+            if (componentValue !== void 0) {
+              result[componentName] = processParameter(component, componentValue);
+            }
+          }
+        });
+        return result;
+      }
+      return value;
+    }
+    return value;
+  }
+  if (outputsLength > 1) {
+    if (!Array.isArray(data)) {
+      throw new Error("Data must be an array");
+    }
+    if (outputsLength !== data.length) {
+      throw new Error(`Mismatch in outputs length: ${outputsLength} !== ${data.length}`);
+    }
+    return data.map((item, index) => {
+      return processParameter(outputs[index], item);
+    });
+  }
+  return processParameter(outputs[0], data);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  extractEncryptableValues,
+  insertEncryptedValues,
+  transformEncryptedReturnTypes
+});
+//# sourceMappingURL=index.cjs.map