# Multi-Chain Payment Gateway

A comprehensive multi-chain payment gateway supporting Ethereum, BSC, Arbitrum, Polygon, and Harmony with advanced dashboards, administrative controls, and easy-to-integrate client-side widgets.

## ✨ Features

### Multi-Chain Support

* **Ethereum Mainnet**: Native ETH, WBTC, WETH, USDT, DAI, USDC
* **Binance Smart Chain**: Native BNB, BTCB, USDT, DAI, USDC
* **Arbitrum One**: Native ETH, WBTC, WETH, USDT, DAI, USDC
* **Polygon**: Native MATIC, WBTC, WETH, USDT, DAI, USDC
* **Harmony One**: Native ONE, ETH, BTC, USDT, DAI, USDC

### Comprehensive Dashboards

* **Main Dashboard**: Real-time overview of all chains, payments, and system health
* **Administrative Dashboard**: Complete configuration management for chains, widgets, and security
* **Widget Management**: Create, configure, and manage client-side payment widgets
* **Multi-Chain Monitoring**: Live status of all blockchain networks with latency and block data

### Client-Side Widgets

* **Easy Integration**: Single script tag deployment
* **Customizable Themes**: Light and dark mode support
* **Multi-Chain Selection**: Users can choose their preferred blockchain
* **Payment Calculation**: Real-time amount calculation with discount support
* **Event-Driven**: Custom events for seamless integration with existing applications

### Advanced Features

* **Discount System**: Configurable discount codes and percentages
* **Transaction Verification**: Automatic blockchain verification of payments
* **Security**: Rate limiting, CORS protection, and secure headers
* **RESTful API**: Clean and well-documented endpoints
* **Real-time Updates**: Auto-refreshing dashboards with live data

## 🛠️ Installation

1. **Clone the repository**

   ```bash
   git clone https://github.com/Whostler/paymentGateway.git
   cd paymentGateway
   ```
2. **Install dependencies**

   ```bash
   npm install
   ```
3. **Set up environment variables**

   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```
4. **Start the server**

   ```bash
   # Development mode
   npm run dev

   # Production mode
   npm start
   ```

## 🔧 Configuration

### Environment Variables

```env
# Server Configuration
PORT=3000
NODE_ENV=development

# Multi-Chain RPC Endpoints
ETH_RPC_URL=https://mainnet.infura.io/v3/YOUR_PROJECT_ID
BSC_RPC_URL=https://bsc-dataseed1.binance.org
ARB_RPC_URL=https://arb1.arbitrum.io/rpc
POLYGON_RPC_URL=https://polygon-rpc.com
HARMONY_RPC_URL=https://api.harmony.one

# Payment Settings
DEFAULT_DISCOUNT_PERCENT=0
MIN_PAYMENT_AMOUNT=1
MAX_PAYMENT_AMOUNT=1000000
```

### Supported Blockchains

| Blockchain | Native Token | Chain ID | Block Explorer                    |
| ---------- | ------------ | -------- | --------------------------------- |
| Ethereum   | ETH          | 1        | [Etherscan](https://etherscan.io) |
| BSC        | BNB          | 56       | [BSCScan](https://bscscan.com)    |
| Arbitrum   | ETH          | 42161    | [Arbiscan](https://arbiscan.io)   |

cd frontend pnpm install pnpm dev

Backend:

pnpm install pnpm dev

When developing locally run the backend at :3000 and the frontend Vite dev server (default :5173) or use `pnpm run frontend:dev` from project root which proxies `/api` to the backend.

\| Harmony | ONE | 1666600000 | [Harmony Explorer](https://explorer.harmony.one) |

## 📊 Dashboards

### Main Dashboard

Access the comprehensive dashboard at `http://localhost:3000/dashboard.html`

**Features:**

* **System Overview**: Real-time health, uptime, and environment status
* **Multi-Chain Status**: Connected chains, latency, and network health
* **Payment Statistics**: Transaction volume, success rates, and analytics
* **Widget Analytics**: Integration health and usage metrics
* **Blockchain Networks**: Live status of all supported chains

### Administrative Dashboard

Access admin controls at `http://localhost:3000/admin-dashboard.html`

**Features:**

* **Chain Management**: Enable/disable chains, configure settings
* **System Configuration**: Payment settings, security controls
* **Widget Management**: Create, configure, and delete widgets
* **Security Settings**: Rate limiting, CORS configuration

## 🔌 API Endpoints

### Base URL

```
http://localhost:3000/api
```

### Dashboard Endpoints

#### Get Dashboard Data

```http
GET /dashboard/data
```

#### Get Multi-Chain Statistics

```http
GET /dashboard/multichain
```

#### Get System Health

```http
GET /dashboard/health
```

### Admin Endpoints

#### Get Configuration

```http
GET /admin/config
```

#### Update Configuration

```http
PUT /admin/config
```

#### Chain Management

```http
GET /admin/chains
PUT /admin/chains/:chainName/toggle
PUT /admin/chains/:chainName/settings
```

### Widget Endpoints

#### Generate Widget

```http
POST /widgets/generate
```

**Request Body:**

```json
{
  "type": "payment",
  "theme": "light",
  "chains": ["ethereum", "bsc"],
  "domain": "yourdomain.com"
}
```

#### List Widgets

```http
GET /widgets/list
```

#### Serve Widget Script

```http
GET /widgets/:widgetId.js
```

## 🔗 Widget Integration

### Quick Integration

Add this script tag to your website:

```html
<script src="http://localhost:3000/widgets/WIDGET_ID.js"></script>
```

### Custom Container

Specify a custom container for the widget:

```html
<div id="my-payment-widget"></div>
<script src="http://localhost:3000/widgets/WIDGET_ID.js"></script>
<script>
  PaymentWidget.init('my-payment-widget');
</script>
```

### Event Handling

Listen for payment events:

```javascript
window.addEventListener('paymentRequested', (event) => {
  const { widgetId, token, amount, chain } = event.detail;
  // Handle payment processing
  console.log('Payment requested:', event.detail);
});
```

### Widget Configuration

Widgets support various configuration options:

* **Type**: `payment`, `calculator`
* **Theme**: `light`, `dark`
* **Chains**: Array of supported chains
* **Customization**: Colors, branding, styling

## 🧪 Testing

Run the test suite:

```bash
npm test
```

Test specific modules:

```bash
npm run test:unit
npm run test:integration
npm run test:e2e
```

## 🔐 Security Features

* **Multi-Chain Security**: Secure transaction verification across all chains
* **Rate Limiting**: Protects against abuse and DDoS attacks
* **CORS Protection**: Configurable origin whitelist
* **Security Headers**: Comprehensive security header configuration
* **Input Validation**: Strict validation of all requests
* **Environment Isolation**: Separate configurations for development and production

## 🚀 Deployment

### Production Setup

1. **Set environment to production**

   ```bash
   export NODE_ENV=production
   ```
2. **Configure production RPC endpoints**
   * Set up reliable RPC endpoints for all chains
   * Configure proper rate limits and security settings
   * Set secure JWT secrets and encryption keys
3. **Use process manager**

   ```bash
   npm install -g pm2
   pm2 start api/server.js --name "payment-gateway"
   ```

### Docker Deployment

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]
```

## 🤝 Integration Examples

### E-commerce Integration

```javascript
// Initialize payment widget
const widget = new PaymentWidget({
  type: 'payment',
  theme: 'light',
  chains: ['ethereum', 'polygon'],
  customization: {
    colors: {
      primary: '#your-brand-color'
    }
  }
});

// Handle payment completion
window.addEventListener('paymentRequested', async (event) => {
  const { token, amount, chain } = event.detail;
  
  // Process payment with your backend
  const result = await processPayment({
    token,
    amount,
    chain,
    orderId: 'your-order-id'
  });
  
  if (result.success) {
    // Redirect to success page
    window.location.href = '/payment-success';
  }
});
```

### Subscription Service Integration

```javascript
// For recurring payments
const subscriptionWidget = new PaymentWidget({
  type: 'subscription',
  chains: ['polygon', 'bsc'], // Lower gas fees
  recurring: {
    interval: 'monthly',
    amount: 9.99
  }
});
```

## 📈 Monitoring and Analytics

The gateway provides comprehensive monitoring:

* **Real-time Chain Status**: Monitor all blockchain networks
* **Payment Analytics**: Track transaction volume and success rates
* **Widget Performance**: Monitor widget usage across domains
* **System Health**: CPU, memory, and network monitoring
* **Custom Metrics**: Configurable business metrics

## 🆘 Support and Documentation

* **API Documentation**: Available at `/api/docs` (when enabled)
* **Widget Documentation**: See `/widget-demo.html` for examples
* **Configuration Guide**: Detailed in this README
* **Troubleshooting**: Check logs and health endpoints

## 📝 License

MIT License - see [LICENSE](https://github.com/Whostler/paymentGateway/blob/dev/LICENSE/README.md) file for details.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

***

Built with ❤️ for the multi-chain future