1.5. ERC-4337 Account Abstraction

To bridge the gap between mathematical security and mainstream usability, Fhenix-FairMarket integrates ERC-4337 Account Abstraction at the presentation layer. Traditional Web3 auctions force users into repetitive, friction-heavy wallet signing prompts for every interaction, creating a cognitive barrier and exposing sensitive signing permits to browser-based XSS (Cross-Site Scripting) attacks.

Version 2.0 resolves this by introducing Ephemeral Session Keys managed by Smart Accounts. Users authenticate once, after which time-bound, cryptographically scoped permits handle all subsequent auction interactions seamlessly. This enables a 1-Click Trade experience while strictly isolating sensitive cryptographic material from persistent browser storage.

Core Design Principles

️ Technical Implementation

1. Session Key Lifecycle Hook (useERC4337Session.ts)

The hook orchestrates Smart Account creation, permit generation, secure storage, and automatic expiration handling.

// Pseudo-architecture: packages/frontend/src/lib/hooks/useERC4337Session.ts
import { useWebCrypto } from '@lib/crypto';
import { permissionless } from 'permissionless';
 
export function useERC4337Session() {
 const [sessionPermit, setSessionPermit] = useState<SessionPermit | null>(null);
 
 // 1. Generate Ephemeral Key on User Authentication
 const createSession = async () => {
 const smartAccount = await permissionless.createSmartAccount();
 const sessionKey = await smartAccount.generateSessionKey({
 ttl: '24h', // Hardcoded Time-To-Live
 scope: ['placeBid', 'lockEscrow', 'claimRefund'], // Granular permissions
 safeStorage: true // Enforces Web Crypto API / IndexedDB
 });
 
 setSessionPermit(sessionKey);
 return sessionKey;
 };
 
 // 2. Secure Storage Enforcement (Blocks localStorage)
 const storePermitSecurely = (permit: SessionPermit) => {
 // Encrypt payload using Web Crypto API before IndexedDB persistence
 const encrypted = encryptWithAES(permit); 
 window.indexedDB.setItem('ffm_session_permit', encrypted);
 };
 
 // 3. Automatic Expiration & Fallback Handling
 useEffect(() => {
 if (sessionPermit && sessionPermit.expiresAt < Date.now()) {
 setSessionPermit(null);
 triggerWalletFallback(); // Prompts user for manual Metamask signing
 }
 }, [sessionPermit]);
 
 return { createSession, executeSessionAction, isSessionActive };
}

2. Strict CI/CD Enforcement

To guarantee the memory-only principle, the project enforces a zero-tolerance policy for insecure browser storage at the build level:

// ESLint Configuration (.eslintrc.js)
{
 "rules": {
 "no-restricted-properties": [
 "error",
 { "object": "localStorage", "message": "Forbidden: Use secure memory or encrypted IndexedDB via Web Crypto API." },
 { "object": "document", "property": "cookie", "message": "Forbidden: No cookies allowed for cryptographic permits." }
]
 }
}

3. 1-Click Trade Execution Flow

When a user submits a bid, the protocol checks for a valid session permit before routing the transaction through an ERC-4337 Bundler.

// Smart Contract Perspective (Unchanged Logic)
function placeBid(uint256 auctionId, InEuint32 calldata encryptedBid) external {
 // Contract validates the signature normally.
 // Abstraction happens entirely on the client-side Bundler.
 require(_verifySignature(encryptedBid, msg.sig), "Invalid signature");
 
 FHE.lte(encryptedBid, FHE.asEuint32(escrowBalances[msg.sender]));
 ciphertextHashes[auctionId].push(keccak256(abi.encode(encryptedBid)));
}

Architectural Impact: UX & Security

Session Execution Flow

️ Security Guarantees & Threat Mitigations

1. XSS Attack Surface Reduction: By strictly prohibiting localStorage and utilizing encrypted IndexedDB + RAM storage, malicious scripts injected into the frontend cannot easily scrape valid session permits.
2. Time-Boxed Compromise Window: Even if a session permit is intercepted, the 24-hour TTL ensures the attacker has a severely limited window to exploit it before the permit cryptographically expires.
3. Function-Specific Scoping: A compromised session key can only trigger placeBid, lockEscrow, or claimRefund. It cannot withdraw funds to arbitrary addresses, modify auction parameters, or upgrade contracts.
4. Graceful Degradation: The triggerWalletFallback() mechanism ensures that UX abstraction never compromises protocol liveness. If the Smart Account network is congested, the user is seamlessly prompted for standard signing.

Audit Gate Compliance (P0)

• [] Zero localStorage/cookies usage: Enforced via ESLint no-restricted-properties rule.
• [] 24-Hour TTL Enforced: Session permits automatically invalidate post-expiry.
• [] Granular Scoping: Keys cannot authorize upgradeToAndCall or arbitrary fund transfers.
• [] Fail-Safe Fallback: UI correctly prompts for wallet signature upon session expiry or Bundler failure.
• [] Memory Encryption: IndexedDB payloads encrypted using Web Crypto API before persistence.

Next Steps

• Proceed to System Architecture to review how all components integrate into the asynchronous CoFHE flow.
• Explore Security Model for comprehensive threat matrices and emergency protocols.
• See Developer Quickstart to configure the ERC-4337 bundler locally and test session management.