chore: sync submodule state (parent ref update)

Made-with: Cursor
2026-03-02 12:14:14 -08:00
parent b6a776e5d7
commit 25c96e210a
316 changed files with 29779 additions and 677 deletions
--- a/docs/ON_RAMP_INTEGRATION_GUIDE.md
+++ b/docs/ON_RAMP_INTEGRATION_GUIDE.md
@@ -0,0 +1,344 @@
+# On-Ramp Integration Guide for ChainID 138
+
+Complete guide for integrating on-ramp (buy/sell) functionality with MetaMask on ChainID 138.
+
+## Overview
+
+This guide covers on-ramp integration options for ChainID 138, enabling users to buy and sell tokens with fiat currency directly in MetaMask.
+
+## On-Ramp Providers
+
+### Recommended Providers
+
+1. **MoonPay**
+   - Leading on-ramp provider
+   - Supports 100+ countries
+   - Multiple payment methods
+   - **Contact**: https://www.moonpay.com/business
+   - **Integration**: https://developers.moonpay.com
+
+2. **Ramp Network**
+   - European-focused
+   - Fast KYC process
+   - Competitive fees
+   - **Contact**: https://ramp.network
+   - **Integration**: https://docs.ramp.network
+
+3. **Transak**
+   - Global coverage
+   - Multiple payment methods
+   - Developer-friendly
+   - **Contact**: https://transak.com
+   - **Integration**: https://docs.transak.com
+
+4. **Wyre**
+   - US-focused
+   - Bank transfers
+   - ACH support
+   - **Contact**: https://www.sendwyre.com
+   - **Integration**: https://docs.sendwyre.com
+
+5. **Banxa**
+   - Global coverage
+   - Multiple payment methods
+   - Fast processing
+   - **Contact**: https://banxa.com
+   - **Integration**: https://docs.banxa.com
+
+## Integration Process
+
+### Step 1: Choose Provider
+
+Considerations:
+- **Geographic Coverage**: Which countries are supported?
+- **Payment Methods**: Credit card, bank transfer, etc.
+- **Fees**: Transaction fees and limits
+- **KYC Requirements**: KYC process and requirements
+- **Integration Complexity**: Ease of integration
+- **Support**: Developer and user support
+
+### Step 2: Partner with Provider
+
+1. **Contact Provider**:
+   - Request ChainID 138 integration
+   - Provide network information
+   - Discuss partnership terms
+
+2. **Requirements**:
+   - Network information
+   - Token information
+   - Compliance documentation
+   - Business information
+
+3. **Agreement**:
+   - Partnership terms
+   - Fee structure
+   - Integration timeline
+   - Support agreement
+
+### Step 3: Technical Integration
+
+#### MoonPay Integration Example
+
+```javascript
+// MoonPay Widget Integration
+import { MoonPayBuyWidget } from '@moonpay/moonpay-js';
+
+const moonPay = new MoonPayBuyWidget({
+  apiKey: 'YOUR_API_KEY',
+  environment: 'production',
+  variant: 'overlay',
+  baseCurrencyCode: 'usd',
+  baseCurrencyAmount: '100',
+  defaultCurrencyCode: 'eth',
+  walletAddress: userAddress,
+  walletAddresses: {
+    eth: userAddress,
+    // Add ChainID 138 address
+  },
+  onClose: () => {
+    console.log('Widget closed');
+  },
+  onComplete: (data) => {
+    console.log('Transaction complete', data);
+  },
+});
+
+moonPay.show();
+```
+
+#### Ramp Integration Example
+
+```javascript
+// Ramp Widget Integration
+import { RampInstant } from '@ramp-network/ramp-instant';
+
+const ramp = new RampInstant({
+  hostAppName: 'Your App',
+  hostLogoUrl: 'https://your-app.com/logo.png',
+  variant: 'auto',
+  defaultAsset: 'ETH_138', // ChainID 138 ETH
+  userAddress: userAddress,
+  onClose: () => {
+    console.log('Widget closed');
+  },
+  onPurchaseCreated: (purchase) => {
+    console.log('Purchase created', purchase);
+  },
+});
+```
+
+### Step 4: Configure Network
+
+1. **Add ChainID 138 to Provider**:
+   - Provide network configuration
+   - Configure RPC endpoints
+   - Set up token support
+
+2. **Token Configuration**:
+   - Add supported tokens
+   - Configure token metadata
+   - Set up token logos
+
+3. **Testing**:
+   - Test buy flow
+   - Test sell flow
+   - Test error handling
+
+## Supported Tokens
+
+### Buy (Fiat → Crypto)
+
+- **ETH**: Native currency
+- **cUSDT**: Compliant Tether USD
+- **cUSDC**: Compliant USD Coin
+- **WETH**: Wrapped Ether
+- **LINK**: Chainlink Token
+
+### Sell (Crypto → Fiat)
+
+- **ETH**: Native currency
+- **cUSDT**: Compliant Tether USD
+- **cUSDC**: Compliant USD Coin
+
+## Payment Methods
+
+### Supported Methods
+
+1. **Credit/Debit Cards**:
+   - Visa, Mastercard, Amex
+   - Instant processing
+   - Higher fees
+
+2. **Bank Transfers**:
+   - ACH (US)
+   - SEPA (Europe)
+   - Lower fees
+   - Slower processing
+
+3. **Apple Pay / Google Pay**:
+   - Mobile payments
+   - Fast processing
+   - Higher fees
+
+4. **Crypto Payments**:
+   - Pay with other cryptocurrencies
+   - Instant processing
+   - Lower fees
+
+## Fees and Limits
+
+### Typical Fees
+
+- **Credit Card**: 3-5%
+- **Bank Transfer**: 1-2%
+- **Apple Pay / Google Pay**: 3-5%
+- **Crypto Payment**: 0.5-1%
+
+### Typical Limits
+
+- **Minimum**: $10-50
+- **Maximum (Daily)**: $1,000-10,000
+- **Maximum (Monthly)**: $10,000-100,000
+- **KYC Required**: Varies by amount
+
+## KYC/AML Requirements
+
+### KYC Levels
+
+1. **Level 1 (No KYC)**:
+   - Small amounts only
+   - Limited features
+   - Basic verification
+
+2. **Level 2 (Basic KYC)**:
+   - Email verification
+   - Phone verification
+   - ID verification
+
+3. **Level 3 (Full KYC)**:
+   - Full identity verification
+   - Address verification
+   - Enhanced due diligence
+
+### Compliance
+
+- **KYC**: Know Your Customer
+- **AML**: Anti-Money Laundering
+- **Sanctions**: Sanctions screening
+- **Regulatory**: Regulatory compliance
+
+## MetaMask Integration
+
+### Requirements
+
+1. **On-Ramp Provider Partnership**:
+   - Partner with on-ramp provider
+   - Complete integration
+   - Test functionality
+
+2. **Consensys Approval**:
+   - Submit on-ramp for MetaMask approval
+   - Provide compliance documentation
+   - Complete integration review
+
+3. **Compliance**:
+   - KYC/AML compliance
+   - Regulatory compliance
+   - Security compliance
+
+### Integration Process
+
+1. **Phase 1: Provider Integration** (Month 1-2)
+   - Partner with provider
+   - Complete technical integration
+   - Test buy/sell flows
+
+2. **Phase 2: Compliance** (Month 2-3)
+   - Complete KYC/AML setup
+   - Regulatory compliance
+   - Security review
+
+3. **Phase 3: MetaMask Integration** (Month 3-6)
+   - Submit to MetaMask
+   - Complete integration review
+   - Test MetaMask integration
+   - Launch on-ramp
+
+## Testing
+
+### Test Scenarios
+
+1. **Buy Flow**:
+   - Buy ETH with credit card
+   - Buy cUSDT with bank transfer
+   - Verify tokens received
+   - Test error handling
+
+2. **Sell Flow**:
+   - Sell ETH for fiat
+   - Sell cUSDT for fiat
+   - Verify fiat received
+   - Test error handling
+
+3. **Edge Cases**:
+   - Minimum amount
+   - Maximum amount
+   - Failed payments
+   - Refunds
+
+## Monitoring
+
+### Metrics to Monitor
+
+- Buy/sell volume
+- Success rate
+- Average transaction time
+- Fee collection
+- User complaints
+- Security events
+
+### Alerts
+
+- Failed transactions
+- High failure rate
+- Security incidents
+- Compliance issues
+
+## Documentation
+
+### User Documentation
+
+- How to buy tokens
+- How to sell tokens
+- Payment methods
+- Fees and limits
+- KYC process
+- Troubleshooting guide
+
+### Developer Documentation
+
+- On-ramp API documentation
+- Integration examples
+- SDK documentation
+- Webhook documentation
+
+## Support
+
+### User Support
+
+- Buy/sell transaction issues
+- Payment method questions
+- KYC questions
+- Troubleshooting
+
+### Developer Support
+
+- Integration help
+- API questions
+- Webhook questions
+- Testing support
+
+---
+
+**Last Updated**: 2026-01-26