4.1. Phase 1: Architectural Foundation

Phase 1 establishes the cryptographic and architectural bedrock of the Fhenix-FairMarket protocol. This phase focuses on isolating volatile FHE libraries, implementing a safe upgradeable proxy standard, constructing the core auction state machine, and achieving foundational test coverage before any business logic or settlement mechanisms are introduced.

By enforcing strict separation of concerns and zero-direct-import policies for cryptographic dependencies, Phase 1 ensures that subsequent phases can iterate safely without risking storage corruption, upgrade failures, or SDK breakage.

Phase Objective

• Configure a deterministic Hardhat environment pinned to Solidity ^0.8.25 and @cofhe/hardhat-plugin ^0.3.
• Deploy FhenixFairMarketProxy.sol using the UUPS/EIP-1967 standard with secure initialization.
• Abstract all @fhenixprotocol/cofhe-contracts calls through CofheAdapter.sol to isolate core logic from external library updates.
• Implement the exhaustive AuctionState machine with guarded transitions.
• Achieve ≥70% unit test coverage on escrow logic and state transitions.

Target File Structure

packages/contracts/
├── hardhat.config.ts # Environment, plugin config, network definitions
├── .env.example # RPC_URL, PRIVATE_KEY, FHE_NETWORK_ID
├── package.json # Dependencies: hardhat, @openzeppelin/contracts-upgradeable, @cofhe/*
│
├── contracts/
│ ├── core/
│ │ ├── FhenixFairMarket.sol # Main logic, state machine, modifiers
│ │ └── FhenixFairMarketProxy.sol # UUPS/EIP-1967 proxy deployment
│ ├── adapters/
│ │ └── CofheAdapter.sol # FHE abstraction layer
│ └── interfaces/
│ └── ICofheAdapter.sol # Stable interface for core contracts
│
├── deploy/
│ ├── 00_deploy_adapters.ts # Adapter deployment & address registration
│ └── 01_deploy_core_proxy.ts # Implementation → Proxy → initialize()
│
└── test/
 ├── mocks/
 │ └── MockCofhe.sol # Zero-gas FHE simulation for local testing
 └── unit/
 └── EscrowLogic.test.ts # Core state & escrow validation tests

️ Execution Tasks & Audit Gates

Technical Implementation

1. UUPS Proxy & Secure Initialization

The protocol separates logic from storage using OpenZeppelin’s UUPSUpgradeable standard. Initialization is strictly guarded to prevent storage layout collisions or double-initialization attacks.

// packages/contracts/core/FhenixFairMarket.sol
contract FhenixFairMarket is 
 UUPSUpgradeable, 
 OwnableUpgradeable, 
 ReentrancyGuardUpgradeable 
{
 // Storage variables live in the Proxy (EIP-1967 compliant)
 address public cofheAdapter;
 mapping(uint256 => Auction) public auctions;
 
 /**
 * @notice Secure initializer called exactly once during proxy deployment
 */
 function initialize(
 address initialOwner, 
 address _cofheAdapter
 ) external initializer {
 __Ownable_init(initialOwner);
 __ReentrancyGuard_init();
 __UUPSUpgradeable_init();
 cofheAdapter = _cofheAdapter;
 }
 
 /**
 * @notice Restricts upgrade capability to authorized governance
 */
 function _authorizeUpgrade(address newImplementation) internal override onlyOwner {
 // Enforced via Multisig + 48h Timelock at governance layer
 }
}

2. FHE Library Isolation via Adapter

Direct imports of cryptographic SDKs into core contracts create severe upgrade risks. The adapter pattern abstracts all FHE operations behind a stable interface.

// packages/contracts/adapters/CofheAdapter.sol
contract CofheAdapter is ICofheAdapter {
 function verifySolvency(InEuint32 encryptedBid, uint256 publicBalance) external pure {
 // Wraps FHE library call, isolating core logic from SDK version bumps
 FHE.lte(encryptedBid, FHE.asEuint32(publicBalance));
 }
 
 function getRawCiphertext(bytes32 hash) external pure returns (InEuint32) {
 return FHE.fromBytes32(hash);
 }
}

3. State Machine & Transition Guards

The auction lifecycle is strictly controlled. Unauthorized transitions are blocked at the modifier level, ensuring mathematical integrity across all phases.

enum AuctionState { CREATED, ACTIVE, RESOLVING, FINALIZED, CANCELLED, VOIDED }
 
modifier onlyActive() {
 require(auctions[auctionId].state == AuctionState.ACTIVE, "Not active");
 _;
}
 
modifier onlyResolving() {
 require(auctions[auctionId].state == AuctionState.RESOLVING, "Not resolving");
 _;
}
 
function createAuction(uint256 duration) external onlyActive {
 // Validates duration bounds, NFT approval, and transitions to ACTIVE
 auctions[auctionId].state = AuctionState.ACTIVE;
 emit AuctionCreated(auctionId, msg.sender, block.timestamp + duration);
}

Phase 1 Audit Gate (P0 Checklist)

Progression to Phase 2 is strictly blocked until all P0 criteria are verified and merged:

• [] Contract inherits UUPSUpgradeable and blocks upgradeToAndCall for non-owner addresses.
• [] Zero direct import of @fhenixprotocol/cofhe-contracts in core logic; all calls route through ICofheAdapter.
• [] initialize() executes exactly once; initializer modifier enforced.
• [] All 6 state transitions (CREATED → ACTIVE → RESOLVING → FINALIZED/CANCELLED/VOIDED) are guarded by modifiers.
• [] Unit test coverage ≥70% on EscrowLogic.test.ts with zero branch misses.
• [] MockCofhe.sol successfully simulates FHE operations locally without gas consumption.
• [] Deployment scripts (00_deploy_adapters.ts, 01_deploy_core_proxy.ts) execute sequentially without storage collisions.

Timeline & Dependencies

Parallel Development Note: Frontend engineers (Phase 5) may begin scaffolding Next.js components using exported mock ABIs from this phase, but full integration is blocked until Phase 3 passes its Audit Gate.

Next Steps

• Proceed to 4.2. Phase 2: Encrypted Security & Settlement to implement FHE.lte solvency checks, Pull over Push refunds, and Dynamic Dead Man's Switch.
• Review Technical Components → CofheAdapter.sol for SDK abstraction layers and homomorphic function wrappers.
• Explore Security Model → Audit Readiness Matrix for P0 classification standards.