Merge pull request #5740 from EdgeApp/sam/ramp-plugin-full

Full New Ramp Plugin Rearchitecture

Author: samholmes

.gitignore

@@ -17,6 +17,7 @@ IDEWorkspaceChecks.plist
 android-release.bundle.map
 ios-release.bundle.map
 keystores/
+.run.env
 
 # Debugging
 overrideTheme.json

AGENTS.md

@@ -1,5 +1,22 @@
 # Edge React GUI - Agent Guidelines
 
+## Initialization
+
+**Before starting any task, ensure `docs/` is in context:**
+
+1. **Use `find docs/ -name "*.md" -type f`** to recursively list all `.md` files in `docs/` folder to get an index of available documentation
+2. **Read relevant docs** to understand existing conventions, patterns, and business logic before implementing features
+
+## Workflow
+
+### Documentation Management
+
+- **Document lessons learned** when prompts contain "always", "remember", "never" or similar memory keywords
+- **Create markdown files** in `docs/` folder for conventions, business logic, and codebase patterns discovered
+- **Amend existing docs** rather than creating duplicates to keep knowledge base organized and succinct
+- **Prioritize documenting** coding conventions, architectural patterns, and business rules
+- **All `.md` files in `docs/` must be indexed** in the Documentation section below with "When to read" and "Summary" descriptions
+
 ## Package Manager
 
 - **Use Yarn v1** instead of npm for all package management and script execution
@@ -9,7 +26,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
@@ -51,3 +69,42 @@
 - Create pseudo-merge commits with "future! branch-name" for dependent features
 - Use `git rebase --onto` to update dependent branches when base changes
 - Remove future commits by rebasing onto master once dependencies are merged
+
+## Documentation
+
+The following documentation files provide detailed guidance for specific areas of development. **Read the relevant documentation before starting work** in these areas:
+
+### `docs/component-styling-guidelines.md`
+
+**When to read**: Before styling components or converting inline styles to styled components
+**Summary**: Guidelines for using the `styled` HOC, file structure patterns, and avoiding inline styles. Essential for maintaining consistent component styling across the codebase.
+
+### `docs/localization-guidelines.md`
+
+**When to read**: Before adding any UI text or working with user-facing strings
+**Summary**: Mandatory guidelines for localizing all UI strings using `lstrings` from `en_US.ts`. Covers naming conventions, parameter handling, and implementation steps for internationalization.
+
+### `docs/MAESTRO.md`
+
+**When to read**: When setting up or running end-to-end tests, or when working on test automation
+**Summary**: Complete setup guide for Maestro mobile testing framework. Includes installation instructions, running tests, and creating new tests with Maestro Studio.
+
+### `docs/GUI_PLUGINS_ARCHITECTURE.md`
+
+**When to read**: When working on fiat on/off ramp features, payment integrations, or plugin system
+**Summary**: Comprehensive architecture guide for the fiat plugin system. Covers provider implementations, payment method configurations, regional restrictions, and integration patterns for buy/sell cryptocurrency features.
+
+### `docs/scene-architecture-patterns.md`
+
+**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.

bity-ramp-plugin-verification.md

@@ -0,0 +1,100 @@
+# Bity Ramp Plugin Verification Report
+
+## Overview
+The Bity ramp plugin implementation has been verified to correctly support the new `checkSupport` API as described in the ramp plugin architecture documentation.
+
+## Verification Results
+
+### 1. Plugin Interface ✅
+The plugin correctly implements both required methods:
+- `checkSupport: (request: RampCheckSupportRequest) => Promise<RampSupportResult>`
+- `fetchQuote: (request: RampQuoteRequest) => Promise<RampQuoteResult[]>`
+
+### 2. Shared Validation Logic ✅
+Both methods share the same validation logic through helper functions:
+- `isRegionSupported()` - Used by both checkSupport (line 607) and fetchQuote (line 671)
+- `isCryptoSupported()` - Used by both checkSupport (lines 612-618) and fetchQuote (line 676)
+- `findCryptoCurrency()` - Used for finding crypto in provider's currency list
+- `findFiatCurrency()` - Used for finding fiat in provider's currency list
+
+### 3. Return Types ✅
+- `checkSupport` correctly returns `{ supported: boolean }` (RampSupportResult type)
+- `fetchQuote` correctly returns `RampQuoteResult[]` array
+
+### 4. Error Handling ✅
+- **checkSupport**: Catches all errors and returns `{ supported: false }` instead of throwing (lines 648-652)
+- **fetchQuote**: Returns empty array `[]` for all error conditions (lines 673, 677, 686, 699, 711, 743, 751, 759, 781, 791, 810)
+
+### 5. Architecture Compliance ✅
+The implementation follows all patterns from the documentation:
+- Fast local checks in `checkSupport` before API calls
+- Shared provider config fetching with 2-minute TTL cache
+- No unnecessary API calls for unsupported pairs
+- Clear separation of concerns between support checking and quote fetching
+
+## Key Implementation Details
+
+### Helper Functions
+```typescript
+// Region validation (line 520)
+function isRegionSupported(regionCode: FiatPluginRegionCode): boolean
+
+// Crypto validation (line 527)
+function isCryptoSupported(
+  pluginId: string,
+  tokenId: EdgeTokenId,
+  direction: 'buy' | 'sell'
+): boolean
+
+// Currency finders (lines 539 & 575)
+function findCryptoCurrency(...)
+function findFiatCurrency(...)
+```
+
+### Caching Strategy
+- Provider config cached for 2 minutes (line 277: `CACHE_TTL_MS = 2 * 60 * 1000`)
+- Cache checked before API calls (line 409)
+- Graceful fallback to cached data on API failures
+
+### Support Checking Flow
+1. Quick local region check
+2. Quick local crypto check against no-KYC list
+3. Fetch provider config (cached)
+4. Check fiat currency support
+5. Return boolean result
+
+### Quote Fetching Flow
+1. Reuse same validation helpers as checkSupport
+2. Skip API calls if validation fails
+3. Return empty array for any failures
+4. Only throw for actual critical errors
+
+## Example Usage
+
+```typescript
+// Check support across multiple plugins
+const supportResults = await Promise.all(
+  plugins.map(plugin => plugin.checkSupport(request))
+)
+
+// Filter to supported plugins
+const supportedPlugins = plugins.filter(
+  (plugin, index) => supportResults[index].supported
+)
+
+// Only fetch quotes from supported plugins
+const quotes = await Promise.all(
+  supportedPlugins.map(plugin => plugin.fetchQuote(quoteRequest))
+)
+```
+
+## Conclusion
+
+The Bity ramp plugin implementation fully complies with the new `checkSupport` API architecture. It demonstrates:
+- Proper type safety with TypeScript
+- Efficient caching to minimize API calls
+- Shared validation logic between methods
+- Correct error handling patterns
+- Clean separation of concerns
+
+The implementation serves as a good example for migrating other ramp plugins to the new architecture.

design.png

@@ -0,0 +1,54 @@
+# Component Styling Guidelines
+
+## File Structure
+
+- **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 (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
+
+- **Always use `styled` HOC** from `@src/components/hoc/styled.tsx` instead of inline styles
+- **Run `yarn eslint --fix`** on all files to format and fix lint errors automatically
+- **EdgeText with styled**: EdgeText can be used with styled HOC since it accepts a `style` prop
+- **Raw text fallback**: If styled EdgeText causes raw text ESLint errors, use regular EdgeText with cacheStyles
+- **Avoid inline styles**: Use styled HOC or cacheStyles, never inline style objects
+
+## Example File Structure
+
+```tsx
+// Types first
+interface Props {
+  // ...
+}
+
+// Exports second
+export const MyComponent = (props: Props) => {
+  return (
+    <Container>
+      <StyledText>{formatText('Hello')}</StyledText>
+    </Container>
+  )
+}
+
+// Styled components third (more relevant to component structure)
+const Container = styled(View)({
+  // styles
+})
+
+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,82 @@
+# Localization Guidelines
+
+## Core Principle
+
+**ALWAYS put strings displayed in the UI in the `@src/locales/en_US.ts` file for localization.** Use `lstrings.string_name` to access the string.
+
+## String Naming Convention
+
+### Basic Strings
+
+- Use descriptive, hierarchical naming: `component_context_description`
+- Example: `trade_region_select_buy_crypto`, `settings_account_title`
+
+### Parameterized Strings
+
+If a string uses sprintf and `%s` or replacements, suffix the string with parameter indicators:
+
+- **Single parameter**: `_s` suffix
+  - Example: `buy_1s: 'Buy %1$s'`
+- **Two parameters**: `_2s` suffix
+  - Example: `error_balance_below_minimum_to_stake_2s: 'Your balance of %1$s does not meet the minimum %2$s required to stake.'`
+- **Multiple parameters**: `_ns` suffix (where n is the number)
+  - Example: `_3s`, `_4s`, `_5s` etc.
+
+## Implementation Steps
+
+1. **Identify hardcoded strings** in UI components
+2. **Add strings to `en_US.ts`** with appropriate naming and parameter suffixes
+3. **Replace hardcoded strings** with `lstrings.string_name` references
+4. **Import lstrings** from `'../../locales/strings'` (adjust path as needed)
+
+## Examples
+
+### Before (Hardcoded)
+
+```tsx
+<EdgeText>Buy Crypto</EdgeText>
+<EdgeText>Start in 4 Easy Steps</EdgeText>
+<EdgeText>{`Step 1: Select Your Region`}</EdgeText>
+```
+
+### After (Localized)
+
+```tsx
+// In en_US.ts
+export const strings = {
+  trade_region_select_buy_crypto: 'Buy Crypto',
+  trade_region_select_start_steps: 'Start in 4 Easy Steps',
+  trade_region_select_step_1: ' Select Your Region for personalized options',
+  // ...
+}
+
+// In component
+import { lstrings } from '../../locales/strings'
+
+<EdgeText>{lstrings.trade_region_select_buy_crypto}</EdgeText>
+<EdgeText>{lstrings.trade_region_select_start_steps}</EdgeText>
+<EdgeText>{lstrings.trade_region_select_step_1}</EdgeText>
+```
+
+### Parameterized Example
+
+```tsx
+// In en_US.ts
+buy_1s: 'Buy %1$s',
+error_balance_below_minimum_2s: 'Balance %1$s below minimum %2$s',
+
+// In component
+<EdgeText>{sprintf(lstrings.buy_1s, currencyCode)}</EdgeText>
+<EdgeText>{sprintf(lstrings.error_balance_below_minimum_2s, balance, minimum)}</EdgeText>
+```
+
+## Benefits
+
+- **Internationalization ready**: All strings can be translated to other languages
+- **Consistency**: Centralized string management prevents duplicates
+- **Maintainability**: Easy to update strings across the entire app
+- **Type safety**: TypeScript ensures string keys exist
+
+## Remember
+
+This is a **mandatory** practice for all UI strings. No exceptions should be made for hardcoded strings in user-facing components.