perp-cli 0.11.0 → 0.12.0

package/dist/__tests__/integration/bridge-strict.integration.test.js

@@ -1,812 +0,0 @@
-/**
- * Strict Bridge Integration Tests — comprehensive verification using real keys.
- *
- * Uses .env keys for address derivation and balance checks.
- * NO transactions are executed. NO funds are spent.
- *
- * Core verification: "sender pays only" — all bridge fees are deducted from
- * the source USDC amount. The recipient receives amountOut without paying
- * any gas or fees on the destination chain.
- *
- * Tests:
- * 1. Key derivation & address consistency
- * 2. Real balance checks on all chains
- * 3. CCTP quote API for all routes (including HyperCore)
- * 4. HyperCore CCTP fees API validation
- * 5. deBridge quote API with real addresses
- * 6. Relay quote API with real addresses
- * 7. getAllQuotes aggregation correctness
- * 8. getBestQuote selection logic
- * 9. Cross-provider quote comparison
- * 10. Edge cases and error handling
- * 11-14. On-chain / API verification
- * 15. SENDER-PAYS-ONLY: full 4-chain matrix verification
- * 16. Complete route matrix (all 12 directional pairs)
- */
-import { describe, it, expect, beforeAll } from "vitest";
-import { config } from "dotenv";
-import { CHAIN_IDS, USDC_ADDRESSES, CCTP_DOMAINS, EXCHANGE_TO_CHAIN, getCctpQuote, getDebridgeQuote, getRelayQuote, getAllQuotes, getBestQuote, getEvmUsdcBalance, getSolanaUsdcBalance, checkBridgeBalance, getNativeGasBalance, checkBridgeGasBalance, } from "../../bridge-engine.js";
-// Load .env
-config();
-const wait = (ms) => new Promise((r) => setTimeout(r, ms));
-// ── Derive real addresses from .env keys ──
-let solanaAddress;
-let evmAddress;
-describe("Strict Bridge Integration Tests", { timeout: 120000 }, () => {
-    // ══════════════════════════════════════════════════════════
-    // 0. Setup: derive addresses from private keys
-    // ══════════════════════════════════════════════════════════
-    beforeAll(async () => {
-        // Derive Solana address
-        const { Keypair } = await import("@solana/web3.js");
-        const bs58 = await import("bs58");
-        const solanaKey = process.env.pk ?? process.env.PACIFICA_PRIVATE_KEY;
-        if (!solanaKey)
-            throw new Error("Missing 'pk' or 'PACIFICA_PRIVATE_KEY' in .env");
-        const keypair = Keypair.fromSecretKey(bs58.default.decode(solanaKey));
-        solanaAddress = keypair.publicKey.toBase58();
-        // Derive EVM address
-        const { ethers } = await import("ethers");
-        const evmKey = process.env.HL_PRIVATE_KEY;
-        if (!evmKey)
-            throw new Error("Missing 'HL_PRIVATE_KEY' in .env");
-        const wallet = new ethers.Wallet(evmKey);
-        evmAddress = wallet.address;
-    });
-    // ══════════════════════════════════════════════════════════
-    // 1. Key & Address Validation
-    // ══════════════════════════════════════════════════════════
-    describe("1. Key derivation & address format", () => {
-        it("Solana address is valid base58 (32-44 chars)", () => {
-            expect(solanaAddress).toBeDefined();
-            expect(solanaAddress.length).toBeGreaterThanOrEqual(32);
-            expect(solanaAddress.length).toBeLessThanOrEqual(44);
-            expect(solanaAddress).toMatch(/^[1-9A-HJ-NP-Za-km-z]+$/);
-        });
-        it("EVM address is valid checksummed address", () => {
-            expect(evmAddress).toBeDefined();
-            expect(evmAddress).toMatch(/^0x[0-9a-fA-F]{40}$/);
-        });
-        it("HL_PRIVATE_KEY and LIGHTER_PRIVATE_KEY derive same EVM address", async () => {
-            const { ethers } = await import("ethers");
-            const hlWallet = new ethers.Wallet(process.env.HL_PRIVATE_KEY);
-            const lighterWallet = new ethers.Wallet(process.env.LIGHTER_PRIVATE_KEY);
-            expect(hlWallet.address).toBe(lighterWallet.address);
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 2. Configuration Consistency
-    // ══════════════════════════════════════════════════════════
-    describe("2. Configuration consistency", () => {
-        it("EXCHANGE_TO_CHAIN maps correctly", () => {
-            expect(EXCHANGE_TO_CHAIN.pacifica).toBe("solana");
-            expect(EXCHANGE_TO_CHAIN.hyperliquid).toBe("hyperliquid");
-            expect(EXCHANGE_TO_CHAIN.lighter).toBe("arbitrum");
-        });
-        it("all standard chains have chain IDs", () => {
-            expect(CHAIN_IDS.solana).toBe(7565164);
-            expect(CHAIN_IDS.arbitrum).toBe(42161);
-            expect(CHAIN_IDS.base).toBe(8453);
-        });
-        it("all standard chains have USDC addresses", () => {
-            for (const chain of ["solana", "arbitrum", "base"]) {
-                expect(USDC_ADDRESSES[chain]).toBeDefined();
-            }
-        });
-        it("CCTP domains include hyperliquid (19)", () => {
-            expect(CCTP_DOMAINS.solana).toBe(5);
-            expect(CCTP_DOMAINS.arbitrum).toBe(3);
-            expect(CCTP_DOMAINS.base).toBe(6);
-            expect(CCTP_DOMAINS.hyperliquid).toBe(19);
-        });
-        it("no unsupported chains leak into config", () => {
-            const supportedChains = ["solana", "arbitrum", "base"];
-            for (const chain of Object.keys(CHAIN_IDS)) {
-                expect(supportedChains).toContain(chain);
-            }
-        });
-        it("CCTP domains only contain supported chains + hyperliquid", () => {
-            const allowed = ["solana", "arbitrum", "base", "hyperliquid"];
-            for (const chain of Object.keys(CCTP_DOMAINS)) {
-                expect(allowed).toContain(chain);
-            }
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 3. Real Balance Checks
-    // ══════════════════════════════════════════════════════════
-    describe("3. Real balance checks", () => {
-        it("Solana USDC balance query succeeds", async () => {
-            const balance = await getSolanaUsdcBalance(solanaAddress);
-            expect(typeof balance).toBe("number");
-            expect(balance).toBeGreaterThanOrEqual(0);
-        });
-        it("Arbitrum USDC balance query succeeds", async () => {
-            const balance = await getEvmUsdcBalance("arbitrum", evmAddress);
-            expect(typeof balance).toBe("number");
-            expect(balance).toBeGreaterThanOrEqual(0);
-        });
-        it("Base USDC balance query succeeds", async () => {
-            const balance = await getEvmUsdcBalance("base", evmAddress);
-            expect(typeof balance).toBe("number");
-            expect(balance).toBeGreaterThanOrEqual(0);
-        });
-        it("checkBridgeBalance returns consistent shape", async () => {
-            const result = await checkBridgeBalance("solana", solanaAddress, 1);
-            expect(typeof result.balance).toBe("number");
-            expect(typeof result.sufficient).toBe("boolean");
-            expect(result.sufficient).toBe(result.balance >= 1);
-        });
-        it("unsupported chain balance throws", async () => {
-            await expect(getEvmUsdcBalance("fakenet", evmAddress)).rejects.toThrow();
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 3b. Native Gas Balance Checks
-    // ══════════════════════════════════════════════════════════
-    describe("3b. Native gas balance checks", () => {
-        it("Solana SOL balance query succeeds", async () => {
-            const balance = await getNativeGasBalance("solana", solanaAddress);
-            expect(typeof balance).toBe("number");
-            expect(balance).toBeGreaterThanOrEqual(0);
-        });
-        it("Arbitrum ETH balance query succeeds", async () => {
-            const balance = await getNativeGasBalance("arbitrum", evmAddress);
-            expect(typeof balance).toBe("number");
-            expect(balance).toBeGreaterThanOrEqual(0);
-        });
-        it("Base ETH balance query succeeds", async () => {
-            const balance = await getNativeGasBalance("base", evmAddress);
-            expect(typeof balance).toBe("number");
-            expect(balance).toBeGreaterThanOrEqual(0);
-        });
-        it("unsupported chain gas balance throws", async () => {
-            await expect(getNativeGasBalance("fakenet", evmAddress)).rejects.toThrow();
-        });
-        it("checkBridgeGasBalance: src-only check (fast mode)", async () => {
-            const result = await checkBridgeGasBalance("arbitrum", evmAddress, "base", evmAddress, false);
-            expect(typeof result.ok).toBe("boolean");
-            expect(Array.isArray(result.errors)).toBe(true);
-        });
-        it("checkBridgeGasBalance: src+dst check (standard mode)", async () => {
-            const result = await checkBridgeGasBalance("arbitrum", evmAddress, "base", evmAddress, true);
-            expect(typeof result.ok).toBe("boolean");
-            expect(Array.isArray(result.errors)).toBe(true);
-        });
-        it("checkBridgeGasBalance: returns errors array for insufficient gas", async () => {
-            // Use an address unlikely to have gas on both chains
-            const emptyAddr = "0x000000000000000000000000000000000000dEaD";
-            const result = await checkBridgeGasBalance("arbitrum", emptyAddr, "base", emptyAddr, true);
-            // Shape is correct regardless of balance
-            expect(typeof result.ok).toBe("boolean");
-            expect(Array.isArray(result.errors)).toBe(true);
-            if (!result.ok) {
-                expect(result.errors[0]).toMatch(/arbitrum|base/);
-            }
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 4. CCTP Quotes — Standard Routes
-    // ══════════════════════════════════════════════════════════
-    describe("4. CCTP standard quotes", () => {
-        const standardRoutes = [
-            ["solana", "arbitrum"],
-            ["solana", "base"],
-            ["arbitrum", "base"],
-            ["arbitrum", "solana"],
-            ["base", "arbitrum"],
-            ["base", "solana"],
-        ];
-        for (const [src, dst] of standardRoutes) {
-            it(`${src} → ${dst}: valid CCTP quote`, async () => {
-                const quote = await getCctpQuote(src, dst, 100);
-                expect(quote.provider).toBe("cctp");
-                expect(quote.srcChain).toBe(src);
-                expect(quote.dstChain).toBe(dst);
-                expect(quote.amountIn).toBe(100);
-                expect(quote.amountOut).toBeGreaterThan(0);
-                expect(quote.amountOut).toBeLessThanOrEqual(100);
-                expect(quote.fee).toBeGreaterThanOrEqual(0);
-                expect(quote.fee).toBeLessThan(5); // max $5 relay fee
-                expect(quote.estimatedTime).toBeGreaterThan(0);
-                expect(Math.abs(quote.fee - (quote.amountIn - quote.amountOut))).toBeLessThan(0.001);
-                expect(quote.raw).toBeDefined();
-            });
-        }
-        it("large amount ($100k) quote is valid", async () => {
-            const quote = await getCctpQuote("arbitrum", "base", 100000);
-            expect(quote.amountOut).toBeGreaterThan(99900); // fee should be tiny relative to amount
-            expect(quote.fee).toBeLessThan(5);
-        });
-        it("tiny amount ($0.01) quote is valid", async () => {
-            const quote = await getCctpQuote("arbitrum", "base", 0.01);
-            expect(quote.amountOut).toBeGreaterThan(-1);
-            expect(quote.fee).toBeLessThan(1);
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 5. CCTP Quotes — HyperCore Routes
-    // ══════════════════════════════════════════════════════════
-    describe("5. HyperCore CCTP quotes", () => {
-        it("solana → hyperliquid: valid HyperCore deposit quote", async () => {
-            const quote = await getCctpQuote("solana", "hyperliquid", 500);
-            expect(quote.provider).toBe("cctp");
-            expect(quote.srcChain).toBe("solana");
-            expect(quote.dstChain).toBe("hyperliquid");
-            expect(quote.amountIn).toBe(500);
-            expect(quote.amountOut).toBeGreaterThan(0);
-            expect(quote.amountOut).toBeLessThan(500);
-            expect(quote.fee).toBeGreaterThan(0);
-            expect(quote.fee).toBeLessThan(5); // should be ~$0.25 (1bp + forwarding)
-            expect(quote.estimatedTime).toBe(65); // Solana source
-            expect(quote.gasIncluded).toBe(true);
-            expect(quote.raw).toHaveProperty("type", "cctp-hypercore");
-            expect(quote.raw).toHaveProperty("maxFee");
-        });
-        it("arbitrum → hyperliquid: valid HyperCore deposit quote", async () => {
-            const quote = await getCctpQuote("arbitrum", "hyperliquid", 1000);
-            expect(quote.provider).toBe("cctp");
-            expect(quote.srcChain).toBe("arbitrum");
-            expect(quote.dstChain).toBe("hyperliquid");
-            expect(quote.amountIn).toBe(1000);
-            expect(quote.amountOut).toBeGreaterThan(0);
-            expect(quote.fee).toBeGreaterThan(0);
-            expect(quote.fee).toBeLessThan(5);
-            expect(quote.estimatedTime).toBe(60); // EVM-to-EVM fast
-            expect(quote.gasIncluded).toBe(true);
-            expect(quote.raw).toHaveProperty("type", "cctp-hypercore");
-        });
-        it("base → hyperliquid: valid HyperCore deposit quote", async () => {
-            const quote = await getCctpQuote("base", "hyperliquid", 200);
-            expect(quote.provider).toBe("cctp");
-            expect(quote.dstChain).toBe("hyperliquid");
-            expect(quote.amountOut).toBeGreaterThan(0);
-            expect(quote.fee).toBeLessThan(5);
-            expect(quote.estimatedTime).toBe(60);
-        });
-        it("hyperliquid → arbitrum: valid HyperCore withdrawal quote", async () => {
-            const quote = await getCctpQuote("hyperliquid", "arbitrum", 300);
-            expect(quote.provider).toBe("cctp");
-            expect(quote.srcChain).toBe("hyperliquid");
-            expect(quote.dstChain).toBe("arbitrum");
-            expect(quote.amountIn).toBe(300);
-            expect(quote.amountOut).toBe(299.80); // $0.20 forwarding fee
-            expect(quote.fee).toBe(0.20);
-            expect(quote.estimatedTime).toBe(60);
-            expect(quote.gasIncluded).toBe(true);
-            expect(quote.raw).toHaveProperty("type", "cctp-hypercore-withdraw");
-        });
-        it("hyperliquid → solana: valid HyperCore withdrawal quote", async () => {
-            const quote = await getCctpQuote("hyperliquid", "solana", 100);
-            expect(quote.provider).toBe("cctp");
-            expect(quote.srcChain).toBe("hyperliquid");
-            expect(quote.dstChain).toBe("solana");
-            expect(quote.fee).toBe(0.20);
-            expect(quote.amountOut).toBe(99.80);
-        });
-        it("HyperCore fees scale correctly with amount", async () => {
-            const small = await getCctpQuote("arbitrum", "hyperliquid", 10);
-            const large = await getCctpQuote("arbitrum", "hyperliquid", 10000);
-            // Protocol fee is 1bp, so large amount pays more
-            expect(large.fee).toBeGreaterThan(small.fee);
-            // But fee percentage should be similar (both ~1bp + flat forwarding)
-            const smallPct = small.fee / small.amountIn;
-            const largePct = large.fee / large.amountIn;
-            expect(smallPct).toBeGreaterThan(largePct); // smaller amounts pay higher % (flat fee dominates)
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 6. HyperCore Fees API Direct Validation
-    // ══════════════════════════════════════════════════════════
-    describe("6. HyperCore fees API", () => {
-        const FEES_API = "https://iris-api.circle.com/v2/burn/USDC/fees";
-        it("Solana (domain 5) → HyperCore (domain 19) fees API responds", async () => {
-            const res = await fetch(`${FEES_API}/5/19?forward=true&hyperCoreDeposit=true`);
-            expect(res.ok).toBe(true);
-            const data = await res.json();
-            expect(Array.isArray(data)).toBe(true);
-            expect(data.length).toBeGreaterThan(0);
-            const schedule = data[0];
-            expect(schedule).toHaveProperty("finalityThreshold");
-            expect(schedule).toHaveProperty("minimumFee");
-        });
-        it("Arbitrum (domain 3) → HyperCore (domain 19) fees API responds", async () => {
-            const res = await fetch(`${FEES_API}/3/19?forward=true&hyperCoreDeposit=true`);
-            expect(res.ok).toBe(true);
-            const data = await res.json();
-            expect(Array.isArray(data)).toBe(true);
-            expect(data.length).toBeGreaterThan(0);
-        });
-        it("Base (domain 6) → HyperCore (domain 19) fees API responds", async () => {
-            const res = await fetch(`${FEES_API}/6/19?forward=true&hyperCoreDeposit=true`);
-            expect(res.ok).toBe(true);
-            const data = await res.json();
-            expect(Array.isArray(data)).toBe(true);
-        });
-        it("fees API returns forward fee structure", async () => {
-            const res = await fetch(`${FEES_API}/3/19?forward=true&hyperCoreDeposit=true`);
-            const data = await res.json();
-            // Look for schedule with forwardFee
-            const hasForwardFee = data.some(s => s.forwardFee !== undefined && s.forwardFee !== null);
-            // At minimum, all schedules should have finalityThreshold and minimumFee
-            for (const schedule of data) {
-                expect(typeof schedule.finalityThreshold).toBe("number");
-                expect(typeof schedule.minimumFee).toBe("number");
-            }
-            // Forward fee may or may not be present depending on API version
-            if (hasForwardFee) {
-                const withFee = data.find(s => s.forwardFee !== undefined);
-                const ff = withFee.forwardFee;
-                expect(typeof ff.low).toBe("number");
-                expect(typeof ff.med).toBe("number");
-                expect(typeof ff.high).toBe("number");
-                expect(ff.med).toBeGreaterThanOrEqual(ff.low);
-                expect(ff.high).toBeGreaterThanOrEqual(ff.med);
-            }
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 7. deBridge DLN Quotes (with real addresses)
-    // ══════════════════════════════════════════════════════════
-    describe("7. deBridge quotes with real addresses", () => {
-        it("solana → arbitrum: quote with real wallet addresses", async () => {
-            const quote = await getDebridgeQuote("solana", "arbitrum", 100, solanaAddress, evmAddress);
-            expect(quote.provider).toBe("debridge");
-            expect(quote.srcChain).toBe("solana");
-            expect(quote.dstChain).toBe("arbitrum");
-            expect(quote.amountIn).toBe(100);
-            expect(quote.amountOut).toBeGreaterThan(0);
-            expect(quote.amountOut).toBeLessThanOrEqual(100);
-            expect(quote.fee).toBeGreaterThanOrEqual(0);
-            expect(quote.estimatedTime).toBeGreaterThan(0);
-            expect(Math.abs(quote.fee - (quote.amountIn - quote.amountOut))).toBeLessThan(0.001);
-        });
-        it("arbitrum → base: EVM-to-EVM with real addresses", async () => {
-            await wait(1500);
-            const quote = await getDebridgeQuote("arbitrum", "base", 200, evmAddress, evmAddress);
-            expect(quote.provider).toBe("debridge");
-            expect(quote.amountOut).toBeGreaterThan(0);
-            expect(quote.amountOut).toBeLessThanOrEqual(200);
-        });
-        it("base → solana: reverse route with real addresses", async () => {
-            await wait(1500);
-            const quote = await getDebridgeQuote("base", "solana", 50, evmAddress, solanaAddress);
-            expect(quote.provider).toBe("debridge");
-            expect(quote.amountOut).toBeGreaterThan(0);
-        });
-        it("unsupported chain throws", async () => {
-            await expect(getDebridgeQuote("hyperliquid", "arbitrum", 100, evmAddress, evmAddress)).rejects.toThrow(/Unsupported chain/i);
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 8. Relay Quotes (with real addresses)
-    // ══════════════════════════════════════════════════════════
-    describe("8. Relay quotes with real addresses", () => {
-        it("solana → arbitrum: Relay quote with real addresses", async () => {
-            const quote = await getRelayQuote("solana", "arbitrum", 100, solanaAddress, evmAddress);
-            expect(quote.provider).toBe("relay");
-            expect(quote.srcChain).toBe("solana");
-            expect(quote.dstChain).toBe("arbitrum");
-            expect(quote.amountIn).toBe(100);
-            expect(quote.amountOut).toBeGreaterThan(0);
-            expect(quote.amountOut).toBeLessThanOrEqual(100);
-            expect(quote.estimatedTime).toBeGreaterThan(0);
-        });
-        it("arbitrum → base: EVM-to-EVM Relay quote", async () => {
-            await wait(1000);
-            const quote = await getRelayQuote("arbitrum", "base", 500, evmAddress, evmAddress);
-            expect(quote.provider).toBe("relay");
-            expect(quote.amountOut).toBeGreaterThan(0);
-        });
-        it("base → solana: reverse Relay quote", async () => {
-            await wait(1000);
-            const quote = await getRelayQuote("base", "solana", 200, evmAddress, solanaAddress);
-            expect(quote.provider).toBe("relay");
-            expect(quote.amountOut).toBeGreaterThan(0);
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 9. getAllQuotes Aggregation
-    // ══════════════════════════════════════════════════════════
-    describe("9. getAllQuotes aggregation", () => {
-        it("arbitrum → base: returns multiple providers sorted by amountOut", async () => {
-            await wait(2000);
-            const quotes = await getAllQuotes("arbitrum", "base", 1000, evmAddress, evmAddress);
-            expect(quotes.length).toBeGreaterThanOrEqual(1);
-            // Should be sorted by amountOut descending (best first)
-            for (let i = 1; i < quotes.length; i++) {
-                expect(quotes[i - 1].amountOut).toBeGreaterThanOrEqual(quotes[i].amountOut);
-            }
-            // All quotes should have consistent shape
-            for (const q of quotes) {
-                expect(["cctp", "debridge", "relay"]).toContain(q.provider);
-                expect(q.srcChain).toBe("arbitrum");
-                expect(q.dstChain).toBe("base");
-                expect(q.amountIn).toBe(1000);
-                expect(q.amountOut).toBeGreaterThan(0);
-                expect(typeof q.fee).toBe("number");
-                expect(typeof q.estimatedTime).toBe("number");
-            }
-            // CCTP should be present (it's always available for supported routes)
-            const cctpQuote = quotes.find(q => q.provider === "cctp");
-            expect(cctpQuote).toBeDefined();
-        });
-        it("solana → arbitrum: includes CCTP + at least one other provider", async () => {
-            await wait(2000);
-            const quotes = await getAllQuotes("solana", "arbitrum", 200, solanaAddress, evmAddress);
-            expect(quotes.length).toBeGreaterThanOrEqual(2);
-            const providers = new Set(quotes.map(q => q.provider));
-            expect(providers.has("cctp")).toBe(true);
-            // Should have debridge or relay too
-            expect(providers.size).toBeGreaterThanOrEqual(2);
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 10. getBestQuote Selection
-    // ══════════════════════════════════════════════════════════
-    describe("10. getBestQuote selection", () => {
-        it("best quote is cheapest provider for standard chains", async () => {
-            const quote = await getBestQuote("arbitrum", "base", 500, evmAddress, evmAddress);
-            // Best quote should be either CCTP or Relay (both valid, sorted by amountOut)
-            expect(["cctp", "relay"]).toContain(quote.provider);
-            expect(quote.amountOut).toBeGreaterThanOrEqual(498);
-            expect(quote.fee).toBeLessThan(2);
-        });
-        it("solana → arbitrum: CCTP preferred", async () => {
-            const quote = await getBestQuote("solana", "arbitrum", 1000, solanaAddress, evmAddress);
-            expect(quote.provider).toBe("cctp");
-            expect(quote.fee).toBeLessThan(2);
-        });
-        it("quote amountIn - amountOut ≈ fee", async () => {
-            const quote = await getBestQuote("base", "solana", 100, evmAddress, solanaAddress);
-            const calculatedFee = quote.amountIn - quote.amountOut;
-            expect(Math.abs(calculatedFee - quote.fee)).toBeLessThan(0.01);
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 11. Cross-Provider Comparison
-    // ══════════════════════════════════════════════════════════
-    describe("11. Cross-provider fee comparison", () => {
-        it("CCTP is cheaper than deBridge for standard routes", async () => {
-            await wait(2000);
-            const cctp = await getCctpQuote("arbitrum", "base", 1000);
-            const debridge = await getDebridgeQuote("arbitrum", "base", 1000, evmAddress, evmAddress);
-            expect(cctp.fee).toBeLessThanOrEqual(debridge.fee);
-            expect(cctp.amountOut).toBeGreaterThanOrEqual(debridge.amountOut);
-        });
-        it("HyperCore CCTP fee is reasonable ($0.20-$2 range)", async () => {
-            const quote = await getCctpQuote("arbitrum", "hyperliquid", 1000);
-            expect(quote.fee).toBeGreaterThanOrEqual(0.10);
-            expect(quote.fee).toBeLessThan(3);
-        });
-        it("HyperCore withdrawal fee is fixed at $0.20", async () => {
-            const q100 = await getCctpQuote("hyperliquid", "arbitrum", 100);
-            const q10000 = await getCctpQuote("hyperliquid", "arbitrum", 10000);
-            expect(q100.fee).toBe(0.20);
-            expect(q10000.fee).toBe(0.20);
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 12. Error Handling & Edge Cases
-    // ══════════════════════════════════════════════════════════
-    describe("12. Error handling", () => {
-        it("CCTP quote for unsupported chain throws", async () => {
-            await expect(getCctpQuote("polygon", "arbitrum", 100)).rejects.toThrow(/not supported/i);
-        });
-        it("deBridge zero amount throws", async () => {
-            await wait(1500);
-            await expect(getDebridgeQuote("solana", "arbitrum", 0, solanaAddress, evmAddress)).rejects.toThrow();
-        });
-        it("deBridge negative amount throws", async () => {
-            await wait(1500);
-            await expect(getDebridgeQuote("arbitrum", "base", -100, evmAddress, evmAddress)).rejects.toThrow();
-        });
-        it("CCTP same-chain quote still valid", async () => {
-            const quote = await getCctpQuote("arbitrum", "arbitrum", 100);
-            expect(quote.provider).toBe("cctp");
-            expect(quote.amountOut).toBeGreaterThan(0);
-        });
-        it("all quotes return gasIncluded field", async () => {
-            const cctp = await getCctpQuote("arbitrum", "base", 100);
-            expect(typeof cctp.gasIncluded).toBe("boolean");
-            const hypercore = await getCctpQuote("arbitrum", "hyperliquid", 100);
-            expect(hypercore.gasIncluded).toBe(true);
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 13. HyperCore CctpForwarder Contract Verification
-    // ══════════════════════════════════════════════════════════
-    describe("13. HyperCore on-chain verification", () => {
-        const HYPERCORE_FORWARDER = "0xb21D281DEdb17AE5B501F6AA8256fe38C4e45757";
-        const HYPERCORE_RPC = "https://rpc.hyperliquid.xyz/evm";
-        it("CctpForwarder contract exists on HyperEVM", async () => {
-            const res = await fetch(HYPERCORE_RPC, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({
-                    jsonrpc: "2.0", id: 1,
-                    method: "eth_getCode",
-                    params: [HYPERCORE_FORWARDER, "latest"],
-                }),
-            });
-            const json = await res.json();
-            // Contract should have code (not "0x")
-            expect(json.result).toBeDefined();
-            expect(json.result.length).toBeGreaterThan(2);
-            expect(json.result).not.toBe("0x");
-        });
-        it("CctpExtension contract exists on Arbitrum", async () => {
-            const CCTP_EXTENSION = "0xA95d9c1F655341597C94393fDdc30cf3c08E4fcE";
-            const res = await fetch("https://arb1.arbitrum.io/rpc", {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({
-                    jsonrpc: "2.0", id: 1,
-                    method: "eth_getCode",
-                    params: [CCTP_EXTENSION, "latest"],
-                }),
-            });
-            const json = await res.json();
-            expect(json.result.length).toBeGreaterThan(2);
-            expect(json.result).not.toBe("0x");
-        });
-        it("HyperEVM RPC is reachable (eth_chainId)", async () => {
-            const res = await fetch(HYPERCORE_RPC, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({
-                    jsonrpc: "2.0", id: 1,
-                    method: "eth_chainId",
-                    params: [],
-                }),
-            });
-            const json = await res.json();
-            expect(json.result).toBeDefined();
-            // HyperEVM chain ID = 999 (0x3e7) or similar
-            const chainId = parseInt(json.result, 16);
-            expect(chainId).toBeGreaterThan(0);
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 14. CCTP V2 Iris Attestation API
-    // ══════════════════════════════════════════════════════════
-    describe("14. CCTP V2 Iris attestation API", () => {
-        it("V2 relay fee API responds for all source domains", async () => {
-            const routes = [
-                [5, 3], // solana → arbitrum
-                [3, 6], // arbitrum → base
-                [6, 5], // base → solana
-                [3, 19], // arbitrum → hyperliquid
-                [5, 19], // solana → hyperliquid
-            ];
-            for (const [src, dst] of routes) {
-                const res = await fetch(`https://iris-api.circle.com/v2/burn/USDC/fees/${src}/${dst}`);
-                expect(res.ok).toBe(true);
-                const data = await res.json();
-                expect(Array.isArray(data)).toBe(true);
-            }
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 15. SENDER-PAYS-ONLY — Core Invariant
-    // ══════════════════════════════════════════════════════════
-    //
-    // The fundamental rule: ALL bridge costs (protocol fee, relay fee,
-    // gas cost) are deducted from the sender's USDC amount.
-    // The recipient receives amountOut without paying anything.
-    //
-    // This is verified by checking that every quote has:
-    //   - gasIncluded === true (auto-relay, no manual dst TX needed)
-    //   - fee === amountIn - amountOut (fee is deducted from sent amount)
-    //   - amountOut > 0 and amountOut <= amountIn
-    //
-    // ══════════════════════════════════════════════════════════
-    describe("15. SENDER-PAYS-ONLY verification", () => {
-        // All 4 chains: arbitrum, base, solana, hyperliquid
-        // Standard routes (6 pairs among arb/base/sol)
-        const standardRoutes = [
-            ["arbitrum", "base"],
-            ["arbitrum", "solana"],
-            ["base", "arbitrum"],
-            ["base", "solana"],
-            ["solana", "arbitrum"],
-            ["solana", "base"],
-        ];
-        // HyperCore routes (deposit into + withdrawal from)
-        const hyperCoreDepositRoutes = [
-            ["arbitrum", "hyperliquid"],
-            ["base", "hyperliquid"],
-            ["solana", "hyperliquid"],
-        ];
-        const hyperCoreWithdrawRoutes = [
-            ["hyperliquid", "arbitrum"],
-            ["hyperliquid", "base"],
-            ["hyperliquid", "solana"],
-        ];
-        const ALL_ROUTES = [
-            ...standardRoutes,
-            ...hyperCoreDepositRoutes,
-            ...hyperCoreWithdrawRoutes,
-        ];
-        for (const [src, dst] of ALL_ROUTES) {
-            it(`${src} → ${dst}: fee deducted from sender's USDC`, async () => {
-                const amount = 100;
-                const quote = await getCctpQuote(src, dst, amount);
-                // 1. Fee is correctly calculated
-                expect(quote.fee).toBeGreaterThanOrEqual(0);
-                expect(Math.abs(quote.fee - (quote.amountIn - quote.amountOut))).toBeLessThan(0.001);
-                // 2. Recipient gets amountOut
-                expect(quote.amountOut).toBeGreaterThan(0);
-                expect(quote.amountOut).toBeLessThanOrEqual(amount);
-                // 3. Gas note present
-                expect(quote.gasNote).toBeDefined();
-                expect(quote.gasNote.length).toBeGreaterThan(0);
-            });
-        }
-        it("fast=true: all standard routes use auto-relay (gasIncluded=true)", async () => {
-            for (const [src, dst] of standardRoutes) {
-                const quote = await getCctpQuote(src, dst, 100, true);
-                expect(quote.gasIncluded).toBe(true);
-                const raw = quote.raw;
-                expect(Number(raw.maxFee)).toBeGreaterThan(0);
-                expect(raw.fast).toBe(true);
-            }
-        });
-        it("fast=false (default): forwarding routes have gasIncluded=true, Solana dst has gasIncluded=false", async () => {
-            for (const [src, dst] of standardRoutes) {
-                const quote = await getCctpQuote(src, dst, 100);
-                const raw = quote.raw;
-                expect(raw.fast).toBe(false);
-                // Forwarding available for all routes except →Solana
-                if (dst === "solana") {
-                    expect(quote.gasIncluded).toBe(false);
-                    expect(raw.forwarding).toBe(false);
-                }
-                else {
-                    expect(quote.gasIncluded).toBe(true);
-                    expect(raw.forwarding).toBe(true);
-                }
-            }
-        });
-        it("fast=true fees are higher than standard fees", async () => {
-            const standard = await getCctpQuote("arbitrum", "base", 1000, false);
-            const fast = await getCctpQuote("arbitrum", "base", 1000, true);
-            expect(fast.fee).toBeGreaterThan(standard.fee);
-            expect(fast.estimatedTime).toBeLessThan(standard.estimatedTime);
-        });
-        it("HyperCore deposits: CctpForwarder auto-deposits (always gasIncluded)", async () => {
-            for (const [src, dst] of hyperCoreDepositRoutes) {
-                const quote = await getCctpQuote(src, dst, 100);
-                expect(quote.gasIncluded).toBe(true);
-                expect(quote.gasNote).toContain("CctpForwarder");
-                const raw = quote.raw;
-                expect(raw.type).toBe("cctp-hypercore");
-                expect(Number(raw.maxFee)).toBeGreaterThan(0);
-            }
-        });
-        it("HyperCore withdrawals: HL handles forwarding (always gasIncluded)", async () => {
-            for (const [src, dst] of hyperCoreWithdrawRoutes) {
-                const quote = await getCctpQuote(src, dst, 100);
-                expect(quote.gasIncluded).toBe(true);
-                expect(quote.gasNote).toContain("HyperCore");
-                expect(quote.fee).toBe(0.20);
-                const raw = quote.raw;
-                expect(raw.type).toBe("cctp-hypercore-withdraw");
-            }
-        });
-        it("deBridge quotes include gas in fee (sender-pays)", async () => {
-            await wait(2000);
-            const quote = await getDebridgeQuote("arbitrum", "base", 100, evmAddress, evmAddress);
-            expect(quote.fee).toBeGreaterThan(0);
-            expect(Math.abs(quote.fee - (quote.amountIn - quote.amountOut))).toBeLessThan(0.001);
-            expect(quote.gasIncluded).toBe(true);
-        });
-        it("Relay quotes include gas in fee (solver pays dst gas)", async () => {
-            await wait(1000);
-            const quote = await getRelayQuote("arbitrum", "base", 100, evmAddress, evmAddress);
-            expect(quote.fee).toBeGreaterThanOrEqual(0);
-            expect(Math.abs(quote.fee - (quote.amountIn - quote.amountOut))).toBeLessThan(0.001);
-            expect(quote.gasIncluded).toBe(true);
-        });
-        it("getAllQuotes: fee math is correct for every provider", async () => {
-            await wait(2000);
-            const quotes = await getAllQuotes("arbitrum", "base", 500, evmAddress, evmAddress);
-            for (const q of quotes) {
-                expect(q.fee).toBeGreaterThanOrEqual(0);
-                expect(Math.abs(q.fee - (q.amountIn - q.amountOut))).toBeLessThan(0.01);
-            }
-        });
-    });
-    // ══════════════════════════════════════════════════════════
-    // 16. Complete 4-Chain Route Matrix
-    // ══════════════════════════════════════════════════════════
-    //
-    // Verify every possible directional pair among:
-    // arbitrum, base, solana, hyperliquid (12 pairs total)
-    //
-    // For each: valid quote, correct fee math, gasIncluded
-    // ══════════════════════════════════════════════════════════
-    describe("16. Complete 4-chain route matrix", () => {
-        const chains = ["arbitrum", "base", "solana", "hyperliquid"];
-        const amount = 250;
-        for (const src of chains) {
-            for (const dst of chains) {
-                if (src === dst)
-                    continue;
-                it(`[MATRIX] ${src} → ${dst}: valid quote with sender-pays`, async () => {
-                    const quote = await getCctpQuote(src, dst, amount);
-                    // Basic shape
-                    expect(quote.provider).toBe("cctp");
-                    expect(quote.srcChain).toBe(src);
-                    expect(quote.dstChain).toBe(dst);
-                    expect(quote.amountIn).toBe(amount);
-                    expect(quote.amountOut).toBeGreaterThan(0);
-                    expect(quote.amountOut).toBeLessThanOrEqual(amount);
-                    // Fee invariant: fee = amountIn - amountOut
-                    expect(Math.abs(quote.fee - (amount - quote.amountOut))).toBeLessThan(0.001);
-                    // gasIncluded: true for HyperCore, forwarding (EVM dst), and fast
-                    // Only →Solana in standard mode has gasIncluded=false (no forwarding)
-                    if (dst === "solana" && src !== "hyperliquid") {
-                        expect(quote.gasIncluded).toBe(false);
-                    }
-                    else {
-                        expect(quote.gasIncluded).toBe(true);
-                    }
-                    // Reasonable fee (< $5 for $250)
-                    expect(quote.fee).toBeLessThan(5);
-                    // Time estimate is positive
-                    expect(quote.estimatedTime).toBeGreaterThan(0);
-                });
-            }
-        }
-        it("[MATRIX] fee comparison: HyperCore deposit > standard CCTP > HyperCore withdrawal", async () => {
-            const standardFee = (await getCctpQuote("arbitrum", "base", 1000)).fee;
-            const depositFee = (await getCctpQuote("arbitrum", "hyperliquid", 1000)).fee;
-            const withdrawFee = (await getCctpQuote("hyperliquid", "arbitrum", 1000)).fee;
-            // HyperCore deposit has protocol + forwarding fee (> standard)
-            expect(depositFee).toBeGreaterThanOrEqual(standardFee);
-            // HyperCore withdrawal is fixed $0.20
-            expect(withdrawFee).toBe(0.20);
-        });
-        it("[MATRIX] ETA comparison: fast mode Solana routes are slower than fast EVM-only", async () => {
-            const evmToEvmFast = (await getCctpQuote("arbitrum", "base", 100, true)).estimatedTime;
-            const solToEvmFast = (await getCctpQuote("solana", "arbitrum", 100, true)).estimatedTime;
-            // Fast finality: Solana ~90s, EVM-only ~60s
-            expect(solToEvmFast).toBeGreaterThanOrEqual(evmToEvmFast);
-            // Standard finality: both positive
-            const evmToEvmStd = (await getCctpQuote("arbitrum", "base", 100)).estimatedTime;
-            const solToEvmStd = (await getCctpQuote("solana", "arbitrum", 100)).estimatedTime;
-            expect(evmToEvmStd).toBeGreaterThan(0);
-            expect(solToEvmStd).toBeGreaterThan(0);
-        });
-        it("[MATRIX] all standard relay fee APIs respond for 4-chain matrix", async () => {
-            // Verify Circle's fee API works for every domain pair we support
-            const domains = [
-                { chain: "arbitrum", domain: 3 },
-                { chain: "base", domain: 6 },
-                { chain: "solana", domain: 5 },
-                { chain: "hyperliquid", domain: 19 },
-            ];
-            const results = [];
-            for (const src of domains) {
-                for (const dst of domains) {
-                    if (src.chain === dst.chain)
-                        continue;
-                    const url = dst.domain === 19
-                        ? `https://iris-api.circle.com/v2/burn/USDC/fees/${src.domain}/${dst.domain}?forward=true&hyperCoreDeposit=true`
-                        : `https://iris-api.circle.com/v2/burn/USDC/fees/${src.domain}/${dst.domain}`;
-                    const res = await fetch(url);
-                    if (res.ok) {
-                        results.push(`${src.chain}→${dst.chain}: OK`);
-                    }
-                    else {
-                        results.push(`${src.chain}→${dst.chain}: ${res.status}`);
-                    }
-                }
-            }
-            // At minimum, all standard routes should work
-            const okCount = results.filter(r => r.includes("OK")).length;
-            expect(okCount).toBeGreaterThanOrEqual(6); // at least standard 6 pairs
-        });
-    });
-});