@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

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

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)