5.1. CofheAdapter.sol (FHE Isolation)

The CofheAdapter is a dedicated cryptographic abstraction layer designed to isolate the Fhenix-FairMarket core logic from external FHE (Fully Homomorphic Encryption) library dependencies. By routing all cryptographic operations through a stable interface (ICofheAdapter), the protocol prevents Solidity compilation breaks, storage layout collisions, or logic vulnerabilities caused by @fhenixprotocol/cofhe-contracts SDK updates.

This architectural constraint ensures that the core auction state machine remains immutable and secure, while cryptographic primitives can be independently tested, upgraded, or swapped without redeploying or migrating user funds.

Core Design Principles

️ Technical Implementation

1. Stable Interface Definition (ICofheAdapter.sol)

The interface guarantees cryptographic consistency regardless of underlying SDK changes.

// packages/contracts/interfaces/ICofheAdapter.sol
pragma solidity ^0.8.25;
 
import "@fhenixprotocol/cofhe-contracts/types/InEuint32.sol";
 
interface ICofheAdapter {
 /**
 * @notice Verifies if encrypted bid is less than or equal to public escrow balance
 * @param encryptedBid Homomorphically encrypted bid value
 * @param publicBalance Publicly visible escrow ceiling
 * @return isValid Boolean result of FHE.lte comparison
 */
 function verifySolvency(InEuint32 calldata encryptedBid, uint256 publicBalance) external view returns (bool);
 
 /**
 * @notice Encrypts plaintext data for secure off-chain routing
 * @param data Raw bytes32 payload
 * @return ciphertext Encrypted result sealed with sender's public key
 */
 function seal(bytes32 data) external view returns (InEuint32);
 
 /**
 * @notice Decodes stored ciphertext hashes back to FHE objects for processing
 * @param hash bytes32 representation of encrypted value
 * @return ciphertext InEuint32 object ready for comparison
 */
 function getRawCiphertext(bytes32 hash) external view returns (InEuint32);
 
 /**
 * @notice Converts uint256 to encrypted uint32 for FHE operations
 * @param value Plaintext number
 * @return encrypted InEuint32 representation
 */
 function asEuint32(uint256 value) external view returns (InEuint32);
}

2. Adapter Implementation (CofheAdapter.sol)

The implementation wraps @fhenixprotocol/cofhe-contracts/FHE.sol calls, providing a stable execution boundary.

// packages/contracts/adapters/CofheAdapter.sol
pragma solidity ^0.8.25;
 
import "@fhenixprotocol/cofhe-contracts/FHE.sol";
import "../interfaces/ICofheAdapter.sol";
 
contract CofheAdapter is ICofheAdapter {
 /**
 * @inheritdoc ICofheAdapter
 * @dev Executes FHE.lte off-chain via coprocessor. Reverts on invalid ciphertext.
 */
 function verifySolvency(InEuint32 calldata encryptedBid, uint256 publicBalance) external pure override returns (bool) {
 InEuint32 encryptedBalance = FHE.asEuint32(publicBalance);
 
 // FHE.lte executes asynchronously. Result is validated before storage.
 // Invalid ciphertext formats revert instantly here, protecting state integrity.
 return FHE.lte(encryptedBid, encryptedBalance);
 }
 
 /**
 * @inheritdoc ICofheAdapter
 */
 function seal(bytes32 data) external view override returns (InEuint32) {
 return FHE.seal(data);
 }
 
 /**
 * @inheritdoc ICofheAdapter
 */
 function getRawCiphertext(bytes32 hash) external pure override returns (InEuint32) {
 return FHE.fromBytes32(hash);
 }
 
 /**
 * @inheritdoc ICofheAdapter
 */
 function asEuint32(uint256 value) external pure override returns (InEuint32) {
 return FHE.asEuint32(uint32(value)); // Safe downcast for euint32 range
 }
}

3. Core Contract Integration (FhenixFairMarket.sol)

The auction logic interacts exclusively with the adapter address, ensuring zero cryptographic coupling.

// packages/contracts/core/FhenixFairMarket.sol
contract FhenixFairMarket {
 ICofheAdapter public cofheAdapter;
 
 function initialize(address _cofheAdapter) external initializer {
 cofheAdapter = ICofheAdapter(_cofheAdapter);
 }
 
 function placeBid(uint256 auctionId, InEuint32 calldata encryptedBid) external {
 require(auctions[auctionId].state == AuctionState.ACTIVE, "Not active");
 
 // Adapter-Isolated Solvency Check
 bool isSolvent = cofheAdapter.verifySolvency(encryptedBid, escrowBalances[msg.sender]);
 require(isSolvent, "Bid exceeds escrow ceiling");
 
 bytes32 bidHash = keccak256(abi.encode(encryptedBid));
 auctions[auctionId].ciphertextHashes.push(bidHash);
 
 emit BidPlaced(auctionId, msg.sender, bidHash);
 }
}

Adapter Upgrade & Swap Flow

️ Security & Upgradeability Guarantees

1. Zero Core Logic Breakage: If @fhenixprotocol/cofhe-contracts releases a breaking change (e.g., FHE.lte signature update), only the adapter requires redeployment. The core auction contract remains untouched, preserving all active escrow balances and state.
2. Immutable State Protection: The adapter contains no persistent state variables related to user funds or auction progress. It acts as a pure computational wrapper, ensuring upgrades cannot accidentally corrupt storage layouts.
3. Strict Input Validation: All adapter functions enforce pure or view context, preventing state mutations. Malformed ciphertexts trigger immediate reverts before reaching the core placeBid execution path.
4. Mock-Production Parity: During development, MockCofhe.sol implements the exact ICofheAdapter interface. This guarantees that local unit tests (EscrowLogic.test.ts) behave identically to production deployments, eliminating environment-specific bugs.

Audit Gate Compliance (P0)

The protocol enforces strict adapter isolation verification gates. Progression to subsequent phases is blocked until all P0 items pass:

• [] Zero Direct FHE Imports: CI scan confirms @fhenixprotocol/cofhe-contracts is imported only in CofheAdapter.sol and MockCofhe.sol. Core contracts reference ICofheAdapter exclusively.
• [] Stable Interface Signature: All adapter functions match ICofheAdapter definition exactly. No function overloading or parameter mismatches allowed.
• [] Pure/View Enforcement: Adapter functions execute without state modification. Sload operations are restricted to public balance reads only.
• [] Range Validation: asEuint32() safely downcasts uint256 to uint32, reverting if input exceeds 2^32 - 1.
• [] Mock Compatibility: MockCofhe.sol passes 100% of adapter unit tests with identical result parity to mainnet SDK simulation.

Next Steps

• Proceed to 5.2. FhenixFairMarket.sol (Core Logic) for state machine transitions, bid registry, and settlement routing.
• Review 4.1. Phase 1: Architectural Foundation for adapter deployment sequence and initialization workflow.
• Explore Security Model → Audit Readiness Matrix for P0 dependency isolation verification steps.