@persistenceone/bridgekitty 0.3.0

package/dist/utils/chains.js

@@ -0,0 +1,154 @@
+// Synthetic chain IDs for non-EVM chains.
+// These are high positive integers that won't collide with real EVM chain IDs
+// but satisfy the routing engine's requirement for positive integer chain IDs.
+export const PERSISTENCE_CHAIN_ID = 9999001;
+export const COSMOSHUB_CHAIN_ID = 9999002;
+// Solana uses its real chain ID (as recognized by deBridge)
+export const SOLANA_CHAIN_ID = 7565164;
+const CHAINS = [
+    { id: 1, name: "Ethereum", key: "ethereum" },
+    { id: 10, name: "Optimism", key: "optimism" },
+    { id: 25, name: "Cronos", key: "cronos" },
+    { id: 56, name: "BNB Chain", key: "bsc" },
+    { id: 100, name: "Gnosis", key: "gnosis" },
+    { id: 122, name: "Fuse", key: "fuse" },
+    { id: 130, name: "Unichain", key: "unichain" },
+    { id: 137, name: "Polygon", key: "polygon" },
+    { id: 143, name: "Monad", key: "monad" },
+    { id: 196, name: "X Layer", key: "xlayer" },
+    { id: 250, name: "Fantom", key: "fantom" },
+    { id: 252, name: "Fraxtal", key: "fraxtal" },
+    { id: 288, name: "Boba", key: "boba" },
+    { id: 324, name: "zkSync Era", key: "zksync" },
+    { id: 480, name: "World Chain", key: "world-chain" },
+    { id: 690, name: "Redstone", key: "redstone" },
+    { id: 1088, name: "Metis", key: "metis" },
+    { id: 1101, name: "Polygon zkEVM", key: "polygon-zkevm" },
+    { id: 1135, name: "Lisk", key: "lisk" },
+    { id: 1284, name: "Moonbeam", key: "moonbeam" },
+    { id: 1329, name: "Sei", key: "sei" },
+    { id: 1625, name: "Gravity", key: "gravity" },
+    { id: 1868, name: "Soneium", key: "soneium" },
+    { id: 1923, name: "Swellchain", key: "swellchain" },
+    { id: 2741, name: "Abstract", key: "abstract" },
+    { id: 5000, name: "Mantle", key: "mantle" },
+    { id: 7560, name: "Cyber", key: "cyber" },
+    { id: 7777777, name: "Zora", key: "zora" },
+    { id: 8453, name: "Base", key: "base" },
+    { id: 13371, name: "Immutable zkEVM", key: "immutable-zkevm" },
+    { id: 17000, name: "Holesky", key: "holesky" },
+    { id: 30, name: "Rootstock", key: "rootstock" },
+    { id: 33139, name: "ApeChain", key: "apechain" },
+    { id: 34443, name: "Mode", key: "mode" },
+    { id: 42161, name: "Arbitrum", key: "arbitrum" },
+    { id: 42170, name: "Arbitrum Nova", key: "arbitrum-nova" },
+    { id: 42220, name: "Celo", key: "celo" },
+    { id: 43114, name: "Avalanche", key: "avalanche" },
+    { id: 44787, name: "Celo Alfajores", key: "celo-alfajores" },
+    { id: 57073, name: "Ink", key: "ink" },
+    { id: 59144, name: "Linea", key: "linea" },
+    { id: 60808, name: "Bob", key: "bob" },
+    { id: 81457, name: "Blast", key: "blast" },
+    { id: 146, name: "Sonic", key: "sonic" },
+    { id: 167000, name: "Taiko", key: "taiko" },
+    { id: 2020, name: "Ronin", key: "ronin" },
+    { id: 204, name: "opBNB", key: "opbnb" },
+    { id: 534352, name: "Scroll", key: "scroll" },
+    { id: 7225878, name: "Saakuru", key: "saakuru" },
+    { id: 666666666, name: "Degen", key: "degen" },
+    { id: 80094, name: "Berachain", key: "berachain" },
+    { id: 50104, name: "Sophon", key: "sophon" },
+    { id: 37714555429, name: "Xai", key: "xai" },
+    { id: 14, name: "Flare", key: "flare" },
+    { id: 1516, name: "Story", key: "story" },
+    { id: 4801, name: "World Chain Testnet", key: "world-chain-testnet" },
+    { id: 8217, name: "Kaia", key: "kaia" },
+    { id: 1750, name: "Metal L2", key: "metal" },
+    { id: 2522, name: "Shadow", key: "shadow" },
+    { id: 98865, name: "Plume", key: "plume" },
+    { id: 21000000, name: "Corn", key: "corn" },
+    { id: 232, name: "Lens", key: "lens" },
+    { id: 999, name: "HyperEVM", key: "hyperevm" },
+    { id: 360, name: "Shape", key: "shape" },
+    { id: 1514, name: "Hemi", key: "hemi" },
+    { id: 810180, name: "zkLink Nova", key: "zklink-nova" },
+    { id: 4326, name: "MegaETH", key: "megaeth" },
+    { id: 9745, name: "Plasma", key: "plasma" },
+    // Cosmos chains (synthetic IDs — mapped to real chain ID strings by Squid backend)
+    { id: PERSISTENCE_CHAIN_ID, name: "Persistence", key: "persistence" },
+    { id: COSMOSHUB_CHAIN_ID, name: "Cosmos Hub", key: "cosmoshub" },
+    // Solana (uses real chain ID as recognized by deBridge)
+    { id: SOLANA_CHAIN_ID, name: "Solana", key: "solana" },
+];
+// Backend-specific chain ID overrides (reserved for future non-EVM chain support)
+const CHAIN_ID_OVERRIDES = {};
+export function getBackendChainId(backendName, chainId) {
+    const key = backendName.toLowerCase().replace(/\s*\(.*\)/, "");
+    return CHAIN_ID_OVERRIDES[key]?.[chainId] ?? chainId;
+}
+// Mapping from chain key → real Cosmos chain ID string (for Squid Router / IBC)
+export const COSMOS_CHAIN_IDS = {
+    persistence: "core-1",
+    cosmoshub: "cosmoshub-4",
+};
+// Reverse mapping: synthetic numeric ID → Cosmos chain ID string (as used by Squid Router)
+export const SYNTHETIC_TO_COSMOS = {
+    [PERSISTENCE_CHAIN_ID]: "core-1",
+    [COSMOSHUB_CHAIN_ID]: "cosmoshub-4",
+};
+export function resolveChainId(input) {
+    // Try numeric: only accept chain IDs that are in the known CHAINS array (V3-LOW-003)
+    const num = Number(input);
+    if (!isNaN(num) && Number.isInteger(num) && num > 0) {
+        const known = CHAINS.find((c) => c.id === num);
+        return known ? known.id : null;
+    }
+    // Also accept Cosmos chain ID strings directly (e.g. "core-1", "cosmoshub-4")
+    const lower = input.toLowerCase().trim();
+    for (const [syntheticId, cosmosId] of Object.entries(SYNTHETIC_TO_COSMOS)) {
+        if (lower === cosmosId || lower === cosmosId.replace(/-/g, "")) {
+            return Number(syntheticId);
+        }
+    }
+    // Also accept common aliases for Cosmos chains
+    if (lower === "persistence-core-1" || lower === "persistencecore1") {
+        return PERSISTENCE_CHAIN_ID;
+    }
+    if (lower === "cosmoshub4") {
+        return COSMOSHUB_CHAIN_ID;
+    }
+    // Solana aliases
+    if (lower === "sol" || lower === "solana") {
+        return SOLANA_CHAIN_ID;
+    }
+    const match = CHAINS.find((c) => c.key === lower || c.name.toLowerCase() === lower);
+    return match?.id ?? null;
+}
+/** Check if a chain key or ID refers to Solana */
+export function isSolanaChain(chainKeyOrId) {
+    if (typeof chainKeyOrId === "number") {
+        return chainKeyOrId === SOLANA_CHAIN_ID;
+    }
+    return chainKeyOrId.toLowerCase() === "solana" || chainKeyOrId.toLowerCase() === "sol";
+}
+/** Check if a chain key or ID refers to a Cosmos chain */
+export function isCosmosChain(chainKeyOrId) {
+    if (typeof chainKeyOrId === "number") {
+        return SYNTHETIC_TO_COSMOS[chainKeyOrId] !== undefined;
+    }
+    return COSMOS_CHAIN_IDS[chainKeyOrId.toLowerCase()] !== undefined;
+}
+/** Get the Cosmos chain ID string for Squid Router from a synthetic numeric ID */
+export function getCosmosChainIdFromSynthetic(syntheticId) {
+    return SYNTHETIC_TO_COSMOS[syntheticId] ?? null;
+}
+/** Get the Cosmos chain ID string from a chain key */
+export function getCosmosChainId(key) {
+    return COSMOS_CHAIN_IDS[key.toLowerCase()] ?? null;
+}
+export function getChainName(id) {
+    return CHAINS.find((c) => c.id === id)?.name ?? `Chain ${id}`;
+}
+export function getAllChains() {
+    return CHAINS;
+}

package/dist/utils/circuit-breaker.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Circuit breaker for backend failure management.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Backend is failing, skip requests for a cooldown period
+ * - HALF_OPEN: Testing with a single request after cooldown
+ *
+ * Transitions:
+ * - CLOSED → OPEN: After `failureThreshold` failures within `failureWindowMs`
+ * - OPEN → HALF_OPEN: After `cooldownMs` elapsed
+ * - HALF_OPEN → CLOSED: On success
+ * - HALF_OPEN → OPEN: On failure (with extended cooldown)
+ */
+export type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+interface CircuitBreakerConfig {
+    /** Number of failures before opening the circuit (default: 3) */
+    failureThreshold?: number;
+    /** Time window for counting failures in ms (default: 300_000 = 5 min) */
+    failureWindowMs?: number;
+    /** How long to wait before testing again in ms (default: 30_000 = 30s) */
+    cooldownMs?: number;
+    /** Extended cooldown after HALF_OPEN failure in ms (default: 60_000 = 60s) */
+    extendedCooldownMs?: number;
+}
+export declare class CircuitBreaker {
+    private circuits;
+    private halfOpenLocks;
+    private config;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Check if a backend is allowed to receive requests.
+     * Returns true if the backend should be called, false if it should be skipped.
+     */
+    isAllowed(backendName: string): boolean;
+    /**
+     * Report a successful request for a backend.
+     * Gradual recovery: removes the oldest failure instead of clearing all at once.
+     * Full reset only happens from HALF_OPEN state (successful probe).
+     */
+    recordSuccess(backendName: string): void;
+    /**
+     * Report a failed request for a backend.
+     * May transition to OPEN if threshold is exceeded.
+     */
+    recordFailure(backendName: string): void;
+    /**
+     * Get the current state of a backend's circuit.
+     */
+    getState(backendName: string): CircuitState;
+    /**
+     * Get a summary of all circuit states (for debugging/monitoring).
+     */
+    getAll(): Record<string, CircuitState>;
+    /**
+     * Reset a specific backend's circuit (for testing/admin).
+     */
+    reset(backendName: string): void;
+    /**
+     * Reset all circuits.
+     */
+    resetAll(): void;
+}
+export {};

package/dist/utils/circuit-breaker.js

@@ -0,0 +1,160 @@
+/**
+ * Circuit breaker for backend failure management.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Backend is failing, skip requests for a cooldown period
+ * - HALF_OPEN: Testing with a single request after cooldown
+ *
+ * Transitions:
+ * - CLOSED → OPEN: After `failureThreshold` failures within `failureWindowMs`
+ * - OPEN → HALF_OPEN: After `cooldownMs` elapsed
+ * - HALF_OPEN → CLOSED: On success
+ * - HALF_OPEN → OPEN: On failure (with extended cooldown)
+ */
+const DEFAULT_CONFIG = {
+    failureThreshold: 3,
+    failureWindowMs: 300_000,
+    cooldownMs: 30_000,
+    extendedCooldownMs: 60_000,
+};
+export class CircuitBreaker {
+    circuits = new Map();
+    halfOpenLocks = new Set();
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Check if a backend is allowed to receive requests.
+     * Returns true if the backend should be called, false if it should be skipped.
+     */
+    isAllowed(backendName) {
+        const circuit = this.circuits.get(backendName);
+        if (!circuit)
+            return true; // No circuit = never failed = allowed
+        const now = Date.now();
+        switch (circuit.state) {
+            case "CLOSED":
+                return true;
+            case "OPEN": {
+                // Check if cooldown has elapsed → transition to HALF_OPEN
+                if (now - circuit.openedAt >= circuit.cooldownMs) {
+                    circuit.state = "HALF_OPEN";
+                    // Lock so only the first caller gets through (V3-LOW-001)
+                    if (this.halfOpenLocks.has(backendName))
+                        return false;
+                    this.halfOpenLocks.add(backendName);
+                    return true; // Allow one test request
+                }
+                return false; // Still in cooldown
+            }
+            case "HALF_OPEN":
+                // Only one concurrent request allowed in HALF_OPEN (V3-LOW-001)
+                if (this.halfOpenLocks.has(backendName))
+                    return false;
+                this.halfOpenLocks.add(backendName);
+                return true;
+            default:
+                return true;
+        }
+    }
+    /**
+     * Report a successful request for a backend.
+     * Gradual recovery: removes the oldest failure instead of clearing all at once.
+     * Full reset only happens from HALF_OPEN state (successful probe).
+     */
+    recordSuccess(backendName) {
+        const circuit = this.circuits.get(backendName);
+        if (!circuit)
+            return;
+        if (circuit.state === "HALF_OPEN") {
+            // Successful probe — fully reset
+            this.halfOpenLocks.delete(backendName);
+            console.error(`[circuit-breaker] ${backendName}: HALF_OPEN → CLOSED (probe succeeded)`);
+            circuit.state = "CLOSED";
+            circuit.failures = [];
+            circuit.cooldownMs = this.config.cooldownMs;
+        }
+        else if (circuit.state === "CLOSED" && circuit.failures.length > 0) {
+            // Gradual recovery: remove oldest failure on each success
+            circuit.failures.shift();
+        }
+    }
+    /**
+     * Report a failed request for a backend.
+     * May transition to OPEN if threshold is exceeded.
+     */
+    recordFailure(backendName) {
+        const now = Date.now();
+        let circuit = this.circuits.get(backendName);
+        if (!circuit) {
+            circuit = {
+                state: "CLOSED",
+                failures: [],
+                openedAt: 0,
+                cooldownMs: this.config.cooldownMs,
+            };
+            this.circuits.set(backendName, circuit);
+        }
+        if (circuit.state === "HALF_OPEN") {
+            // Test request failed → back to OPEN with extended cooldown
+            this.halfOpenLocks.delete(backendName);
+            circuit.state = "OPEN";
+            circuit.openedAt = now;
+            circuit.cooldownMs = this.config.extendedCooldownMs;
+            console.error(`[circuit-breaker] ${backendName}: HALF_OPEN → OPEN (probe failed, extended cooldown ${this.config.extendedCooldownMs}ms)`);
+            return;
+        }
+        // Add failure timestamp (prune old failures outside the window)
+        circuit.failures = circuit.failures
+            .filter((t) => now - t < this.config.failureWindowMs)
+            .concat(now);
+        // Check if threshold exceeded
+        if (circuit.failures.length >= this.config.failureThreshold) {
+            circuit.state = "OPEN";
+            circuit.openedAt = now;
+            circuit.cooldownMs = this.config.cooldownMs;
+            console.error(`[circuit-breaker] ${backendName}: CLOSED → OPEN (${circuit.failures.length} failures in ${this.config.failureWindowMs}ms window, cooldown ${this.config.cooldownMs}ms)`);
+        }
+    }
+    /**
+     * Get the current state of a backend's circuit.
+     */
+    getState(backendName) {
+        const circuit = this.circuits.get(backendName);
+        if (!circuit)
+            return "CLOSED";
+        // Check for OPEN → HALF_OPEN transition
+        if (circuit.state === "OPEN") {
+            if (Date.now() - circuit.openedAt >= circuit.cooldownMs) {
+                circuit.state = "HALF_OPEN";
+            }
+        }
+        return circuit.state;
+    }
+    /**
+     * Get a summary of all circuit states (for debugging/monitoring).
+     */
+    getAll() {
+        const result = {};
+        for (const [name] of this.circuits) {
+            result[name] = this.getState(name);
+        }
+        return result;
+    }
+    /**
+     * Reset a specific backend's circuit (for testing/admin).
+     */
+    reset(backendName) {
+        this.circuits.delete(backendName);
+        this.halfOpenLocks.delete(backendName);
+    }
+    /**
+     * Reset all circuits.
+     */
+    resetAll() {
+        this.circuits.clear();
+        this.halfOpenLocks.clear();
+    }
+}

package/dist/utils/evm.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared EVM utilities used across multiple backends.
+ */
+/**
+ * Build ERC20 approve(address spender, uint256 amount) calldata.
+ */
+export declare function buildApproveData(spender: string, amount: string): string;
+/**
+ * Check if an address is the native token (zero address).
+ */
+export declare const NATIVE_ADDRESS = "0x0000000000000000000000000000000000000000";
+export declare function isNativeToken(address: string): boolean;
+/**
+ * Validate an EVM hex address (0x + 40 hex chars).
+ * Returns { valid, warning? } — accepts all valid hex addresses but warns
+ * on mixed-case addresses that fail EIP-55 checksum validation (MEDIUM-002).
+ */
+export declare function isValidEvmAddress(address: string): boolean;

package/dist/utils/evm.js

@@ -0,0 +1,46 @@
+/**
+ * Shared EVM utilities used across multiple backends.
+ */
+import { getAddress } from "ethers";
+/**
+ * Build ERC20 approve(address spender, uint256 amount) calldata.
+ */
+export function buildApproveData(spender, amount) {
+    // ERC20 approve(address,uint256) selector = 0x095ea7b3
+    const spenderPadded = spender.toLowerCase().replace("0x", "").padStart(64, "0");
+    const amountHex = BigInt(amount).toString(16).padStart(64, "0");
+    return `0x095ea7b3${spenderPadded}${amountHex}`;
+}
+/**
+ * Check if an address is the native token (zero address).
+ */
+export const NATIVE_ADDRESS = "0x0000000000000000000000000000000000000000";
+export function isNativeToken(address) {
+    return (address === NATIVE_ADDRESS ||
+        address === "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" ||
+        address.toLowerCase() === "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee");
+}
+/**
+ * Validate an EVM hex address (0x + 40 hex chars).
+ * Returns { valid, warning? } — accepts all valid hex addresses but warns
+ * on mixed-case addresses that fail EIP-55 checksum validation (MEDIUM-002).
+ */
+export function isValidEvmAddress(address) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address))
+        return false;
+    // If all-lowercase or all-uppercase (after 0x), no checksum to validate
+    const body = address.slice(2);
+    if (body === body.toLowerCase() || body === body.toUpperCase())
+        return true;
+    // Mixed-case: validate EIP-55 checksum using ethers
+    try {
+        const checksummed = getAddress(address.toLowerCase());
+        if (checksummed !== address) {
+            console.warn(`[evm] MEDIUM-002: Address ${address} has invalid mixed-case (expected EIP-55: ${checksummed}). Accepting but flagging.`);
+        }
+    }
+    catch {
+        console.warn(`[evm] MEDIUM-002: Could not verify EIP-55 checksum for ${address}. Accepting anyway.`);
+    }
+    return true;
+}

package/dist/utils/fill-detector.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Multi-signal fill detector for cross-chain bridge fills.
+ *
+ * Public RPCs aggressively cache ALL RPC responses (eth_call, eth_getLogs)
+ * for 30-120s server-side. WebSocket transport does NOT bypass this.
+ *
+ * This module provides five detection methods:
+ *
+ * 1. **eth_subscribe("logs")** — push-based real-time subscription via raw
+ *    WebSocket. The server pushes matching logs as new blocks are mined.
+ *    NOT cached because each block is novel. Detects in 3-15s.
+ *    Uses BROAD filter (token + Transfer topic only) with client-side
+ *    recipient filtering, because some RPCs don't support topic[2] filtering
+ *    in subscriptions. ONLY uses drpc (publicnode silently drops log events).
+ *
+ * 2. **newHeads + targeted getLogs** — subscribe to new block headers via WS,
+ *    then do a getLogs for just that block number. Bypasses RPC caching
+ *    because we query a specific (newly mined) block.
+ *
+ * 3. HTTP getLogs — rotated across RPCs, 30-120s (server-side cached)
+ * 4. HTTP balance check — rotated across RPCs, 30-120s (server-side cached)
+ * 5. Status API — Persistence backend (often broken)
+ *
+ * IMPORTANT: Create the FillWatcher BEFORE the initiate transaction to
+ * allow time for WebSocket connection + subscription establishment.
+ */
+export interface FillWatcher {
+    /** Non-blocking check: has the fill been detected? */
+    isDetected: () => boolean;
+    /** How many WS connections are alive? */
+    connectedCount: () => number;
+    /** Clean up all WebSocket connections. Must be called when done. */
+    cleanup: () => void;
+}
+/**
+ * Create a push-based fill watcher using raw WebSocket eth_subscribe.
+ *
+ * Two strategies run in parallel:
+ * A) eth_subscribe("logs") on drpc — direct Transfer event push (fastest)
+ * B) eth_subscribe("newHeads") — on each new block, do a targeted
+ *    getLogs(blockNum, blockNum) which bypasses RPC caching
+ *
+ * Call BEFORE signAndExecute to give connections time to establish (~2-5s).
+ * Check isDetected() in the polling loop — returns true as soon as a
+ * matching Transfer event is found by ANY method.
+ */
+export declare function createFillWatcher(chainId: number, tokenAddress: string, walletAddress: string, onDetected?: () => void): FillWatcher;
+export interface TransferEventResult {
+    found: boolean;
+    latestBlock?: number;
+}
+export interface BalanceChangeResult {
+    changed: boolean;
+    newBalance: bigint;
+}
+/**
+ * Check for fill via ERC20 Transfer event logs over HTTP.
+ * Uses fresh providers rotated across RPCs. Subject to server-side
+ * caching (30-120s), kept as a fallback for when WS subscription fails.
+ */
+export declare function checkTransferEvents(chainId: number, tokenAddress: string, walletAddress: string, fromBlock: number, rpcIndex: number): Promise<TransferEventResult>;
+/**
+ * Check for fill via balance change using a fresh (uncached) provider.
+ * Each call cycles through a different RPC via rpcIndex.
+ */
+export declare function checkBalanceChange(chainId: number, tokenAddress: string, walletAddress: string, preBalance: bigint, rpcIndex: number): Promise<BalanceChangeResult>;
+/**
+ * Get the current block number on a chain using a fresh provider.
+ */
+export declare function getCurrentBlockNumber(chainId: number): Promise<number>;