Chirper - A Bridge Optimizer

Chirper is a Cross-chain stablecoin bridge optimizer.
It queries multiple protocols to find and rank the optimal route for stablecoin transfers based on fees, speed, and output amount.

Features

• Multi-Protocol Support: Queries 6 major bridge protocols simultaneously
• Smart Ranking: Ranks routes by fees, speed, and output amount
• Fast: Parallel API requests for quick results
• Customizable: Configure ranking weights and preferences
• Stablecoin Optimized: Focused on stablecoin transfers across chains

Supported Protocols

• Stargate - Leading stablecoin bridge (LayerZero-powered)
• Squid Router - Cross-chain swap aggregator (Axelar-powered)
• Wormhole - Wide chain coverage including non-EVM chains
• Celer cBridge - Strong liquidity, multi-chain support
• Hop Protocol - Ethereum L2 specialist
• Across Protocol - Fast, capital-efficient transfers

Setup

npm install
npm run build

Web UI

cd frontend
npm install            # already run once, but repeat after core changes
npm run dev            # launches Vite dev server

The UI imports the core bridge package locally via file:... Rebuild the root project (npm run build) whenever you change the bridge logic so the UI picks up the latest APIs.

Usage

Basic Example

import { BridgeFinder, BridgeQuoteRequest } from 'hydra-bridge-finder';

const finder = new BridgeFinder();

const request: BridgeQuoteRequest = {
  fromChain: '1',        // Ethereum
  toChain: '137',        // Polygon
  token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
  amount: '1000000',     // 1 USDC (6 decimals)
  fromAddress: '0xYourAddress',
  toAddress: '0xYourAddress',
};

// Find all ranked routes
const routes = await finder.findBestRoutes(request);

// Get the best route
const bestRoute = await finder.findBestRoute(request);
console.log(`Best: ${bestRoute.protocol} - Score: ${bestRoute.score}`);

Custom Ranking Criteria

const finder = new BridgeFinder(undefined, {
  feeWeight: 0.6,        // Prioritize low fees
  timeWeight: 0.3,       // Consider speed
  outputWeight: 0.1,     // Maximize output
  maxTime: 600,          // Max 10 minutes
  maxFeePercentage: 1,   // Max 1% fee
  preferredProtocols: ['Across Protocol', 'Stargate'],
});

Run Example

npm run dev

API Reference

BridgeFinder

Main class for finding and ranking bridge routes.

const finder = new BridgeFinder(protocols?, rankingCriteria?);

Methods:

• findRoutes(request) - Get all available routes
• findBestRoutes(request) - Get ranked routes
• findBestRoute(request) - Get single best route
• getAllSupportedChains() - List supported chains per protocol
• getAllSupportedTokens(chain) - List supported tokens per protocol
• updateRankingCriteria(criteria) - Update ranking preferences

RouteRanker

Ranks and scores bridge routes.

const ranker = new RouteRanker(criteria?);

Methods:

• rankRoutes(routes, inputAmount) - Rank multiple routes
• findBestRoute(routes, inputAmount) - Find best route
• filterRoutes(routes, filters) - Filter routes by criteria

Ranking Algorithm

Routes are scored (0-1) based on:

1. Fee Score (default 50% weight): Lower fees = higher score

   • 0% fee = 1.0
   • 1% fee = 0.5
   • ≥5% fee = 0.0

2. Time Score (default 30% weight): Faster = higher score

   • ≤2 min = 1.0
   • 5 min = 0.7
   • 15 min = 0.3
   • ≥30 min = 0.0

3. Output Score (default 20% weight): Higher output = higher score

   • 100% output = 1.0
   • 95% output = 0.5
   • ≤90% output = 0.0

4. Bonuses/Penalties:

   • Preferred protocol: +0.1
   • Exceeds max time/fee: ×0.5

Project Structure

Chirper/
├── frontend/
│   ├── api/                    # Bridge + scoring TypeScript source
│   ├── src/                    # React application
│   ├── package.json            # Frontend build config
│   └── ...
├── dist/                       # Compiled bridge package output
├── package.json                # Core (bridge) package manifest
└── tsconfig.json

Environment Variables

Optional API keys and integrator IDs:

# Squid Router credentials (see https://docs.squidrouter.com/quick-start)
SQUID_INTEGRATOR_ID=hydra-3edc27f3-2efb-403c-ad90-3586c6cda016

Development

# Build
npm run build

# Run example
npm run dev

# Test (coming soon)
npm test

Roadmap

• Add more protocols (Synapse, Meson, Allbridge)
• Implement transaction execution
• Add WebSocket support for real-time updates
• Create REST API wrapper
• Add comprehensive test suite
• Add liquidity depth checks
• Historical route analytics

License

MIT

---

Status: ✅ Core functionality complete - All protocol integrations and ranking logic implemented