@pushchain/core 5.1.5-alpha.0 → 5.1.5

package/src/lib/orchestrator/internals/inbound-tracker.d.ts

@@ -0,0 +1,83 @@
+/**
+ * R3 inbound-to-Push tracking. After CEA executes on the source chain
+ * (R3 outbound poll completes with 309-03), the source-chain CEA fires
+ * `sendUniversalTxToUEA` which produces a child UniversalTx whose pcTx[0]
+ * is the inbound Push Chain tx that closes the round-trip.
+ *
+ * The correlation mechanism mirrors `scripts/poll-outbound.ts` Step D:
+ *   1. Search Cosmos for `universal_tx_created.inbound_tx_hash='${extHash}'`
+ *      and pull the child `utx_id` from the resulting events.
+ *   2. Query the child UTX via `getUniversalTxByIdV2(utxId)`. Its `pcTx[0]`
+ *      is the inbound Push Chain tx; its `universalStatus` tells us terminal.
+ */
+import type { OrchestratorContext } from './context';
+export type InboundPushTxStatus = 'pending' | 'confirmed' | 'failed';
+export interface InboundPushTxDetails {
+    /** The Push Chain tx hash that processed the inbound from the CEA. */
+    pushTxHash: string;
+    /** Child UTX id (Push Chain UniversalTx that owns the inbound). */
+    childUtxId: string;
+    /** Source chain that the CEA executed on. */
+    sourceChain: string;
+    /** External tx hash used as the correlation key. */
+    outboundExternalTxHash: string;
+    /** Final status of the inbound execution. */
+    status: InboundPushTxStatus;
+    /** Error message when status === 'failed'. */
+    errorMessage?: string;
+}
+export interface WaitForInboundOptions {
+    initialWaitMs?: number;
+    pollingIntervalMs?: number;
+    /** Total timeout from the call site (includes initialWaitMs). */
+    timeout?: number;
+    /** Optional callback for streamed status updates. */
+    progressHook?: (event: {
+        status: 'waiting' | 'polling' | 'found' | 'confirmed' | 'failed' | 'timeout';
+        elapsedMs: number;
+        childUtxId?: string;
+        pushTxHash?: string;
+    }) => void;
+}
+/**
+ * Resolves the child UTX id for an R3 round-trip from the source-chain tx.
+ *
+ * Primary path: use the universal-tx-detector to parse the source-chain
+ * receipt, locate the `UniversalTx(fromCEA=true)` log emitted by the CEA's
+ * `sendUniversalTxToUEA` call, and derive the child utxId via the
+ * deterministic `sha256(caip:txHash:logIndex)` formula. This bypasses the
+ * cosmos `universal_tx_created.inbound_tx_hash` indexer which has been
+ * unreliable on testnet.
+ *
+ * Fallback: the original cosmos text search, kept in place so if the
+ * indexer ever becomes the source of truth again (or the detector path
+ * hits an RPC snag for the source chain) we still have a second chance.
+ *
+ * Returns `{ utxId: string }` on hit, `{ utxId: null }` when neither path
+ * has seen it yet, or `{ utxId: null, error }` when both paths failed with
+ * recoverable RPC errors.
+ */
+export declare function findChildUtxIdFromExternalTx(ctx: OrchestratorContext, externalTxHash: string, sourceChain?: string): Promise<{
+    utxId: string | null;
+    error?: Error;
+    derivedFrom?: 'detector' | 'cosmos-fallback';
+}>;
+/**
+ * Polls Push Chain for the inbound tx that closes an R3 round-trip.
+ * Resolves when the child UTX reaches a terminal state (success/failure) or
+ * rejects with a Timeout error if neither child UTX nor terminal state is
+ * observed within the configured timeout.
+ */
+export declare function waitForInboundPushTx(ctx: OrchestratorContext, outboundExternalTxHash: string, sourceChain: string, opts?: WaitForInboundOptions): Promise<InboundPushTxDetails>;
+/**
+ * Thrown by `waitForInboundPushTx` when the polling loop exceeds the
+ * configured timeout without observing a terminal inbound Push tx. Callers
+ * (response-builder) `instanceof`-check to distinguish timeout (→ 399-03)
+ * from generic failure (→ 399-02) without relying on error-message prefixes.
+ */
+export declare class InboundTimeoutError extends Error {
+    readonly code: "INBOUND_TIMEOUT";
+    readonly correlationKey: string;
+    readonly elapsedMs: number;
+    constructor(correlationKey: string, elapsedMs: number);
+}

package/src/lib/orchestrator/internals/inbound-tracker.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * R3 inbound-to-Push tracking. After CEA executes on the source chain
+ * (R3 outbound poll completes with 309-03), the source-chain CEA fires
+ * `sendUniversalTxToUEA` which produces a child UniversalTx whose pcTx[0]
+ * is the inbound Push Chain tx that closes the round-trip.
+ *
+ * The correlation mechanism mirrors `scripts/poll-outbound.ts` Step D:
+ *   1. Search Cosmos for `universal_tx_created.inbound_tx_hash='${extHash}'`
+ *      and pull the child `utx_id` from the resulting events.
+ *   2. Query the child UTX via `getUniversalTxByIdV2(utxId)`. Its `pcTx[0]`
+ *      is the inbound Push Chain tx; its `universalStatus` tells us terminal.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboundTimeoutError = void 0;
+exports.findChildUtxIdFromExternalTx = findChildUtxIdFromExternalTx;
+exports.waitForInboundPushTx = waitForInboundPushTx;
+const tslib_1 = require("tslib");
+const types_1 = require("../../generated/uexecutor/v2/types");
+const context_1 = require("./context");
+const detector_1 = require("../../universal-tx-detector/detector");
+const child_inbounds_1 = require("../../universal-tx-detector/child-inbounds");
+const TERMINAL_SUCCESS_STATUSES = new Set([
+    types_1.UniversalTxStatus.INBOUND_SUCCESS,
+    types_1.UniversalTxStatus.PC_EXECUTED_SUCCESS,
+]);
+const TERMINAL_FAILURE_STATUSES = new Set([
+    types_1.UniversalTxStatus.PC_EXECUTED_FAILED,
+    types_1.UniversalTxStatus.PC_PENDING_REVERT,
+    types_1.UniversalTxStatus.OUTBOUND_FAILED,
+    types_1.UniversalTxStatus.CANCELED,
+]);
+const stripHex = (id) => id.startsWith('0x') ? id.slice(2) : id;
+const ensureHex = (id) => id.startsWith('0x') ? id : `0x${id}`;
+/**
+ * Resolves the child UTX id for an R3 round-trip from the source-chain tx.
+ *
+ * Primary path: use the universal-tx-detector to parse the source-chain
+ * receipt, locate the `UniversalTx(fromCEA=true)` log emitted by the CEA's
+ * `sendUniversalTxToUEA` call, and derive the child utxId via the
+ * deterministic `sha256(caip:txHash:logIndex)` formula. This bypasses the
+ * cosmos `universal_tx_created.inbound_tx_hash` indexer which has been
+ * unreliable on testnet.
+ *
+ * Fallback: the original cosmos text search, kept in place so if the
+ * indexer ever becomes the source of truth again (or the detector path
+ * hits an RPC snag for the source chain) we still have a second chance.
+ *
+ * Returns `{ utxId: string }` on hit, `{ utxId: null }` when neither path
+ * has seen it yet, or `{ utxId: null, error }` when both paths failed with
+ * recoverable RPC errors.
+ */
+function findChildUtxIdFromExternalTx(ctx, externalTxHash, sourceChain) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        // Primary: detector-based deterministic derivation.
+        if (sourceChain) {
+            try {
+                const detection = yield (0, detector_1.detectUniversalTx)(externalTxHash, sourceChain, {
+                    pushClient: ctx.pushClient,
+                    rpcUrls: ctx.rpcUrls,
+                    skipPushChainLookup: true,
+                });
+                const resolutions = yield (0, child_inbounds_1.resolveChildInboundsFromDetection)(ctx.pushClient, detection);
+                // Pick the R3 return-trip child: prefer UniversalTx over RevertUniversalTx.
+                const match = (_a = resolutions.find((r) => r.sourceEventName === 'UniversalTx')) !== null && _a !== void 0 ? _a : resolutions[0];
+                if (match === null || match === void 0 ? void 0 : match.universalTxId) {
+                    (0, context_1.printLog)(ctx, `[findChildUtxIdFromExternalTx] detector derived utxId ${match.universalTxId} for ${externalTxHash} on ${sourceChain}`);
+                    return { utxId: ensureHex(match.universalTxId), derivedFrom: 'detector' };
+                }
+            }
+            catch (err) {
+                const wrapped = err instanceof Error ? err : new Error(String(err));
+                (0, context_1.printLog)(ctx, `[findChildUtxIdFromExternalTx] detector path failed: ${wrapped.message} — falling back to cosmos search`);
+                // Fall through to cosmos search.
+            }
+        }
+        // Fallback: cosmos text search (original path).
+        try {
+            const query = `universal_tx_created.inbound_tx_hash='${externalTxHash}'`;
+            const results = yield ctx.pushClient.searchCosmosByQuery(query);
+            for (const tx of results) {
+                for (const event of (_b = tx.events) !== null && _b !== void 0 ? _b : []) {
+                    if (event.type === 'universal_tx_created' ||
+                        event.type === 'outbound_created') {
+                        for (const attr of (_c = event.attributes) !== null && _c !== void 0 ? _c : []) {
+                            if (attr.key === 'utx_id' && attr.value) {
+                                return {
+                                    utxId: ensureHex(attr.value),
+                                    derivedFrom: 'cosmos-fallback',
+                                };
+                            }
+                        }
+                    }
+                }
+            }
+            return { utxId: null };
+        }
+        catch (err) {
+            const wrapped = err instanceof Error ? err : new Error(String(err));
+            (0, context_1.printLog)(ctx, `[findChildUtxIdFromExternalTx] cosmos fallback also failed: ${wrapped.message}`);
+            return { utxId: null, error: wrapped };
+        }
+    });
+}
+/**
+ * Polls Push Chain for the inbound tx that closes an R3 round-trip.
+ * Resolves when the child UTX reaches a terminal state (success/failure) or
+ * rejects with a Timeout error if neither child UTX nor terminal state is
+ * observed within the configured timeout.
+ */
+function waitForInboundPushTx(ctx_1, outboundExternalTxHash_1, sourceChain_1) {
+    return tslib_1.__awaiter(this, arguments, void 0, function* (ctx, outboundExternalTxHash, sourceChain, opts = {}) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        const initialWaitMs = (_a = opts.initialWaitMs) !== null && _a !== void 0 ? _a : 30000;
+        const pollingIntervalMs = (_b = opts.pollingIntervalMs) !== null && _b !== void 0 ? _b : 5000;
+        const timeout = (_c = opts.timeout) !== null && _c !== void 0 ? _c : 300000;
+        const progressHook = opts.progressHook;
+        const startedAt = Date.now();
+        const elapsed = () => Date.now() - startedAt;
+        (0, context_1.printLog)(ctx, `[waitForInboundPushTx] Starting | externalTxHash: ${outboundExternalTxHash} | sourceChain: ${sourceChain} | initialWait: ${initialWaitMs}ms | pollInterval: ${pollingIntervalMs}ms | timeout: ${timeout}ms`);
+        progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'waiting', elapsedMs: 0 });
+        if (initialWaitMs > 0) {
+            (0, context_1.printLog)(ctx, `[waitForInboundPushTx] Initial wait of ${initialWaitMs}ms...`);
+            yield new Promise((r) => setTimeout(r, Math.min(initialWaitMs, timeout)));
+            (0, context_1.printLog)(ctx, `[waitForInboundPushTx] Initial wait done. Starting polling. Elapsed: ${elapsed()}ms`);
+        }
+        let childUtxId = null;
+        let strippedChildUtxId;
+        let pushTxHash;
+        let lastEmittedStatus;
+        let consecutiveRpcErrors = 0;
+        let pendingTerminalSuccessRetries = 0;
+        let pollCount = 0;
+        // Heuristic threshold — log a distinct warning when this many back-to-back
+        // RPC failures happen so callers can see the difference between
+        // "indexer hasn't seen it yet" and "RPC is down."
+        const RPC_FAILURE_WARN_THRESHOLD = 5;
+        // When chain reports terminal success but pcTx hasn't populated yet, give
+        // the indexer one extra poll cycle to catch up before returning empty hash.
+        const MAX_PENDING_TERMINAL_RETRIES = 2;
+        while (elapsed() < timeout) {
+            pollCount++;
+            const pollStart = Date.now();
+            (0, context_1.printLog)(ctx, `[waitForInboundPushTx] Poll #${pollCount} | Elapsed: ${elapsed()}ms / ${timeout}ms | phase: ${childUtxId ? 'utx-status' : 'child-search'}`);
+            // Phase 1 — find child UTX id from the outbound external tx hash
+            if (!childUtxId) {
+                const search = yield findChildUtxIdFromExternalTx(ctx, outboundExternalTxHash, sourceChain);
+                (0, context_1.printLog)(ctx, `[waitForInboundPushTx] Poll #${pollCount} child-search result: utxId=${(_d = search.utxId) !== null && _d !== void 0 ? _d : 'null'}${search.error ? ` error=${search.error.message}` : ''}`);
+                if (search.error) {
+                    consecutiveRpcErrors++;
+                    if (consecutiveRpcErrors === RPC_FAILURE_WARN_THRESHOLD) {
+                        (0, context_1.printLog)(ctx, `[waitForInboundPushTx] ${RPC_FAILURE_WARN_THRESHOLD} consecutive Cosmos search errors — RPC may be unhealthy. Continuing until timeout.`);
+                    }
+                }
+                else {
+                    consecutiveRpcErrors = 0;
+                    if (search.utxId) {
+                        childUtxId = search.utxId;
+                        strippedChildUtxId = stripHex(childUtxId);
+                        progressHook === null || progressHook === void 0 ? void 0 : progressHook({
+                            status: 'found',
+                            elapsedMs: elapsed(),
+                            childUtxId,
+                        });
+                        lastEmittedStatus = 'found';
+                    }
+                    else if (lastEmittedStatus !== 'polling') {
+                        progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'polling', elapsedMs: elapsed() });
+                        lastEmittedStatus = 'polling';
+                    }
+                }
+            }
+            // Phase 2 — once we have the child UTX, query its status until terminal
+            if (childUtxId && strippedChildUtxId) {
+                try {
+                    const response = yield ctx.pushClient.getUniversalTxByIdV2(strippedChildUtxId);
+                    consecutiveRpcErrors = 0;
+                    const utx = response === null || response === void 0 ? void 0 : response.universalTx;
+                    const status = (_e = utx === null || utx === void 0 ? void 0 : utx.universalStatus) !== null && _e !== void 0 ? _e : -1;
+                    if ((_g = (_f = utx === null || utx === void 0 ? void 0 : utx.pcTx) === null || _f === void 0 ? void 0 : _f[0]) === null || _g === void 0 ? void 0 : _g.txHash) {
+                        pushTxHash = utx.pcTx[0].txHash;
+                    }
+                    (0, context_1.printLog)(ctx, `[waitForInboundPushTx] Poll #${pollCount} utx-status | status: ${status} | pcTx[0].txHash: '${pushTxHash !== null && pushTxHash !== void 0 ? pushTxHash : ''}' | pcTx len: ${(_j = (_h = utx === null || utx === void 0 ? void 0 : utx.pcTx) === null || _h === void 0 ? void 0 : _h.length) !== null && _j !== void 0 ? _j : 0}`);
+                    if (TERMINAL_SUCCESS_STATUSES.has(status)) {
+                        // Wait one more poll cycle if pcTx hasn't populated yet — the
+                        // indexer occasionally flips status before the pcTx hash is queryable.
+                        if (!pushTxHash && pendingTerminalSuccessRetries < MAX_PENDING_TERMINAL_RETRIES) {
+                            pendingTerminalSuccessRetries++;
+                        }
+                        else {
+                            progressHook === null || progressHook === void 0 ? void 0 : progressHook({
+                                status: 'confirmed',
+                                elapsedMs: elapsed(),
+                                childUtxId,
+                                pushTxHash,
+                            });
+                            return {
+                                childUtxId,
+                                pushTxHash: pushTxHash !== null && pushTxHash !== void 0 ? pushTxHash : '',
+                                sourceChain,
+                                outboundExternalTxHash,
+                                status: 'confirmed',
+                            };
+                        }
+                    }
+                    else if (TERMINAL_FAILURE_STATUSES.has(status)) {
+                        const errMsg = ((_l = (_k = utx === null || utx === void 0 ? void 0 : utx.pcTx) === null || _k === void 0 ? void 0 : _k[0]) === null || _l === void 0 ? void 0 : _l.errorMsg) ||
+                            `inbound terminated with status ${status}`;
+                        progressHook === null || progressHook === void 0 ? void 0 : progressHook({
+                            status: 'failed',
+                            elapsedMs: elapsed(),
+                            childUtxId,
+                            pushTxHash,
+                        });
+                        return {
+                            childUtxId,
+                            pushTxHash: pushTxHash !== null && pushTxHash !== void 0 ? pushTxHash : '',
+                            sourceChain,
+                            outboundExternalTxHash,
+                            status: 'failed',
+                            errorMessage: errMsg,
+                        };
+                    }
+                    else if (pushTxHash) {
+                        // Tiebreaker: cosmos has the Push Chain tx hash populated but the
+                        // indexer hasn't transitioned universalStatus to a terminal yet.
+                        // Query Push RPC directly for the receipt — if it's confirmed on
+                        // chain, treat as terminal-success; if it reverted, treat as
+                        // terminal-failure. Cosmos-indexer lag stops blocking us here.
+                        try {
+                            const receipt = yield ctx.pushClient.publicClient.getTransactionReceipt({
+                                hash: pushTxHash,
+                            });
+                            if ((receipt === null || receipt === void 0 ? void 0 : receipt.status) === 'success') {
+                                (0, context_1.printLog)(ctx, `[waitForInboundPushTx] Push RPC tiebreaker: ${pushTxHash} confirmed on chain (cosmos still status=${status}); treating as terminal-success`);
+                                progressHook === null || progressHook === void 0 ? void 0 : progressHook({
+                                    status: 'confirmed',
+                                    elapsedMs: elapsed(),
+                                    childUtxId,
+                                    pushTxHash,
+                                });
+                                return {
+                                    childUtxId,
+                                    pushTxHash,
+                                    sourceChain,
+                                    outboundExternalTxHash,
+                                    status: 'confirmed',
+                                };
+                            }
+                            if ((receipt === null || receipt === void 0 ? void 0 : receipt.status) === 'reverted') {
+                                (0, context_1.printLog)(ctx, `[waitForInboundPushTx] Push RPC tiebreaker: ${pushTxHash} REVERTED on chain (cosmos still status=${status}); treating as terminal-failure`);
+                                progressHook === null || progressHook === void 0 ? void 0 : progressHook({
+                                    status: 'failed',
+                                    elapsedMs: elapsed(),
+                                    childUtxId,
+                                    pushTxHash,
+                                });
+                                return {
+                                    childUtxId,
+                                    pushTxHash,
+                                    sourceChain,
+                                    outboundExternalTxHash,
+                                    status: 'failed',
+                                    errorMessage: 'Push Chain inbound tx reverted on chain',
+                                };
+                            }
+                            // receipt missing / pending — keep polling.
+                        }
+                        catch (rpcErr) {
+                            // TransactionReceiptNotFoundError means not yet mined — continue
+                            // polling. Other errors get logged but don't break the loop.
+                            const msg = rpcErr instanceof Error ? rpcErr.message : String(rpcErr);
+                            if (!/not found|TransactionReceiptNotFound|could not be found/i.test(msg)) {
+                                (0, context_1.printLog)(ctx, `[waitForInboundPushTx] Push RPC tiebreaker failed for ${pushTxHash}: ${msg}`);
+                            }
+                        }
+                    }
+                }
+                catch (err) {
+                    consecutiveRpcErrors++;
+                    if (consecutiveRpcErrors === RPC_FAILURE_WARN_THRESHOLD) {
+                        (0, context_1.printLog)(ctx, `[waitForInboundPushTx] ${RPC_FAILURE_WARN_THRESHOLD} consecutive getUniversalTxByIdV2 errors — RPC may be unhealthy. Continuing until timeout.`);
+                    }
+                    (0, context_1.printLog)(ctx, `[waitForInboundPushTx] getUniversalTxByIdV2 failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (lastEmittedStatus !== 'polling') {
+                    progressHook === null || progressHook === void 0 ? void 0 : progressHook({
+                        status: 'polling',
+                        elapsedMs: elapsed(),
+                        childUtxId,
+                    });
+                    lastEmittedStatus = 'polling';
+                }
+            }
+            if (elapsed() >= timeout)
+                break;
+            (0, context_1.printLog)(ctx, `[waitForInboundPushTx] Poll #${pollCount} not ready (${Date.now() - pollStart}ms). Waiting ${pollingIntervalMs}ms...`);
+            yield new Promise((r) => setTimeout(r, pollingIntervalMs));
+        }
+        (0, context_1.printLog)(ctx, `[waitForInboundPushTx] TIMEOUT after ${pollCount} polls | elapsed: ${elapsed()}ms`);
+        progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'timeout', elapsedMs: elapsed() });
+        throw new InboundTimeoutError(outboundExternalTxHash, elapsed());
+    });
+}
+/**
+ * Thrown by `waitForInboundPushTx` when the polling loop exceeds the
+ * configured timeout without observing a terminal inbound Push tx. Callers
+ * (response-builder) `instanceof`-check to distinguish timeout (→ 399-03)
+ * from generic failure (→ 399-02) without relying on error-message prefixes.
+ */
+class InboundTimeoutError extends Error {
+    constructor(correlationKey, elapsedMs) {
+        super(`Timeout waiting for inbound Push tx after ${Math.round(elapsedMs / 1000)}s (correlation key: ${correlationKey}).`);
+        this.code = 'INBOUND_TIMEOUT';
+        this.name = 'InboundTimeoutError';
+        this.correlationKey = correlationKey;
+        this.elapsedMs = elapsedMs;
+    }
+}
+exports.InboundTimeoutError = InboundTimeoutError;
+//# sourceMappingURL=inbound-tracker.js.map

package/src/lib/orchestrator/internals/index.d.ts

@@ -6,7 +6,9 @@ export { computeExecutionHash, computeMigrationHash, signUniversalPayload, signM
 export { waitForEvmConfirmationsWithCountdown, waitForSvmConfirmationsWithCountdown, waitForLockerFeeConfirmation, } from './confirmation';
 export { buildSvmUniversalTxRequest, buildSvmUniversalTxRequestFromReq, getSvmProtocolFee, getSvmGatewayLogIndexFromTx, } from './svm-helpers';
 export { computeUniversalTxId, extractUniversalSubTxIdFromTx, extractAllUniversalSubTxIds, } from './outbound-tracker';
-export { waitForOutboundTx, waitForAllOutboundTxsV2, OUTBOUND_INITIAL_WAIT_MS, OUTBOUND_POLL_INTERVAL_MS, OUTBOUND_MAX_TIMEOUT_MS, } from './outbound-sync';
+export { waitForOutboundTx, waitForAllOutboundTxsV2, OUTBOUND_INITIAL_WAIT_MS, OUTBOUND_POLL_INTERVAL_MS, OUTBOUND_MAX_TIMEOUT_MS, INBOUND_INITIAL_WAIT_MS, INBOUND_MAX_TIMEOUT_MS, } from './outbound-sync';
+export { findChildUtxIdFromExternalTx, waitForInboundPushTx, } from './inbound-tracker';
+export type { InboundPushTxDetails, InboundPushTxStatus, WaitForInboundOptions, } from './inbound-tracker';
 export { transformToUniversalTxReceipt, reconstructProgressEvents, detectRouteFromUniversalTxData, } from './tx-transformer';
 export { ensureErc20Allowance, queryOutboundGasFee, queryRescueGasFee, calculateNativeAmountForDeposit, calculateGasAmountFromAmountOutMinETH, } from './gas-calculator';
 export { quoteExactOutput } from './quote';

package/src/lib/orchestrator/internals/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getUeaNonceForExecution = exports.getUEANonce = exports.computeUEA = exports.computeUEAOffchain = exports.quoteExactOutput = exports.calculateGasAmountFromAmountOutMinETH = exports.calculateNativeAmountForDeposit = exports.queryRescueGasFee = exports.queryOutboundGasFee = exports.ensureErc20Allowance = exports.detectRouteFromUniversalTxData = exports.reconstructProgressEvents = exports.transformToUniversalTxReceipt = exports.OUTBOUND_MAX_TIMEOUT_MS = exports.OUTBOUND_POLL_INTERVAL_MS = exports.OUTBOUND_INITIAL_WAIT_MS = exports.waitForAllOutboundTxsV2 = exports.waitForOutboundTx = exports.extractAllUniversalSubTxIds = exports.extractUniversalSubTxIdFromTx = exports.computeUniversalTxId = exports.getSvmGatewayLogIndexFromTx = exports.getSvmProtocolFee = exports.buildSvmUniversalTxRequestFromReq = exports.buildSvmUniversalTxRequest = exports.waitForLockerFeeConfirmation = exports.waitForSvmConfirmationsWithCountdown = exports.waitForEvmConfirmationsWithCountdown = exports.encodeUniversalPayloadSvm = exports.encodeUniversalPayload = exports.signMigrationPayload = exports.signUniversalPayload = exports.computeMigrationHash = exports.computeExecutionHash = exports.buildGatewayPayloadAndGas = exports.buildMulticallPayloadData = exports.buildUniversalTxRequest = exports.SUPPORTED_GATEWAY_CHAINS = exports.fetchOriginChainTransactionForProgress = exports.toExecuteParams = exports.bigintReplacer = exports.validateMainnetConnection = exports.getUniversalGatewayPCAddress = exports.getNativePRC20ForChain = exports.chainFromNamespace = exports.getChainNamespace = exports.getPushChainForNetwork = exports.isPushChain = exports.fireProgressHook = exports.printLog = void 0;
-exports.executeStandardPayload = exports.executeFundsWithPayload = exports.executeFundsOnly = exports.rescueFunds = exports.sendSVMTxWithFunds = exports.createCascadedBuilder = exports.composeCascade = exports.getSegmentType = exports.classifyIntoSegments = exports.buildHopDescriptor = exports.prepareTransaction = exports.buildPayloadForRoute = exports.executeCeaToCea = exports.executeCeaToPushSvm = exports.executeCeaToPush = exports.executeUoaToCeaSvm = exports.executeUoaToCea = exports.executeMultiChain = exports.extractPcTxAndTransform = exports.sendUniversalTx = exports.sendPushTx = exports.transformToUniversalTxResponse = exports.trackTransaction = exports.queryUniversalTxStatusFromGatewayTx = exports.getOriginGatewayContext = exports.lockFee = exports.sendGatewayTokenTxWithFallback = exports.sendGatewayTxWithFallback = exports.toGatewayTokenRequestV1 = exports.toGatewayRequestV1 = exports.migrateCEA = exports.fetchLatestUEAVersion = exports.upgradeAccount = exports.getAccountStatus = exports.fetchUEAVersion = exports.getUeaStatusAndNonce = void 0;
+exports.quoteExactOutput = exports.calculateGasAmountFromAmountOutMinETH = exports.calculateNativeAmountForDeposit = exports.queryRescueGasFee = exports.queryOutboundGasFee = exports.ensureErc20Allowance = exports.detectRouteFromUniversalTxData = exports.reconstructProgressEvents = exports.transformToUniversalTxReceipt = exports.waitForInboundPushTx = exports.findChildUtxIdFromExternalTx = exports.INBOUND_MAX_TIMEOUT_MS = exports.INBOUND_INITIAL_WAIT_MS = exports.OUTBOUND_MAX_TIMEOUT_MS = exports.OUTBOUND_POLL_INTERVAL_MS = exports.OUTBOUND_INITIAL_WAIT_MS = exports.waitForAllOutboundTxsV2 = exports.waitForOutboundTx = exports.extractAllUniversalSubTxIds = exports.extractUniversalSubTxIdFromTx = exports.computeUniversalTxId = exports.getSvmGatewayLogIndexFromTx = exports.getSvmProtocolFee = exports.buildSvmUniversalTxRequestFromReq = exports.buildSvmUniversalTxRequest = exports.waitForLockerFeeConfirmation = exports.waitForSvmConfirmationsWithCountdown = exports.waitForEvmConfirmationsWithCountdown = exports.encodeUniversalPayloadSvm = exports.encodeUniversalPayload = exports.signMigrationPayload = exports.signUniversalPayload = exports.computeMigrationHash = exports.computeExecutionHash = exports.buildGatewayPayloadAndGas = exports.buildMulticallPayloadData = exports.buildUniversalTxRequest = exports.SUPPORTED_GATEWAY_CHAINS = exports.fetchOriginChainTransactionForProgress = exports.toExecuteParams = exports.bigintReplacer = exports.validateMainnetConnection = exports.getUniversalGatewayPCAddress = exports.getNativePRC20ForChain = exports.chainFromNamespace = exports.getChainNamespace = exports.getPushChainForNetwork = exports.isPushChain = exports.fireProgressHook = exports.printLog = void 0;
+exports.executeStandardPayload = exports.executeFundsWithPayload = exports.executeFundsOnly = exports.rescueFunds = exports.sendSVMTxWithFunds = exports.createCascadedBuilder = exports.composeCascade = exports.getSegmentType = exports.classifyIntoSegments = exports.buildHopDescriptor = exports.prepareTransaction = exports.buildPayloadForRoute = exports.executeCeaToCea = exports.executeCeaToPushSvm = exports.executeCeaToPush = exports.executeUoaToCeaSvm = exports.executeUoaToCea = exports.executeMultiChain = exports.extractPcTxAndTransform = exports.sendUniversalTx = exports.sendPushTx = exports.transformToUniversalTxResponse = exports.trackTransaction = exports.queryUniversalTxStatusFromGatewayTx = exports.getOriginGatewayContext = exports.lockFee = exports.sendGatewayTokenTxWithFallback = exports.sendGatewayTxWithFallback = exports.toGatewayTokenRequestV1 = exports.toGatewayRequestV1 = exports.migrateCEA = exports.fetchLatestUEAVersion = exports.upgradeAccount = exports.getAccountStatus = exports.fetchUEAVersion = exports.getUeaStatusAndNonce = exports.getUeaNonceForExecution = exports.getUEANonce = exports.computeUEA = exports.computeUEAOffchain = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "printLog", { enumerable: true, get: function () { return context_1.printLog; } });
 Object.defineProperty(exports, "fireProgressHook", { enumerable: true, get: function () { return context_1.fireProgressHook; } });
@@ -53,6 +53,12 @@ Object.defineProperty(exports, "waitForAllOutboundTxsV2", { enumerable: true, ge
 Object.defineProperty(exports, "OUTBOUND_INITIAL_WAIT_MS", { enumerable: true, get: function () { return outbound_sync_1.OUTBOUND_INITIAL_WAIT_MS; } });
 Object.defineProperty(exports, "OUTBOUND_POLL_INTERVAL_MS", { enumerable: true, get: function () { return outbound_sync_1.OUTBOUND_POLL_INTERVAL_MS; } });
 Object.defineProperty(exports, "OUTBOUND_MAX_TIMEOUT_MS", { enumerable: true, get: function () { return outbound_sync_1.OUTBOUND_MAX_TIMEOUT_MS; } });
+Object.defineProperty(exports, "INBOUND_INITIAL_WAIT_MS", { enumerable: true, get: function () { return outbound_sync_1.INBOUND_INITIAL_WAIT_MS; } });
+Object.defineProperty(exports, "INBOUND_MAX_TIMEOUT_MS", { enumerable: true, get: function () { return outbound_sync_1.INBOUND_MAX_TIMEOUT_MS; } });
+// === Inbound Tracking (R3 round-trip) ===
+var inbound_tracker_1 = require("./inbound-tracker");
+Object.defineProperty(exports, "findChildUtxIdFromExternalTx", { enumerable: true, get: function () { return inbound_tracker_1.findChildUtxIdFromExternalTx; } });
+Object.defineProperty(exports, "waitForInboundPushTx", { enumerable: true, get: function () { return inbound_tracker_1.waitForInboundPushTx; } });
 // === Transaction Transformation ===
 var tx_transformer_1 = require("./tx-transformer");
 Object.defineProperty(exports, "transformToUniversalTxReceipt", { enumerable: true, get: function () { return tx_transformer_1.transformToUniversalTxReceipt; } });

package/src/lib/orchestrator/internals/outbound-sync.d.ts

@@ -11,8 +11,39 @@ import type { OrchestratorContext } from './context';
 export declare const OUTBOUND_INITIAL_WAIT_MS = 20000;
 /** Interval between consecutive polls (ms). */
 export declare const OUTBOUND_POLL_INTERVAL_MS = 5000;
-/** Maximum total timeout for the polling loop (ms). */
+/** Maximum total timeout for the outbound polling loop (ms). */
 export declare const OUTBOUND_MAX_TIMEOUT_MS = 180000;
+/** Maximum total timeout for the R3 inbound round-trip polling loop (ms). */
+export declare const INBOUND_MAX_TIMEOUT_MS = 300000;
+/** Initial wait before the first inbound poll (ms). Set to 0 — the outbound just completed, so the indexer may already have the child UTX. */
+export declare const INBOUND_INITIAL_WAIT_MS = 0;
+/**
+ * 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.
+ */
+export declare class OutboundTimeoutError extends Error {
+    readonly code: "OUTBOUND_TIMEOUT";
+    readonly pushChainTxHash: string;
+    readonly elapsedMs: number;
+    constructor(pushChainTxHash: string, elapsedMs: number, timeoutMs: number);
+}
+/**
+ * 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).
+ */
+export declare class OutboundFailedError extends Error {
+    readonly code: "OUTBOUND_FAILED";
+    readonly pushChainTxHash: string;
+    readonly destinationChain?: string;
+    /** Observed tx hash on the destination chain (when available). Lets the
+     * receipt expose the reverted external tx so consumers can link to the
+     * explorer without parsing the error message. */
+    readonly externalTxHash?: string;
+    constructor(message: string, pushChainTxHash: string, destinationChain?: string, externalTxHash?: string);
+}
 /**
  * Wait for outbound transaction to complete and return external chain details.
  * @internal Used by .wait() for outbound routes - not part of public API.