BridgeShield — AML Gateway for LI.FI Cross-Chain Trades

BridgeShield is an Anti-Money Laundering (AML) compliance gateway designed specifically for cross-chain trading platforms like LI.FI. It provides real-time risk assessment, transaction monitoring, and regulatory compliance for decentralized finance (DeFi) transactions.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                                                                         │
│   ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐  │
│   │                 │    │                 │    │                 │  │
│   │  Frontend Demo  │    │   Backend API   │    │ Frontend Admin  │  │
│   │  (Port: 5173)   │◄───┤   (Port: 3000)  │───►│  (Port: 5174)   │  │
│   │                 │    │                 │    │                 │  │
│   └─────────────────┘    └─────────────────┘    └─────────────────┘  │
│                                    │                                  │
│                                    ▼                                  │
│                          ┌─────────────────┐                          │
│                          │   SDK Package  │                          │
│                          │ @bridgeshield/ │                          │
│                          │      sdk       │                          │
│                          └─────────────────┘                          │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

🚀 Quick Start

Using Docker Compose (Recommended)

1. Clone the repository:

   git clone https://github.com/easyshellworld/bridgeshield
   cd bridgeshield

2. Start all services:

   docker-compose up -d

3. Access the applications:

   • Frontend Demo: http://localhost:5173
   • Earn Integration Flow Demo: http://localhost:5173/earn-flow
   • Backend API: http://localhost:3000
   • Frontend Admin: http://localhost:5174
   • API Documentation: http://localhost:3000/api/v1/docs

4. Stop services:

   docker-compose down

Development Mode

For hot-reload during development:

docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d

📦 SDK Package

For easy integration into your own applications:

npm install @bridgeshield/sdk

import { BridgeShieldClient } from '@bridgeshield/sdk';

const client = new BridgeShieldClient({
  baseUrl: 'https://api.bridgeshield.io',
});

const result = await client.checkAddress({
  address: '0x1234567890abcdef1234567890abcdef12345678',
  chainId: 1,
});

console.log(result.riskLevel); // 'LOW' | 'MEDIUM' | 'HIGH'
console.log(result.decision);  // 'ALLOW' | 'REVIEW' | 'BLOCK'

See packages/sdk/README.md for full documentation.

📁 Project Structure

bridgeshield/
├── backend/                 # Node.js/TypeScript backend API
│   ├── src/                # Source code
│   ├── prisma/             # Database schema and migrations
│   ├── tests/              # Unit and integration tests
│   ├── Dockerfile           # Production Dockerfile
│   └── package.json
├── frontend-demo/          # Demo interface for users
│   ├── src/                # React/TypeScript source
│   ├── Dockerfile           # Production Dockerfile
│   └── package.json
├── frontend-admin/         # Admin dashboard
│   ├── src/                # React/TypeScript source
│   ├── Dockerfile           # Production Dockerfile
│   └── package.json
├── packages/
│   └── sdk/                 # @bridgeshield/sdk npm package
│       ├── src/             # TypeScript source
│       ├── __tests__/       # Unit tests
│       ├── README.md        # SDK documentation
│       └── package.json
├── docker-compose.yml      # Production services
├── docker-compose.dev.yml  # Development overrides
└── README.md               # This file

🔧 Manual Setup

Backend Setup

1. Navigate to backend directory:

   cd backend

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your configuration

   • Set COMPOSER_API_KEY (from LI.FI Partner Portal) to enable /api/v1/composer/quote.

4. Initialize database:

   npx prisma migrate dev
   npx prisma generate

5. Start development server:

   npm run dev

Frontend Demo Setup

1. Navigate to frontend-demo directory:

   cd frontend-demo

2. Install dependencies:

   npm install

3. Start development server:

   npm run dev

Frontend Admin Setup

1. Navigate to frontend-admin directory:

   cd frontend-admin

2. Install dependencies:

   npm install

3. Start development server:

   npm run dev

SDK Development

1. Navigate to SDK directory:

   cd packages/sdk

2. Install dependencies:

   npm install

3. Build:

   npm run build

4. Run tests:

   npm test

🌐 API Endpoints

Core AML API (Port 3000)

Method	Endpoint	Description
GET	/api/v1/health	Health check with service status
POST	/api/v1/aml/check	Check address risk score
GET	/api/v1/aml/whitelist	Get whitelist summary
POST	/api/v1/aml/appeal	Submit appeal for flagged address
GET	/api/v1/aml/appeal/status/:ticketId	Check appeal status

Admin API (Port 3000)

Method	Endpoint	Description
GET	/api/v1/admin/dashboard/stats	Dashboard statistics
GET	/api/v1/admin/dashboard/risk-trend	7-day risk trend
GET	/api/v1/admin/dashboard/risk-distribution	Risk level distribution
GET	/api/v1/admin/appeals	List all appeals
POST	/api/v1/admin/appeal/:id/approve	Approve appeal
POST	/api/v1/admin/appeal/:id/reject	Reject appeal
GET	/api/v1/admin/whitelist	List whitelist entries
POST	/api/v1/admin/whitelist	Add to whitelist
DELETE	/api/v1/admin/whitelist/:id	Remove from whitelist
GET	/api/v1/admin/logs	View check logs

Earn + Composer Integration API (Port 3000)

Method	Endpoint	Description
GET	/api/v1/earn/vaults	Proxy vault discovery from Earn Data API
GET	/api/v1/earn/vault/:network/:address	Proxy single vault detail
GET	/api/v1/earn/portfolio/:wallet	Proxy wallet portfolio positions
GET	/api/v1/composer/quote	AML-gated Composer quote (BLOCK/REVIEW/ALLOW)
GET	/api/v1/behavior/profile/:wallet	C-end wallet behavior profile and anomaly signals

🛡️ Features

Risk Assessment

• Wallet Screening: Check addresses against OFAC, UN, EU sanctions lists
• Real-time Scoring: Risk score 0-100 with HIGH/MEDIUM/LOW classification
• Risk Factors: Detailed breakdown of risk indicators
• Caching: Multi-tier in-memory caching with TTL
• Behavior Analytics: C-end behavior anomaly detection (velocity, chain novelty, amount spikes, decision drift)

Compliance Tools

• Appeal System: Users can contest flagged addresses
• Whitelist Management: Admin can manage permanent whitelists
• Audit Trail: Complete logging of all checks and decisions
• Transaction Monitoring: Track checked transactions

Integration Options

• REST API: Full-featured API for direct integration
• @bridgeshield/sdk: Official JavaScript/TypeScript SDK
• Demo Frontend: Working example with React
• Admin Dashboard: Admin panel for managing whitelist and appeals

🧪 Testing

Backend Tests

cd backend
npm test           # Run all tests (88 tests)

SDK Tests

cd packages/sdk
npm test           # Run SDK tests (21 tests)

Frontend Builds

cd frontend-demo && npm run build
cd frontend-admin && npm run build

🐳 Docker Commands

Build and Run

# Build all images
docker-compose build

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Remove all images and volumes
docker-compose down -v --rmi all

Individual Services

# Build specific service
docker-compose build backend

# Start specific service
docker-compose up -d backend

# View specific service logs
docker-compose logs -f backend

🔐 Security

Environment Variables

• DATABASE_URL: SQLite/PostgreSQL connection string
• LOG_LEVEL: Logging level (debug, info, warn, error)
• EARN_DATA_API_BASE_URL: Earn Data API base URL (default: https://earn.li.fi)
• COMPOSER_API_BASE_URL: Composer API base URL (default: https://li.quest)
• COMPOSER_API_KEY: LI.FI Partner Portal API key (required for Composer quote route)
• BEHAVIOR_*: Thresholds for C-end behavior risk model (velocity, amount spikes, decision drift)

Security Features

• Rate limiting on public endpoints
• Input validation on all endpoints
• Helmet security headers
• CORS configuration
• Parameterized queries (Prisma)

📊 Tech Stack

Component	Technology
Backend	Node.js, TypeScript, Express, Prisma
Database	SQLite (dev), PostgreSQL (prod)
Frontend	React 18, TypeScript, Vite, Tailwind CSS
SDK	TypeScript, tsup (ESM + CJS)
Container	Docker, Docker Compose
Testing	Vitest, Supertest
Monitoring	Winston logging, Health checks

📈 Monitoring & Logging

Health Checks

• Backend: GET http://localhost:3000/api/v1/health
• Returns service status, uptime, and dependency health

View Logs

# All services
docker-compose logs

# Specific service
docker-compose logs backend

# Follow logs in real-time
docker-compose logs -f backend

🔄 Development Workflow

1. Make changes to source code
2. Run tests to ensure functionality
3. Build Docker images if needed
4. Deploy locally with Docker Compose
5. Verify functionality through API and UI

🚨 Troubleshooting

Common Issues

1. Port conflicts:

   Error: Port 3000 is already in use
   

   Solution: Stop the conflicting service or use a different port in docker-compose.yml

2. Database connection errors:

   Error: Database connection failed
   

   Solution: Check DATABASE_URL in environment variables and ensure database is running

3. Docker build failures:

   Error: npm ci failed
   

   Solution: Check package.json files for syntax errors

Getting Help

Check the logs for detailed error information:

docker-compose logs --tail=100

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• LI.FI for cross-chain transaction infrastructure
• React and TypeScript communities
• Open-source contributors to all dependencies