iLayer Solver Bot

An example implementation of a solver bot using the iLayer network, supporting multiple EVM chains and ERC20 tokens.

See the iLayer documentation for more details.

Table of Contents

• Prerequisites
• Quick Start
  • Local Development
  • Docker Development
• Database Setup
• Production Deployment
• Configuration
• Available Scripts
• Troubleshooting

---

Prerequisites

Local Development

• Node.js 20 or higher
• npm or yarn
• PostgreSQL 14 or higher (if running locally)

Docker Development/Production

• Docker 20.10 or higher
• Docker Compose 2.0 or higher

---

Quick Start

Local Development

1. Clone the repository

   git clone <repository-url>
   cd bot-2

2. Install dependencies

   npm install

3. Set up environment variables

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

4. Set up PostgreSQL (if not using Docker)

   Install PostgreSQL:

   # macOS
   brew install postgresql@16
   brew services start postgresql@16
   
   # Ubuntu/Debian
   sudo apt-get install postgresql-16
   sudo systemctl start postgresql

   Create database and user:

   psql postgres -c "CREATE USER ilayer_admin WITH PASSWORD 'ilayer_password' CREATEDB;"
   psql postgres -c "CREATE DATABASE ilayer_db OWNER ilayer_admin;"

5. Start the bot

   npm run start:dev

   The bot will automatically:

   • Generate Prisma client
   • Run database migrations
   • Start the application in watch mode

   The API will be available at http://localhost:8080

Docker Development

1. Start all services

   docker compose up

   This will start:

   • PostgreSQL database with automatic initialization
   • Soketi WebSocket server
   • The database will be accessible at localhost:5432

2. Run the bot locally (connected to Docker database)

   # In a separate terminal
   npm run start:dev

---

Database Setup

Automatic Setup (Recommended)

The database setup is fully automated when using npm run start:dev or npm run start:prod:

1. Prisma client is generated
2. Pending migrations are applied
3. Application starts

Manual Setup (Advanced)

If you need to manually manage the database:

# Generate Prisma client
npm run prisma:generate

# Apply migrations (development - interactive)
npm run prisma:migrate:dev

# Apply migrations (production - no prompts)
npm run prisma:migrate:deploy

# Open Prisma Studio (database GUI)
npm run prisma:studio

# Reset database (WARNING: deletes all data)
npm run prisma:reset

Database Migrations

Creating a new migration:

npx prisma migrate dev --name your_migration_name

The migration will be automatically applied the next time you run npm run start:dev.

---

Production Deployment

Using Docker Compose (Recommended)

1. Prepare environment

   # Create production environment file
   cp .env .env.prod
   # Edit .env.prod with production values

2. Deploy

   docker compose -f docker-compose.prod.yml up -d --build

   This will:

   • Build the optimized production image
   • Start PostgreSQL with health checks
   • Start Soketi with health checks
   • Wait for services to be healthy
   • Run database migrations automatically
   • Start the bot application

3. Verify deployment

   # Check service health
   docker compose -f docker-compose.prod.yml ps
   
   # View logs
   docker compose -f docker-compose.prod.yml logs -f bot
   
   # Check API
   curl http://localhost:8080/api

Using Docker (Manual)

1. Build production image

   docker build -t ilayer-bot:latest .

2. Run with database connection

   docker run -d \
     --name ilayer-bot \
     -p 8080:8080 \
     -e DATABASE_URL="postgresql://user:password@host:5432/dbname" \
     --env-file .env.prod \
     ilayer-bot:latest

   The entrypoint script will automatically run migrations before starting the app.

---

Configuration

Environment Variables

Key environment variables in .env:

# Application
PORT=8080

# Database
DATABASE_USER=ilayer_admin
DATABASE_PASSWORD=ilayer_password
DATABASE_NAME=ilayer_db
DATABASE_URL=postgresql://ilayer_admin:ilayer_password@localhost:5432/ilayer_db

# Blockchain RPC URLs
RPC_URL_ARBITRUM=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY
RPC_URL_BASE=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
RPC_URL_BSC=https://bsc-dataseed.binance.org
RPC_URL_POLYGON=https://polygon-rpc.com

# Private Keys (one per chain)
PRIVATE_KEY_ARBITRUM=your_private_key
PRIVATE_KEY_BASE=your_private_key
PRIVATE_KEY_BSC=your_private_key
PRIVATE_KEY_POLYGON=your_private_key

# Soketi Configuration
SOKETI_APP_ID=ilayer
SOKETI_APP_KEY=app-key
SOKETI_APP_SECRET=app-secret
SOKETI_HOST=localhost
SOKETI_PORT=6001

# Solver Configuration
SOLVER_ID=solver-bot-1
SOLVER_LISTEN_CHAINS=arbitrum,base
SOLVER_NUMERAIRE=USDC
SOLVER_MARGIN_BPS=10

For a complete list of configuration options, see DATABASE_SETUP_PLAN.md.

---

Available Scripts

Development

• npm run start:dev - Start in development mode with auto-reload (includes DB setup)
• npm run start:debug - Start in debug mode
• npm run dev - Alias for start:dev

Production

• npm run build - Build for production
• npm run start:prod - Start in production mode (includes DB migrations)

Database

• npm run prisma:generate - Generate Prisma client
• npm run prisma:migrate:dev - Create and apply migration (dev)
• npm run prisma:migrate:deploy - Apply migrations (production)
• npm run prisma:studio - Open Prisma Studio GUI
• npm run prisma:reset - Reset database (WARNING: deletes all data)
• npm run db:setup - Generate client + deploy migrations
• npm run db:setup:dev - Generate client + run dev migrations

Code Quality

• npm run lint - Run ESLint
• npm run format - Format code with Prettier
• npm test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run test:cov - Run tests with coverage

Utilities

• npm run smoke:soketi - Test Soketi WebSocket connection

---

Troubleshooting

Database Connection Issues

Problem: P1010: User was denied access on the database

Solution:

1. Verify PostgreSQL is running:

   # macOS
   brew services list | grep postgresql
   
   # Linux
   sudo systemctl status postgresql

2. Check database credentials:

   psql -U ilayer_admin -d ilayer_db -c "SELECT 1;"

3. Verify DATABASE_URL in .env matches your setup

Problem: Error: P1001: Can't reach database server

Solution:

• If using Docker: Ensure database service is running (docker compose ps)
• If local: Check PostgreSQL is running on port 5432
• Verify firewall settings

Migration Issues

Problem: Migrations fail with "relation already exists"

Solution:

# Mark existing migrations as applied
npx prisma migrate resolve --applied <migration_name>

# Or reset and reapply (WARNING: deletes data)
npm run prisma:reset

Problem: Prisma client out of sync

Solution:

npm run prisma:generate

Docker Issues

Problem: docker compose up fails with port conflicts

Solution:

# Stop conflicting services
docker compose down

# Or change ports in docker-compose.yml

Problem: Docker containers keep restarting

Solution:

# Check logs
docker compose logs -f bot

# Common causes:
# - Database not ready (wait for health check)
# - Migration failure (check DATABASE_URL)
# - Missing environment variables

Development Issues

Problem: Hot reload not working

Solution:

1. Ensure you're using npm run start:dev not npm start
2. Check file watcher limits (Linux):

   echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
   sudo sysctl -p

Problem: "Module not found" errors after updating

Solution:

# Clean install
rm -rf node_modules package-lock.json
npm install
npm run prisma:generate

For More Help

• Check the database setup plan for detailed architecture
• Review Prisma logs: DEBUG="prisma:*" npm run start:dev
• Check application logs in docker compose logs
• Open an issue on GitHub

---

Architecture

The bot uses:

• NestJS: Backend framework
• Prisma: Type-safe database ORM
• PostgreSQL: Primary database
• Soketi: WebSocket server for RFQ
• Viem/Ethers: Blockchain interaction
• Docker: Containerization

For detailed architecture and setup process, see DATABASE_SETUP_PLAN.md.

---

License

MIT