@pushchain/core 5.1.5-alpha.0 → 5.1.5

package/src/lib/orchestrator/internals/outbound-sync.js

@@ -6,10 +6,11 @@
  * Extracted from Orchestrator.waitForOutboundTx / waitForAllOutboundTxsV2.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OUTBOUND_MAX_TIMEOUT_MS = exports.OUTBOUND_POLL_INTERVAL_MS = exports.OUTBOUND_INITIAL_WAIT_MS = void 0;
+exports.OutboundFailedError = exports.OutboundTimeoutError = exports.INBOUND_INITIAL_WAIT_MS = exports.INBOUND_MAX_TIMEOUT_MS = exports.OUTBOUND_MAX_TIMEOUT_MS = exports.OUTBOUND_POLL_INTERVAL_MS = exports.OUTBOUND_INITIAL_WAIT_MS = void 0;
 exports.waitForOutboundTx = waitForOutboundTx;
 exports.waitForAllOutboundTxsV2 = waitForAllOutboundTxsV2;
 const tslib_1 = require("tslib");
+const viem_1 = require("viem");
 const bs58_1 = require("../../internal/bs58");
 const chain_1 = require("../../constants/chain");
 const enums_1 = require("../../constants/enums");
@@ -25,11 +26,107 @@ const outbound_tracker_1 = require("./outbound-tracker");
 exports.OUTBOUND_INITIAL_WAIT_MS = 20000; // 20s
 /** Interval between consecutive polls (ms). */
 exports.OUTBOUND_POLL_INTERVAL_MS = 5000; // 5s
-/** Maximum total timeout for the polling loop (ms). */
+/** Maximum total timeout for the outbound polling loop (ms). */
 exports.OUTBOUND_MAX_TIMEOUT_MS = 180000; // 180s (3 min)
+/** Maximum total timeout for the R3 inbound round-trip polling loop (ms). */
+exports.INBOUND_MAX_TIMEOUT_MS = 300000; // 300s (5 min) — covers R3 inbound latency on testnet
+/** Initial wait before the first inbound poll (ms). Set to 0 — the outbound just completed, so the indexer may already have the child UTX. */
+exports.INBOUND_INITIAL_WAIT_MS = 0;
+// ============================================================================
+// Typed errors
+// ============================================================================
+/**
+ * Thrown by `waitForOutboundTx` when the polling loop exceeds the configured
+ * timeout without observing an external tx hash. Callers can `instanceof`
+ * check to distinguish between timeout (→ 299-03) and terminal failure
+ * (→ 299-02) without resorting to error-message prefix matching.
+ */
+class OutboundTimeoutError extends Error {
+    constructor(pushChainTxHash, elapsedMs, timeoutMs) {
+        super(`Timeout waiting for outbound transaction. Push Chain TX: ${pushChainTxHash}. Timeout: ${timeoutMs}ms. The relay may still be processing.`);
+        this.code = 'OUTBOUND_TIMEOUT';
+        this.name = 'OutboundTimeoutError';
+        this.pushChainTxHash = pushChainTxHash;
+        this.elapsedMs = elapsedMs;
+    }
+}
+exports.OutboundTimeoutError = OutboundTimeoutError;
+/**
+ * Thrown by `waitForOutboundTx` when the universal tx reaches a terminal
+ * failure state or an outbound leg reports REVERTED status. Distinguishes
+ * a *failure* (→ 299-02) from a *timeout* (→ 299-03).
+ */
+class OutboundFailedError extends Error {
+    constructor(message, pushChainTxHash, destinationChain, externalTxHash) {
+        super(message);
+        this.code = 'OUTBOUND_FAILED';
+        this.name = 'OutboundFailedError';
+        this.pushChainTxHash = pushChainTxHash;
+        this.destinationChain = destinationChain;
+        this.externalTxHash = externalTxHash;
+    }
+}
+exports.OutboundFailedError = OutboundFailedError;
 // ============================================================================
 // waitForOutboundTx
 // ============================================================================
+/**
+ * Source-chain RPC tiebreaker.
+ *
+ * Cosmos sometimes populates `observedTx.txHash` while the relayer is still
+ * voting on the outboundStatus update. The Push indexer can stay at
+ * UNSPECIFIED for the full 180s budget even though the destination tx mined
+ * minutes earlier. To avoid those false timeouts we ask the destination
+ * chain's own RPC: if it has a confirmed receipt with status=success, we
+ * trust it and return FOUND; if status=reverted, we throw OutboundFailedError
+ * (preserves the silent-success bug fix); if no receipt yet or RPC failure,
+ * we keep polling.
+ *
+ * EVM-only — SVM tiebreaker would need a separate signature lookup path.
+ */
+function verifyExternalEvmReceipt(ctx, destinationChain, externalTxHash) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const chainInfo = chain_1.CHAIN_INFO[destinationChain];
+        if (!chainInfo || chainInfo.vm !== enums_1.VM.EVM) {
+            return 'unsupported';
+        }
+        // Guard against unit-test contexts that don't pass a real rpcUrls map —
+        // we'd otherwise hit live testnet RPC inside Jest.
+        if (!ctx.rpcUrls)
+            return 'unsupported';
+        const rpcUrls = ((_a = ctx.rpcUrls) === null || _a === void 0 ? void 0 : _a[destinationChain]) && ctx.rpcUrls[destinationChain].length > 0
+            ? ctx.rpcUrls[destinationChain]
+            : chainInfo.defaultRPC;
+        if (!(rpcUrls === null || rpcUrls === void 0 ? void 0 : rpcUrls.length))
+            return 'unsupported';
+        try {
+            const client = (0, viem_1.createPublicClient)({
+                transport: (0, viem_1.fallback)(rpcUrls.map((url) => (0, viem_1.http)(url))),
+            });
+            const receipt = yield client.getTransactionReceipt({
+                hash: externalTxHash,
+            });
+            if (!receipt)
+                return 'pending';
+            if (receipt.status === 'success')
+                return 'success';
+            if (receipt.status === 'reverted')
+                return 'reverted';
+            return 'pending';
+        }
+        catch (err) {
+            // viem throws TransactionReceiptNotFoundError when the tx isn't mined
+            // yet — treat as 'pending' rather than 'unsupported' so we keep polling.
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/not found|TransactionReceiptNotFound|could not be found/i.test(msg)) {
+                return 'pending';
+            }
+            (0, context_1.printLog)(ctx, `[verifyExternalEvmReceipt] RPC error for ${destinationChain} tx ${externalTxHash}: ${msg}`);
+            return 'pending';
+        }
+    });
+}
 /**
  * Wait for outbound transaction to complete and return external chain details.
  * @internal Used by .wait() for outbound routes - not part of public API.
@@ -45,7 +142,7 @@ exports.OUTBOUND_MAX_TIMEOUT_MS = 180000; // 180s (3 min)
  */
 function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
     return tslib_1.__awaiter(this, arguments, void 0, function* (ctx, pushChainTxHash, options = {}) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
         const { initialWaitMs = exports.OUTBOUND_INITIAL_WAIT_MS, pollingIntervalMs = exports.OUTBOUND_POLL_INTERVAL_MS, timeout = exports.OUTBOUND_MAX_TIMEOUT_MS, progressHook, _resolvedSubTxId, _expectedDestinationChain, } = options;
         // Terminal failure states — fail fast instead of polling until timeout
         const TERMINAL_FAILURE_STATES = new Set([
@@ -56,8 +153,21 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
         const startTime = Date.now();
         (0, context_1.printLog)(ctx, `[waitForOutboundTx] Starting | txHash: ${pushChainTxHash} | initialWait: ${initialWaitMs}ms | pollInterval: ${pollingIntervalMs}ms | timeout: ${timeout}ms`);
         progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'waiting', elapsed: 0 });
-        (0, context_1.printLog)(ctx, `[waitForOutboundTx] Initial wait of ${initialWaitMs}ms...`);
-        yield new Promise((resolve) => setTimeout(resolve, initialWaitMs));
+        // Clamp the initial wait to the configured timeout so a short per-call
+        // `outboundTimeoutMs` (e.g. from `tx.wait({ outboundTimeoutMs })`) isn't
+        // blocked by the default 20s settle-time. Mirrors the equivalent
+        // Math.min(initialWaitMs, timeout) clamp in inbound-tracker.ts.
+        const effectiveInitialWaitMs = Math.min(initialWaitMs, timeout);
+        (0, context_1.printLog)(ctx, `[waitForOutboundTx] Initial wait of ${effectiveInitialWaitMs}ms (configured: ${initialWaitMs}ms, clamped to timeout ${timeout}ms)...`);
+        yield new Promise((resolve) => setTimeout(resolve, effectiveInitialWaitMs));
+        // Fast-exit: if the clamped initial wait already consumed the full budget,
+        // skip the poll loop and go straight to the timeout throw below.
+        if (Date.now() - startTime >= timeout) {
+            const elapsedMs = Date.now() - startTime;
+            (0, context_1.printLog)(ctx, `[waitForOutboundTx] Timeout reached during initial wait (elapsed: ${elapsedMs}ms / ${timeout}ms)`);
+            progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'timeout', elapsed: elapsedMs });
+            throw new OutboundTimeoutError(pushChainTxHash, elapsedMs, timeout);
+        }
         // Start polling
         (0, context_1.printLog)(ctx, `[waitForOutboundTx] Initial wait done. Starting polling. Elapsed: ${Date.now() - startTime}ms`);
         progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'polling', elapsed: Date.now() - startTime });
@@ -90,7 +200,7 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
                 if (TERMINAL_FAILURE_STATES.has(statusNum)) {
                     (0, context_1.printLog)(ctx, `[waitForOutboundTx] Terminal failure state: ${statusName}`);
                     progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'failed', elapsed: Date.now() - startTime });
-                    throw new Error(`Outbound transaction failed with status ${statusName}. Push Chain TX: ${pushChainTxHash}.`);
+                    throw new OutboundFailedError(`Outbound transaction failed with status ${statusName}. Push Chain TX: ${pushChainTxHash}.`, pushChainTxHash);
                 }
                 // Iterate V2 outbound array
                 for (const ob of outbounds) {
@@ -98,18 +208,43 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
                     if (ob.outboundStatus === types_2.OutboundStatus.REVERTED) {
                         (0, context_1.printLog)(ctx, `[waitForOutboundTx] Outbound to ${ob.destinationChain} REVERTED`);
                         progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'failed', elapsed: Date.now() - startTime });
-                        throw new Error(`Outbound to ${ob.destinationChain} reverted: ${((_h = ob.observedTx) === null || _h === void 0 ? void 0 : _h.errorMsg) || 'Unknown'}. Push Chain TX: ${pushChainTxHash}.`);
+                        throw new OutboundFailedError(`Outbound to ${ob.destinationChain} reverted: ${((_h = ob.observedTx) === null || _h === void 0 ? void 0 : _h.errorMsg) || 'Unknown'}. Push Chain TX: ${pushChainTxHash}.`, pushChainTxHash, ob.destinationChain, (_j = ob.observedTx) === null || _j === void 0 ? void 0 : _j.txHash);
                     }
-                    if ((_j = ob.observedTx) === null || _j === void 0 ? void 0 : _j.txHash) {
+                    // FOUND gating logic:
+                    //   1. Primary path — cosmos has transitioned to OBSERVED (the
+                    //      authoritative success signal from the indexer).
+                    //   2. Tiebreaker — cosmos has the txHash but outboundStatus is
+                    //      still UNSPECIFIED/PENDING (indexer lag). We ask the
+                    //      destination chain's own RPC: if its receipt is success,
+                    //      treat as FOUND; if reverted, throw OutboundFailedError.
+                    //      Pending receipts keep polling.
+                    if ((_k = ob.observedTx) === null || _k === void 0 ? void 0 : _k.txHash) {
                         // If a destination chain filter is set, skip outbound entries that don't match
                         if (_expectedDestinationChain && ob.destinationChain !== _expectedDestinationChain) {
                             (0, context_1.printLog)(ctx, `[waitForOutboundTx] Poll #${pollCount} | outbound chain '${ob.destinationChain}' does not match expected '${_expectedDestinationChain}', skipping`);
                             continue;
                         }
                         const chain = (0, helpers_1.chainFromNamespace)(ob.destinationChain);
-                        if (chain) {
-                            const explorerBaseUrl = (_k = chain_1.CHAIN_INFO[chain]) === null || _k === void 0 ? void 0 : _k.explorerUrl;
-                            const isSvm = ((_l = chain_1.CHAIN_INFO[chain]) === null || _l === void 0 ? void 0 : _l.vm) === enums_1.VM.SVM;
+                        if (!chain)
+                            continue;
+                        const isCosmosObserved = ob.outboundStatus === types_2.OutboundStatus.OBSERVED;
+                        if (!isCosmosObserved) {
+                            // Tiebreaker: ask the destination-chain RPC directly.
+                            const verdict = yield verifyExternalEvmReceipt(ctx, chain, ob.observedTx.txHash);
+                            if (verdict === 'reverted') {
+                                (0, context_1.printLog)(ctx, `[waitForOutboundTx] Source-chain RPC reports REVERTED for ${ob.destinationChain} tx ${ob.observedTx.txHash} (cosmos still ${(_l = types_1.UniversalTxStatus[statusNum]) !== null && _l !== void 0 ? _l : statusNum})`);
+                                progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'failed', elapsed: Date.now() - startTime });
+                                throw new OutboundFailedError(`Outbound to ${ob.destinationChain} reverted on source-chain RPC (tx: ${ob.observedTx.txHash}). Push Chain TX: ${pushChainTxHash}.`, pushChainTxHash, ob.destinationChain, ob.observedTx.txHash);
+                            }
+                            if (verdict !== 'success') {
+                                // 'pending' or 'unsupported' — keep polling, cosmos will catch up.
+                                continue;
+                            }
+                            (0, context_1.printLog)(ctx, `[waitForOutboundTx] Source-chain RPC tiebreaker: ${chain} tx ${ob.observedTx.txHash} succeeded; treating as FOUND despite cosmos status ${(_m = types_1.UniversalTxStatus[statusNum]) !== null && _m !== void 0 ? _m : statusNum}`);
+                        }
+                        {
+                            const explorerBaseUrl = (_o = chain_1.CHAIN_INFO[chain]) === null || _o === void 0 ? void 0 : _o.explorerUrl;
+                            const isSvm = ((_p = chain_1.CHAIN_INFO[chain]) === null || _p === void 0 ? void 0 : _p.vm) === enums_1.VM.SVM;
                             // For SVM chains, convert hex txHash to base58 and append cluster param
                             let displayTxHash = ob.observedTx.txHash;
                             let explorerUrl = '';
@@ -139,8 +274,10 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
                 }
             }
             catch (error) {
-                // Re-throw terminal failure and reverted errors
-                if (error instanceof Error && (error.message.includes('Outbound transaction failed') || error.message.includes('reverted'))) {
+                // Re-throw typed terminal failure so the caller can classify it as
+                // 299-02. Transient errors (RPC hiccups, deserialization) are logged
+                // and the loop continues polling until timeout.
+                if (error instanceof OutboundFailedError) {
                     throw error;
                 }
                 (0, context_1.printLog)(ctx, `[waitForOutboundTx] Poll #${pollCount} ERROR: ${error instanceof Error ? error.message : String(error)}`);
@@ -149,10 +286,10 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
             // Wait before next poll
             yield new Promise((resolve) => setTimeout(resolve, pollingIntervalMs));
         }
-        (0, context_1.printLog)(ctx, `[waitForOutboundTx] TIMEOUT after ${pollCount} polls | elapsed: ${Date.now() - startTime}ms`);
-        progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'timeout', elapsed: Date.now() - startTime });
-        throw new Error(`Timeout waiting for outbound transaction. Push Chain TX: ${pushChainTxHash}. ` +
-            `Timeout: ${timeout}ms. The relay may still be processing.`);
+        const elapsedMs = Date.now() - startTime;
+        (0, context_1.printLog)(ctx, `[waitForOutboundTx] TIMEOUT after ${pollCount} polls | elapsed: ${elapsedMs}ms`);
+        progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'timeout', elapsed: elapsedMs });
+        throw new OutboundTimeoutError(pushChainTxHash, elapsedMs, timeout);
     });
 }
 // ============================================================================

package/src/lib/orchestrator/internals/pc-usd-oracle.d.ts

@@ -0,0 +1,28 @@
+import { CHAIN } from '../../constants/enums';
+import type { OrchestratorContext } from './context';
+type StableKey = 'USDT_ETH' | 'USDT_ARB' | 'USDT_BASE' | 'USDT_BNB' | 'USDT_SOL';
+/**
+ * Get $PC/USD price (8 decimals) for the given origin chain's route.
+ * Returns 0 on any failure — caller is expected to fall back to
+ * pushClient.pushToUSDC (the hardcoded $0.10 rate).
+ */
+export declare function getPcUsdPrice(ctx: OrchestratorContext, originChain: CHAIN): Promise<bigint>;
+/**
+ * Convert a nPUSH (18-dec) amount to USD (8-dec) using the per-route oracle.
+ * Falls back to the fixed pushToUSDC rate if the oracle returns 0.
+ */
+export declare function pcToUsd(ctx: OrchestratorContext, pcAmount: bigint, originChain: CHAIN): Promise<bigint>;
+/**
+ * Convert a USD (8-dec) amount to nPUSH (18-dec) using the per-route oracle.
+ * Falls back to the fixed usdcToPush rate if the oracle returns 0.
+ */
+export declare function usdToPc(ctx: OrchestratorContext, usdAmount: bigint, originChain: CHAIN): Promise<bigint>;
+/**
+ * Test-only: clear the module-level cache. Unit tests mock `readContract`
+ * and need a fresh slate between runs.
+ * @internal
+ */
+export declare function __resetPcUsdCache(): void;
+/** Re-exported for tests that need to assert chain coverage. */
+export declare const __ORIGIN_TO_STABLE: Partial<Record<CHAIN, StableKey>>;
+export {};

package/src/lib/orchestrator/internals/pc-usd-oracle.js

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__ORIGIN_TO_STABLE = void 0;
+exports.getPcUsdPrice = getPcUsdPrice;
+exports.pcToUsd = pcToUsd;
+exports.usdToPc = usdToPc;
+exports.__resetPcUsdCache = __resetPcUsdCache;
+const tslib_1 = require("tslib");
+/**
+ * Per-route $PC/USD oracle.
+ *
+ * There is no on-chain $PC/USD price feed today. Per Harsh (2026-04-17),
+ * derive $PC/USD from the WPC/stable Uniswap V3 pool on Push Chain, with
+ * the stable leg chosen by the origin route:
+ *   - Ethereum / Arbitrum / Base / BNB → WPC/USDT.<route>
+ *   - Solana → WPC/USDT.sol
+ *
+ * Pool pair (USDT vs USDC) is pending Zaryab/Zartaj confirmation — flip the
+ * ORIGIN_TO_STABLE map below if they pick USDC.
+ *
+ * Returns price in **8 decimals** (USD per 1 WPC) to match the convention
+ * used by PriceFetch.getPrice.
+ */
+const viem_1 = require("viem");
+const abi_1 = require("../../constants/abi");
+const chain_1 = require("../../constants/chain");
+const enums_1 = require("../../constants/enums");
+const context_1 = require("./context");
+const helpers_1 = require("./helpers");
+/**
+ * Chosen stable token per origin chain. Change these values to switch to USDC.
+ * Decimals: assume 6 (standard USDT/USDC). If a PRC-20 deviates, add an entry
+ * to STABLE_DECIMALS override below.
+ */
+const ORIGIN_TO_STABLE = {
+    [enums_1.CHAIN.ETHEREUM_SEPOLIA]: 'USDT_ETH',
+    [enums_1.CHAIN.ARBITRUM_SEPOLIA]: 'USDT_ARB',
+    [enums_1.CHAIN.BASE_SEPOLIA]: 'USDT_BASE',
+    [enums_1.CHAIN.BNB_TESTNET]: 'USDT_BNB',
+    [enums_1.CHAIN.SOLANA_DEVNET]: 'USDT_SOL',
+};
+/** Default decimals for stable PRC-20s on Push Chain. */
+const DEFAULT_STABLE_DECIMALS = 6;
+// ============================================================================
+// QuoterV2 ABI (same subset used elsewhere in gas-calculator.ts)
+// ============================================================================
+const QUOTER_V2_ABI = [
+    {
+        type: 'function',
+        name: 'quoteExactInputSingle',
+        inputs: [
+            {
+                type: 'tuple',
+                components: [
+                    { name: 'tokenIn', type: 'address' },
+                    { name: 'tokenOut', type: 'address' },
+                    { name: 'amountIn', type: 'uint256' },
+                    { name: 'fee', type: 'uint24' },
+                    { name: 'sqrtPriceLimitX96', type: 'uint160' },
+                ],
+            },
+        ],
+        outputs: [
+            { name: 'amountOut', type: 'uint256' },
+            { name: 'sqrtPriceX96After', type: 'uint160' },
+            { name: 'initializedTicksCrossed', type: 'uint32' },
+            { name: 'gasEstimate', type: 'uint256' },
+        ],
+        stateMutability: 'view',
+    },
+];
+const UNIVERSAL_CORE_SWAP_HELPERS_ABI = [
+    {
+        type: 'function',
+        name: 'WPC',
+        inputs: [],
+        outputs: [{ name: '', type: 'address' }],
+        stateMutability: 'view',
+    },
+    {
+        type: 'function',
+        name: 'uniswapV3Factory',
+        inputs: [],
+        outputs: [{ name: '', type: 'address' }],
+        stateMutability: 'view',
+    },
+    {
+        type: 'function',
+        name: 'defaultFeeTier',
+        inputs: [{ name: '', type: 'address' }],
+        outputs: [{ name: '', type: 'uint24' }],
+        stateMutability: 'view',
+    },
+];
+const UNISWAP_V3_FACTORY_ABI = [
+    {
+        type: 'function',
+        name: 'getPool',
+        inputs: [
+            { name: 'tokenA', type: 'address' },
+            { name: 'tokenB', type: 'address' },
+            { name: 'fee', type: 'uint24' },
+        ],
+        outputs: [{ name: 'pool', type: 'address' }],
+        stateMutability: 'view',
+    },
+];
+/**
+ * Fee tiers to probe when `defaultFeeTier(stable)` returns 0 on UniversalCore.
+ * Per the 2026-04-17 testnet probe, all WPC/USDT.* stable pools live at 500.
+ * Fall back through the standard Uniswap V3 tier set if 500 misses.
+ */
+const STABLE_FEE_TIER_FALLBACKS = [500, 3000, 100, 10000];
+const ZERO_ADDR = '0x0000000000000000000000000000000000000000';
+// ============================================================================
+// Cache (module-level, 30s TTL — mirrors price-fetch.ts)
+// ============================================================================
+const PRICE_CACHE_TTL_MS = 30000;
+const pcUsdPriceCache = new Map();
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Get $PC/USD price (8 decimals) for the given origin chain's route.
+ * Returns 0 on any failure — caller is expected to fall back to
+ * pushClient.pushToUSDC (the hardcoded $0.10 rate).
+ */
+function getPcUsdPrice(ctx, originChain) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const cached = pcUsdPriceCache.get(originChain);
+        if (cached && Date.now() < cached.expiry) {
+            return cached.price;
+        }
+        const stableKey = ORIGIN_TO_STABLE[originChain];
+        if (!stableKey) {
+            (0, context_1.printLog)(ctx, `getPcUsdPrice — no stable token mapped for origin ${originChain}; returning 0`);
+            return BigInt(0);
+        }
+        const pushChain = (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork);
+        const quoterAddress = (_b = (_a = chain_1.CHAIN_INFO[pushChain]) === null || _a === void 0 ? void 0 : _a.dex) === null || _b === void 0 ? void 0 : _b.uniV3QuoterV2;
+        if (!quoterAddress || quoterAddress.startsWith('0xTBD')) {
+            (0, context_1.printLog)(ctx, `getPcUsdPrice — no QuoterV2 configured for ${pushChain}; returning 0`);
+            return BigInt(0);
+        }
+        const stableAddress = (_c = chain_1.SYNTHETIC_PUSH_ERC20[ctx.pushNetwork]) === null || _c === void 0 ? void 0 : _c[stableKey];
+        if (!stableAddress || stableAddress.startsWith('0xTBD')) {
+            (0, context_1.printLog)(ctx, `getPcUsdPrice — no ${stableKey} mapped on ${ctx.pushNetwork}; returning 0`);
+            return BigInt(0);
+        }
+        try {
+            const gatewayPcAddress = (0, helpers_1.getUniversalGatewayPCAddress)();
+            const universalCoreAddress = yield ctx.pushClient.readContract({
+                address: gatewayPcAddress,
+                abi: abi_1.UNIVERSAL_GATEWAY_PC,
+                functionName: 'UNIVERSAL_CORE',
+                args: [],
+            });
+            const [wpcAddress, factoryAddress, defaultFeeTier] = yield Promise.all([
+                ctx.pushClient.readContract({
+                    address: universalCoreAddress,
+                    abi: UNIVERSAL_CORE_SWAP_HELPERS_ABI,
+                    functionName: 'WPC',
+                    args: [],
+                }),
+                ctx.pushClient.readContract({
+                    address: universalCoreAddress,
+                    abi: UNIVERSAL_CORE_SWAP_HELPERS_ABI,
+                    functionName: 'uniswapV3Factory',
+                    args: [],
+                }),
+                ctx.pushClient.readContract({
+                    address: universalCoreAddress,
+                    abi: UNIVERSAL_CORE_SWAP_HELPERS_ABI,
+                    functionName: 'defaultFeeTier',
+                    args: [stableAddress],
+                }),
+            ]);
+            if (!wpcAddress) {
+                (0, context_1.printLog)(ctx, `getPcUsdPrice — missing WPC; returning 0`);
+                return BigInt(0);
+            }
+            // UniversalCore's defaultFeeTier is set only for gas tokens (pETH*, pSOL).
+            // For stables, probe the factory for the first tier with a live pool.
+            let feeTier = defaultFeeTier;
+            if (!feeTier) {
+                for (const candidate of STABLE_FEE_TIER_FALLBACKS) {
+                    const pool = yield ctx.pushClient.readContract({
+                        address: factoryAddress,
+                        abi: UNISWAP_V3_FACTORY_ABI,
+                        functionName: 'getPool',
+                        args: [wpcAddress, stableAddress, candidate],
+                    });
+                    if (pool && pool !== ZERO_ADDR) {
+                        feeTier = candidate;
+                        (0, context_1.printLog)(ctx, `getPcUsdPrice — resolved fee tier ${candidate} via factory probe for WPC/${stableKey}`);
+                        break;
+                    }
+                }
+            }
+            if (!feeTier) {
+                (0, context_1.printLog)(ctx, `getPcUsdPrice — no WPC/${stableKey} pool found at any fee tier; returning 0`);
+                return BigInt(0);
+            }
+            // Quote: 1 WPC (1e18) → X stable (DEFAULT_STABLE_DECIMALS)
+            const oneWpc = (0, viem_1.parseUnits)('1', 18);
+            const result = yield ctx.pushClient.readContract({
+                address: quoterAddress,
+                abi: QUOTER_V2_ABI,
+                functionName: 'quoteExactInputSingle',
+                args: [
+                    {
+                        tokenIn: wpcAddress,
+                        tokenOut: stableAddress,
+                        amountIn: oneWpc,
+                        fee: feeTier,
+                        sqrtPriceLimitX96: BigInt(0),
+                    },
+                ],
+            });
+            const stableOut = result[0];
+            if (stableOut === BigInt(0)) {
+                (0, context_1.printLog)(ctx, `getPcUsdPrice — quoter returned 0 for WPC→${stableKey}`);
+                return BigInt(0);
+            }
+            // Normalize stableOut (DEFAULT_STABLE_DECIMALS) to 8-decimal USD.
+            // If stable decimals > 8, divide; otherwise multiply.
+            const decDelta = 8 - DEFAULT_STABLE_DECIMALS;
+            const price = decDelta >= 0
+                ? stableOut * BigInt(Math.pow(10, decDelta))
+                : stableOut / BigInt(Math.pow(10, -decDelta));
+            (0, context_1.printLog)(ctx, `getPcUsdPrice — origin=${originChain} stable=${stableKey} quote: 1 WPC = ${stableOut.toString()} (${DEFAULT_STABLE_DECIMALS}d) = ${price.toString()} (1e8 USD)`);
+            pcUsdPriceCache.set(originChain, {
+                price,
+                expiry: Date.now() + PRICE_CACHE_TTL_MS,
+            });
+            return price;
+        }
+        catch (err) {
+            (0, context_1.printLog)(ctx, `getPcUsdPrice — failed: ${err instanceof Error ? err.message : String(err)}`);
+            return BigInt(0);
+        }
+    });
+}
+/**
+ * Convert a nPUSH (18-dec) amount to USD (8-dec) using the per-route oracle.
+ * Falls back to the fixed pushToUSDC rate if the oracle returns 0.
+ */
+function pcToUsd(ctx, pcAmount, originChain) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const price = yield getPcUsdPrice(ctx, originChain);
+        if (price === BigInt(0)) {
+            return ctx.pushClient.pushToUSDC(pcAmount);
+        }
+        const oneWpc = (0, viem_1.parseUnits)('1', 18);
+        return (pcAmount * price) / oneWpc;
+    });
+}
+/**
+ * Convert a USD (8-dec) amount to nPUSH (18-dec) using the per-route oracle.
+ * Falls back to the fixed usdcToPush rate if the oracle returns 0.
+ */
+function usdToPc(ctx, usdAmount, originChain) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const price = yield getPcUsdPrice(ctx, originChain);
+        if (price === BigInt(0)) {
+            return ctx.pushClient.usdcToPush(usdAmount);
+        }
+        const oneWpc = (0, viem_1.parseUnits)('1', 18);
+        return (usdAmount * oneWpc + (price - BigInt(1))) / price;
+    });
+}
+/**
+ * Test-only: clear the module-level cache. Unit tests mock `readContract`
+ * and need a fresh slate between runs.
+ * @internal
+ */
+function __resetPcUsdCache() {
+    pcUsdPriceCache.clear();
+}
+/** Re-exported for tests that need to assert chain coverage. */
+exports.__ORIGIN_TO_STABLE = ORIGIN_TO_STABLE;
+// Reference to keep VM import used (stable decimals may differ by VM later).
+void enums_1.VM;
+//# sourceMappingURL=pc-usd-oracle.js.map

package/src/lib/orchestrator/internals/progress-route-hooks.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Per-route progress hook builders for the outbound polling phase
+ * (.wait() in response-builder.ts and per-hop loops in cascade.waitForAll).
+ *
+ * Splitting this out gives both call sites a single source of truth for
+ * which IDs fire on each route, so cascade hops and single-tx outbound
+ * stay in lockstep.
+ */
+import type { OutboundTxDetails } from '../orchestrator.types';
+import type { ProgressEvent } from '../../progress-hook/progress-hook.types';
+import { TransactionRoute } from '../route-detector';
+export type WaitHookSet = {
+    intermediatePushOk?: (chain: string, pushTxHash: string) => ProgressEvent;
+    awaiting: (chain: string) => ProgressEvent;
+    polling: (chain: string, elapsedMs: number) => ProgressEvent;
+    success: (details: OutboundTxDetails) => ProgressEvent;
+    timeout: (chain: string, elapsedMs: number) => ProgressEvent;
+    failed: (chain: string, errMsg: string) => ProgressEvent;
+};
+export declare function pickWaitHooks(route: TransactionRoute | string | undefined): WaitHookSet;
+/** True when the hook set is the no-op placeholder (route has no spec'd
+ * ID range). Emission sites should skip firing and receipt-mutation blocks. */
+export declare function isNoopHookSet(hooks: WaitHookSet): boolean;

package/src/lib/orchestrator/internals/progress-route-hooks.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Per-route progress hook builders for the outbound polling phase
+ * (.wait() in response-builder.ts and per-hop loops in cascade.waitForAll).
+ *
+ * Splitting this out gives both call sites a single source of truth for
+ * which IDs fire on each route, so cascade hops and single-tx outbound
+ * stay in lockstep.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickWaitHooks = pickWaitHooks;
+exports.isNoopHookSet = isNoopHookSet;
+const tslib_1 = require("tslib");
+const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
+const progress_hook_1 = tslib_1.__importDefault(require("../../progress-hook/progress-hook"));
+const route_detector_1 = require("../route-detector");
+function pickWaitHooks(route) {
+    if (route === route_detector_1.TransactionRoute.UOA_TO_CEA) {
+        return {
+            intermediatePushOk: (chain, txHash) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_99](chain, txHash),
+            awaiting: (chain) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_209_01](chain),
+            polling: (chain, elapsed) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_209_02](chain, elapsed),
+            success: (details) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_01](details),
+            timeout: (chain, elapsed) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_03](chain, elapsed),
+            failed: (chain, msg) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02](chain, msg),
+        };
+    }
+    if (route === route_detector_1.TransactionRoute.CEA_TO_PUSH) {
+        return {
+            intermediatePushOk: (_chain, txHash) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_99_99](txHash),
+            awaiting: (chain) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_01](chain),
+            polling: (chain, elapsed) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_02](chain, elapsed),
+            // For R3, the outbound-poll "success" is the source-chain CEA executing
+            // (309-03 INFO). Terminal 399-01 fires after the inbound-to-Push poll
+            // (handled by waitForInboundPushTx in response-builder).
+            success: (details) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_03](details.destinationChain, details.externalTxHash),
+            // R3 outbound (source-chain CEA) failures share the 399-02/03 IDs with
+            // R3 inbound; pass phase='outbound' so the title reflects the source
+            // chain instead of "Push Chain Inbound …".
+            timeout: (chain, elapsed) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03](chain, elapsed, 'outbound'),
+            failed: (chain, msg) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](msg, 'outbound', chain),
+        };
+    }
+    // Route 4 (CEA_TO_CEA) has no spec'd ID range yet; cascade hops and
+    // trackTransaction of pre-existing R4 UTXs still flow through here. Return
+    // a no-op set so wait() / cascade progress without emitting progress
+    // events for R4. When R4 gets its own ID range, add a branch above.
+    return NOOP_WAIT_HOOKS;
+}
+/** Sentinel event returned by NOOP_WAIT_HOOKS. Emission sites can detect
+ * and skip it by id === '' if they want to suppress no-op events. */
+const NOOP_EVENT = Object.freeze({
+    id: '',
+    title: '',
+    message: '',
+    level: 'INFO',
+    response: null,
+    timestamp: '',
+});
+const NOOP_WAIT_HOOKS = Object.freeze({
+    awaiting: () => NOOP_EVENT,
+    polling: () => NOOP_EVENT,
+    success: () => NOOP_EVENT,
+    timeout: () => NOOP_EVENT,
+    failed: () => NOOP_EVENT,
+});
+/** True when the hook set is the no-op placeholder (route has no spec'd
+ * ID range). Emission sites should skip firing and receipt-mutation blocks. */
+function isNoopHookSet(hooks) {
+    return hooks === NOOP_WAIT_HOOKS;
+}
+//# sourceMappingURL=progress-route-hooks.js.map