@pushchain/core 5.1.14 → 5.1.16

package/src/lib/orchestrator/internals/error-decoder.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Decoder for revert-error messages surfaced by Cosmos `tx.rawLog`.
+ *
+ * Two extraction paths:
+ *   1. 4-byte custom selector (e.g. `0xacfdb444:` or `0xf4d678b8000000…`) —
+ *      looked up against `KNOWN_ERROR_SELECTORS` for a friendly name + hint.
+ *   2. `Error(string)` ABI-encoded revert (`0x08c379a0` selector + offset +
+ *      length + data) — decoded into the original UTF-8 string.
+ *
+ * Unknown selectors fall through with `kind: 'unknown'` so callers can log
+ * them at INFO and grow the table from real reverts.
+ *
+ * The selector→name mappings below are EMPIRICAL: they were observed in
+ * production e2e logs and SDK test fixtures. `keccak256` of the obvious
+ * parameterless signatures (e.g. `keccak256("InsufficientBalance()")` =
+ * `0x01e1e567`) does NOT reproduce the listed selectors, so the deployed-
+ * source mapping is still unverified. Names and hints are worded as
+ * "likely cause" until the bytecode-source trace lands.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_STRING_SELECTOR = exports.KNOWN_ERROR_SELECTORS = void 0;
+exports.decodeRevert = decodeRevert;
+exports.KNOWN_ERROR_SELECTORS = {
+    '0xacfdb444': {
+        name: 'ExecutionFailed',
+        hint: 'Likely cause: subcall reverted (target contract or internal gas-swap precompile). ' +
+            'Check that the target accepts native value (has receive/fallback) and that calldata matches a valid signature. ' +
+            'Note: this selector also fires from internal SDK paths (e.g. fresh-wallet gas-swap) — see route2-fresh-wallet-gas-bug.spec.ts.',
+        provenance: 'Production e2e: e2e-2026-04-09T13-58-42-237Z.log:103 (R2 EVM target revert)',
+    },
+    '0x179a867c': {
+        name: 'ExpiredDeadline',
+        hint: 'Likely cause: transaction deadline passed before relay. Retry — the SDK will set a new deadline.',
+        provenance: 'Production e2e (associated with deadline-related reverts)',
+    },
+    '0xf4d678b8': {
+        name: 'InsufficientBalance',
+        hint: 'Likely cause: UEA does not hold enough of the burn token (PRC-20 mapped from the outbound `funds.token`). ' +
+            'For Solana SPL outbounds, ensure UEA holds the corresponding pUSDT.sol / pUSDC.sol mint before retrying. ' +
+            'Same selector may also surface from other balance-check reverters; verify burn-token balance first.',
+        provenance: 'Production e2e: e2e-2026-04-16T16-27-58-082Z.log:342 (R2 SPL fresh-UEA, no pUSDT.sol)',
+    },
+    '0x66f9d09e': {
+        name: 'GasLimitBelowBase',
+        hint: 'Likely cause: provided gasLimit is below the chain minimum. Omit `gasLimit` to use the per-chain default.',
+        provenance: 'Observed in dev (selector source unverified — see plan §9 #5)',
+    },
+};
+/** Selector for `Error(string)` (Solidity `require(false, "msg")`). */
+exports.ERROR_STRING_SELECTOR = '0x08c379a0';
+/** Hard cap on the decoded string length; protects against malformed data. */
+const MAX_DECODED_STRING_LEN = 1024;
+/**
+ * Extracts the first hex blob after `ret ` from a Cosmos tx error message,
+ * pulls the 4-byte selector, and looks it up. Returns `null` when no blob
+ * is found.
+ *
+ * **Assumption**: today's Cosmos `tx.rawLog` format contains a single
+ * `ret 0x…:` substring per failed message. If a future log format includes
+ * nested call traces with multiple `ret` substrings, this regex will pick
+ * the first selector — which may not be the most relevant one. Revisit
+ * if multi-revert log formats appear in production.
+ */
+function decodeRevert(errorMsg) {
+    if (!errorMsg)
+        return null;
+    const m = errorMsg.match(/ret (0x[0-9a-fA-F]+)/);
+    if (!m)
+        return null;
+    const blob = m[1].toLowerCase();
+    if (blob.length < 10)
+        return null;
+    const sel = blob.slice(0, 10);
+    const entry = exports.KNOWN_ERROR_SELECTORS[sel];
+    if (entry) {
+        return {
+            kind: 'custom',
+            selector: sel,
+            name: entry.name,
+            hint: entry.hint,
+            provenance: entry.provenance,
+        };
+    }
+    if (sel === exports.ERROR_STRING_SELECTOR) {
+        try {
+            const data = blob.slice(10);
+            // Error(string) ABI: offset(32 bytes) + length(32 bytes) + data
+            // Skip the 32-byte offset (always 0x20).
+            const lengthHex = data.slice(64, 128);
+            if (lengthHex.length === 64) {
+                const length = parseInt(lengthHex, 16);
+                if (Number.isFinite(length) &&
+                    length > 0 &&
+                    length < MAX_DECODED_STRING_LEN) {
+                    const strHex = data.slice(128, 128 + length * 2);
+                    if (strHex.length === length * 2) {
+                        const decoded = Buffer.from(strHex, 'hex').toString('utf8');
+                        return { kind: 'string', selector: sel, decoded };
+                    }
+                }
+            }
+        }
+        catch (_a) {
+            /* fall through to unknown */
+        }
+    }
+    return { kind: 'unknown', selector: sel };
+}
+//# sourceMappingURL=error-decoder.js.map

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

@@ -0,0 +1,78 @@
+/**
+ * Typed errors for orchestrator pre-flight checks.
+ *
+ * `PushChainExecutionError` lives here (instead of push-chain-tx.ts) so the
+ * pre-flight `InsufficientUEABalanceError` can extend it without creating a
+ * circular import (preflight.ts → errors.ts → push-chain-tx.ts → context.ts
+ * → … → route-handlers.ts → preflight.ts). push-chain-tx.ts re-exports it
+ * for backward-compat with existing `instanceof PushChainExecutionError`
+ * callers.
+ */
+/**
+ * Structured decoded-error payload attached to terminal failure hooks
+ * (199-02 / 299-02 / 399-02). Mirrors the optional formatter parameter
+ * shape so the orchestrator's outer catch can lift it off the thrown
+ * error and pass it straight through.
+ */
+export interface DecodedErrorPayload {
+    name?: string;
+    hint?: string;
+    selector?: string;
+    decoded?: string;
+}
+/**
+ * Typed error for Route 1 Push Chain tx failures. Thrown by
+ * `extractPcTxAndTransform` when the final pcTx commits with `status === 'FAILED'`,
+ * and surfaced as `SEND_TX_199_02` on the live stream. The readonly `code`
+ * discriminator lets callers classify via `instanceof PushChainExecutionError`
+ * instead of sniffing error messages.
+ *
+ * Carries the origin-chain gateway tx hash. There is no successful Push Chain
+ * tx to reference on this path — by definition the pcTx committed `FAILED`.
+ *
+ * `decodedError`: optional structured payload that flows through to terminal
+ * failure hook payloads (199-02 / 299-02 / 399-02 / 999-02). Set by the
+ * decoder wire-in (push-chain-tx.ts) and by InsufficientUEABalanceError so
+ * consumers don't have to parse the message string.
+ */
+export declare class PushChainExecutionError extends Error {
+    readonly code: "PUSH_CHAIN_EXECUTION_FAILED";
+    readonly gatewayTxHash?: string;
+    readonly decodedError?: DecodedErrorPayload;
+    constructor(message: string, opts?: {
+        gatewayTxHash?: string;
+        decodedError?: DecodedErrorPayload;
+    });
+}
+export type PreflightPathTag = 'R2_EVM' | 'R2_SVM' | 'R3_EVM' | 'R3_SVM' | 'CASCADE';
+export type PreflightShortfallReason = 'NATIVE' | 'PRC20';
+export interface InsufficientUEABalanceErrorOpts {
+    required: bigint;
+    available: bigint;
+    shortfall: bigint;
+    ueaAddress: `0x${string}`;
+    pathTag: PreflightPathTag;
+    /** 'NATIVE' = UPC shortfall; 'PRC20' = burn-token shortfall. */
+    reason?: PreflightShortfallReason;
+    /** Burn token address (only set when reason === 'PRC20'). */
+    burnToken?: `0x${string}`;
+    /** Cascade-only: zero-based index of the failing segment. */
+    segmentIndex?: number;
+}
+/**
+ * Thrown by `runPreflight` when the UEA cannot cover the required outbound
+ * cost. No cosmos tx is submitted on this path — the existing silent-clamp
+ * behaviour was previously submitting under-funded swaps that reverted
+ * inside Uniswap with `Error("STF")`.
+ */
+export declare class InsufficientUEABalanceError extends PushChainExecutionError {
+    readonly required: bigint;
+    readonly available: bigint;
+    readonly shortfall: bigint;
+    readonly ueaAddress: `0x${string}`;
+    readonly pathTag: PreflightPathTag;
+    readonly reason: PreflightShortfallReason;
+    readonly burnToken?: `0x${string}`;
+    readonly segmentIndex?: number;
+    constructor(opts: InsufficientUEABalanceErrorOpts);
+}

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

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Typed errors for orchestrator pre-flight checks.
+ *
+ * `PushChainExecutionError` lives here (instead of push-chain-tx.ts) so the
+ * pre-flight `InsufficientUEABalanceError` can extend it without creating a
+ * circular import (preflight.ts → errors.ts → push-chain-tx.ts → context.ts
+ * → … → route-handlers.ts → preflight.ts). push-chain-tx.ts re-exports it
+ * for backward-compat with existing `instanceof PushChainExecutionError`
+ * callers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InsufficientUEABalanceError = exports.PushChainExecutionError = void 0;
+/**
+ * Typed error for Route 1 Push Chain tx failures. Thrown by
+ * `extractPcTxAndTransform` when the final pcTx commits with `status === 'FAILED'`,
+ * and surfaced as `SEND_TX_199_02` on the live stream. The readonly `code`
+ * discriminator lets callers classify via `instanceof PushChainExecutionError`
+ * instead of sniffing error messages.
+ *
+ * Carries the origin-chain gateway tx hash. There is no successful Push Chain
+ * tx to reference on this path — by definition the pcTx committed `FAILED`.
+ *
+ * `decodedError`: optional structured payload that flows through to terminal
+ * failure hook payloads (199-02 / 299-02 / 399-02 / 999-02). Set by the
+ * decoder wire-in (push-chain-tx.ts) and by InsufficientUEABalanceError so
+ * consumers don't have to parse the message string.
+ */
+class PushChainExecutionError extends Error {
+    constructor(message, opts = {}) {
+        super(message);
+        this.code = 'PUSH_CHAIN_EXECUTION_FAILED';
+        this.name = 'PushChainExecutionError';
+        this.gatewayTxHash = opts.gatewayTxHash;
+        this.decodedError = opts.decodedError;
+    }
+}
+exports.PushChainExecutionError = PushChainExecutionError;
+/**
+ * Thrown by `runPreflight` when the UEA cannot cover the required outbound
+ * cost. No cosmos tx is submitted on this path — the existing silent-clamp
+ * behaviour was previously submitting under-funded swaps that reverted
+ * inside Uniswap with `Error("STF")`.
+ */
+class InsufficientUEABalanceError extends PushChainExecutionError {
+    constructor(opts) {
+        var _a;
+        const reason = (_a = opts.reason) !== null && _a !== void 0 ? _a : 'NATIVE';
+        const segLabel = opts.segmentIndex !== undefined ? `:seg${opts.segmentIndex}` : '';
+        const tokenSuffix = reason === 'PRC20' && opts.burnToken
+            ? ` of token ${opts.burnToken}`
+            : '';
+        const currencyLabel = reason === 'PRC20' ? 'units' : 'wei UPC';
+        const remediation = reason === 'PRC20'
+            ? `Bridge the burn token to UEA on Push Chain before retrying.`
+            : `Bridge >=${opts.shortfall} wei UPC to the UEA on Push Chain before retrying.`;
+        const message = `InsufficientUEABalance [${opts.pathTag}${segLabel}:${reason}]: ` +
+            `UEA ${opts.ueaAddress} has ${opts.available} ${currencyLabel}${tokenSuffix}; ` +
+            `outbound requires ${opts.required} ${currencyLabel}; shortfall ${opts.shortfall} ${currencyLabel}. ` +
+            remediation;
+        // Lift the structured info into the parent's decodedError so the
+        // orchestrator's outer catch can pass it straight through to the
+        // terminal failure hook payload (299-02 / 399-02 / 999-02) without
+        // parsing the message string.
+        super(message, {
+            decodedError: {
+                name: 'InsufficientUEABalance',
+                hint: remediation,
+            },
+        });
+        this.name = 'InsufficientUEABalanceError';
+        this.required = opts.required;
+        this.available = opts.available;
+        this.shortfall = opts.shortfall;
+        this.ueaAddress = opts.ueaAddress;
+        this.pathTag = opts.pathTag;
+        this.reason = reason;
+        this.burnToken = opts.burnToken;
+        this.segmentIndex = opts.segmentIndex;
+    }
+}
+exports.InsufficientUEABalanceError = InsufficientUEABalanceError;
+//# sourceMappingURL=errors.js.map

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

@@ -15,8 +15,8 @@ export declare const OUTBOUND_POLL_INTERVAL_MS = 3000;
 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;
+/** Initial wait before the first inbound poll (ms). Validator observation + Push commit + indexer ingestion realistically take 15-25 s on testnet (esp. SVM source), so polling immediately just burns RPC on guaranteed-empty results. */
+export declare const INBOUND_INITIAL_WAIT_MS = 15000;
 /**
  * Thrown by `waitForOutboundTx` when the polling loop exceeds the configured
  * timeout without observing an external tx hash. Callers can `instanceof`

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

@@ -30,8 +30,8 @@ exports.OUTBOUND_POLL_INTERVAL_MS = 3000; // 3s
 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;
+/** Initial wait before the first inbound poll (ms). Validator observation + Push commit + indexer ingestion realistically take 15-25 s on testnet (esp. SVM source), so polling immediately just burns RPC on guaranteed-empty results. */
+exports.INBOUND_INITIAL_WAIT_MS = 15000;
 // ============================================================================
 // Typed errors
 // ============================================================================

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

@@ -0,0 +1,80 @@
+/**
+ * Shared pre-flight balance check for all six outbound paths
+ * (R2 EVM, R2 SVM, R3 EVM, R3 SVM, Cascade EVM, Cascade SVM).
+ *
+ * Today the route handlers silently clamp `nativeValueForGas` down to a
+ * value the UEA cannot fully cover, then submit anyway. The under-funded
+ * swap reverts inside Uniswap V3's `TransferHelper.safeTransferFrom`
+ * with `Error("STF")`, fees are burned, and the user sees an opaque
+ * library string with no balance signal.
+ *
+ * `runPreflight` replaces that branch: it checks the **pre-clamp**
+ * buffered pool quote against UEA balance (and optionally a PRC-20 burn
+ * balance) and either:
+ *   - emits `SEND-TX-203-03` (INFO, sufficient) and lets the caller proceed; or
+ *   - emits `SEND-TX-203-03` (ERROR, insufficient) + `SEND-TX-203-04` and
+ *     throws `InsufficientUEABalanceError`.
+ *
+ * The helper is intentionally not "pure" — it emits hooks and may throw.
+ * Callers fetch all balances (so the helper itself does no I/O).
+ */
+import type { OrchestratorContext } from './context';
+import { type PreflightPathTag } from './errors';
+export interface RunPreflightOpts {
+    ctx: OrchestratorContext;
+    ueaAddress: `0x${string}`;
+    /** Effective UEA balance in wei UPC (already includes fresh-wallet prediction). */
+    ueaBalance: bigint;
+    /** Buffered pool quote (pre-clamp) — what the SDK would actually attempt. */
+    requiredValue: bigint;
+    /** Reserve covering outer-tx gas + approve(s). */
+    gasReserve: bigint;
+    pathTag: PreflightPathTag;
+    /** Optional: PRC-20 burn token + amount + on-chain UEA balance. */
+    burnToken?: `0x${string}`;
+    burnAmount?: bigint;
+    prc20Balance?: bigint;
+    /** Cascade-only: identifies which segment failed. */
+    segmentIndex?: number;
+    /**
+     * Per-call opt-out (`params.options.allowUnderfundedSwap`). When `true`,
+     * pre-flight logs the shortfall but does NOT fire 203-04 or throw —
+     * caller can fall back to the legacy clamp-and-refund branch.
+     */
+    allowUnderfundedSwap?: boolean;
+}
+export type PreflightResult = {
+    ok: true;
+    /** What `nativeValueForGas` should be (== requiredValue when sufficient). */
+    adjustedValue: bigint;
+} | {
+    ok: false;
+    /** Set when allowUnderfundedSwap=true: the legacy clamped value. */
+    legacyClampedValue: bigint;
+};
+/**
+ * Pre-flight check. PRC-20 balance is checked before the native check —
+ * a missing burn token fails before the gas-balance check, so the user
+ * sees the actionable PRC-20 shortfall instead of a stale UPC error.
+ *
+ * Returns a result object instead of throwing for the legacy opt-out
+ * path. The throw happens here (not in the caller) for the default
+ * `allowUnderfundedSwap=false` case so all 6 paths share one throw site.
+ */
+export declare function runPreflight(opts: RunPreflightOpts): PreflightResult;
+/**
+ * SVM-only telemetry threshold. Buffered pool quotes above this value
+ * fire `SEND-TX-203-05` (single-route) or `SEND-TX-003-05` (cascade).
+ * The threshold is for visibility, not truncation — pre-flight handles
+ * drain protection. v2 may add a hard cap once telemetry justifies a
+ * number.
+ */
+export declare const SVM_NATIVE_VALUE_WARN_THRESHOLD: bigint;
+/**
+ * Fire the SVM warn-threshold hook + log line if the buffered quote
+ * exceeds the threshold. Non-blocking; `nativeValueForGas` is not
+ * truncated by the caller. The hook ID switches to the cascade 0xx
+ * bucket (`003-05`) when `pathTag === 'CASCADE'` so cascade streams
+ * stay self-consistent.
+ */
+export declare function maybeFireSvmWarnThreshold(ctx: OrchestratorContext, bufferedQuote: bigint, gasToken: `0x${string}`, pathTag: PreflightPathTag): void;

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

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Shared pre-flight balance check for all six outbound paths
+ * (R2 EVM, R2 SVM, R3 EVM, R3 SVM, Cascade EVM, Cascade SVM).
+ *
+ * Today the route handlers silently clamp `nativeValueForGas` down to a
+ * value the UEA cannot fully cover, then submit anyway. The under-funded
+ * swap reverts inside Uniswap V3's `TransferHelper.safeTransferFrom`
+ * with `Error("STF")`, fees are burned, and the user sees an opaque
+ * library string with no balance signal.
+ *
+ * `runPreflight` replaces that branch: it checks the **pre-clamp**
+ * buffered pool quote against UEA balance (and optionally a PRC-20 burn
+ * balance) and either:
+ *   - emits `SEND-TX-203-03` (INFO, sufficient) and lets the caller proceed; or
+ *   - emits `SEND-TX-203-03` (ERROR, insufficient) + `SEND-TX-203-04` and
+ *     throws `InsufficientUEABalanceError`.
+ *
+ * The helper is intentionally not "pure" — it emits hooks and may throw.
+ * Callers fetch all balances (so the helper itself does no I/O).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SVM_NATIVE_VALUE_WARN_THRESHOLD = void 0;
+exports.runPreflight = runPreflight;
+exports.maybeFireSvmWarnThreshold = maybeFireSvmWarnThreshold;
+const context_1 = require("./context");
+const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
+const errors_1 = require("./errors");
+/**
+ * Internal: compute the legacy clamp value (matches the pre-existing
+ * branches in route-handlers.ts:643-659 / :968-980 / :1396-1412).
+ * Returned only when `allowUnderfundedSwap=true`.
+ */
+function legacyClamp(ueaBalance, requiredValue, gasReserve) {
+    if (ueaBalance >= requiredValue + gasReserve)
+        return requiredValue;
+    if (ueaBalance > gasReserve)
+        return ueaBalance - gasReserve;
+    if (ueaBalance > BigInt(0))
+        return ueaBalance < requiredValue ? ueaBalance : requiredValue;
+    return BigInt(0);
+}
+/**
+ * Pre-flight check. PRC-20 balance is checked before the native check —
+ * a missing burn token fails before the gas-balance check, so the user
+ * sees the actionable PRC-20 shortfall instead of a stale UPC error.
+ *
+ * Returns a result object instead of throwing for the legacy opt-out
+ * path. The throw happens here (not in the caller) for the default
+ * `allowUnderfundedSwap=false` case so all 6 paths share one throw site.
+ */
+function runPreflight(opts) {
+    const { ctx, ueaAddress, ueaBalance, requiredValue, gasReserve, pathTag, burnToken, burnAmount, prc20Balance, segmentIndex, allowUnderfundedSwap, } = opts;
+    // Cascade context emits 003-xx (cascade 0xx bucket); single routes (R2/R3)
+    // emit 203-xx (R2 bucket). The two ID sets share an identical formatter
+    // signature, so the runtime branching is just an ID swap at each fire site.
+    const isCascade = pathTag === 'CASCADE';
+    const HOOK_PRE_INFO = isCascade
+        ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_03
+        : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_03;
+    const HOOK_PRE_FAIL = isCascade
+        ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_04
+        : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_04;
+    // 1. PRC-20 burn-balance check (skipped when burnAmount = 0 — R3 paths
+    //    structurally hold zero of the source-chain native PRC-20; see plan §9 #4).
+    if (burnAmount && burnAmount > BigInt(0) && burnToken) {
+        const onHand = prc20Balance !== null && prc20Balance !== void 0 ? prc20Balance : BigInt(0);
+        const sufficient = onHand >= burnAmount;
+        (0, context_1.fireProgressHook)(ctx, HOOK_PRE_INFO, burnAmount, onHand, sufficient, ueaAddress, pathTag, { kind: 'PRC20', burnToken, segmentIndex });
+        if (!sufficient) {
+            const shortfall = burnAmount - onHand;
+            if (allowUnderfundedSwap) {
+                (0, context_1.printLog)(ctx, `[preflight ${pathTag}] PRC-20 shortfall ${shortfall} of ${burnToken}; ` +
+                    `allowUnderfundedSwap=true — proceeding with legacy clamp behaviour, ` +
+                    `swap is expected to revert with InsufficientBalance(0xf4d678b8) on-chain.`);
+                return {
+                    ok: false,
+                    legacyClampedValue: legacyClamp(ueaBalance, requiredValue, gasReserve),
+                };
+            }
+            (0, context_1.fireProgressHook)(ctx, HOOK_PRE_FAIL, burnAmount, onHand, shortfall, ueaAddress, pathTag, { kind: 'PRC20', burnToken, segmentIndex });
+            throw new errors_1.InsufficientUEABalanceError({
+                required: burnAmount,
+                available: onHand,
+                shortfall,
+                ueaAddress,
+                pathTag,
+                reason: 'PRC20',
+                burnToken,
+                segmentIndex,
+            });
+        }
+    }
+    // 2. Native (UPC) balance check.
+    const totalRequired = requiredValue + gasReserve;
+    const sufficient = ueaBalance >= totalRequired;
+    (0, context_1.fireProgressHook)(ctx, HOOK_PRE_INFO, totalRequired, ueaBalance, sufficient, ueaAddress, pathTag, { kind: 'NATIVE', segmentIndex });
+    if (sufficient) {
+        return { ok: true, adjustedValue: requiredValue };
+    }
+    const shortfall = totalRequired - ueaBalance;
+    if (allowUnderfundedSwap) {
+        const clamped = legacyClamp(ueaBalance, requiredValue, gasReserve);
+        (0, context_1.printLog)(ctx, `[preflight ${pathTag}] UPC shortfall ${shortfall} wei; ` +
+            `allowUnderfundedSwap=true — proceeding with legacy clamped value ${clamped}, ` +
+            `swap may revert inside Uniswap with Error("STF") if the clamp under-funds the pool quote.`);
+        return { ok: false, legacyClampedValue: clamped };
+    }
+    (0, context_1.fireProgressHook)(ctx, HOOK_PRE_FAIL, totalRequired, ueaBalance, shortfall, ueaAddress, pathTag, { kind: 'NATIVE', segmentIndex });
+    throw new errors_1.InsufficientUEABalanceError({
+        required: totalRequired,
+        available: ueaBalance,
+        shortfall,
+        ueaAddress,
+        pathTag,
+        reason: 'NATIVE',
+        segmentIndex,
+    });
+}
+/**
+ * SVM-only telemetry threshold. Buffered pool quotes above this value
+ * fire `SEND-TX-203-05` (single-route) or `SEND-TX-003-05` (cascade).
+ * The threshold is for visibility, not truncation — pre-flight handles
+ * drain protection. v2 may add a hard cap once telemetry justifies a
+ * number.
+ */
+exports.SVM_NATIVE_VALUE_WARN_THRESHOLD = BigInt(5000) * BigInt(1e18);
+/**
+ * Fire the SVM warn-threshold hook + log line if the buffered quote
+ * exceeds the threshold. Non-blocking; `nativeValueForGas` is not
+ * truncated by the caller. The hook ID switches to the cascade 0xx
+ * bucket (`003-05`) when `pathTag === 'CASCADE'` so cascade streams
+ * stay self-consistent.
+ */
+function maybeFireSvmWarnThreshold(ctx, bufferedQuote, gasToken, pathTag) {
+    if (bufferedQuote <= exports.SVM_NATIVE_VALUE_WARN_THRESHOLD)
+        return;
+    const HOOK_WARN = pathTag === 'CASCADE'
+        ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_05
+        : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_05;
+    (0, context_1.fireProgressHook)(ctx, HOOK_WARN, bufferedQuote, exports.SVM_NATIVE_VALUE_WARN_THRESHOLD, gasToken, pathTag);
+    (0, context_1.printLog)(ctx, `[preflight ${pathTag}] SVM warn-threshold tripped: bufferedQuote=${bufferedQuote} > ` +
+        `${exports.SVM_NATIVE_VALUE_WARN_THRESHOLD} for gasToken=${gasToken} — pool may be skewed`);
+}
+//# sourceMappingURL=preflight.js.map

package/src/lib/orchestrator/internals/push-chain-tx.d.ts

@@ -10,23 +10,8 @@ import { UniversalPayload } from '../../generated/v1/tx';
 import type { TxResponse } from '../../vm-client/vm-client.types';
 import type { ExecuteParams, UniversalTxResponse } from '../orchestrator.types';
 import type { OrchestratorContext } from './context';
-/**
- * Typed error for Route 1 Push Chain tx failures. Thrown by
- * `extractPcTxAndTransform` when the final pcTx commits with `status === 'FAILED'`,
- * and surfaced as `SEND_TX_199_02` on the live stream. The readonly `code`
- * discriminator lets callers classify via `instanceof PushChainExecutionError`
- * instead of sniffing error messages.
- *
- * Carries the origin-chain gateway tx hash. There is no successful Push Chain
- * tx to reference on this path — by definition the pcTx committed `FAILED`.
- */
-export declare class PushChainExecutionError extends Error {
-    readonly code: "PUSH_CHAIN_EXECUTION_FAILED";
-    readonly gatewayTxHash?: string;
-    constructor(message: string, opts?: {
-        gatewayTxHash?: string;
-    });
-}
+import { PushChainExecutionError } from './errors';
+export { PushChainExecutionError };
 type TransformToResponseFn = (tx: TxResponse, eventBuffer: ProgressEvent[]) => Promise<UniversalTxResponse>;
 /**
  * Sends an EVM transaction directly on Push Chain.
@@ -55,4 +40,3 @@ export declare function sendUniversalTx(ctx: OrchestratorContext, isUEADeployed:
  * and transforms to UniversalTxResponse.
  */
 export declare function extractPcTxAndTransform(ctx: OrchestratorContext, pushChainUniversalTx: UniversalTx | undefined, gatewayTxHash: string, eventBuffer: ProgressEvent[], label: string, transformFn: TransformToResponseFn): Promise<UniversalTxResponse>;
-export {};