7. User Experience

The Fhenix-FairMarket protocol redefines decentralized auction participation by delivering a Web2-like experience without compromising the mathematical guarantees of Fully Homomorphic Encryption (FHE) or the economic security of EigenLayer AVS. Version 2.0 formalizes a User Experience Framework built on three foundational pillars: Cryptographic Abstraction, Responsive Feedback, and Trust Transparency.

By integrating ERC-4337 Account Abstraction, Optimistic UI patterns, and Progressive Disclosure principles, the protocol ensures that users interact with sealed-bid auctions through intuitive interfaces—never exposed to raw ciphertexts, signing pop-ups for every action, or technical jargon that obscures economic intent.

Quick Summary

• Core Philosophy: “Trust in proof, not in intermediaries” translated into user-facing language and flows.
• Key Innovation: 1-Click Trade interface powered by ephemeral ERC-4337 session keys (24h TTL, memory-only storage).
• State Management: Optimistic UI updates with automatic rollback on transaction failure.
• Data Privacy: Zero plaintext bid values displayed at any stage; only safe metrics shown via ConfidenceDashboard.
• Accessibility: Progressive disclosure replaces FHE/AVS terminology with user-centric language ( Protected Bid, ️ Sealed Vault).
• Notification Layer: Async status updates via Push Protocol or WalletConnect Notify for settlement events.

Detailed Answer (Cited)

7.1. 1-Click Trade Interface

Traditional Web3 auctions require users to sign a wallet prompt for every bid, escrow lock, or refund claim—creating friction and exposing signing permits to browser-based XSS attacks. Fhenix-FairMarket v2.0 resolves this through ERC-4337 Smart Account integration.

Technical Implementation

// packages/frontend/src/lib/hooks/useERC4337Session.ts
import { createSmartAccountClient } from 'permissionless';
import { encryptWithWebCrypto } from '@lib/crypto';
 
export function useERC4337Session() {
 const createSession = async () => {
 const smartAccount = await createSmartAccountClient({ /* config */ });
 const permit = await smartAccount.createSessionKey({
 ttl: 24 * 60 * 60, // 24-hour Time-To-Live
 scope: ['placeBid', 'lockEscrow', 'claimRefund'], // Granular permissions
 safeStorage: true // Enforces Web Crypto API + IndexedDB
 });
 
 // Encrypt and store in memory/IndexedDB only
 const encrypted = await encryptWithWebCrypto(permit);
 await window.indexedDB.setItem('ffm_session', encrypted);
 
 return permit;
 };
 
 return { createSession, executeSessionAction, isSessionActive };
}

User Flow

1. User connects wallet once → Smart Account created.
2. Session key generated with 24h TTL and scoped permissions.
3. Subsequent bids execute silently via session permit—no Metamask pop-ups.
4. Session expires automatically; UI prompts re-authentication without losing form state.

Fact: Session keys are never stored in localStorage or cookies. ESLint rules enforce this at the CI level. (Source: Phase 5 Sub-Tasks Matrix, Task 5.1)

7.2. Optimistic UI & Automatic Rollback

To match the responsiveness of centralized platforms, the protocol implements an Optimistic UI engine that updates interface state immediately upon signature generation, with guaranteed rollback if the transaction fails.

Technical Implementation

// packages/frontend/src/lib/hooks/useOptimisticUI.ts
import { useWaitForTransactionReceipt } from 'wagmi';
 
export function useOptimisticUI(txHash?: string) {
 const { status, isError } = useWaitForTransactionReceipt({ hash: txHash });
 
 const rollback = useCallback(() => {
 // Revert UI state, clear optimistic cache, notify user
 useAuctionStore.getState().resetOptimisticState();
 }, []);
 
 useEffect(() => {
 if (status === 'reverted' || status === 'dropped' || isError) {
 rollback();
 }
 }, [status, isError, rollback]);
 
 return { isOptimistic: !!txHash && status === 'pending', rollback };
}

UX Guarantee

• Immediate Feedback: Button state changes to “Processing ” within <500ms of signature.
• Safe Fallback: If transaction reverts, UI auto-rolls back and prompts retry with clear error messaging.
• State Persistence: Draft bids and form inputs persist across page reloads via Zustand store.

Fact: Optimistic UI auto-reverts on transaction rejection. Unit tests confirm 100% rollback coverage. (Source: Phase 5 Audit Gate, Task 5.2)

7.3. Progressive Disclosure & Confidence Dashboard

Technical complexity is abstracted into user-friendly metrics through a Confidence Dashboard that displays only safe, non-revealing information until cryptographic settlement is complete.

Terminology Mapping

Dashboard Metrics (Safe Display)

// packages/frontend/src/app/auction/[id]/components/ConfidenceDashboard.tsx
export function ConfidenceDashboard({ auctionId }: { auctionId: string }) {
 const { activeBids, timeRemaining, encryptionStatus } = useAuctionState(auctionId);
 
 return (
 <div className="dashboard">
 <Metric label="Sealed Bids" value={activeBids} />
 <Metric label="Time Until Reveal" value={formatTime(timeRemaining)} />
 <Metric label="Your Bid Status" value={encryptionStatus} />
 {/* Zero numeric bid values, winner addresses, or plaintext data */}
 </div>
 );
}

Fact: ConfidenceDashboard displays zero numeric bid values or winner addresses prior to FINALIZED state. (Source: Phase 5 Audit Gate, Task 5.4)

7.4. Client-Side Encryption Flow

All bid encryption occurs locally in the user’s browser before any network transmission, ensuring plaintext values never traverse the mempool or node infrastructure.

Encryption Pipeline

// packages/frontend/src/lib/cofhe/encryption.ts
import { cofheClient, Encryptable } from '@cofhe/sdk';
 
export async function encryptBid(amount: number): Promise<InEuint32> {
 // 1. Range validation (euint32 max: 2^32 - 1)
 if (amount < 0 || amount > 2 ** 32 - 1) {
 throw new Error('Bid amount exceeds euint32 range');
 }
 
 // 2. Local encryption via CoFHE SDK
 const encryptedPayload = await cofheClient.encryptInputs([
 Encryptable.uint32(amount)
]);
 
 return encryptedPayload[0]; // Returns InEuint32 Ciphertext
}

Pre-Flight Validation

Before submission, the UI performs client-side checks to prevent failed transactions:

• bidAmount < 2^32 (euint32 range)
• lockEscrow >= bidAmount (via viem.readContract)
• Dynamic gas estimation with 20% safety buffer

Fact: Pre-flight validation rejects out-of-range or insolvent bids locally. Zero plaintext leakage in console logs. (Source: Phase 5 Sub-Tasks Matrix, Task 5.3)

7.5. Async Notifications & Status Updates

Users receive real-time updates on auction progression without polling or manual refresh, via integration with decentralized notification protocols.

Notification Architecture

Supported Events

• EscrowLocked: “Deposit confirmed ”
• BidPlaced: “Encrypted bid submitted ”
• AuctionFinalized: “Settlement complete — check results”
• RefundClaimed: “Funds returned to wallet ”
• EmergencyHaltActivated: “Auto-refund triggered due to network issue”

Fact: Notification integration is optional but recommended for UX completeness. Events are emitted on-chain and indexed for third-party services. (Source: README.md, Monitoring & KPIs section)

Confirmed Facts

1. Session Key Isolation: ERC-4337 session keys are stored exclusively in encrypted IndexedDB or memory. localStorage usage is prohibited via ESLint rules and CI checks.
2. Optimistic Rollback: UI state auto-reverts within <500ms of transaction failure. Unit tests confirm 100% coverage for rollback logic.
3. Zero Plaintext Display: ConfidenceDashboard never shows numeric bid values, winner addresses, or decrypted data before FINALIZED or VOIDED state.
4. Client-Side Encryption: All bid encryption occurs in-browser via @cofhe/sdk. Plaintext values never enter the network layer or mempool.
5. Pre-Flight Validation: Range checks (< 2^32) and solvency verification (escrow >= bid) execute locally before transaction submission.
6. Async Notifications: Event-driven updates via Push Protocol or WalletConnect Notify provide real-time status without polling.

Unresolved Points & Explicit Gaps

Fact vs. Analysis Distinction: Session key isolation, optimistic rollback, zero-plaintext display, client-side encryption, and pre-flight validation are verified facts from the official Phase 5 documentation and Technical Specification. Gas sponsorship, offline submission, i18n, accessibility, and mobile optimization are unresolved UX enhancements requiring explicit definition before Mainnet launch.

Sources (Internal Documentation References)

1. Whitepaper Fhenix-FairMarket.txt → Section 2.A (UX & Account Abstraction Layer), Section 5 (Strategic Market Features)
2. وثيقة المواصفات التقنية الرسمية.txt → Section 5 (UX 2.0 Design Principles), Section 5.2 (Confidence Dashboard)
3. README.md → UX 2.0 Design Principles, Confidence Dashboard specifications, Push Protocol integration notes
4. Phase 5 Sub-Tasks Matrix.txt → Tasks 5.1–5.6 (ERC-4337, Optimistic UI, Encryption, Dashboard, E2E, CI/CD)
5. المرحلة 5.txt → Frontend file structure, component specifications, and audit gate criteria
6. GitHub (Issue Templates).txt → UX-related issue templates for bug reports and feature requests

(Note: All references correspond to the private repository documents provided. Public URLs will be generated upon official documentation site deployment.)

Next Steps

• Proceed to 8. Governance & DAO Transition for multisig-to-DAO migration procedures and treasury voting mechanics.
• Review Security Model → Session Key Isolation for detailed Web Crypto API implementation and XSS mitigation strategies.
• Explore Developer Quickstart → Frontend Setup for local environment configuration and ERC-4337 testing instructions.