feat(ramp): add new plugin architecture for fiat on/off ramps

- Implement TradeCreateScene and TradeOptionSelectScene for buy/sell flow
- Add Paybis as first ramp plugin with full API integration
- Create reusable hooks for ramp plugin management (useRampPlugins, useRampQuotes)
- Add payment type icon system with comprehensive mappings
- Implement quote fetching and comparison across multiple providers
- Add best rate badge component for quote comparison
- Create ramp plugin type definitions and store utilities
- Add comprehensive documentation for migration and architecture
- Include unit tests for payment types and store IDs
- Update navigation and deeplink handlers for ramp flows

BREAKING CHANGE: Replaces legacy FiatPluginUi with new ramp plugin system

Author: samholmes

AGENTS.md

@@ -21,7 +21,8 @@
 
 ## Build/Test/Lint Commands
 
-- `yarn lint` - Run ESLint on entire codebase
+- `yarn lint` - Run ESLint on entire codebase (only use when working on warning cleanup)
+- `yarn lint --quiet` - Run ESLint on entire codebase and only get error (Prefer this usage always)
 - `yarn fix` - Auto-fix linting issues and deduplicate yarn
 - `yarn test` - Run Jest tests (single run)
 - `yarn watch` - Run Jest tests in watch mode
@@ -92,3 +93,13 @@ The following documentation files provide detailed guidance for specific areas o
 
 **When to read**: Before creating new scenes or modifying existing scene components
 **Summary**: Critical architectural patterns for Edge scenes. Covers the fundamental rule that scenes must never implement custom headers (managed by react-navigation), proper SceneWrapper usage, and navigation configuration patterns. Includes TradeCreateScene case study showing common architectural violations to avoid.
+
+### `docs/payment-type-icons.md`
+
+**When to read**: When working with payment type icons in fiat plugins or payment method displays
+**Summary**: Explains the payment type icon mapping system for displaying appropriate icons for different payment methods. Covers usage with `getPaymentTypeIcon` utility, integration with PaymentOptionCard, direct and fallback mappings, and how to add new payment types.
+
+### `docs/ramp-plugin-migration-guide.md`
+
+**When to read**: Before migrating ramp plugins from legacy provider architecture to new ramp plugin architecture or when creating new ramp plugins
+**Summary**: Comprehensive migration guide for removing FiatPluginUi abstraction and using direct API imports. Covers migration of toasts, modals, navigation, permissions (with important boolean logic inversion note), wallet operations, and environment configuration requirements. Includes detailed steps for creating init options cleaners, validating plugin initialization, and registering plugins in envConfig. Also explains how to migrate getSupportedAssets initialization logic to an internal fetchProviderConfig function with 2-minute TTL caching. Essential for converting legacy fiat providers to new ramp plugins and ensuring proper type safety.

design.png

@@ -4,7 +4,8 @@
 
 - **Types first**: Type definitions at the top serve as documentation
 - **Exports second**: Component exports immediately after types for visibility
-- **Styled components third**: All styled components after the main export
+- **Styled components third**: All styled components after the main export (more relevant to component structure)
+- **Utility functions fourth**: Helper functions and components scoped to the file come after styled components
 - **Styles last**: cacheStyles objects at the bottom of the file
 
 ## Styling Patterns
@@ -27,12 +28,12 @@ interface Props {
 export const MyComponent = (props: Props) => {
   return (
     <Container>
-      <StyledText>Hello</StyledText>
+      <StyledText>{formatText('Hello')}</StyledText>
     </Container>
   )
 }
 
-// Styled components third
+// Styled components third (more relevant to component structure)
 const Container = styled(View)({
   // styles
 })
@@ -41,6 +42,11 @@ const StyledText = styled(EdgeText)({
   // styles
 })
 
+// Utility functions fourth (scoped to this file)
+const formatText = (text: string): string => {
+  return text.toUpperCase()
+}
+
 // Styles last (if needed for complex cases)
 const styles = cacheStyles({
   // fallback styles

docs/component-styling-guidelines.md

@@ -0,0 +1,122 @@
+# Payment Type Icons
+
+This document explains how to use the payment type icon mapping system for displaying appropriate icons for different payment methods in the fiat plugin system.
+
+## Overview
+
+The payment type icon system provides a consistent way to map `FiatPaymentType` values to their corresponding theme icon keys. This ensures that payment methods are displayed with the correct visual representation across the application.
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { getPaymentTypeIcon } from '../util/paymentTypeIcons'
+import { useTheme } from '../services/ThemeContext'
+
+const MyComponent = () => {
+  const theme = useTheme()
+  const paymentType = 'applepay' // FiatPaymentType
+  
+  const icon = getPaymentTypeIcon(paymentType, theme)
+  // Returns: { uri: 'path/to/apple-pay-icon.png' }
+}
+```
+
+### Integration with PaymentOptionCard
+
+When rendering payment options from quotes, use the first payment type to determine the icon:
+
+```typescript
+const QuoteResult = ({ quote }) => {
+  const theme = useTheme()
+  
+  // Get icon for the first payment type, fallback to partner icon
+  const paymentTypeIcon = quote.paymentTypes[0]
+    ? getPaymentTypeIcon(quote.paymentTypes[0], theme)
+    : undefined
+  const icon = paymentTypeIcon ?? { uri: quote.partnerIcon }
+  
+  return (
+    <PaymentOptionCard
+      title={quote.paymentTypes.join(', ')}
+      icon={icon}
+      // ... other props
+    />
+  )
+}
+```
+
+## Payment Type Mappings
+
+### Direct Mappings
+
+These payment types have dedicated icons in the theme:
+
+- `applepay` → `paymentTypeLogoApplePay`
+- `credit` → `paymentTypeLogoCreditCard`
+- `fasterpayments` → `paymentTypeLogoFasterPayments`
+- `googlepay` → `paymentTypeLogoGooglePay`
+- `ideal` → `paymentTypeLogoIdeal`
+- `interac` → `paymentTypeLogoInterac`
+- `payid` → `paymentTypeLogoPayid`
+- `paypal` → `paymentTypeLogoPaypal`
+- `pix` → `paymentTypeLogoPix`
+- `revolut` → `paymentTypeLogoRevolut`
+- `venmo` → `paymentTypeLogoVenmo`
+
+### Fallback Mappings
+
+These payment types use the generic bank transfer icon as a fallback:
+
+- `ach` → `paymentTypeLogoBankTransfer`
+- `colombiabank` → `paymentTypeLogoBankTransfer`
+- `directtobank` → `paymentTypeLogoBankTransfer`
+- `iach` → `paymentTypeLogoBankTransfer`
+- `iobank` → `paymentTypeLogoBankTransfer`
+- `mexicobank` → `paymentTypeLogoBankTransfer`
+- `pse` → `paymentTypeLogoBankTransfer`
+- `sepa` → `paymentTypeLogoBankTransfer`
+- `spei` → `paymentTypeLogoBankTransfer`
+- `turkishbank` → `paymentTypeLogoBankTransfer`
+- `wire` → `paymentTypeLogoBankTransfer`
+
+## API Reference
+
+### `getPaymentTypeIcon(paymentType: FiatPaymentType, theme: Theme): ImageProp | undefined`
+
+Returns the theme icon for a given payment type.
+
+**Parameters:**
+- `paymentType`: The payment type to get the icon for
+- `theme`: The theme object containing the icon images
+
+**Returns:**
+- `ImageProp`: The icon image object (`{ uri: string } | number`)
+- `undefined`: If the payment type doesn't have a corresponding icon
+
+### `getPaymentTypeThemeKey(paymentType: FiatPaymentType): keyof Theme | null`
+
+Returns just the theme key for a payment type without requiring the theme object.
+
+**Parameters:**
+- `paymentType`: The payment type to get the theme key for
+
+**Returns:**
+- `keyof Theme`: The theme key string
+- `null`: If the payment type doesn't have a corresponding theme key
+
+## Adding New Payment Types
+
+To add support for a new payment type:
+
+1. Add the payment type to the `FiatPaymentType` union in `fiatPluginTypes.ts`
+2. Add the corresponding icon to the theme in `types/Theme.ts`
+3. Update the `paymentTypeToThemeKey` mapping in `util/paymentTypeIcons.ts`
+4. Add the icon assets to all theme variations (edgeLight, edgeDark, etc.)
+
+## Notes
+
+- Payment types that are primarily bank-based use the generic bank transfer icon as a reasonable fallback
+- The system is designed to be extensible - new payment types can be added without breaking existing functionality
+- Always provide a fallback (like the partner icon) when using payment type icons in case the mapping returns undefined