@terkoizmy/intent-sdk 1.0.0 → 1.0.2

package/README.md

@@ -1,258 +1,485 @@
-# Intent Parser SDK
+# 🔗 Intent Parser SDK
 
-Lightweight natural language parser and autonomous solver SDK for blockchain intents.
+> **Parse natural language blockchain intents. Solve them cross-chain. Automatically.**
 
-## Installation
+`@terkoizmy/intent-sdk` is a TypeScript SDK that converts everyday language like *"Bridge 500 USDC from Ethereum to Polygon"* into structured, executable blockchain transactions — while an autonomous solver agent handles the cross-chain execution, fee optimization, and settlement proof on your behalf.
+
+[![npm version](https://img.shields.io/npm/v/@terkoizmy/intent-sdk)](https://www.npmjs.com/package/@terkoizmy/intent-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![Build](https://img.shields.io/badge/build-passing-brightgreen)](#)
+
+---
+
+## ✨ What It Does
+
+| Capability | Description |
+|-----------|-------------|
+| 🧠 **Natural Language Parsing** | Turn plain English into structured `StructuredIntent` objects |
+| ⚡ **Cross-Chain Bridging** | Autonomous solver executes bridge intents across EVM chains |
+| 💰 **Dynamic Fee Pricing** | Fee scales with inventory levels, gas costs, and user slippage tolerance |
+| 🔒 **Settlement Proofs** | ERC-7683–compliant on-chain settlement with signature proof verification |
+| 📊 **Monitoring & Alerting** | Built-in `ProfitTracker`, `HealthChecker`, and `AlertManager` |
+| 🔄 **Auto-Rebalancing** | Inventory rebalancer uses Li.Fi or Swing to keep liquidity optimally distributed |
+| 🛡️ **Battle-Tested Error Handling** | Domain-specific error classes and retry logic with exponential backoff |
+
+---
+
+## 📦 Installation
 
 ```bash
+# npm
 npm install @terkoizmy/intent-sdk
-# or
+
+# bun
 bun add @terkoizmy/intent-sdk
+
+# yarn
+yarn add @terkoizmy/intent-sdk
+
+# pnpm
+pnpm add @terkoizmy/intent-sdk
 ```
 
-## Quick Start
+**Requirements:** Node.js ≥ 18 or Bun ≥ 1.0
 
-> **For the full, comprehensive guide, please see [docs/USAGE.md](./docs/USAGE.md).**
+---
 
-### Parser Only
+## 🚀 Quick Start
+
+### 1. Parse-Only (No Solver)
 
 ```typescript
 import { IntentParser } from "@terkoizmy/intent-sdk";
 
 const parser = new IntentParser();
-const result = await parser.parse("Bridge 100 USDC from Ethereum to Arbitrum");
-
-// { success: true, data: { intentType: 'bridge', parameters: { ... } } }
+const result = parser.parse("Bridge 500 USDC from Ethereum to Polygon");
+
+if (result.success) {
+    console.log(result.data);
+    // {
+    //   intentType: "bridge",
+    //   parameters: {
+    //     inputToken: "USDC",
+    //     inputAmount: "500",
+    //     sourceChain: "1",
+    //     targetChain: "137",
+    //     recipient: undefined
+    //   },
+    //   constraints: { maxSlippage: 50 },
+    //   metadata: { confidence: 0.92, parsedAt: 1709123456789 }
+    // }
+}
 ```
 
-### SDK Factory (Parser + Solver)
+### 2. Parser + Solver (Simulate Mode)
 
 ```typescript
 import { createIntentSDK } from "@terkoizmy/intent-sdk";
 
 const { parser, solver } = createIntentSDK({
     solver: {
-        privateKey: process.env.SOLVER_PRIVATE_KEY!,
-        supportedChains: [1, 10, 42161],
-        supportedTokens: ["USDC", "USDT"],
-        mode: "simulate"   // use "live" for real execution
+        agent: {
+            privateKey: process.env.SOLVER_PRIVATE_KEY!,
+            mode: "simulate",                         // No real transactions
+            supportedChains: [1, 10, 42161, 137],     // ETH, OP, ARB, Polygon
+            supportedTokens: ["USDC", "USDT"],
+            maxConcurrentIntents: 5,
+        },
+        contractAddress: "0xYOUR_SETTLEMENT_CONTRACT",
     },
-    }
 });
 
 await solver.initialize();
 
-if (solver.canSolve(intent)) {
-    const result = await solver.solve(intent);
-    console.log(result); // { success: true, txHash: "0x...", profit: "..." }
+// Parse + solve in one flow
+const { data: intent } = parser.parse("Bridge 200 USDC from Ethereum to Arbitrum");
+const solverIntent = buildSolverIntent(intent, userAddress, deadline);
+
+if (solver.canSolve(solverIntent)) {
+    const quote = solver.getQuote(solverIntent);
+    console.log(`Fee: ${quote.totalFee} | User gets: ${quote.userReceives}`);
+
+    const result = await solver.solve(solverIntent);
+    console.log(result);
+    // { success: true, txHash: "0x...", profit: "4500000", metadata: { ... } }
 }
 ```
 
-### Autonomous Mode
-
-Connect to a mempool server and solve intents automatically in the background:
+### 3. Autonomous Mode (Live Mempool Listener)
 
 ```typescript
 import { createIntentSDK } from "@terkoizmy/intent-sdk";
 
 const { solver } = createIntentSDK({
     solver: {
-        privateKey: process.env.SOLVER_PRIVATE_KEY!,
-        supportedChains: [1, 10, 42161],
-        supportedTokens: ["USDC"],
-        mode: "live"
+        agent: {
+            privateKey: process.env.SOLVER_PRIVATE_KEY!,
+            mode: "live",                              // Real ERC-20 transfers
+            supportedChains: [1, 10, 42161],
+            supportedTokens: ["USDC", "USDT"],
+        },
+        contractAddress: process.env.SETTLEMENT_CONTRACT!,
+        settlement: {
+            onPermanentFailure: (intentId, error, attempts) => {
+                console.error(`Intent ${intentId} failed permanently after ${attempts} tries: ${error}`);
+                // Send alert, page on-call, etc.
+            },
+        },
     },
-    }
 });
 
 await solver.initialize();
+
+// Connect to mempool — solver handles everything automatically
 solver.start("wss://mempool.yourprotocol.com/ws");
 
+// Poll stats every 30s
 setInterval(() => {
     const stats = solver.getStats();
     console.log("Solved:", stats.mempoolStats.solved);
-}, 5000);
+    console.log("Total Profit:", stats.profitStats.totalProfit);
+    console.log("Success Rate:", `${(stats.profitStats.successCount / stats.profitStats.totalAttempts * 100).toFixed(1)}%`);
+}, 30_000);
+
+// Graceful shutdown
+process.on("SIGINT", () => {
+    solver.stop();
+    process.exit(0);
+});
 ```
 
-## Supported Intent Types
+---
+
+## 🧠 Supported Intent Types
 
-| Type | Example |
-|------|---------|
-| **bridge** | "Bridge 100 USDC from Ethereum to Arbitrum" |
-| **send** | "Send 50 USDT to 0xAbc..." |
-| **swap** | "Swap 1 ETH for USDC on Uniswap" |
-| **claim** | "Claim rewards from staking" |
-| **yield_strategy** | "Deposit 1000 USDC into yield strategy with low risk" |
+| Type | Example Phrases |
+|------|----------------|
+| **`bridge`** | *"Bridge 100 USDC from Ethereum to Arbitrum"* |
+| **`send`** | *"Send 50 USDT to 0xAbc..."* or *"Transfer 0.1 ETH to alice.eth"* |
+| **`swap`** | *"Swap 1 ETH for USDC on Uniswap with max 1% slippage"* |
+| **`claim`** | *"Claim my ARB airdrop"* / *"Claim staking rewards from Aave"* |
+| **`yield_strategy`** | *"Deposit 1000 USDC for safe yield"* / *"degen high APY"* |
 
-## Supported Chains
+### Parser Output Shape
+
+```typescript
+interface StructuredIntent {
+    intentType: "bridge" | "send" | "swap" | "claim" | "yield_strategy" | "unknown";
+    parameters: IntentParameters;  // inputToken, inputAmount, sourceChain, targetChain, recipient, etc.
+    constraints: {
+        maxSlippage?: number;      // basis points (100 = 1%)
+        deadline?: number;        // unix timestamp
+        maxGasCost?: string;      // in native token
+        preferredDEXs?: string[];
+        minProtocols?: number;
+        // ... and more
+    };
+    metadata: {
+        confidence: number;       // 0 to 1 — how confident the parser is
+        parsedAt: number;        // unix ms timestamp
+        rawText?: string;        // original user input
+    };
+}
+```
+
+---
+
+## 🌐 Supported Chains
 
 ### Mainnets
 
-| Chain | ID |
-|-------|----|
-| Ethereum Mainnet | 1 |
-| Optimism | 10 |
-| Arbitrum One | 42161 |
+| Chain | ID | Notes |
+|-------|----|----|
+| Ethereum | `1` | Primary liquidity hub |
+| Optimism | `10` | L2 — low gas |
+| Arbitrum One | `42161` | L2 — low gas |
+| Polygon | `137` | Fast finality |
 
 ### Testnets
 
 | Chain | ID | Settlement Contract |
-|-------|----|--------------------|
-| Unichain Sepolia | 1301 | [`0x7066f6...`](https://unichain-sepolia.blockscout.com/address/0x7066f6dFc1C652c165Bc9BB10085fD95719b5eA6) |
-| Ethereum Sepolia | 11155111 | — |
-| Arbitrum Sepolia | 421614 | — |
-| Base Sepolia | 84532 | — |
+|-------|----|---------------------|
+| Unichain Sepolia | `1301` | [`0x7066f6...`](https://unichain-sepolia.blockscout.com/address/0x7066f6dFc1C652c165Bc9BB10085fD95719b5eA6) ✅ Deployed |
+| Ethereum Sepolia | `11155111` | — |
+| Arbitrum Sepolia | `421614` | — |
+| Base Sepolia | `84532` | — |
 
-Configure additional chains by adding their IDs to `supportedChains` and providing RPC URLs.
+> Add any EVM chain by supplying its `chainId` in `supportedChains` and an RPC URL.
 
-## Environment Configuration
+---
+
+## 💸 Fee Structure
+
+The solver earns fees on every successful solve:
 
-```bash
-cp .env.example .env
+```
+totalFee = baseFee + gasCost + slippageCapture
 ```
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `SOLVER_PRIVATE_KEY` | ✅ | Solver wallet private key (hex, with `0x`) |
-| `UNICHAIN_SEPOLIA_RPC_URL` | ✅ | RPC for Unichain Sepolia (1301) |
-| `SEPOLIA_RPC_URL` | Optional | RPC for Ethereum Sepolia |
-| `ARB_SEPOLIA_RPC_URL` | Optional | RPC for Arbitrum Sepolia |
-| `ETH_RPC_URL` | Optional | Ethereum Mainnet RPC (Aave reads) |
-| `SETTLEMENT_CONTRACT_UNICHAIN_SEPOLIA` | For live settlement | Deployed proxy address |
+| Component | Default | Description |
+|-----------|---------|-------------|
+| `baseFee` | 0.5% | Service charge on bridge amount |
+| `gasCost` | Dynamic | Estimated destination-chain gas |
+| `slippageCapture` | 50% of user's tolerance | Profit from unused slippage |
+
+### Dynamic Inventory Multiplier
+
+When liquidity on the target chain is low, fees adjust automatically:
+
+| Capacity | Multiplier | Behavior |
+|----------|-----------|----------|
+| ≥ 80% | **0.8×** | Discount — aggressively fill to rebalance |
+| 50–79% | **1.0×** | Normal pricing |
+| 20–49% | **1.5×** | Premium — inventory getting scarce |
+| 5–19% | **2.0×** | High premium |
+| < 5% | **Rejected** | Intent declined — not enough liquidity |
+
+---
+
+## 🛡️ Error Handling
+
+The SDK exposes typed error classes for precise catch handling:
 
-See [.env.example](./.env.example) for the full list.
+```typescript
+import {
+    IntentExpiredError,
+    InsufficientInventoryError,
+    UnsupportedIntentError,
+    ClaimFailedError,
+    ProofGenerationError,
+    SettlementError,
+} from "@terkoizmy/intent-sdk";
+
+try {
+    const result = await solver.solve(intent);
+} catch (error) {
+    if (error instanceof IntentExpiredError) {
+        // Intent deadline passed — ignore or notify user
+        console.warn("Deadline passed, skipping intent.");
+    } else if (error instanceof InsufficientInventoryError) {
+        // Not enough tokens on target chain
+        console.error(`Low inventory on chain ${error.chainId}`);
+    } else if (error instanceof ClaimFailedError) {
+        // Settlement claim on source chain failed
+        console.error(`Claim failed: ${error.reason}`);
+    } else {
+        throw error; // Rethrow unexpected errors
+    }
+}
+```
 
-## Solver Economics
+---
 
-The solver earns a fee on every successful solve:
+## 🔧 Configuration Reference
 
+```typescript
+createIntentSDK({
+    solver: {
+        agent: {
+            privateKey: "0x...",             // Required — solver wallet private key
+            mode: "simulate" | "live",       // Required — simulate or real transactions
+            name?: "MySolver",               // Optional name
+            supportedChains: [1, 137],       // Which chain IDs to service
+            supportedTokens: ["USDC"],       // Which tokens to handle
+            maxConcurrentIntents?: 5,        // Parallel solve limit (default: 5)
+        },
+        contractAddress: "0x...",            // IntentSettlement.sol proxy address
+
+        rpcUrls?: {                          // Optional override — fallback to public RPCs
+            1: "https://eth.rpc.example.com",
+            137: "https://polygon.rpc.example.com",
+        },
+
+        pricing?: {
+            baseFeePercent?: 0.005,          // 0.5% base fee (default)
+            minFeeUSD?: 1,                   // Minimum $1 USDC (default)
+            maxFeePercent?: 0.03,            // 3% cap (default)
+            slippageSharePercent?: 0.5,      // Capture 50% of user's tolerance (default)
+        },
+
+        inventory?: {
+            minReservePercent?: 0.10,        // Keep 10% in reserve (default)
+            rebalanceThreshold?: 0.15,       // Trigger rebalance at 15% imbalance (default)
+        },
+
+        settlement?: {
+            requiredConfirmations?: 3,       // Blocks before proof is generated (default: 3)
+            maxClaimRetries?: 3,             // Max retry attempts (default: 3)
+            watchIntervalMs?: 30_000,        // Watcher poll interval (default: 30s)
+            onPermanentFailure?: (intentId, error, attempts) => void,  // Failure callback
+        },
+    },
+});
 ```
-totalFee = baseFee + gasCost + slippageCapture
+
+---
+
+## ⚙️ Environment Variables
+
+```bash
+cp .env.example .env
 ```
 
-- **baseFee** — fixed % of the bridge amount (configurable, default 0.05%)
-- **gasCost** — estimated gas cost on the destination chain
-- **slippageCapture** — profit from unused slippage tolerance
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SOLVER_PRIVATE_KEY` | ✅ | Solver wallet private key (hex, with `0x`) |
+| `UNICHAIN_SEPOLIA_RPC_URL` | ✅ for testnet | RPC endpoint for Unichain Sepolia |
+| `SEPOLIA_RPC_URL` | Optional | Ethereum Sepolia RPC |
+| `ARB_SEPOLIA_RPC_URL` | Optional | Arbitrum Sepolia RPC |
+| `BASE_SEPOLIA_RPC_URL` | Optional | Base Sepolia RPC |
+| `ETH_RPC_URL` | Optional | Ethereum Mainnet (Aave reads) |
+| `SETTLEMENT_CONTRACT_UNICHAIN_SEPOLIA` | For live settlement | Deployed contract proxy address |
 
-The solver receives `userPays = inputAmount` from the source chain settlement and pays the user `userReceives = inputAmount - totalFee` on the target chain. The difference is solver profit.
+---
 
-## API
+## 📖 API Reference
 
 ### `IntentParser`
 
 ```typescript
-new IntentParser(config?: ParserConfig)
+const parser = new IntentParser(config?: ParserConfig);
 ```
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `parse(text)` | `Promise<ParseResult>` | Parse a natural language intent |
-| `parseBatch(texts)` | `Promise<ParseResult[]>` | Parse multiple intents |
+| `parse(text)` | `ParseResult` | Parse a single natural language intent (sync) |
+| `parseBatch(texts[])` | `ParseResult[]` | Parse multiple intents at once (sync) |
 
 ### `IntentSolver`
 
 ```typescript
-new IntentSolver(config: LiquidityAgentConfig)
+const solver = new IntentSolver(config: LiquidityAgentConfig);
 ```
 
 | Method | Description |
 |--------|-------------|
-| `initialize()` | Load balances and derive solver address |
-| `start(url)` | Connect to mempool WebSocket |
-| `stop()` | Disconnect and stop all background work |
-| `canSolve(intent)` | Check if this intent can be solved |
-| `getQuote(intent)` | Get fee breakdown without executing |
-| `solve(intent)` | Execute full solve → settlement flow |
+| `initialize()` | Load on-chain balances, derive solver address. **Call before anything else.** |
+| `start(mempoolUrl)` | Connect to mempool WebSocket and autonomously solve intents |
+| `stop()` | Gracefully disconnect and stop all background work |
+| `canSolve(intent)` | Returns `true` if the solver supports this intent type, chain, token, and has enough inventory |
+| `getQuote(intent)` | Returns full `PricingResult` fee breakdown without executing anything |
+| `solve(intent)` | Execute full solve → settlement flow. Returns `SolutionResult` |
 | `getStatus()` | Returns `"idle"` or `"processing"` |
-| `getStats()` | Returns profit + mempool statistics |
+| `getStats()` | Returns `{ profitStats, mempoolStats }` |
 
-### `createIntentSDK(config)`
+### `createIntentSDK(config)` — Factory
 
-Factory that creates both `parser` and `solver` in one call:
+Returns `{ parser, solver }` — the easiest way to get started:
 
 ```typescript
 const { parser, solver } = createIntentSDK(config);
+// parser → IntentParser
+// solver → IntentSolver (wraps LiquidityAgent + all subsystems)
+```
+
+---
+
+## 📂 Project Structure
+
+```
+src/
+├── parser/           ← IntentParser — NLP-to-structured-intent engine
+│   ├── classifiers/  ← Intent type detection (bridge/send/swap/...)
+│   ├── extractors/   ← Amount, token, chain, action extraction
+│   ├── validators/   ← Zod schema validation
+│   └── utils/        ← Normalization, confidence scoring
+├── solver/           ← IntentSolver — autonomous liquidity agent
+│   ├── agent/        ← LiquidityAgent, AgentConfig
+│   ├── contracts/    ← ViemSettlementContract (ERC-7683 wrapper)
+│   ├── inventory/    ← InventoryManager, Rebalancer (Li.Fi / Swing)
+│   ├── mempool/      ← MempoolClient, IntentFilter, SolutionSubmitter
+│   ├── monitoring/   ← ProfitTracker, HealthChecker, AlertManager
+│   ├── pricing/      ← DynamicPricing, FeeCalculator, SlippageCapture
+│   ├── protocols/    ← Li.Fi (bridge aggregator), Aave (lending), Swing
+│   └── settlement/   ← ProofGenerator, ProofVerifier, SettlementManager
+├── shared/           ← Reusable utilities
+│   ├── rpc/          ← ViemProvider (with retry backoff), RPCProviderManager
+│   ├── utils/        ← ERC-20 ABI utils, withRetry
+│   ├── chain-registry/ ← Chain configs, name resolvers
+│   ├── token-registry/ ← Token metadata
+│   └── wallet-manager/ ← WalletManager (sign, transfer)
+├── errors/           ← Domain-specific typed error classes
+├── types/            ← Shared TypeScript interfaces
+└── config/           ← Chain configs, default pricing, testnet RPC URLs
+contracts/            ← IntentSettlement.sol (ERC-7683 + UUPS upgradeable)
+tests/
+├── parser/           ← Parser unit tests
+├── solver/           ← Solver unit tests (pricing, settlement, protocols)
+├── shared/           ← Shared utility tests (retry, viem, chain registry)
+├── integration/      ← Mock-based full pipeline tests
+├── live/             ← Live testnet tests (requires funded wallet + RPC)
+└── e2e/              ← End-to-end testnet tests
+docs/                 ← Full documentation
+examples/             ← Runnable code examples
 ```
 
-## Documentation
+---
+
+## 📚 Documentation
+
+| Document | What You'll Find |
+|----------|-----------------|
+| [docs/USAGE.md](./docs/USAGE.md) | Full usage guide with all features and code samples |
+| [docs/SOLVER.md](./docs/SOLVER.md) | Solver architecture, config reference, fee structure, API |
+| [docs/SDK_WORKFLOW.md](./docs/SDK_WORKFLOW.md) | End-to-end workflow diagrams (Parser → Solver → Settlement) |
+| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | System architecture, component map, data flows |
+| [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md) | Deploy the IntentSettlement smart contract |
+| [docs/TESTNET_GUIDE.md](./docs/TESTNET_GUIDE.md) | Faucets, wallet funding, troubleshooting on testnets |
+| [docs/ERC_STANDARDS.md](./docs/ERC_STANDARDS.md) | ERC-7683, ERC-712 standards used in settlement |
 
-| Document | Contents |
-|----------|----------|
-| [docs/USAGE.md](./docs/USAGE.md) | Comprehensive How-To Guide for using the SDK |
-| [docs/SOLVER.md](./docs/SOLVER.md) | Architecture, config reference, fee structure, API details |
-| [docs/SDK_WORKFLOW.md](./docs/SDK_WORKFLOW.md) | End-to-end workflow diagrams |
-| [docs/ERC_STANDARDS.md](./docs/ERC_STANDARDS.md) | ERC-7683, ERC-712 standards used |
-| [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md) | Step-by-step testnet deployment guide |
-| [docs/TESTNET_GUIDE.md](./docs/TESTNET_GUIDE.md) | Faucets, funding, troubleshooting |
+---
 
-## Examples
+## 💡 Examples
 
 | File | Description |
 |------|-------------|
-| `examples/basic-bridge.ts` | Parse + manual solve |
-| `examples/autonomous-agent.ts` | Autonomous mempool listener |
-| `examples/inventory-management.ts` | Inventory snapshot + rebalancing |
+| [`examples/basic-bridge.ts`](./examples/basic-bridge.ts) | Parse and manually solve a bridge intent |
+| [`examples/autonomous-agent.ts`](./examples/autonomous-agent.ts) | Fully autonomous mempool listener agent |
+| [`examples/inventory-management.ts`](./examples/inventory-management.ts) | Inventory snapshot + auto-rebalancing |
+
+```bash
+# Run an example
+npx tsx examples/basic-bridge.ts
+```
 
-## Development
+---
+
+## 🧪 Development
 
 ```bash
 # Install dependencies
 bun install
 
-# Build
+# Build TypeScript
 bun run build
 
-# Test all (parser + solver units + integration)
-bun test
-
-# Run specific test suites
-bun test tests/parser/
-bun test tests/solver/
-bun test tests/integration/
-bun test tests/shared/
+# Run all tests (no network needed)
+bun test tests/parser/ tests/solver/ tests/shared/ tests/integration/
 
-# Live tests (requires funded wallet + RPC)
-bun test tests/live/
+# Run specific suites
+bun test tests/parser/           # parser unit tests
+bun test tests/solver/           # solver unit tests
+bun test tests/integration/      # integration pipeline tests
 
-# E2E testnet tests (full pipeline)
-bun test tests/e2e/
+# Tests requiring a funded wallet + RPC
+bun test tests/live/             # live testnet tests
+bun test tests/e2e/              # full E2E pipeline
 
-# Run an example
-npx tsx examples/basic-bridge.ts
+# Type check only
+bun run build --noEmit
 ```
 
-## Project Structure
+---
 
-```
-src/
-├── parser/          ← IntentParser (Stage 1)
-├── solver/          ← IntentSolver / LiquidityAgent (Stage 2+3)
-│   ├── agent/       ← LiquidityAgent, AgentConfig
-│   ├── contracts/   ← IntentSettlement viem wrapper
-│   ├── inventory/   ← InventoryManager, Rebalancer
-│   ├── pricing/     ← DynamicPricing, FeeCalculator
-│   ├── settlement/  ← ProofGenerator, SettlementManager
-│   ├── mempool/     ← MempoolClient, IntentFilter
-│   ├── monitoring/  ← ProfitTracker, HealthChecker
-│   └── protocols/   ← LiFi (aggregator), Aave (lending)
-├── shared/          ← WalletManager, ChainRegistry, RPC, TokenRegistry
-│   ├── rpc/         ← RPCProviderManager, ViemProvider (with retry)
-│   ├── utils/       ← ERC-20 utils, retry with backoff
-│   └── chain-registry/ ← Chain configs, chain names
-├── errors/          ← Domain-specific error classes
-└── types/           ← Shared types
-contracts/           ← IntentSettlement.sol (ERC-7683, UUPS)
-tests/
-├── parser/          ← Parser unit tests
-├── solver/          ← Solver unit tests
-├── shared/          ← Shared util tests (retry, viem, enrichment)
-├── integration/     ← Mock-based integration tests
-├── live/            ← Live testnet tests (guarded)
-└── e2e/             ← Full E2E pipeline tests (guarded)
-docs/                ← Documentation
-examples/            ← Runnable usage examples
-```
+## 🤝 Contributing
+
+Pull requests are welcome! Please:
+1. Run `bun test` and confirm all non-live tests pass
+2. Run `bun run build` and confirm no TypeScript errors
+3. Follow the existing code style (typed catch blocks, no `any`, typed interfaces)
+
+---
 
-## License
+## 📄 License
 
-MIT
+MIT © 2024 [@terkoizmy](https://github.com/terkoizmy)

package/dist/config/testnets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testnets.d.ts","sourceRoot":"","sources":["../../src/config/testnets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,WAgB5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAgBrC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAgBrC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAgBjC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,EAK3C,CAAC"}
+{"version":3,"file":"testnets.d.ts","sourceRoot":"","sources":["../../src/config/testnets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,WAkB5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAkBrC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAgBrC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAkBjC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,EAK3C,CAAC"}