Monrail 🚄

The Fastest & Simplest USDC Bridge - Bridge USDC between Solana and Base with a beautiful neon-themed UI. Powered by Circle's CCTP for trustless, secure transfers.

🌟 Features

Bridging

Trustless USDC Bridge: Powered by Circle Bridge Kit (CCTP)
Two-Way Bridge: Solana ↔ Base
Beautiful UI Flow:
1. Connect both Solana and Base wallets
2. Select source and destination chains
3. Enter USDC amount to bridge
4. If no USDC → Embedded Jupiter widget to swap
5. Bridge with signature on source chain
6. Animated plane loading screen
7. Claim with signature on destination chain
8. Success! View transaction on explorer

Points & Leaderboard

Earn Points: Get points for every bridge transaction
Volume-Based: More USDC bridged = more points
Transaction Bonus: 10 points per transaction
Multipliers:
- 1.5x for volumes > $1,000
- 2x for volumes > $10,000
Leaderboard: Compete with other users
Track Progress: See your total volume and transaction count

Backend Tracking

Automatic Fee Tracking: Monitors fee addresses on both chains
Transaction Recording: Captures all bridge transactions
Points Calculation: Automatic points updates
Transaction History: Full history per wallet

🏗️ Architecture

packitupgg/
├── packages/
│   ├── backend/              # Hono + Prisma API
│   │   ├── src/
│   │   │   ├── api/          # REST API routes
│   │   │   ├── services/     # Balance & Points services
│   │   │   ├── jobs/         # Fee listener jobs
│   │   │   └── config/       # Chain configurations
│   │   └── prisma/
│   │       └── schema.prisma # Database schema
│   └── frontend/             # React + Vite + Circle Bridge Kit
│       ├── src/
│       │   ├── components/   # BridgeUI, Providers, UI components
│       │   ├── lib/          # API client, wagmi config
│       │   └── pages/        # Application pages
│       └── package.json
├── docker-compose.yml        # PostgreSQL database
└── .env.example

📦 Tech Stack

Backend

Runtime: Bun
Framework: Hono (fast HTTP server)
Database: PostgreSQL + Prisma ORM
Blockchain:
- Solana: @solana/web3.js + @solana/spl-token
- Base: viem (Ethereum client)
Bridge: Circle Bridge Kit
Jobs: Custom fee listeners for both chains

Frontend

Framework: React 19
Build Tool: Vite
Styling: Tailwind CSS + shadcn/ui
Animations: Framer Motion
Wallets:
- Solana: @solana/wallet-adapter (Phantom, Solflare)
- Base: wagmi + viem (MetaMask, WalletConnect)
Bridge: @circle-fin/bridge-kit
Swaps: Jupiter widget embedded

🚀 Getting Started

Prerequisites

Bun >= 1.0.0 (install)
Docker & Docker Compose (for PostgreSQL)
WalletConnect Project ID (get one)
Fee Addresses: Create Solana and Base wallets for receiving fees

Installation

Clone and install:

cd packitupgg
bun install

Start PostgreSQL:

docker compose up -d

Configure environment:

# Root .env (backend)
cp .env.example .env
# Edit .env:
# - Set DATABASE_URL (if different from default)
# - Set SOLANA_FEE_ADDRESS (your Solana wallet for fees)
# - Set BASE_FEE_ADDRESS (your Base wallet for fees)
# - Optionally set custom RPC URLs

# Frontend .env
cp packages/frontend/.env.example packages/frontend/.env
# Edit packages/frontend/.env:
# - Set VITE_WALLETCONNECT_PROJECT_ID

Setup database:

cd packages/backend
bun run db:push
# Creates all tables: Transaction, Points, FeeAddress

Start backend:

cd packages/backend
bun run dev
# Runs on http://localhost:3001
# Automatically starts fee listeners

Start frontend:

cd packages/frontend
bun run dev
# Runs on http://localhost:5173

Open browser: http://localhost:5173

🎮 Usage

Bridging Flow

Connect Wallets
- Connect Solana wallet (Phantom or Solflare)
- Connect Base wallet (MetaMask or WalletConnect)
- Both required for bridging
Select Chains
- Choose source chain (Base or Solana)
- Choose destination chain (Solana or Base)
- Swap button to reverse direction
Enter Amount
- See your current USDC balance
- Enter amount to bridge
- If insufficient balance → Jupiter widget appears
Get USDC (if needed)
- Embedded Jupiter widget
- Swap any token to USDC
- Click "I have USDC now" when done
Bridge
- Review amount and destination
- Click "Bridge"
- Sign with source wallet
- Watch the plane animation ✈️
Claim
- Notification when USDC arrives
- Sign with destination wallet
- USDC deposited to your wallet
Success
- View transaction on explorer
- See your points earned
- Bridge again or view leaderboard

Earning Points

Points are calculated using this formula:

Base: 1 point per $1 USDC
Bonus: 10 points per transaction
Multiplier: 1.5x if volume > $1,000
Multiplier: 2x if volume > $10,000

Example:

Bridge $500 → 500 + 10 = 510 points
Bridge $1,500 → (1500 + 10) × 1.5 = 2,265 points
Bridge $15,000 → (15000 + 10) × 2 = 30,020 points

🔌 API Reference

Backend Endpoints

`GET /balance/:chain/:address`

Get USDC balance for a wallet.

Example:

curl http://localhost:3001/balance/solana/YourSolanaAddress
curl http://localhost:3001/balance/base/0xYourBaseAddress

Response:

{
  "chain": "solana",
  "address": "...",
  "balance": "123.45",
  "decimals": 6,
  "token": "USDC"
}

`GET /points/:address`

Get points for a wallet.

Response:

{
  "walletAddress": "...",
  "totalPoints": 5420,
  "totalVolume": "5000.00",
  "totalTxCount": 12,
  "solanaVolume": "3000.00",
  "solanaTxCount": 7,
  "baseVolume": "2000.00",
  "baseTxCount": 5
}

`GET /leaderboard?limit=100`

Get top users by points.

Response:

{
  "leaderboard": [
    {
      "rank": 1,
      "walletAddress": "...",
      "totalPoints": 50000,
      "totalVolume": "45000.00",
      "totalTxCount": 100
    }
  ]
}

`GET /bridge/status/:txHash`

Get bridge transaction status.

Response:

{
  "id": "...",
  "status": "completed",
  "sourceChain": "base",
  "destinationChain": "solana",
  "amount": "100.00",
  "fee": "0.10",
  "sourceTxHash": "0x...",
  "claimTxHash": "...",
  "initiatedAt": "...",
  "completedAt": "..."
}

`GET /transactions/:address?limit=50`

Get transaction history for a wallet.

🛠️ Development

Database Schema

Transaction Table

Tracks all bridge transactions:

Source/destination chains
Wallet addresses
Amounts and fees
Transaction hashes
Status tracking
Timestamps for each stage

Points Table

Tracks user points:

Wallet address
Total points
Total volume
Transaction counts
Per-chain breakdown

FeeAddress Table

Configuration for fee addresses:

Chain identifier
Fee address
Last processed block
Active status

Fee Listeners

Two background jobs monitor fee addresses:

Solana Listener (packages/backend/src/jobs/fee-listener.ts):

Polls Solana RPC every 5 seconds
Watches for USDC transfers to fee address
Extracts transaction details
Creates database records
Updates user points

Base Listener:

Polls Base RPC every 10 seconds
Watches for USDC Transfer events
Extracts transaction details
Creates database records
Updates user points

Points Calculation

Points service (packages/backend/src/services/points.ts):

calculatePoints(volume, txCount): Formula implementation
updateUserPoints(wallet, chain, amount): Update after transaction
getUserPoints(wallet): Get points for display
getLeaderboard(limit): Get top users

Adding a New Chain

Update packages/backend/src/config/chains.ts:

mynewchain: {
  name: 'My New Chain',
  rpcUrl: process.env.MYNEWCHAIN_RPC_URL,
  usdcAddress: '0x...',
  decimals: 6,
  feeAddress: process.env.MYNEWCHAIN_FEE_ADDRESS,
}

Add balance adapter in packages/backend/src/services/balance.ts
Add fee listener in packages/backend/src/jobs/fee-listener.ts
Update frontend chain selector in BridgeUI.tsx
Ensure Circle CCTP supports the chain

🚢 Production Deployment

Environment Variables

Required:

DATABASE_URL: PostgreSQL connection string
SOLANA_FEE_ADDRESS: Solana wallet for fees
BASE_FEE_ADDRESS: Base wallet for fees

Optional:

SOLANA_RPC_URL: Custom Solana RPC (default: public)
BASE_RPC_URL: Custom Base RPC (default: public)
ENABLE_FEE_LISTENERS: Set to false to disable (default: true)
CORS_ORIGINS: Comma-separated allowed origins

Building

# Build backend
cd packages/backend
bun run build

# Build frontend
cd packages/frontend
bun run build

Docker Deployment

# Production compose file (create docker-compose.prod.yml)
docker-compose -f docker-compose.prod.yml up -d

🔒 Security

Trust Model

Fully Trustless: Circle Bridge Kit handles all bridging
No Custody: Backend never holds user funds
Client-Side Signing: All transactions signed in user wallets
Fee Transparency: Fee addresses are public and verifiable

Best Practices

Never commit .env files
Use separate fee wallets (don't use main wallets)
Monitor fee addresses regularly
Set up alerts for unusual activity
Use hardware wallets for fee address control
Regularly rotate database credentials

Fee Address Security

The fee addresses are used to:

Track transactions (by monitoring incoming fees)
Calculate points for users
Record transaction volume

Important: These addresses receive small fees. Ensure:

Private keys are securely stored
Access is restricted
Regular monitoring is in place

🐛 Troubleshooting

"Both wallets must be connected"

Connect both Solana AND Base wallets
Required for bridging in both directions

"Insufficient balance"

Use the Jupiter widget to swap to USDC
Check you're on the correct chain

"Transaction failed"

Check wallet for pending transactions
Ensure sufficient gas (SOL or ETH)
Verify USDC approval (for Base transactions)

"Fee listeners not working"

Check .env file has correct fee addresses
Verify database connection
Check backend logs for errors
Ensure RPC URLs are accessible

"Points not updating"

Fee listeners must be running
Check that fees were sent to correct addresses
Verify transaction appears in /transactions/:address
Check backend logs for fee listener errors

📜 License

MIT

🙏 Acknowledgments

Circle for Bridge Kit and CCTP
Jupiter for excellent DEX aggregation
Solana & Base for the ecosystems
shadcn/ui for beautiful components
Framer Motion for smooth animations

Built with ❤️ for cross-chain DeFi

Pack it up, ship it out, earn points! ✨🚀

Name		Name	Last commit message	Last commit date
Latest commit History 77 Commits
.claude		.claude
.github/workflows		.github/workflows
packages		packages
.env.example		.env.example
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
README.md		README.md
bun.lock		bun.lock
docker-compose.yml		docker-compose.yml
package.json		package.json
start.sh		start.sh
tsconfig.json		tsconfig.json

kevinfaveri/Monrail

Folders and files

Latest commit

History

Repository files navigation

Monrail 🚄

🌟 Features

Bridging

Points & Leaderboard

Backend Tracking

🏗️ Architecture

📦 Tech Stack

Backend

Frontend

🚀 Getting Started

Prerequisites

Installation

🎮 Usage

Bridging Flow

Earning Points

🔌 API Reference

Backend Endpoints

GET /balance/:chain/:address

GET /points/:address

GET /leaderboard?limit=100

GET /bridge/status/:txHash

GET /transactions/:address?limit=50

🛠️ Development

Database Schema

Transaction Table

Points Table

FeeAddress Table

Fee Listeners

Points Calculation

Adding a New Chain

🚢 Production Deployment

Environment Variables

Building

Docker Deployment

🔒 Security

Trust Model

Best Practices

Fee Address Security

🐛 Troubleshooting

📜 License

🙏 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`GET /balance/:chain/:address`

`GET /points/:address`

`GET /leaderboard?limit=100`

`GET /bridge/status/:txHash`

`GET /transactions/:address?limit=50`

Packages