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)

Clone the repository:

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

Start all services:
```
docker-compose up -d
```
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
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',
  apiKey: process.env.BRIDGESHIELD_API_KEY,
});

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

Navigate to backend directory:
```
cd backend
```
Install dependencies:
```
npm install
```
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.

Initialize database:

npx prisma migrate dev
npx prisma generate

Start development server:
```
npm run dev
```

Frontend Demo Setup

Navigate to frontend-demo directory:
```
cd frontend-demo
```
Install dependencies:
```
npm install
```
Start development server:
```
npm run dev
```

Frontend Admin Setup

Navigate to frontend-admin directory:
```
cd frontend-admin
```
Install dependencies:
```
npm install
```
Start development server:
```
npm run dev
```

SDK Development

Navigate to SDK directory:
```
cd packages/sdk
```
Install dependencies:
```
npm install
```
Build:
```
npm run build
```
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 (API Key required)
GET	`/api/v1/aml/whitelist`	Get whitelist summary (API Key required)
POST	`/api/v1/aml/appeal`	Submit appeal for flagged address (API Key required)
GET	`/api/v1/aml/appeal/status/:ticketId`	Check appeal status (API Key required)

Admin API (Port 3000)

Method	Endpoint	Description
POST	`/api/v1/admin/auth/login`	Admin login (username/password -> JWT)
GET	`/api/v1/admin/auth/me`	Get current admin session
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
GET	`/api/v1/analytics/transfers`	LI.FI cross-chain transaction history for investigation

LI.FI Analytics Integration

BridgeShield enhances AML decision-making by integrating LI.FI Analytics API for cross-chain transaction history:

Address Check → [LI.FI Analytics History] + [Local checkLog] → Enhanced Behavior Analysis → AML Decision

Enhanced Risk Signals from LI.FI:

High-risk address interactions — Detects if the address has transacted with known mixer/sanctioned addresses
Cross-chain tumbling patterns — Identifies suspicious chain-hopping behavior
Amount spike detection — Compares current transaction against LI.FI historical averages
First-time LI.FI user high-value detection — Flags new addresses with large transactions

Combined Confidence: When both local BridgeShield history and LI.FI history are available, behavior analysis confidence increases to HIGH.

🛡️ 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 enhanced with LI.FI cross-chain history
- Local checkLog history for BridgeShield-observed transactions
- LI.FI Analytics API for complete cross-chain transaction history
- Combined signals: velocity, chain novelty, amount spikes, decision drift, high-risk interactions

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 (138 tests)

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

SDK Tests (21 tests)

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

Frontend Tests (38 tests)

cd frontend-demo && npm test     # 19 tests
cd frontend-admin && npm test    # 19 tests

Note: Frontend tests are skipped in CI. Run locally for development.

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)
LI_FI_API_BASE_URL: LI.FI API base URL (Composer + Analytics, 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)
JWT_SECRET: JWT signing secret for admin tokens
ADMIN_INIT_USERNAME: Initial admin username bootstrap
ADMIN_INIT_PASSWORD: Initial admin password bootstrap
DEMO_API_KEY: Fixed API key for demo/integration environments

Security Features

Rate limiting on public endpoints
Input validation on all endpoints
JWT authentication for admin routes
API key authentication for AML/admin protected routes
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

Make changes to source code
Run tests to ensure functionality
Build Docker images if needed
Deploy locally with Docker Compose
Verify functionality through API and UI

🚨 Troubleshooting

Common Issues

Port conflicts:
```
Error: Port 3000 is already in use
```
Solution: Stop the conflicting service or use a different port in docker-compose.yml
Database connection errors:
```
Error: Database connection failed
```
Solution: Check DATABASE_URL in environment variables and ensure database is running
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

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.github/workflows		.github/workflows
backend		backend
docs		docs
frontend-admin		frontend-admin
frontend-demo		frontend-demo
packages/sdk		packages/sdk
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

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

🏗️ Architecture

🚀 Quick Start

Using Docker Compose (Recommended)

Development Mode

📦 SDK Package

📁 Project Structure

🔧 Manual Setup

Backend Setup

Frontend Demo Setup

Frontend Admin Setup

SDK Development

🌐 API Endpoints

Core AML API (Port 3000)

Admin API (Port 3000)

Earn + Composer Integration API (Port 3000)

LI.FI Analytics Integration

🛡️ Features

Risk Assessment

Compliance Tools

Integration Options

🧪 Testing

Backend Tests (138 tests)

SDK Tests (21 tests)

Frontend Tests (38 tests)

Frontend Builds

🐳 Docker Commands

Build and Run

Individual Services

🔐 Security

Environment Variables

Security Features

📊 Tech Stack

📈 Monitoring & Logging

Health Checks

View Logs

🔄 Development Workflow

🚨 Troubleshooting

Common Issues

Getting Help

📄 License

🙏 Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages