DEX Frontend Application
Relevant source files
The following files were used as context for generating this wiki page:
The DEX Frontend Application is a production-ready Decentralized Exchange interface built for the X3 Chain ecosystem. It leverages Next.js 16 to provide a high-performance, real-time trading experience, integrating directly with X3 Chain nodes via a custom WebSocket RPC client. The application supports market swaps (spot trading) and limit order management, utilizing the X3 Atomic Settlement engine to ensure trust-minimized asset exchanges.
Sources: apps/dex/README.md:1-10, X3_END_TO_END_GAPS_MASTER_PLAN.md:145-150
Architecture and Tech Stack
The application follows a modern React architecture utilizing the Next.js App Router pattern. It is designed for modularity, separating UI components from blockchain interaction logic and state management.
Technical Specifications
| Category | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| Language | TypeScript |
| Styling | Tailwind CSS 4 |
| State Management | Zustand |
| Data Fetching | TanStack Query (React Query v5) |
| Animations | Framer Motion |
| Icons | Lucide React |
| Notifications | React Hot Toast |
Sources: apps/dex/README.md:12-21, apps/dex/package.json:11-26
Directory Structure
The codebase is organized into functional modules to ensure scalability and maintainability:
app/: Contains the Next.js App Router pages and root layouts.components/: Reusable React components such asSwapInterfaceandWalletConnector.hooks/: Custom React hooks for local state and blockchain interactions.lib/: Utility functions and the specializedrpc-client.ts.types/: Global TypeScript definitions for orders and RPC responses.
Sources: apps/dex/README.md:23-35, apps/dex/CLAUDE.md:13-22
RPC Integration and Data Flow
The DEX interacts with the X3 Chain through a dedicated WebSocket RPC client located in apps/dex/app/lib/rpc-client.ts. This client manages JSON-RPC 2.0 communication, request ID tracking, and automatic reconnection.
Communication Flow
The following diagram illustrates the lifecycle of a swap estimation and execution request:
Core RPC Methods
The frontend expects specific methods to be registered on the X3 Node:
walletDex_estimateSwap: Retrieves estimated output for market orders.walletDex_executeSwap: Submits a swap transaction to the chain.walletDex_getBalance: Queries specific token balances for the connected wallet.walletDex_getApprovalStatus: Checks if the DEX has permission to spend the user's tokens.
Sources: apps/dex/README.md:100-110, apps/dex/README.md:154-165
Trading Interfaces
Swap Interface (Market Orders)
The SwapInterface component handles immediate spot trades. It supports real-time estimation, slippage tolerance configuration (defaulted to allow for 5% slippage in high-volatility scenarios), and token pair selection for X3, USDC, BTC, and ETH.
Sources: apps/dex/README.md:39-50, production/public/x3-technical.html:125-135
Limit Order Interface
The LimitOrderInterface allows users to place Buy/Sell orders at specific price points. When a limit order is placed, the frontend creates an OrderSettlementIntent.
- Order Structure: Includes
id,tokenIn,tokenOut,limitPrice,status, andexpiresAt. - Workflow: Orders are matched by the
limit_order_bookand executed atomically by thepallet_x3_settlement_engine.
Sources: apps/dex/README.md:73-85, apps/dex/README.md:144-152
Component Logic and Constraints
Following the project's architectural guidelines, components are designed to be concise and type-safe.
Implementation Pattern
Every feature follows a strict validation-first pattern as defined in the project's Blueprint templates:
// Pattern MIRRORED from apps/dex/PRPs/templates/prp_base.md
export default function TradingFeature({ amount, pair }: FeatureProps) {
// 1. Validate props using Zod or local schema
// 2. Use 'use client' for interactive trading state
// 3. Utilize centralized hooks (e.g., useX3RpcClient)
// 4. Implement standardized Loading/Error fallbacks
}
Sources: apps/dex/PRPs/templates/prp_base.md:85-110, apps/dex/CLAUDE.md:25-30
Key Global Rules
- File Length: No file should exceed 500 lines to ensure readability.
- TypeScript: Mandatory use for all components and utility functions.
- Server vs Client: Components use Next.js App Router patterns (Server Components by default,
use clientfor trading interfaces).
Sources: apps/dex/CLAUDE.md:9-12, apps/dex/CLAUDE.md:58-65
Wallet Integration
The WalletConnector component provides the interface for connecting Web3 wallets. While initial versions utilize mock connections, the production path integrates the Polkadot.js extension.
Conclusion
The DEX Frontend Application serves as the primary gateway for users to access the X3 Chain's liquidity pools. By combining Next.js 16's performance with a custom WebSocket RPC client and atomic settlement logic, it provides a secure and responsive environment for both market and limit-based decentralized trading.
Sources: apps/dex/README.md:230-245, X3_END_TO_END_GAPS_MASTER_PLAN.md:280-285