@t402/smart-router 1.0.0-beta.1

package/README.md

@@ -0,0 +1,388 @@
+# @t402-internal/smart-router
+
+Smart Payment Routing Engine for T402 Protocol.
+
+## Overview
+
+This package provides intelligent multi-chain payment routing with optimal path finding, real-time pricing, liquidity aggregation, and MEV protection. It enables finding the most cost-effective or fastest route for cross-chain payments.
+
+## Installation
+
+```bash
+pnpm add @t402-internal/smart-router
+```
+
+## Quick Start
+
+```typescript
+import {
+  RoutingEngine,
+  GasOracle,
+  FeeEstimator,
+  LiquidityAggregator,
+  TransactionBuilder,
+  MevProtection,
+} from '@t402-internal/smart-router';
+
+// Set up routing engine
+const router = new RoutingEngine();
+
+// Add network graph edges (liquidity sources)
+router.updateGraph([
+  {
+    from: 'eip155:1',
+    to: 'eip155:8453',
+    fromAsset: '0xUSDT',
+    toAsset: '0xUSDT',
+    protocol: 'layerzero',
+    type: 'bridge',
+    cost: 50000,
+    liquidity: '50000000000',
+    maxAmount: '10000000000',
+    minAmount: '10000000',
+    estimatedTime: 120,
+  },
+  // ... more edges
+]);
+
+// Find best route
+const routes = await router.findRoutes({
+  sourceChain: 'eip155:1',
+  sourceAsset: '0xUSDT',
+  sourceAmount: '1000000000', // 1000 USDT
+  destinationChain: 'eip155:8453',
+  destinationAsset: '0xUSDT',
+  recipient: '0xRecipient',
+  sender: '0xSender',
+  optimization: 'balanced',
+});
+
+console.log(routes[0].totalCost);
+console.log(routes[0].estimatedTime);
+```
+
+## Modules
+
+### Routing
+
+The routing module provides path-finding algorithms and route optimization.
+
+```typescript
+import {
+  RoutingEngine,
+  dijkstra,
+  astar,
+  kShortestPaths,
+  paretoOptimalPaths,
+} from '@t402-internal/smart-router/routing';
+
+// Create engine with configuration
+const router = new RoutingEngine({
+  maxRoutes: 5,
+  cacheTtl: 30000,
+  minConfidence: 50,
+});
+
+// Find routes with different optimization strategies
+const costOptimized = await router.findRoutes({
+  ...request,
+  optimization: 'cost',
+});
+
+const speedOptimized = await router.findRoutes({
+  ...request,
+  optimization: 'speed',
+});
+
+// Get best single route
+const best = await router.getBestRoute(request);
+
+// Validate route before execution
+const validation = await router.validateRoute(route);
+if (!validation.valid) {
+  console.log(validation.errors);
+}
+```
+
+### Optimization Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| `cost` | Minimize total fees and gas costs |
+| `speed` | Minimize execution time |
+| `balanced` | Balance cost, speed, and reliability |
+| `slippage` | Minimize price impact |
+| `privacy` | Prefer privacy-preserving routes |
+
+### Pricing
+
+Real-time gas and fee estimation with predictive modeling.
+
+```typescript
+import {
+  GasOracle,
+  FeeEstimator,
+  MockGasProvider,
+} from '@t402-internal/smart-router/pricing';
+
+// Gas oracle for multi-chain gas tracking
+const gasOracle = new GasOracle({
+  cacheTtl: 15000,
+  enablePrediction: true,
+});
+
+// Get gas prices
+const gasPrice = await gasOracle.getGasPrice('eip155:8453');
+console.log(gasPrice.standard); // Standard gas price in wei
+
+// Calculate gas cost in USD
+const { costUsd } = await gasOracle.calculateGasCostUsd(
+  'eip155:8453',
+  '150000', // gas units
+  'fast',
+);
+
+// Get gas price prediction
+const prediction = gasOracle.predictGasPrice('eip155:8453', 5);
+
+// Fee estimator
+const feeEstimator = new FeeEstimator(gasOracle);
+
+const estimate = await feeEstimator.estimateFees({
+  chain: 'eip155:8453',
+  operation: 'swap',
+  protocol: 'uniswap',
+  inputAsset: '0xUSDT',
+  outputAsset: '0xUSDC',
+  amount: '1000000000',
+  gasSpeed: 'standard',
+});
+
+console.log(estimate.totalFeeUsd);
+```
+
+### Liquidity
+
+Aggregate liquidity across multiple DEXs and bridges.
+
+```typescript
+import {
+  LiquidityAggregator,
+  MockLiquidityProvider,
+  MockBridgeProvider,
+} from '@t402-internal/smart-router/liquidity';
+
+const aggregator = new LiquidityAggregator({
+  cacheTtl: 30000,
+  minLiquidity: '1000',
+});
+
+// Register providers
+aggregator.registerProvider(new MockLiquidityProvider('eip155:8453', 'uniswap'));
+aggregator.registerBridgeProvider(new MockBridgeProvider('layerzero'));
+
+// Get aggregated liquidity
+const liquidity = await aggregator.getLiquidity(
+  'eip155:8453',
+  '0xUSDT',
+  '0xUSDC',
+);
+
+console.log(liquidity.totalLiquidity);
+console.log(liquidity.bestPrice);
+
+// Calculate slippage
+const slippage = aggregator.calculateSlippage(
+  liquidity,
+  '100000000', // 100 USDT
+  '0.5', // 0.5% tolerance
+);
+
+console.log(slippage.priceImpact);
+console.log(slippage.minOutputAmount);
+
+// Get cross-chain liquidity
+const crossChain = await aggregator.getCrossChainLiquidity(
+  'eip155:1',
+  'eip155:8453',
+  '0xUSDT',
+);
+
+console.log(crossChain.bestBridge);
+```
+
+### Execution
+
+Build and execute transactions with MEV protection.
+
+```typescript
+import {
+  TransactionBuilder,
+  MevProtection,
+  createMevProtectedOptions,
+} from '@t402-internal/smart-router/execution';
+
+// Build transactions from route
+const builder = new TransactionBuilder(gasOracle);
+
+const transactions = await builder.buildRoute(route, '0xSender', {
+  gasSpeed: 'fast',
+  mevProtection: 'flashbots',
+  autoApprove: true,
+});
+
+// Get required approvals
+const approvals = builder.getRequiredApprovals(route, '0xSender');
+
+// MEV protection
+const mev = new MevProtection({
+  flashbotsRelay: 'https://relay.flashbots.net',
+});
+
+// Estimate MEV risk
+const risk = mev.estimateMevRisk(transaction, 'eip155:1');
+console.log(risk.riskLevel);
+console.log(risk.recommendations);
+
+// Submit with protection
+const result = await mev.protect(
+  transaction,
+  signedTransaction,
+  'flashbots',
+  'eip155:1',
+);
+```
+
+## Route Types
+
+| Type | Description |
+|------|-------------|
+| `transfer` | Simple token transfer |
+| `swap` | DEX swap |
+| `bridge` | Cross-chain bridge |
+| `wrap` | Wrap native token (ETH -> WETH) |
+| `unwrap` | Unwrap to native (WETH -> ETH) |
+| `approve` | Token approval |
+
+## Path Finding Algorithms
+
+The package includes several path-finding algorithms:
+
+```typescript
+import {
+  dijkstra,
+  astar,
+  kShortestPaths,
+  paretoOptimalPaths,
+  COST_CONFIGS,
+} from '@t402-internal/smart-router/routing';
+
+// Dijkstra's algorithm
+const path = dijkstra(
+  edges,
+  'eip155:1', '0xUSDT',
+  'eip155:8453', '0xUSDT',
+  COST_CONFIGS.balanced,
+  5, // max hops
+);
+
+// A* with heuristic
+const fastPath = astar(
+  edges,
+  'eip155:1', '0xUSDT',
+  'eip155:8453', '0xUSDT',
+  COST_CONFIGS.speed,
+  5,
+);
+
+// K-shortest paths (Yen's algorithm)
+const topPaths = kShortestPaths(
+  edges,
+  'eip155:1', '0xUSDT',
+  'eip155:8453', '0xUSDT',
+  COST_CONFIGS.balanced,
+  5, // k paths
+);
+
+// Pareto-optimal paths (multi-objective)
+const pareto = paretoOptimalPaths(
+  edges,
+  'eip155:1', '0xUSDT',
+  'eip155:8453', '0xUSDT',
+);
+```
+
+## Supported Chains
+
+The router uses CAIP-2 chain identifiers:
+
+| Chain | ID |
+|-------|-----|
+| Ethereum | `eip155:1` |
+| Base | `eip155:8453` |
+| Arbitrum | `eip155:42161` |
+| Optimism | `eip155:10` |
+| Polygon | `eip155:137` |
+| BSC | `eip155:56` |
+| Solana | `solana:mainnet` |
+
+## MEV Protection Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| `none` | No protection (public mempool) |
+| `flashbots` | Use Flashbots bundle (Ethereum) |
+| `private_mempool` | Use private RPC endpoints |
+| `timing` | Submit at optimal time |
+| `splitting` | Split into smaller transactions |
+
+## API Reference
+
+### RoutingEngine
+
+- `findRoutes(request)` - Find all routes matching request
+- `getBestRoute(request)` - Get single best route
+- `validateRoute(route)` - Validate route is still executable
+- `updateGraph(edges)` - Update network graph
+- `addEdge(edge)` - Add single edge to graph
+
+### GasOracle
+
+- `getGasPrice(chain)` - Get current gas prices
+- `getMultiChainGasPrices(chains)` - Get prices for multiple chains
+- `calculateGasCostUsd(chain, gas, speed)` - Calculate cost in USD
+- `predictGasPrice(chain, horizon)` - Predict future prices
+- `getRecommendedGasPrice(chain, urgency)` - Get recommended price
+
+### FeeEstimator
+
+- `estimateFees(request)` - Estimate fees for operation
+- `estimateRouteFees(steps)` - Estimate total route fees
+- `getSwapQuote(...)` - Get swap quote
+- `getBridgeQuote(...)` - Get bridge quote
+
+### LiquidityAggregator
+
+- `getLiquidity(chain, input, output)` - Get aggregated liquidity
+- `getCrossChainLiquidity(from, to, asset)` - Get bridge liquidity
+- `calculateSlippage(source, amount, tolerance)` - Calculate slippage
+- `getLiquidityDepth(...)` - Get liquidity at price levels
+- `findBestRoute(source, amount)` - Find best execution route
+
+### TransactionBuilder
+
+- `buildRoute(route, sender, options)` - Build all transactions
+- `buildStep(step, sender, options)` - Build single transaction
+- `buildApproval(...)` - Build approval transaction
+- `getRequiredApprovals(route, sender)` - Get required approvals
+
+### MevProtection
+
+- `protect(tx, signed, strategy, chain)` - Apply MEV protection
+- `submitBundle(txs, block, chain)` - Submit Flashbots bundle
+- `simulate(tx, chain)` - Simulate transaction
+- `estimateMevRisk(tx, chain)` - Estimate MEV risk
+
+## License
+
+Internal use only - T402 Protocol