asle/README.md

# ASLE - Ali & Saum Liquidity Engine

> Hybrid Cross-Chain Liquidity Infrastructure with PMM, CCIP, ERC-2535, ERC-1155, and ISO/ICC Compliance

## 🚀 Overview

ASLE is a comprehensive DeFi liquidity infrastructure platform combining:

- **DODO PMM (Proactive Market Maker)** for efficient liquidity provision
- **Chainlink CCIP** for secure cross-chain operations
- **ERC-2535 Diamond Standard** for fully upgradeable smart contracts
- **ERC-1155 & ERC-4626** for multi-asset vaults and tokenization
- **Hybrid Compliance** with three modes (Regulated/Fintech/Decentralized)
- **ISO 20022 & FATF Travel Rule** compliance for institutional use

## 📋 Features

### Core Features
- ✅ PMM Liquidity Pools with configurable parameters
- ✅ ERC-4626 and ERC-1155 Vaults
- ✅ Cross-chain liquidity synchronization
- ✅ Governance with timelock and multi-sig
- ✅ Security features (pause, circuit breakers)
- ✅ Real-World Asset (RWA) tokenization

### Compliance Features
- ✅ Multi-mode compliance (Regulated/Fintech/Decentralized)
- ✅ KYC/AML verification integration
- ✅ OFAC sanctions screening
- ✅ FATF Travel Rule compliance
- ✅ ISO 20022 messaging
- ✅ Multi-jurisdiction regulatory support

### Infrastructure
- ✅ RESTful API with authentication
- ✅ GraphQL API
- ✅ Database integration (PostgreSQL)
- ✅ Comprehensive monitoring
- ✅ Docker containerization
- ✅ CI/CD pipelines

## 🏗️ Architecture

### Smart Contracts
- **Diamond.sol**: Core ERC-2535 Diamond contract
- **LiquidityFacet**: DODO PMM implementation
- **VaultFacet**: ERC-4626 and ERC-1155 vaults
- **ComplianceFacet**: Multi-mode compliance management
- **CCIPFacet**: Cross-chain messaging
- **GovernanceFacet**: DAO governance with timelock
- **SecurityFacet**: Pause and circuit breakers
- **RWAFacet**: Real-world asset tokenization

### Backend
- Node.js/Express REST API
- Apollo GraphQL Server
- Prisma ORM with PostgreSQL
- JWT authentication
- Rate limiting and security middleware
- Service layer architecture

### Frontend
- Next.js 16 with React 19
- Wagmi/Viem for Web3 integration
- Tailwind CSS for styling
- React Query for data fetching
- TypeScript throughout

## 🚦 Quick Start

### Prerequisites
- Node.js 20+
- Docker and Docker Compose
- Foundry (for smart contracts)
- PostgreSQL 15+

### Installation

1. **Clone the repository with submodules**
```bash
# Clone with submodules (recommended)
git clone --recurse-submodules <repository-url>
cd asle

# Or if already cloned, initialize submodules
git submodule update --init --recursive
```

2. **Set up environment variables**
```bash
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env.local
# Edit .env files with your configuration
```

3. **Start infrastructure**
```bash
docker-compose up -d postgres redis
```

4. **Set up database**
```bash
cd backend
npm install
npx prisma migrate deploy
npx prisma generate
```

5. **Deploy contracts** (see [DEPLOYMENT.md](./DEPLOYMENT.md))

6. **Start backend**
```bash
cd backend
npm install
npm run dev
```

7. **Start frontend**
```bash
cd frontend
npm install
npm run dev
```

## 📁 Project Structure

```
asle/
├── contracts/          # Smart contracts (Foundry) - Git submodule
├── backend/           # Node.js API server (monorepo)
│   ├── src/api/       # REST API routes
│   ├── src/middleware/# Express middleware
│   ├── src/jobs/      # Background jobs/orchestration
│   └── src/services/  # Business logic services
├── frontend/          # Next.js application - Git submodule
├── mobile/            # React Native mobile app
├── docs/              # Documentation
├── scripts/           # Utility scripts
└── .github/           # CI/CD workflows
```

**Note:** `contracts/` and `frontend/` are git submodules. See [SUBMODULE_SETUP.md](./SUBMODULE_SETUP.md) for details.

For detailed structure, see [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md)

## 🧪 Testing

### Smart Contracts
```bash
cd contracts
forge test
forge test -vvv  # Verbose output
```

### Backend
```bash
cd backend
npm test
```

### Frontend
```bash
cd frontend
npm test
```

For comprehensive testing guide, see [TESTING.md](./TESTING.md)

## 📚 Documentation

### Quick Links
- **[DOCUMENTATION_INDEX.md](./DOCUMENTATION_INDEX.md)** - Complete documentation index and navigation
- **[STATUS.md](./STATUS.md)** - Current project status
- **[DEPLOYMENT.md](./DEPLOYMENT.md)** - Deployment guide
- **[API_DOCUMENTATION.md](./API_DOCUMENTATION.md)** - Complete API reference
- **[TESTING.md](./TESTING.md)** - Testing procedures
- **[PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md)** - Project structure
- **[RECOMMENDATIONS.md](./RECOMMENDATIONS.md)** - Recommendations and suggestions
- **[UPGRADES_AND_VISUAL_ELEMENTS.md](./UPGRADES_AND_VISUAL_ELEMENTS.md)** - Complete list of upgrades and visual enhancements

### Additional Documentation
- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) - System architecture
- [docs/PHASES.md](./docs/PHASES.md) - Phase-by-phase implementation
- [docs/README.md](./docs/README.md) - Documentation directory index
- [docs/project-status/](./docs/project-status/) - Project status and audit documents
- [docs/project-management/](./docs/project-management/) - Roadmap and setup guides
- [contracts/FOUNDRY_SETUP.md](./contracts/FOUNDRY_SETUP.md) - Foundry setup

> **📖 For complete documentation navigation, see [DOCUMENTATION_INDEX.md](./DOCUMENTATION_INDEX.md)**

## 🔒 Security

- All contracts are upgradeable via Diamond pattern
- Access control with role-based permissions
- Reentrancy guards on all external functions
- Circuit breakers for risk management
- Comprehensive audit trail

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## 📄 License

See LICENSE file in repository root for details.

## 🆘 Support

For issues and questions:
- Open an issue on GitHub
- Check documentation in `/docs`
- Review [DEPLOYMENT.md](./DEPLOYMENT.md) for deployment issues
- See [STATUS.md](./STATUS.md) for current status

## 🔮 Roadmap

- [ ] Additional chain support
- [ ] Enhanced analytics dashboard
- [ ] Mobile app
- [ ] Additional compliance integrations
- [ ] Advanced governance features

> **📋 Detailed Implementation Plan:** See [ROADMAP_PLAN.md](./ROADMAP_PLAN.md) for comprehensive implementation plans, timelines, and technical specifications for all roadmap items.

---

**Built with ❤️ by the ASLE team**

**Project Status:** 100% Complete ✅ - Ready for Production