4. Execution Roadmap

The Fhenix-FairMarket protocol follows a rigorously sequenced 6-Phase Execution Roadmap, engineered to balance cryptographic complexity, economic security, and developer velocity. Each phase is gated by a mandatory Audit Gate—a set of P0 security and functionality checks that must pass before progression to the next phase.

This phased approach ensures that foundational architecture is solidified before cryptographic logic is layered, that off-chain integrations are validated before infrastructure scaling, and that user experience is refined only after core settlement mechanics are proven secure. No exceptions. No shortcuts.

️ Roadmap Overview

Phase	Focus	Duration	Key Deliverable	Audit Gate Status
Phase 1	Architectural Foundation	10–14 days	UUPS Proxy, CofheAdapter, State Machine, ≥70% test coverage	Complete
Phase 2	Encrypted Security & Settlement	12–16 days	FHE solvency check, Pull refunds, Dynamic Dead Man’s Switch, SlashedPot	Complete
Phase 3	CoFHE & AVS Integration	14–18 days	Async event flow, Keeper services, EigenLayer AVS verification, Mock fraud proofs	Complete
Phase 4	Keepers & Infrastructure	10–12 days	Batch processing, Race condition prevention, Docker stack, CI/CD pipelines	Complete
Phase 5	Frontend & UX 2.0	12–15 days	ERC-4337 session keys, Optimistic UI, Confidence Dashboard, E2E tests	Complete
Phase 6	Testnet Deployment & Audit	10–14 days	Fhenix Testnet launch, KPI monitoring, Chaos engineering, External audit package	In Progress

️ Critical Execution Rule: Any P0 Audit Gate failure immediately halts progression to the next phase. Never skip DynamicTimeout, Pull over Push, or AVS Fraud Proof validation under any circumstance.

Phase 1: Architectural Foundation

** Goal**: Establish the development environment, implement UUPS Proxy pattern, isolate CoFHE libraries via Adapter, and build the core state machine.

Target Files

packages/contracts/
├── hardhat.config.ts
├── contracts/core/FhenixFairMarket.sol
├── contracts/core/FhenixFairMarketProxy.sol
├── contracts/adapters/CofheAdapter.sol
├── contracts/test/mocks/MockCofhe.sol
└── contracts/test/unit/EscrowLogic.test.ts

️ Execution Tasks

Task	Description	Audit Gate Check
1.1 Environment Setup	Configure `hardhat.config.ts` with `@cofhe/hardhat-plugin`, pin Solidity `^0.8.25`, set up test networks	`npx hardhat compile` succeeds with zero warnings
1.2 CofheAdapter Development	Build `CofheAdapter.sol` to wrap all `@fhenixprotocol/cofhe-contracts` calls; prevent direct imports in core logic	Zero direct FHE imports in `FhenixFairMarket.sol`
1.3 UUPS Proxy Implementation	Deploy `FhenixFairMarketProxy.sol` (EIP-1967) with secure `initialize()` and `_authorizeUpgrade()` restricted to multisig	Contract inherits `UUPSUpgradeable`; unauthorized upgrades revert
1.4 State Machine Construction	Implement `enum AuctionState { CREATED, ACTIVE, RESOLVING, FINALIZED, CANCELLED, VOIDED }` with guarded transitions	All state transitions protected by modifiers; no unauthorized jumps
1.5 Mock Contracts	Write `MockCofhe.sol` to simulate FHE operations locally without gas consumption	Tests run successfully in `hardhat localcofhe` mode
1.6 Unit Testing	Implement `EscrowLogic.test.ts` covering `lockEscrow()`, `createAuction()`, and state transitions	Test coverage ≥70%; zero console warnings

Phase 1 Audit Gate (P0)

[] Contract inherits UUPSUpgradeable and blocks upgradeToAndCall for non-owner
[] No direct import of FHE library in core contract—only via ICofheAdapter interface
[] All state transitions work without unauthorized jumps
[] Unit test coverage ≥ 70%

️ Estimated Duration: 10–14 days

Phase 2: Encrypted Security & Settlement Logic

** Goal**: Implement solvency verification without decryption, individual refund system, dynamic emergency threshold, and safe cancellation/failure mechanics.

Target Files

packages/contracts/
├── contracts/core/FhenixFairMarket.sol (placeBid, claimRefund, triggerFallbackVoid)
├── contracts/settlement/SettlementEngine.sol
├── contracts/settlement/SlashedPot.sol
├── contracts/test/unit/AsyncResolution.test.ts
└── contracts/test/unit/DynamicTimeout.test.ts

️ Execution Tasks

Task	Description	Audit Gate Check
2.1 Encrypted Solvency	Apply `FHE.lte(encryptedBid, escrowBalances[msg.sender])` for on-chain balance verification without decryption	Invalid bids revert instantly; no plaintext leakage
2.2 Pull Refund Pattern	Design `claimRefund()` with `mapping hasWithdrawn`; eliminate `for/while` loops in payout logic	Zero loops in refund/compensation functions
2.3 Dynamic Timeout	Build `_getResolutionTimeout()` using `Moving Time Average` of `block.timestamp` with `×1.5` self-compensating factor	Threshold adapts to network volatility; no hardcoded values
2.4 Emergency Void	Implement `triggerFallbackVoid()` to recover 100% of liquidity and return NFT to seller on timeout breach	Full liquidity recovery; FHE engine disabled post-void
2.5 SlashedPot Integration	Develop `SlashedPot.sol` to distribute cancellation penalties pro-rata to bidders; platform takes 0% cut	Penalties distributed fairly; zero platform extraction

Phase 2 Audit Gate (P0)

[] Zero for/while loops in refund or compensation logic
[] Emergency threshold operates dynamically under network volatility simulation
[] triggerFallbackVoid() returns 100% of liquidity and disables FHE engine
[] P0 test coverage ≥ 90%

️ Estimated Duration: 12–16 days

Phase 3: CoFHE & EigenLayer AVS Async Integration

** Goal**: Enable off-chain processing flow, event emission, and connect EigenLayer AVS for economic verification.

Target Files

packages/
├── contracts/interfaces/ISettlementEngine.sol
├── keeper/services/auctionMonitor.ts
├── keeper/services/cofheDispatcher.ts
├── keeper/services/avsSubmitter.ts
├── contracts/test/integration/CoFHEFlow.test.ts
└── contracts/test/mocks/MockEigenLayerAVS.sol

️ Execution Tasks

Task	Description	Audit Gate Check
3.1 Async Finalization	Modify `finalizeAuction()` to emit `DecryptionRequested` event; remove on-chain FHE comparisons	Zero FHE computation in `finalizeAuction()`
3.2 Keeper Monitoring	Build `auctionMonitor.ts` to watch `endTime` and invoke `cofheDispatcher` on completion	Monitor detects closure within ±1 block
3.3 CoFHE Dispatch	Develop `cofheDispatcher.ts` to send `Ciphertext Hashes` to FHEOS servers and receive encrypted result	Batch dispatch capped at 10 auctions/block; no OOG risk
3.4 AVS Verification	Integrate `avsSubmitter.ts` to collect operator signatures, verify `Fraud Proof`, and call `submitResolution()`	Contract rejects `submitResolution` without valid AVS proof
3.5 Integration Testing	Implement `CoFHEFlow.test.ts` simulating full cycle: create → encrypt → close → AVS result → withdrawal	Test passes 100%; latency ≤120s in simulation

Phase 3 Audit Gate (P0)

[] Zero plaintext bid values broadcast in Events or Storage
[] FHEOS result rejected without valid AVS Fraud Proof
[] Integration test passes 100% in local environment (hardhat localcofhe)
[] Slashing mechanism auto-applies on fraudulent results

️ Estimated Duration: 14–18 days

Phase 4: Decentralized Keeper Network & Infrastructure

** Goal**: Self-paying keeper execution, batch processing, race condition prevention, and local Docker setup.

Target Files

packages/keeper/
├── src/config.ts
├── docker-compose.yml
├── src/services/*.ts (performance improvements)
└── .github/workflows/ci-contracts.yml

️ Execution Tasks

Task	Description	Audit Gate Check
4.1 Public Finalization	Convert `triggerFinalize()` to `public` function with `0.2%` incentive for first valid executor	Keeper auto-invokes closure at `endTime` without human intervention
4.2 Race Prevention	Add `nonce` or `blockhash` to prevent Race Conditions between multiple Keepers	Zero duplicate executions; distributed locking via Redis
4.3 Batch Processing	Implement `Batch Queue` capping at 10 auctions/block to prevent OOG under load	Batch processing maintains stable gas under network congestion
4.4 Local Docker Stack	Configure `docker-compose.yml` to run `auctionMonitor + cofheDispatcher + avsSubmitter` locally	`docker compose up` succeeds and simulates full cycle locally
4.5 CI/CD Automation	Connect `ci-contracts.yml` to auto-run integration tests on every `push`	CI pipelines pass without errors; zero High/Critical Slither findings

Phase 4 Audit Gate (P0)

[] Keepers auto-invoke closure at endTime without human intervention
[] Batch processing maintains stable gas under network congestion
[] docker compose up succeeds and simulates full cycle locally
[] CI pipelines pass without errors

️ Estimated Duration: 10–12 days

Phase 5: Frontend & UX 2.0

** Goal**: Build Next.js interface with ERC-4337 key isolation, optimistic UI, and non-revealing trust dashboards.

Target Files

packages/frontend/
├── src/lib/hooks/useERC4337Session.ts
├── src/lib/hooks/useOptimisticUI.ts
├── src/lib/cofhe/encryption.ts
├── src/app/auction/[id]/components/BidForm.tsx
├── src/app/auction/[id]/components/ConfidenceDashboard.tsx
└── tests/e2e/auction-flow.spec.ts

️ Execution Tasks

Task	Description	Audit Gate Check
5.1 Session Key Abstraction	Implement `useERC4337Session.ts` to create `Smart Account` and temporary session keys (no `localStorage`)	Session keys never stored in `localStorage` or `cookies`
5.2 Optimistic UI	Develop `useOptimisticUI.ts` to update button state immediately on signing before network confirmation	Optimistic UI auto-reverts on transaction rejection
5.3 Encryption Integration	Connect `BidForm.tsx` to `encryption.ts` with pre-submission checks (`euint32` range validation)	Pre-flight checks reject invalid bids locally; zero plaintext leakage
5.4 Confidence Dashboard	Build `ConfidenceDashboard.tsx` showing only: bid count, time remaining, encryption status	Dashboard displays zero numeric bid values or winner addresses
5.5 E2E Testing	Write `Playwright` E2E tests covering: connect wallet → encrypt → track status → claim refund	E2E tests pass 100% on simulation environment

Phase 5 Audit Gate (P0)

[] Session keys never stored in localStorage or cookies
[] Optimistic UI auto-reverts on transaction rejection
[] ConfidenceDashboard displays zero numeric bid values or winner addresses
[] E2E tests pass 100% on simulation environment

️ Estimated Duration: 12–15 days

Phase 6: Testnet Deployment, Monitoring & Final Audit

** Goal**: Deploy to Fhenix Testnet, activate KPIs, set up alerting, and prepare for external audit.

Target Files

.github/workflows/deploy-testnet.yml
docs/architecture/async-cofhe-flow.md
docs/operations/monitoring-kpis.md
docs/security-model.md
packages/contracts/test/mocks/ (coverage reports)

️ Execution Tasks

Task	Description	Audit Gate Check
6.1 Sequential Deployment	Implement `deploy-testnet.yml` with sequential deployment: `Adapters → Proxy → Factory`	All contracts deployed and verified on Fhenix Testnet
6.2 KPI Monitoring	Activate performance metrics: `Avg Decryption Latency`, `Failed Decryption Attempts`, `Gas/Bid`	Monitoring dashboard displays live, accurate data
6.3 Alerting Setup	Set up alert system (`Slack/PagerDuty`) for emergency thresholds (`>300s latency`, `>5% failure rate`)	Test alert successfully delivered to team
6.4 Load & Chaos Testing	Run load test (50 concurrent auctions) measuring `CoFHE Dispatcher` stability; simulate network outage	System handles 50 concurrent auctions without OOG or data loss
6.5 Audit Package Compilation	Compile report ready for external auditor (`CertiK` / `OpenZeppelin`) with full documentation	All P0/P1 items completed and documented; project ready for Tier-A audit

Phase 6 Final Audit Gate (Definition of Done)

[] All P0/P1 items completed and documented
[] Testnet deployment stable for 72 consecutive hours
[] Load tests pass without OOG or Decryption Timeout
[] Documentation matches actual code 100%
[] Project officially ready for Tier-A External Audit request

️ Estimated Duration: 10–14 days

Phase Timeline Summary

Week 1-2 ████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Phase 1: Architecture
Week 3-4 ░░░░░████████████░░░░░░░░░░░░░░░░░░░░░░░ Phase 2: Security
Week 5-7 ░░░░░░░░░████████████████░░░░░░░░░░░░░░░ Phase 3: CoFHE/AVS
Week 8-9 ░░░░░░░░░░░░░░░░░████████████░░░░░░░░░░░ Phase 4: Keepers
Week 10-12 ░░░░░░░░░░░░░░░░░░░░░░░████████████░░░░░ Phase 5: Frontend
Week 13-14 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░████████░░ Phase 6: Deploy/Audit

 ↑ Phase 5 can run in parallel with Phase 2 using mock ABIs

️ Critical Execution Note: Any P0 Audit Gate failure halts progression to the next phase. Never skip DynamicTimeout or Pull over Push under any circumstance.

Dependency Mapping

Phase	Depends On	Enables
Phase 2	Phase 1 (Proxy, Adapter, State Machine)	Encrypted solvency, Pull refunds, Emergency void
Phase 3	Phase 2 (Settlement logic, SlashedPot)	Async CoFHE flow, AVS verification, Integration tests
Phase 4	Phase 3 (Keeper interfaces, AVS mocks)	Self-paying automation, Batch processing, Local Docker
Phase 5	Phase 1 (ABI definitions) + Phase 3 (Events)	ERC-4337 UX, Optimistic UI, Confidence Dashboard
Phase 6	All previous phases	Testnet deployment, Monitoring, External audit readiness

Parallel Development Note: Phase 5 (Frontend) can begin using mock ABIs from Phase 1, but full integration is blocked until Phase 3 (CoFHE/AVS) passes its Audit Gate.

Next Steps

Proceed to 5. Technical Components for detailed contract references, function signatures, and integration patterns.

Review 6. Economic Model for fee distribution, treasury allocation, and keeper incentive mechanics.

Explore Security Model → Audit Readiness Matrix for P0/P1/P2 classification and verification stack.

Phase 1: Architectural Foundation