396 lines
19 KiB
Markdown
396 lines
19 KiB
Markdown
# UI/UX Specification: ISO-20022 Combo Builder v2
|
|
|
|
## Overview
|
|
This document specifies the user interface and user experience for the Combo Builder v2, which enables users to compose multi-step financial workflows combining DeFi protocols and traditional banking rails (ISO-20022). The UI is inspired by Furucombo's Create page but extends it with compliance overlays, hybrid adapter support, and optional simulation.
|
|
|
|
## Design Principles
|
|
1. **Composability**: Drag-and-drop interface for building complex financial workflows
|
|
2. **Transparency**: Clear display of compliance status, fees, and execution risks
|
|
3. **Flexibility**: Support for both DeFi and fiat/DTL adapters with selection control
|
|
4. **User Control**: Optional simulation for advanced users, mandatory compliance checks
|
|
5. **Accessibility**: Intuitive for non-developers while providing advanced features
|
|
|
|
---
|
|
|
|
## 1. Main Builder Canvas
|
|
|
|
### Layout Structure
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Header: [Combo Builder] [User Identity] [Wallet] [Settings] │
|
|
├─────────────┬─────────────────────────────────────────────────────────┤
|
|
│ │ │
|
|
│ Adapter │ Canvas (Drop Zone) │
|
|
│ Palette │ ┌─────────────────────┐ │
|
|
│ │ │ Step 1: Borrow │ │
|
|
│ [DeFi] │ │ 💰 CBDC_USD: 100k │ │
|
|
│ - Swap │ └─────────────────────┘ │
|
|
│ - Borrow │ ┌─────────────────────┐ │
|
|
│ - Deposit │ │ Step 2: Swap │ │
|
|
│ - Bridge │ │ 🔄 USD → EUR │ │
|
|
│ │ └─────────────────────┘ │
|
|
│ [Fiat] │ ┌─────────────────────┐ │
|
|
│ - Pay │ │ Step 3: Pay │ │
|
|
│ - Repay │ │ 📤 EUR to IBAN │ │
|
|
│ - Transfer │ └─────────────────────┘ │
|
|
│ │ │
|
|
│ [Compliance]│ │
|
|
│ ✓ LEI │ │
|
|
│ ✓ KYC │ │
|
|
│ ✓ AML │ │
|
|
└─────────────┴─────────────────────────────────────────────────────┘
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Summary Panel: │
|
|
│ Initial Funds: 100,000 CBDC_USD │
|
|
│ You will receive: ~78,000 EUR │
|
|
│ Fees: 0.2% (200 USD) | Compliance: ✓ | Simulation: [Toggle] │
|
|
│ [Review & Sign] [Simulate] [Save Draft] │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Key Components
|
|
|
|
#### A. Adapter Palette (Left Sidebar)
|
|
- **DeFi Section**: Swappable protocols (Uniswap, Aave, Compound, etc.)
|
|
- **Fiat/DTL Section**: Banking rails (ISO-20022 pay, SWIFT, SEPA, etc.)
|
|
- **Compliance Badge**: Shows current user compliance status (LEI/DID/KYC/AML)
|
|
- **Filter Toggle**: "Show All" / "Show Whitelisted Only" / "Show DeFi Only" / "Show Fiat Only"
|
|
|
|
#### B. Canvas (Center)
|
|
- **Drop Zone**: Visual area where users place workflow steps
|
|
- **Step Cards**: Each step shows:
|
|
- Step number (1, 2, 3...)
|
|
- Icon (💰, 🔄, 💳, 📤)
|
|
- Step type and summary
|
|
- Compliance badge (if applicable)
|
|
- Drag handle (⋮⋮) for reordering
|
|
- Edit/Remove buttons
|
|
|
|
#### C. Summary Panel (Bottom)
|
|
- **Initial Funds**: What user must supply (from wallet or borrow)
|
|
- **You will receive**: Expected output at workflow end
|
|
- **Fee Display**: "Included 0.2% fee" (if applicable)
|
|
- **Compliance Status**: Visual indicators (✓ LEI, ✓ KYC, ✓ AML, ✓ DID)
|
|
- **Simulation Toggle**: Optional checkbox for advanced users
|
|
- **Action Buttons**: Review & Sign, Simulate (optional), Save Draft
|
|
|
|
---
|
|
|
|
## 2. Step Configuration Drawer
|
|
|
|
### Layout
|
|
```
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ Configure Step: Swap [X] │
|
|
├────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ From Token: [CBDC_USD ▼] │
|
|
│ Amount: [100,000] │
|
|
│ │
|
|
│ To Token: [CBDC_EUR ▼] │
|
|
│ Min Receive: [90,000] (auto-calculated) │
|
|
│ │
|
|
│ Slippage: [0.5%] (default) │
|
|
│ │
|
|
│ ────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ Compliance Requirements: │
|
|
│ ☑ LEI Required: [5493000IBP32UQZ0KL24] │
|
|
│ ☑ KYC Status: ✓ Verified │
|
|
│ ☑ AML Check: ✓ Passed │
|
|
│ │
|
|
│ [Save] [Cancel] │
|
|
└────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Features
|
|
- **Token/Asset Selection**: Dropdown with supported tokens (DeFi) or currencies (Fiat)
|
|
- **Amount Input**: Numeric input with validation
|
|
- **Compliance Fields**: Auto-populated from user session (LEI, KYC, AML status)
|
|
- **Dependency Visualization**: Shows which previous steps feed into this step
|
|
- **Validation Feedback**: Real-time error messages (insufficient balance, invalid IBAN, etc.)
|
|
|
|
---
|
|
|
|
## 3. Simulation Results Panel (Optional)
|
|
|
|
### Layout
|
|
```
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ Simulation Results [Close] │
|
|
├────────────────────────────────────────────────────────┤
|
|
│ Status: ✓ Simulation Successful │
|
|
│ │
|
|
│ Execution Summary: │
|
|
│ • Step 1 (Borrow): ✓ 100,000 CBDC_USD │
|
|
│ • Step 2 (Swap): ✓ 90,000 CBDC_EUR (estimated) │
|
|
│ • Step 3 (Pay): ✓ 78,000 EUR to beneficiary │
|
|
│ │
|
|
│ Gas Estimate: 450,000 gas │
|
|
│ Estimated Cost: $25.50 (at 50 gwei) │
|
|
│ │
|
|
│ Slippage Risk: Low (0.2% expected) │
|
|
│ Liquidity Check: ✓ Sufficient │
|
|
│ │
|
|
│ Compliance: ✓ All checks passed │
|
|
│ │
|
|
│ [Run Simulation Again] [Proceed to Sign] │
|
|
└────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Features
|
|
- **Step-by-Step Results**: Shows success/failure for each step
|
|
- **Gas Estimation**: Calculated gas cost for entire workflow
|
|
- **Slippage Analysis**: Expected slippage for swaps
|
|
- **Liquidity Checks**: Verifies sufficient liquidity for trades
|
|
- **Compliance Status**: Confirms all compliance requirements met
|
|
- **Error Warnings**: Highlights any potential failure points
|
|
|
|
---
|
|
|
|
## 4. Compliance Status Dashboard Overlay
|
|
|
|
### Layout
|
|
```
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ Compliance Status [Dismiss] │
|
|
├────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Identity Verification: │
|
|
│ ✓ LEI: 5493000IBP32UQZ0KL24 │
|
|
│ ✓ DID: did:web:example.com:user:123 │
|
|
│ ✓ KYC: Level 2 Verified (Expires: 2026-12-31) │
|
|
│ ✓ AML: Passed (Last check: 2025-01-15) │
|
|
│ │
|
|
│ Current Workflow Compliance: │
|
|
│ • All steps require LEI: ✓ Provided │
|
|
│ • KYC Level Required: 2 ✓ Met │
|
|
│ • AML Screening: ✓ Passed │
|
|
│ │
|
|
│ Missing Requirements: None │
|
|
│ │
|
|
│ [Update Identity] [View Compliance Details] │
|
|
└────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Features
|
|
- **Always Visible Badge**: Small indicator in header showing compliance status
|
|
- **Detailed View**: Expandable overlay with full compliance details
|
|
- **Workflow-Specific Checks**: Validates compliance for current workflow
|
|
- **Expiration Warnings**: Alerts if KYC/AML checks are expiring soon
|
|
- **Update Actions**: Quick links to update identity or run new checks
|
|
|
|
---
|
|
|
|
## 5. Adapter Selection Modal
|
|
|
|
### Layout
|
|
```
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ Select Adapter Type [X] │
|
|
├────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Filter: [All] [DeFi] [Fiat/DTL] [Whitelisted Only] │
|
|
│ │
|
|
│ ┌──────────────────┐ ┌──────────────────┐ │
|
|
│ │ DeFi Protocols │ │ Fiat/DTL Rails │ │
|
|
│ ├──────────────────┤ ├──────────────────┤ │
|
|
│ │ 🔄 Uniswap V3 │ │ 📤 ISO-20022 Pay │ │
|
|
│ │ 💰 Aave │ │ 💳 SWIFT MT │ │
|
|
│ │ 📊 Compound │ │ 🌐 SEPA │ │
|
|
│ │ 🌉 Bridge │ │ 🏦 FedNow │ │
|
|
│ │ │ │ │ │
|
|
│ └──────────────────┘ └──────────────────┘ │
|
|
│ │
|
|
│ Selected: ISO-20022 Pay │
|
|
│ │
|
|
│ [Add to Palette] [Cancel] │
|
|
└────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Features
|
|
- **Category Filtering**: Separate DeFi and Fiat/DTL adapters
|
|
- **Whitelist Toggle**: Show only approved/whitelisted adapters
|
|
- **Adapter Status**: Visual indicators (✓ Approved, ⚠ Deprecated, 🔒 Restricted)
|
|
- **Search**: Quick search for specific adapters
|
|
- **Version Info**: Shows adapter version and last updated date
|
|
|
|
---
|
|
|
|
## 6. User Flows
|
|
|
|
### Flow 1: Building a Simple Combo (DeFi Only)
|
|
1. User opens Builder page
|
|
2. User drags "Borrow" from DeFi palette → Canvas
|
|
3. Configures borrow step (asset, amount, collateral)
|
|
4. Drags "Swap" from palette → Canvas (after borrow step)
|
|
5. Configures swap step (from/to tokens, amount)
|
|
6. Summary panel updates automatically
|
|
7. User clicks "Review & Sign" (compliance auto-checked)
|
|
8. Redirected to preview/sign page
|
|
|
|
### Flow 2: Building Hybrid Combo (DeFi + Fiat)
|
|
1. User opens Builder page
|
|
2. Compliance badge shows: ✓ LEI, ✓ KYC, ✓ AML
|
|
3. User drags "Borrow" (DeFi) → Canvas
|
|
4. User drags "Swap" (DeFi) → Canvas
|
|
5. User drags "Pay" (Fiat/DTL) → Canvas
|
|
6. Configures pay step (IBAN, amount, beneficiary)
|
|
7. Compliance overlay appears: "Fiat step requires LEI"
|
|
8. LEI auto-populated from user session
|
|
9. User optionally enables simulation toggle
|
|
10. Clicks "Simulate" → sees results
|
|
11. Clicks "Review & Sign" → proceeds
|
|
|
|
### Flow 3: Advanced User with Simulation
|
|
1. User enables "Simulation" toggle in summary panel
|
|
2. Builds workflow as normal
|
|
3. Before signing, clicks "Simulate" button
|
|
4. Simulation results panel shows:
|
|
- Gas estimate
|
|
- Slippage analysis
|
|
- Liquidity checks
|
|
- Failure predictions
|
|
5. User reviews results, adjusts workflow if needed
|
|
6. Clicks "Proceed to Sign" after simulation passes
|
|
|
|
### Flow 4: Compliance Validation Failure
|
|
1. User builds workflow with fiat step requiring LEI
|
|
2. User has not provided LEI in settings
|
|
3. Compliance badge shows: ⚠ LEI Missing
|
|
4. User attempts to sign
|
|
5. Error modal: "LEI required for this workflow. Please update your identity in Settings."
|
|
6. User redirected to Settings page to add LEI
|
|
7. Returns to Builder, workflow auto-validated
|
|
|
|
---
|
|
|
|
## 7. Responsive Design
|
|
|
|
### Desktop (≥1024px)
|
|
- Full layout with sidebar palette, canvas, and summary panel
|
|
- All features visible simultaneously
|
|
|
|
### Tablet (768px - 1023px)
|
|
- Collapsible sidebar palette
|
|
- Canvas takes full width when palette collapsed
|
|
- Summary panel remains at bottom
|
|
|
|
### Mobile (<768px)
|
|
- Palette accessible via bottom sheet/modal
|
|
- Canvas scrollable vertically
|
|
- Step cards stack vertically
|
|
- Summary panel sticky at bottom
|
|
|
|
---
|
|
|
|
## 8. Accessibility Requirements
|
|
|
|
- **Keyboard Navigation**: Full keyboard support for drag-and-drop (arrow keys, space/enter)
|
|
- **Screen Reader Support**: ARIA labels for all interactive elements
|
|
- **Color Contrast**: WCAG AA compliance for all text and UI elements
|
|
- **Focus Indicators**: Clear focus states for all interactive elements
|
|
- **Error Messages**: Clear, actionable error messages for all validation failures
|
|
|
|
---
|
|
|
|
## 9. Performance Requirements
|
|
|
|
- **Initial Load**: < 2 seconds for Builder page
|
|
- **Step Addition**: < 500ms for drag-and-drop response
|
|
- **Summary Calculation**: Real-time updates < 200ms
|
|
- **Simulation**: < 5 seconds for full workflow simulation
|
|
- **Compliance Check**: < 1 second for status validation
|
|
|
|
---
|
|
|
|
## 10. Integration Points
|
|
|
|
### Frontend → Backend API
|
|
- `POST /api/plans` - Create execution plan
|
|
- `GET /api/plans/:id/simulate` - Run simulation (optional)
|
|
- `GET /api/compliance/status` - Fetch compliance status
|
|
- `GET /api/adapters` - List available adapters (filtered by type/whitelist)
|
|
|
|
### Frontend → Smart Contracts
|
|
- Wallet connection via Wagmi
|
|
- Plan signing via wallet signature
|
|
- Transaction submission via handler contract
|
|
|
|
---
|
|
|
|
## 11. Visual Design System
|
|
|
|
### Color Palette
|
|
- **Primary**: Black (#000000) for actions
|
|
- **Secondary**: Blue (#3B82F6) for compliance/info
|
|
- **Success**: Green (#10B981) for valid states
|
|
- **Warning**: Yellow (#F59E0B) for warnings
|
|
- **Error**: Red (#EF4444) for errors
|
|
- **Background**: White (#FFFFFF) for cards, Gray-50 (#F9FAFB) for canvas
|
|
|
|
### Typography
|
|
- **Headings**: Inter, 24px/32px (h1), 18px/24px (h2)
|
|
- **Body**: Inter, 14px/20px
|
|
- **Code/Monospace**: Fira Code, 12px/16px for addresses/IDs
|
|
|
|
### Icons
|
|
- Emoji icons for step types (💰, 🔄, 💳, 📤)
|
|
- Lucide React icons for UI elements (Edit, Remove, Drag, etc.)
|
|
|
|
---
|
|
|
|
## 12. Error States & Edge Cases
|
|
|
|
### Insufficient Balance
|
|
- Red warning badge on step card
|
|
- Error message: "Insufficient balance. You need 100,000 CBDC_USD but have 50,000."
|
|
|
|
### Invalid Workflow
|
|
- Step dependency error: "Step 2 requires output from Step 1. Please reorder steps."
|
|
- Visual connection lines between dependent steps
|
|
|
|
### Compliance Failure
|
|
- Modal overlay: "This workflow requires LEI verification. Please update your identity in Settings."
|
|
- Link to Settings page
|
|
|
|
### Simulation Failure
|
|
- Results panel shows: "⚠ Simulation Failed"
|
|
- Detailed error: "Step 2 (Swap) would fail due to insufficient liquidity."
|
|
|
|
### Network/Chain Mismatch
|
|
- Warning: "Selected adapter (Uniswap) is on Ethereum, but you're connected to Polygon."
|
|
- Option to switch network or select different adapter
|
|
|
|
---
|
|
|
|
## 13. Future Enhancements (Out of Scope for v2)
|
|
|
|
- **Workflow Templates**: Pre-built combo templates for common strategies
|
|
- **Workflow Sharing**: Share workflows with other users (with compliance validation)
|
|
- **Multi-user Workflows**: Collaborative workflow building
|
|
- **Advanced Analytics**: Historical performance tracking for workflows
|
|
- **Mobile App**: Native mobile app for workflow building
|
|
|
|
---
|
|
|
|
## Acceptance Criteria
|
|
|
|
1. ✅ User can drag adapters from palette to canvas
|
|
2. ✅ User can reorder steps by dragging
|
|
3. ✅ User can configure each step via drawer
|
|
4. ✅ Compliance status is always visible and validated
|
|
5. ✅ Optional simulation works for advanced users
|
|
6. ✅ Summary panel updates in real-time
|
|
7. ✅ Hybrid adapters (DeFi + Fiat) are selectable
|
|
8. ✅ Error states are clearly communicated
|
|
9. ✅ Responsive design works on mobile/tablet/desktop
|
|
10. ✅ Accessibility requirements are met
|
|
|
|
---
|
|
|
|
**Document Version**: 1.0
|
|
**Last Updated**: 2025-01-15
|
|
**Author**: Engineering Team
|
|
|