5. Technical Components

The Fhenix-FairMarket protocol is structured into three distinct operational layers: Smart Contracts (Settlement & Logic), Keepers (Automation & Off-Chain Processing), and Frontend (User Interaction & Abstraction). This section provides a component-level reference for developers, auditors, and integrators.

️ Component Map

1. Smart Contract Components

FhenixFairMarket.sol (Core Logic)

The central logic contract implementing the UUPS pattern. It manages the auction lifecycle, encrypted bid storage, and settlement.

Key State Machine: CREATED → ACTIVE → RESOLVING → (FINALIZED | CANCELLED | VOIDED)

Critical Functions:

// O(1) Encrypted bid submission
function placeBid(uint256 auctionId, InEuint32 calldata encryptedBid) external;
 
// Pull-based refund pattern
function claimRefund(uint256 auctionId) external;
 
// Asynchronous finalization trigger
function triggerFinalize(uint256 auctionId) external;
 
// Emergency recovery (Dead Man's Switch)
function triggerFallbackVoid(uint256 auctionId) external;

Security Mechanisms:

• Solvency Gate: Uses CofheAdapter.lte to verify encryptedBid <= escrowBalance.
• No-Loop Refunds: claimRefund updates hasWithdrawn state before external transfer.
• Dynamic Timeout: triggerFallbackVoid activates based on Moving Time Average of block times, not hardcoded values.

CofheAdapter.sol (FHE Abstraction)

A dedicated wrapper isolating the volatile @fhenixprotocol/cofhe-contracts library from the core auction logic. This prevents core contract upgrades when the FHE SDK changes.

Interface (ICofheAdapter):

• verifySolvency(InEuint32 bid, uint256 balance): Wraps FHE.lte.
• seal(bytes32 hash): Encrypts data for transfer.
• getRawCiphertext(bytes32 hash): Decodes storage hashes.

SettlementEngine.sol & SlashedPot.sol (Auxiliary Settlement)

• SettlementEngine: Manages the resolutionQueue and interfaces with the avsSubmitter to batch process finalized auctions.
• SlashedPot: Handles the distribution of seller cancellation penalties. It calculates pro-rata shares for valid bidders and ensures the platform takes a 0% cut of penalties.

NFTGuard.sol (Asset Custody)

Ensures the seller’s NFT is locked in a dedicated vault during the ACTIVE state. It prevents the asset from being moved or double-sold while bids are being collected.

2. Keeper Network Components (Off-Chain)

The Keeper network is a self-sustaining automation layer responsible for finalizing auctions and resolving FHE results.

auctionMonitor.ts (Event Listener)

• Role: Listens for AuctionCreated events and tracks endTime.
• Mechanism: Uses WebSocket for real-time detection with a fallback polling interval (30s).
• Action: Calls triggerFinalize() when block.timestamp >= endTime - 60s.
• Incentive: Earns a 0.2% bounty from the auction value for the first successful execution.

cofheDispatcher.ts (FHEOS Orchestrator)

• Role: Bridges the on-chain ciphertext hashes with the off-chain FHEOS servers.
• Batching: Aggregates up to 10 auctions per block to prevent API rate limits and gas spikes.
• Resilience: Implements Redis-backed queues with exponential backoff for failed requests.
• Timeout: Enforces a 120s hard limit on FHEOS processing before escalating to the AVS layer.

avsSubmitter.ts (EigenLayer Verifier)

• Role: Collects partial signatures from EigenLayer AVS operators.
• Threshold: Verifies a quorum (e.g., 3/5 operators) before submission.
• Action: Calls submitResolution(auctionId, winnerCiphertext, avsProof) on the contract.
• Security: Validates the Fraud Proof locally before broadcasting to the chain to prevent slashing.

3. Frontend Components (UX 2.0)

useERC4337Session.ts (Account Abstraction Hook)

Manages the lifecycle of ephemeral session keys to eliminate repetitive wallet pop-ups.

• Isolation: Keys are encrypted via Web Crypto API and stored in IndexedDB. localStorage is strictly prohibited via ESLint rules.
• Scoping: Permissions are limited to placeBid, lockEscrow, and claimRefund.
• TTL: Keys expire after 24 hours, forcing a secure re-authentication.

useOptimisticUI.ts (State Management)

Provides Web2-like responsiveness by updating the UI immediately upon signature generation.

• Flow: User signs → UI updates to “Processing” → wagmi/viem awaits receipt → UI confirms or rolls back on failure.
• Safety: Automatically reverts state if the transaction reverts or is dropped, preventing “ghost” bids.

BidForm.tsx (Encryption & Submission)

The primary interface for bid submission.

• Pre-flight Checks: Validates bidAmount < 2^32 and lockEscrow >= bidAmount locally.
• Encryption: Calls @cofhe/sdk to generate the InEuint32 ciphertext client-side.
• Gas Estimation: Adds a 20% safety buffer (estimate * 1.2) to prevent out-of-gas errors on complex state transitions.

ConfidenceDashboard.tsx (Progressive Disclosure)

Displays user-friendly metrics while hiding cryptographic complexity.

• Metrics Shown: Active Bids, Time Remaining, Encryption Status.
• Data Hidden: Actual bid values and winner addresses remain hidden until FINALIZED or VOIDED state.

4. Interfaces & Standards

The protocol adheres to strict interface definitions to ensure interoperability and upgrade safety.

ISettlementEngine.sol

interface ISettlementEngine {
 function submitResolution(
 uint256 auctionId, 
 bytes32 winnerCiphertext, 
 bytes calldata avsProof
 ) external;
}

ICofheAdapter.sol

interface ICofheAdapter {
 function verifySolvency(InEuint32 encryptedBid, uint256 publicBalance) external view returns (bool);
 function seal(bytes32 data) external view returns (bytes32);
}

️ 5. Security & Audit Considerations

Next Steps

• Proceed to 6. Economic Model for fee distribution, treasury allocation, and keeper incentives.
• Review Security Model for detailed threat matrices and emergency protocols.
• Explore Developer Quickstart for local environment setup and testing instructions.