@pushchain/core 5.1.17 → 6.0.0

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

@@ -16,6 +16,11 @@ const enums_1 = require("../../constants/enums");
 // ============================================================================
 // EIP-712 Domain Separator (shared by execution & migration hashes)
 // ============================================================================
+// NOTE: Push Chain testnet UEA implementation (UEA_VM[EVM] =
+// 0x4C8401F885c79b0e6e0241812f089e8529045d11) still uses the pre-audit
+// 4-field domain (typehash 0x2aef22f9…) — the salted post-audit typehash
+// 0xb90aaffa… in the audit-fixes contracts hasn't been deployed yet. Drop
+// `salt` until the contracts redeploy. See docs/audit-2026-05/sdk-changes-required.md#11.
 function buildDomainSeparator(vm, chainId, version, verifyingContract) {
     const domainTypeHash = (0, viem_1.keccak256)((0, viem_1.toBytes)(vm === enums_1.VM.EVM
         ? 'EIP712Domain(string version,uint256 chainId,address verifyingContract)'
@@ -23,12 +28,12 @@ function buildDomainSeparator(vm, chainId, version, verifyingContract) {
     return (0, viem_1.keccak256)((0, viem_1.encodeAbiParameters)([
         { name: 'typeHash', type: 'bytes32' },
         { name: 'version', type: 'bytes32' },
-        { name: 'chainId', type: vm === enums_1.VM.EVM ? 'uint256' : 'string' },
+        { name: 'chainId', type: vm === enums_1.VM.EVM ? 'uint256' : 'bytes32' },
         { name: 'verifyingContract', type: 'address' },
     ], [
         domainTypeHash,
         (0, viem_1.keccak256)((0, viem_1.toBytes)(version)),
-        vm === enums_1.VM.EVM ? BigInt(chainId) : chainId,
+        vm === enums_1.VM.EVM ? BigInt(chainId) : (0, viem_1.keccak256)((0, viem_1.toBytes)(chainId)),
         verifyingContract,
     ]));
 }

package/src/lib/orchestrator/internals/svm-helpers.js

@@ -82,7 +82,7 @@ function buildSvmUniversalTxRequestFromReq(req, revertRecipient, signatureDataOv
 // ============================================================================
 function getSvmProtocolFee(svmClient, programId) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e;
         const [feeVaultPda] = web3_js_1.PublicKey.findProgramAddressSync([(0, viem_1.stringToBytes)('fee_vault')], programId);
         try {
             const feeVault = yield svmClient.readContract({
@@ -91,10 +91,10 @@ function getSvmProtocolFee(svmClient, programId) {
                 functionName: 'feeVault',
                 args: [feeVaultPda.toBase58()],
             });
-            const protocolFeeLamports = BigInt((_c = (_b = ((_a = feeVault.protocolFeeLamports) !== null && _a !== void 0 ? _a : feeVault.protocol_fee_lamports)) === null || _b === void 0 ? void 0 : _b.toString()) !== null && _c !== void 0 ? _c : '0');
+            const protocolFeeLamports = BigInt((_e = (_d = ((_c = (_b = (_a = feeVault.inboundFeeLamports) !== null && _a !== void 0 ? _a : feeVault.inbound_fee_lamports) !== null && _b !== void 0 ? _b : feeVault.protocolFeeLamports) !== null && _c !== void 0 ? _c : feeVault.protocol_fee_lamports)) === null || _d === void 0 ? void 0 : _d.toString()) !== null && _e !== void 0 ? _e : '0');
             return { feeVaultPda, protocolFeeLamports };
         }
-        catch (_d) {
+        catch (_f) {
             return { feeVaultPda, protocolFeeLamports: BigInt(0) };
         }
     });

package/src/lib/orchestrator/internals/svm-rent.d.ts

@@ -1,5 +1,5 @@
 /**
- * Conditional CEA-ATA rent bump for SVM SPL outbounds.
+ * SVM finalize gas-budget helpers.
  *
  * The gateway program (svm-gateway) computes per-tx fees with a conditional
  * rent for first-time SPL transfers — see `calculateSplExecuteFees` in
@@ -7,21 +7,26 @@
  *
  *   const ataExists = await ceaAtaExists(connection, ceaAta);
  *   const ceaAtaRent = ataExists ? 0n : BigInt(getMinimumBalanceForRentExemption(165));
- *   gasFee = executedTxRent + ceaAtaRent + COMPUTE_BUFFER;
+ *   gasFee = signatureFee + executedTxRent + ceaAtaRent + COMPUTE_BUFFER;
  *
  * The gateway's on-chain `getOutboundTxGasAndFees` quote does NOT factor in
  * the ATA rent today, so the SDK has to bump `effectiveGasLimit` itself
- * before calling that quote. Native-SOL outbounds use `calculateSolExecuteFees`
- * which has no conditional rent, so no SDK bump is needed there.
+ * before building the outbound request. Native-SOL outbounds still need the
+ * same base finalize budget plus compute buffer.
  */
 import { PublicKey } from '@solana/web3.js';
 import type { OrchestratorContext } from './context';
 import type { CHAIN as ChainType } from '../../constants/enums';
-/** ATA rent (165-byte SPL token account) + executed-tx rent (8-byte) + compute buffer.
- *  Mirrors getMinimumBalanceForRentExemption(165) ≈ 2_039_280
- *       + getMinimumBalanceForRentExemption(8) ≈ 9_200
- *       + COMPUTE_BUFFER 100_000.
- *  Signature fee (5_000) is already included in the gateway's base quote. */
+import { queryOutboundGasFee } from './gas-calculator';
+/** Base Solana fee per relayer signature, mirrored from SVM gateway execute.rs. */
+export declare const SVM_SIGNATURE_FEE_LAMPORTS: bigint;
+/** Operational buffer used by SVM gateway tests for tx fees / compute. */
+export declare const SVM_FINALIZE_COMPUTE_BUFFER_LAMPORTS: bigint;
+/** Devnet/mainnet rent-exempt minimum for ExecutedSubTx::LEN = 8 bytes. */
+export declare const SVM_EXECUTED_SUB_TX_RENT_FALLBACK: bigint;
+/** Devnet/mainnet rent-exempt minimum for a 165-byte SPL token account. */
+export declare const SVM_TOKEN_ACCOUNT_RENT_FALLBACK: bigint;
+/** Back-compat export for older tests/callers: ATA rent + base finalization overhead. */
 export declare const CEA_ATA_RENT_LAMPORTS_BUMP: bigint;
 /** Derive CEA PDA from a 20-byte EVM address. Seeds: ["push_identity", evmBytes]. */
 export declare function deriveSvmCeaPda(evmAddress: `0x${string}`): PublicKey;
@@ -37,6 +42,33 @@ export interface MaybeBumpInput {
     burnAmount: bigint;
     effectiveGasLimit: bigint;
 }
+export interface SvmFinalizeGasBudgetInput {
+    ctx: OrchestratorContext;
+    ueaAddress: `0x${string}`;
+    targetChain: ChainType;
+    /** SPL mint as base58. undefined means native SOL / no SPL staging. */
+    splMintBase58: string | undefined;
+    /** Burn amount in token units. 0 means no SPL staging. */
+    burnAmount: bigint;
+}
+export declare function gasLimitForSvmGasFeeBudget(gasFeeBudget: bigint, gasPrice: bigint): bigint;
+type OutboundGasQuote = Awaited<ReturnType<typeof queryOutboundGasFee>>;
+export declare function ensureSvmFinalizeGasBudgetQuote({ ctx, ueaAddress, targetChain, prc20Token, quote, splMintBase58, burnAmount, pathTag, }: {
+    ctx: OrchestratorContext;
+    ueaAddress: `0x${string}`;
+    targetChain: ChainType;
+    prc20Token: `0x${string}`;
+    quote: OutboundGasQuote;
+    splMintBase58: string | undefined;
+    burnAmount: bigint;
+    pathTag: string;
+}): Promise<OutboundGasQuote>;
+/**
+ * Returns the minimum SVM `gas_fee` budget in lamports for the gateway
+ * finalize instruction, including a small compute buffer. If RPC is not
+ * available, falls back to Solana protocol rent constants.
+ */
+export declare function getSvmFinalizeGasBudget(input: SvmFinalizeGasBudgetInput): Promise<bigint>;
 /**
  * Returns the (possibly bumped) effectiveGasLimit. Logs the decision via
  * printLog. On any RPC failure or invalid input, logs a warning and returns
@@ -44,3 +76,4 @@ export interface MaybeBumpInput {
  * outbounds on RPC flake; pre-flight will surface insufficient gas anyway.
  */
 export declare function maybeBumpForCeaAtaRent(input: MaybeBumpInput): Promise<bigint>;
+export {};

package/src/lib/orchestrator/internals/svm-rent.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CEA_ATA_RENT_LAMPORTS_BUMP = void 0;
+exports.CEA_ATA_RENT_LAMPORTS_BUMP = exports.SVM_TOKEN_ACCOUNT_RENT_FALLBACK = exports.SVM_EXECUTED_SUB_TX_RENT_FALLBACK = exports.SVM_FINALIZE_COMPUTE_BUFFER_LAMPORTS = exports.SVM_SIGNATURE_FEE_LAMPORTS = void 0;
 exports.deriveSvmCeaPda = deriveSvmCeaPda;
 exports.deriveAtaPubkey = deriveAtaPubkey;
+exports.gasLimitForSvmGasFeeBudget = gasLimitForSvmGasFeeBudget;
+exports.ensureSvmFinalizeGasBudgetQuote = ensureSvmFinalizeGasBudgetQuote;
+exports.getSvmFinalizeGasBudget = getSvmFinalizeGasBudget;
 exports.maybeBumpForCeaAtaRent = maybeBumpForCeaAtaRent;
 const tslib_1 = require("tslib");
 /**
- * Conditional CEA-ATA rent bump for SVM SPL outbounds.
+ * SVM finalize gas-budget helpers.
  *
  * The gateway program (svm-gateway) computes per-tx fees with a conditional
  * rent for first-time SPL transfers — see `calculateSplExecuteFees` in
@@ -14,31 +17,40 @@ const tslib_1 = require("tslib");
  *
  *   const ataExists = await ceaAtaExists(connection, ceaAta);
  *   const ceaAtaRent = ataExists ? 0n : BigInt(getMinimumBalanceForRentExemption(165));
- *   gasFee = executedTxRent + ceaAtaRent + COMPUTE_BUFFER;
+ *   gasFee = signatureFee + executedTxRent + ceaAtaRent + COMPUTE_BUFFER;
  *
  * The gateway's on-chain `getOutboundTxGasAndFees` quote does NOT factor in
  * the ATA rent today, so the SDK has to bump `effectiveGasLimit` itself
- * before calling that quote. Native-SOL outbounds use `calculateSolExecuteFees`
- * which has no conditional rent, so no SDK bump is needed there.
+ * before building the outbound request. Native-SOL outbounds still need the
+ * same base finalize budget plus compute buffer.
  */
 const web3_js_1 = require("@solana/web3.js");
 const buffer_1 = require("buffer");
 const context_1 = require("./context");
 const chain_1 = require("../../constants/chain");
+const gas_calculator_1 = require("./gas-calculator");
 // ---------------------------------------------------------------------------
 // Constants — mirror gateway test-utils.ts. These are SOL protocol values;
 // they only change if Solana itself adjusts rent rates (effectively never).
 // ---------------------------------------------------------------------------
-/** ATA rent (165-byte SPL token account) + executed-tx rent (8-byte) + compute buffer.
- *  Mirrors getMinimumBalanceForRentExemption(165) ≈ 2_039_280
- *       + getMinimumBalanceForRentExemption(8) ≈ 9_200
- *       + COMPUTE_BUFFER 100_000.
- *  Signature fee (5_000) is already included in the gateway's base quote. */
-exports.CEA_ATA_RENT_LAMPORTS_BUMP = BigInt(2148480);
+/** Base Solana fee per relayer signature, mirrored from SVM gateway execute.rs. */
+exports.SVM_SIGNATURE_FEE_LAMPORTS = BigInt(5000);
+/** Operational buffer used by SVM gateway tests for tx fees / compute. */
+exports.SVM_FINALIZE_COMPUTE_BUFFER_LAMPORTS = BigInt(100000);
+/** Devnet/mainnet rent-exempt minimum for ExecutedSubTx::LEN = 8 bytes. */
+exports.SVM_EXECUTED_SUB_TX_RENT_FALLBACK = BigInt(946560);
+/** Devnet/mainnet rent-exempt minimum for a 165-byte SPL token account. */
+exports.SVM_TOKEN_ACCOUNT_RENT_FALLBACK = BigInt(2039280);
+/** Back-compat export for older tests/callers: ATA rent + base finalization overhead. */
+exports.CEA_ATA_RENT_LAMPORTS_BUMP = exports.SVM_SIGNATURE_FEE_LAMPORTS +
+    exports.SVM_EXECUTED_SUB_TX_RENT_FALLBACK +
+    exports.SVM_TOKEN_ACCOUNT_RENT_FALLBACK +
+    exports.SVM_FINALIZE_COMPUTE_BUFFER_LAMPORTS;
 /** SVM gateway program ID (matches CHAIN_INFO[SOLANA_DEVNET].lockerContract). */
 const SVM_GATEWAY_PROGRAM = new web3_js_1.PublicKey('CFVSincHYbETh2k7w6u1ENEkjbSLtveRCEBupKidw2VS');
 const TOKEN_PROGRAM_ID = new web3_js_1.PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
 const ASSOCIATED_TOKEN_PROGRAM_ID = new web3_js_1.PublicKey('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL');
+const SVM_RENT_RPC_TIMEOUT_MS = 3000;
 // ---------------------------------------------------------------------------
 // PDA derivations
 // ---------------------------------------------------------------------------
@@ -53,6 +65,129 @@ function deriveAtaPubkey(owner, mint) {
     const [ata] = web3_js_1.PublicKey.findProgramAddressSync([owner.toBuffer(), TOKEN_PROGRAM_ID.toBuffer(), mint.toBuffer()], ASSOCIATED_TOKEN_PROGRAM_ID);
     return ata;
 }
+function getRpcUrl(ctx, targetChain) {
+    var _a, _b, _c, _d, _e;
+    return ((_c = (_b = (_a = ctx.rpcUrls) === null || _a === void 0 ? void 0 : _a[targetChain]) === null || _b === void 0 ? void 0 : _b[0]) !== null && _c !== void 0 ? _c : (_e = (_d = chain_1.CHAIN_INFO[targetChain]) === null || _d === void 0 ? void 0 : _d.defaultRPC) === null || _e === void 0 ? void 0 : _e[0]);
+}
+function isAccountInitialized(info) {
+    return info !== null && info.data.length > 0;
+}
+function withSvmRentRpcTimeout(promise, label) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        let timer;
+        try {
+            return yield Promise.race([
+                promise,
+                new Promise((_, reject) => {
+                    var _a, _b;
+                    timer = setTimeout(() => reject(new Error(`${label} timed out after ${SVM_RENT_RPC_TIMEOUT_MS}ms`)), SVM_RENT_RPC_TIMEOUT_MS);
+                    (_b = (_a = timer).unref) === null || _b === void 0 ? void 0 : _b.call(_a);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    });
+}
+function gasLimitForSvmGasFeeBudget(gasFeeBudget, gasPrice) {
+    if (gasPrice <= BigInt(0)) {
+        throw new Error(`Cannot derive SVM gasLimit from gasPrice=${gasPrice.toString()}`);
+    }
+    return (gasFeeBudget + gasPrice - BigInt(1)) / gasPrice;
+}
+function ensureSvmFinalizeGasBudgetQuote(_a) {
+    return tslib_1.__awaiter(this, arguments, void 0, function* ({ ctx, ueaAddress, targetChain, prc20Token, quote, splMintBase58, burnAmount, pathTag, }) {
+        const minGasFee = yield getSvmFinalizeGasBudget({
+            ctx,
+            ueaAddress,
+            targetChain,
+            splMintBase58,
+            burnAmount,
+        });
+        if (quote.gasFee >= minGasFee) {
+            (0, context_1.printLog)(ctx, `${pathTag} — SVM finalize gas budget ok: gasFee=${quote.gasFee.toString()}, ` +
+                `minimum=${minGasFee.toString()}, gasLimit=${quote.gasLimitUsed.toString()}`);
+            return quote;
+        }
+        const bumpedGasLimit = gasLimitForSvmGasFeeBudget(minGasFee, quote.gasPrice);
+        (0, context_1.printLog)(ctx, `${pathTag} — bumping SVM gasLimit ${quote.gasLimitUsed.toString()} → ${bumpedGasLimit.toString()}; ` +
+            `gasFee=${quote.gasFee.toString()} below finalize minimum=${minGasFee.toString()}`);
+        const bumpedQuote = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, bumpedGasLimit, targetChain);
+        if (bumpedQuote.gasFee < minGasFee) {
+            (0, context_1.printLog)(ctx, `${pathTag} — WARNING: bumped SVM gasFee=${bumpedQuote.gasFee.toString()} ` +
+                `still below finalize minimum=${minGasFee.toString()}`);
+        }
+        return bumpedQuote;
+    });
+}
+/**
+ * Returns the minimum SVM `gas_fee` budget in lamports for the gateway
+ * finalize instruction, including a small compute buffer. If RPC is not
+ * available, falls back to Solana protocol rent constants.
+ */
+function getSvmFinalizeGasBudget(input) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const { ctx, ueaAddress, targetChain, splMintBase58, burnAmount } = input;
+        const needsSplAta = Boolean(splMintBase58) && burnAmount > BigInt(0);
+        const rpcUrl = getRpcUrl(ctx, targetChain);
+        let executedTxRent = exports.SVM_EXECUTED_SUB_TX_RENT_FALLBACK;
+        let ataRent = BigInt(0);
+        if (!needsSplAta) {
+            const budget = exports.SVM_SIGNATURE_FEE_LAMPORTS +
+                executedTxRent +
+                ataRent +
+                exports.SVM_FINALIZE_COMPUTE_BUFFER_LAMPORTS;
+            (0, context_1.printLog)(ctx, `getSvmFinalizeGasBudget — no SPL ATA needed for ${targetChain}; ` +
+                `using fallback base budget ${budget.toString()}`);
+            return budget;
+        }
+        if (!rpcUrl) {
+            ataRent = exports.SVM_TOKEN_ACCOUNT_RENT_FALLBACK;
+            (0, context_1.printLog)(ctx, `getSvmFinalizeGasBudget — no Solana RPC URL for ${targetChain}; ` +
+                `using fallback budget ${(exports.SVM_SIGNATURE_FEE_LAMPORTS +
+                    executedTxRent +
+                    ataRent +
+                    exports.SVM_FINALIZE_COMPUTE_BUFFER_LAMPORTS).toString()}`);
+            return (exports.SVM_SIGNATURE_FEE_LAMPORTS +
+                executedTxRent +
+                ataRent +
+                exports.SVM_FINALIZE_COMPUTE_BUFFER_LAMPORTS);
+        }
+        try {
+            const conn = new web3_js_1.Connection(rpcUrl, 'confirmed');
+            executedTxRent = BigInt(yield withSvmRentRpcTimeout(conn.getMinimumBalanceForRentExemption(8), 'getMinimumBalanceForRentExemption(8)'));
+            if (needsSplAta && splMintBase58) {
+                const ceaPda = deriveSvmCeaPda(ueaAddress);
+                const splMint = new web3_js_1.PublicKey(splMintBase58);
+                const ceaAta = deriveAtaPubkey(ceaPda, splMint);
+                const info = yield withSvmRentRpcTimeout(conn.getAccountInfo(ceaAta), `getAccountInfo(${ceaAta.toBase58()})`);
+                if (!isAccountInitialized(info)) {
+                    ataRent = BigInt(yield withSvmRentRpcTimeout(conn.getMinimumBalanceForRentExemption(165), 'getMinimumBalanceForRentExemption(165)'));
+                    (0, context_1.printLog)(ctx, `getSvmFinalizeGasBudget — CEA ATA ${ceaAta.toBase58()} not deployed on ${targetChain}; ` +
+                        `including ${ataRent.toString()} lamports ATA rent`);
+                }
+                else {
+                    (0, context_1.printLog)(ctx, `getSvmFinalizeGasBudget — CEA ATA ${ceaAta.toBase58()} already deployed on ${targetChain}; no ATA rent`);
+                }
+            }
+        }
+        catch (err) {
+            ataRent = exports.SVM_TOKEN_ACCOUNT_RENT_FALLBACK;
+            (0, context_1.printLog)(ctx, `getSvmFinalizeGasBudget — RPC error on ${targetChain}: ` +
+                `${err instanceof Error ? err.message : String(err)}; using fallback rents`);
+        }
+        const budget = exports.SVM_SIGNATURE_FEE_LAMPORTS +
+            executedTxRent +
+            ataRent +
+            exports.SVM_FINALIZE_COMPUTE_BUFFER_LAMPORTS;
+        (0, context_1.printLog)(ctx, `getSvmFinalizeGasBudget — budget=${budget.toString()} ` +
+            `(signature=${exports.SVM_SIGNATURE_FEE_LAMPORTS}, executedTxRent=${executedTxRent}, ataRent=${ataRent}, ` +
+            `computeBuffer=${exports.SVM_FINALIZE_COMPUTE_BUFFER_LAMPORTS})`);
+        return budget;
+    });
+}
 /**
  * Returns the (possibly bumped) effectiveGasLimit. Logs the decision via
  * printLog. On any RPC failure or invalid input, logs a warning and returns
@@ -61,14 +196,13 @@ function deriveAtaPubkey(owner, mint) {
  */
 function maybeBumpForCeaAtaRent(input) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e;
         const { ctx, ueaAddress, targetChain, splMintBase58, burnAmount, effectiveGasLimit, } = input;
         // Only applies to SPL outbounds. Native SOL outbounds use the gateway's
         // calculateSolExecuteFees which has no ATA conditional.
         if (!splMintBase58 || burnAmount === BigInt(0)) {
             return effectiveGasLimit;
         }
-        const rpcUrl = (_c = (_b = (_a = ctx.rpcUrls) === null || _a === void 0 ? void 0 : _a[targetChain]) === null || _b === void 0 ? void 0 : _b[0]) !== null && _c !== void 0 ? _c : (_e = (_d = chain_1.CHAIN_INFO[targetChain]) === null || _d === void 0 ? void 0 : _d.defaultRPC) === null || _e === void 0 ? void 0 : _e[0];
+        const rpcUrl = getRpcUrl(ctx, targetChain);
         if (!rpcUrl) {
             (0, context_1.printLog)(ctx, `maybeBumpForCeaAtaRent — no Solana RPC URL for ${targetChain}; skipping rent bump`);
             return effectiveGasLimit;
@@ -78,7 +212,7 @@ function maybeBumpForCeaAtaRent(input) {
             const splMint = new web3_js_1.PublicKey(splMintBase58);
             const ceaAta = deriveAtaPubkey(ceaPda, splMint);
             const conn = new web3_js_1.Connection(rpcUrl, 'confirmed');
-            const info = yield conn.getAccountInfo(ceaAta);
+            const info = yield withSvmRentRpcTimeout(conn.getAccountInfo(ceaAta), `getAccountInfo(${ceaAta.toBase58()})`);
             const ataExists = info !== null && info.data.length > 0;
             if (!ataExists) {
                 const bumped = effectiveGasLimit + exports.CEA_ATA_RENT_LAMPORTS_BUMP;

package/src/lib/orchestrator/internals/tx-transformer.js

@@ -16,6 +16,7 @@ const types_1 = require("../../generated/uexecutor/v1/types");
 const types_2 = require("../../generated/uexecutor/v2/types");
 const progress_hook_1 = tslib_1.__importDefault(require("../../progress-hook/progress-hook"));
 const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
+const formatters_1 = require("../../formatters");
 const payload_builders_1 = require("../payload-builders");
 const route_detector_1 = require("../route-detector");
 // ============================================================================
@@ -58,9 +59,12 @@ function reconstructProgressEvents(universalTxResponse, universalTxData) {
     // scoped phase ('outbound' + source-chain). Emitting in both places
     // would double-fire the terminal with a misleading 'push' title on top.
     const isFailed = isPcFailed || isOutboundFailed;
+    const pcErrorMsg = (pcTx === null || pcTx === void 0 ? void 0 : pcTx.errorMsg)
+        ? (0, formatters_1.normalizePcInsufficientFundsError)(pcTx.errorMsg)
+        : 'Unknown error';
     const errorMsg = isOutboundFailed
         ? 'Outbound transaction failed (status: OUTBOUND_FAILED)'
-        : ((pcTx === null || pcTx === void 0 ? void 0 : pcTx.errorMsg) || 'Unknown error');
+        : pcErrorMsg;
     // Route 2 / 3 reconstruction — keep parity with live emission from
     // route-handlers.ts (which fires 201/203/207 or 301/303/307 then suppresses
     // R1 IDs via fireProgressHook). Skip the R1 101–107 sequence here; it would
@@ -70,7 +74,6 @@ function reconstructProgressEvents(universalTxResponse, universalTxData) {
     // leg itself failed — so prefer pcTx.errorMsg over the outbound-failed
     // sentinel. The outer `errorMsg` above carries the outbound text when
     // `isOutboundFailed` is set; that path is handled by wait() instead.
-    const pcErrorMsg = (pcTx === null || pcTx === void 0 ? void 0 : pcTx.errorMsg) || 'Unknown error';
     // Multichain cascade: a single Push-chain tx that fanned out into >1
     // outbound legs (executeTransactions([tx1, tx2, …])). The cosmos record
     // carries one UniversalTx with multiple outboundTx entries; wrap the

package/src/lib/orchestrator/max-pc-for-gas.d.ts

@@ -0,0 +1,60 @@
+export declare const DEFAULT_MAX_PC_FOR_GAS_BUFFER_BPS = 1000;
+export declare const MAX_PC_FOR_GAS_BUFFER_BPS_LIMIT = 10000;
+export interface MaxPCForGasCapInput {
+    /**
+     * Native PC estimate intended for the gas-token swap, excluding protocolFee.
+     */
+    gasLegNativePc: bigint;
+    /**
+     * Protocol fee returned by UniversalCore. Included in nativeValueForGas but
+     * excluded from maxPCForGas because UGPC subtracts it before applying the cap.
+     */
+    protocolFee?: bigint;
+    /**
+     * Slippage buffer in basis points. Defaults to 1000 bps (10%).
+     */
+    bufferBps?: number;
+}
+export interface MaxPCForGasCapFromNativeValueInput {
+    /**
+     * Total native PC value planned for sendUniversalTxOutbound msg.value.
+     */
+    nativeValueForGas: bigint;
+    /**
+     * Protocol fee returned by UniversalCore.
+     */
+    protocolFee: bigint;
+    /**
+     * Slippage buffer in basis points. Defaults to 1000 bps (10%).
+     */
+    bufferBps?: number;
+}
+export interface MaxPCForGasCapQuote {
+    /**
+     * Value to pass as UniversalExecuteParams.maxPCForGas.
+     */
+    maxPCForGas: bigint;
+    /**
+     * Minimum native PC msg.value that satisfies the cap:
+     * protocolFee + maxPCForGas.
+     */
+    nativeValueForGas: bigint;
+    /**
+     * Gas-swap leg before the buffer, excluding protocolFee.
+     */
+    gasLegNativePc: bigint;
+    protocolFee: bigint;
+    bufferBps: number;
+}
+/**
+ * Builds a contract-safe maxPCForGas cap from a native PC gas-leg estimate.
+ *
+ * UGPC validates maxPCForGas against `msg.value - protocolFee`, so the helper
+ * returns the minimum matching nativeValueForGas as well as the cap.
+ */
+export declare function quoteMaxPCForGasCap(input: MaxPCForGasCapInput): MaxPCForGasCapQuote;
+/**
+ * Builds a maxPCForGas cap from queryOutboundGasFee's nativeValueForGas and
+ * protocolFee fields.
+ */
+export declare function quoteMaxPCForGasCapFromNativeValue(input: MaxPCForGasCapFromNativeValueInput): MaxPCForGasCapQuote;

package/src/lib/orchestrator/max-pc-for-gas.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PC_FOR_GAS_BUFFER_BPS_LIMIT = exports.DEFAULT_MAX_PC_FOR_GAS_BUFFER_BPS = void 0;
+exports.quoteMaxPCForGasCap = quoteMaxPCForGasCap;
+exports.quoteMaxPCForGasCapFromNativeValue = quoteMaxPCForGasCapFromNativeValue;
+const BPS_DENOMINATOR = BigInt(10000);
+exports.DEFAULT_MAX_PC_FOR_GAS_BUFFER_BPS = 1000;
+exports.MAX_PC_FOR_GAS_BUFFER_BPS_LIMIT = 10000;
+/**
+ * Builds a contract-safe maxPCForGas cap from a native PC gas-leg estimate.
+ *
+ * UGPC validates maxPCForGas against `msg.value - protocolFee`, so the helper
+ * returns the minimum matching nativeValueForGas as well as the cap.
+ */
+function quoteMaxPCForGasCap(input) {
+    var _a;
+    assertNonNegativeBigInt('gasLegNativePc', input.gasLegNativePc);
+    const protocolFee = (_a = input.protocolFee) !== null && _a !== void 0 ? _a : BigInt(0);
+    assertNonNegativeBigInt('protocolFee', protocolFee);
+    const bufferBps = normalizeBufferBps(input.bufferBps);
+    const maxPCForGas = applyBufferCeil(input.gasLegNativePc, bufferBps);
+    return {
+        maxPCForGas,
+        nativeValueForGas: protocolFee + maxPCForGas,
+        gasLegNativePc: input.gasLegNativePc,
+        protocolFee,
+        bufferBps,
+    };
+}
+/**
+ * Builds a maxPCForGas cap from queryOutboundGasFee's nativeValueForGas and
+ * protocolFee fields.
+ */
+function quoteMaxPCForGasCapFromNativeValue(input) {
+    assertNonNegativeBigInt('nativeValueForGas', input.nativeValueForGas);
+    assertNonNegativeBigInt('protocolFee', input.protocolFee);
+    if (input.nativeValueForGas < input.protocolFee) {
+        throw new RangeError('nativeValueForGas must be greater than or equal to protocolFee');
+    }
+    return quoteMaxPCForGasCap({
+        gasLegNativePc: input.nativeValueForGas - input.protocolFee,
+        protocolFee: input.protocolFee,
+        bufferBps: input.bufferBps,
+    });
+}
+function normalizeBufferBps(bufferBps) {
+    const normalized = bufferBps !== null && bufferBps !== void 0 ? bufferBps : exports.DEFAULT_MAX_PC_FOR_GAS_BUFFER_BPS;
+    if (!Number.isInteger(normalized) ||
+        normalized < 0 ||
+        normalized > exports.MAX_PC_FOR_GAS_BUFFER_BPS_LIMIT) {
+        throw new RangeError(`bufferBps must be an integer between 0 and ${exports.MAX_PC_FOR_GAS_BUFFER_BPS_LIMIT}`);
+    }
+    return normalized;
+}
+function applyBufferCeil(amount, bufferBps) {
+    if (amount === BigInt(0))
+        return BigInt(0);
+    const multiplier = BPS_DENOMINATOR + BigInt(bufferBps);
+    return (amount * multiplier + BPS_DENOMINATOR - BigInt(1)) / BPS_DENOMINATOR;
+}
+function assertNonNegativeBigInt(name, value) {
+    if (value < BigInt(0)) {
+        throw new RangeError(`${name} must be non-negative`);
+    }
+}
+//# sourceMappingURL=max-pc-for-gas.js.map

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

@@ -85,9 +85,15 @@ export declare class Orchestrator {
      * The cascade composes all hops bottom-to-top into a single Push Chain tx.
      *
      * @param preparedTxs - Array of prepared transactions
+     * @param options - Optional per-call options. `progressHook` is additive with
+     *   the init-time hook from `PushChain.initialize` and receives every
+     *   `ProgressEvent` emitted during this cascade (pre-flight, broadcast, and
+     *   tracking). Dedups by reference if it matches the init-time hook.
      * @returns Object with send() method
      */
-    createCascadedBuilder(preparedTxs: PreparedUniversalTx[]): {
+    createCascadedBuilder(preparedTxs: PreparedUniversalTx[], options?: {
+        progressHook?: (event: ProgressEvent) => void;
+    }): {
         send: () => Promise<CascadedTxResponse>;
     };
     /**
@@ -99,6 +105,7 @@ export declare class Orchestrator {
         protocolFee: bigint;
         nativeValueForGas: bigint;
         gasPrice: bigint;
+        gasLimitUsed: bigint;
     }>;
     /**
        * Extracts the first universal sub-tx ID from a Push Chain transaction's Cosmos events.

package/src/lib/orchestrator/orchestrator.js

@@ -30,6 +30,7 @@ class Orchestrator {
         return {
             executeFn: this.execute.bind(this),
             waitForOutboundTxFn: (hash, opts) => (0, internals_1.waitForOutboundTx)(this.ctx, hash, opts),
+            waitForInboundPushTxFn: (hash, sourceChain, opts) => (0, internals_1.waitForInboundPushTx)(this.ctx, hash, sourceChain, opts),
             waitForAllOutboundTxsFn: (hash, hops, opts) => (0, internals_1.waitForAllOutboundTxsV2)(this.ctx, hash, hops, opts),
         };
     }
@@ -296,10 +297,47 @@ class Orchestrator {
      * The cascade composes all hops bottom-to-top into a single Push Chain tx.
      *
      * @param preparedTxs - Array of prepared transactions
+     * @param options - Optional per-call options. `progressHook` is additive with
+     *   the init-time hook from `PushChain.initialize` and receives every
+     *   `ProgressEvent` emitted during this cascade (pre-flight, broadcast, and
+     *   tracking). Dedups by reference if it matches the init-time hook.
      * @returns Object with send() method
      */
-    createCascadedBuilder(preparedTxs) {
-        return (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks());
+    createCascadedBuilder(preparedTxs, options) {
+        const perCallHook = options === null || options === void 0 ? void 0 : options.progressHook;
+        if (!perCallHook) {
+            return (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks());
+        }
+        // Wrap ctx.progressHook for the synchronous send() phase — captures every
+        // fireProgressHook(ctx, ...) call during pre-flight, composeCascade, and
+        // the Push Chain broadcast. Restored when send() resolves/rejects so the
+        // wrapper doesn't leak across calls.
+        //
+        // For the asynchronous tracking phase (waitForAll), we pass perCallHook as
+        // the cascade builder's `defaultEventHook` — waitForAll falls back to it
+        // when callers don't pass their own `eventHook`, and the existing
+        // `dispatchCascadeProgressEvent` path delivers events to BOTH that hook
+        // and ctx.progressHook (the init-time hook, restored by then) with
+        // reference-dedup.
+        const innerBuilder = (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks(), perCallHook);
+        return {
+            send: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                const originalHook = this.progressHook;
+                const wrapped = (event) => {
+                    if (originalHook && originalHook !== perCallHook) {
+                        originalHook(event);
+                    }
+                    perCallHook(event);
+                };
+                this.progressHook = wrapped;
+                try {
+                    return yield innerBuilder.send();
+                }
+                finally {
+                    this.progressHook = originalHook;
+                }
+            }),
+        };
     }
     /**
      * Queries gas fee for an outbound transaction from the UniversalCore contract.