@pushchain/core 5.1.18 → 6.0.0

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

@@ -105,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.types.d.ts

@@ -50,6 +50,12 @@ export type ExecuteParams = {
      * @reason Prevents runaway gas consumption and lets users enforce limits.
      */
     gasLimit?: bigint;
+    /**
+     * Optional cap on native PC used for outbound gas swap.
+     * Applies only to Push -> external-chain outbound legs. Omit or set 0n for
+     * uncapped legacy behavior.
+     */
+    maxPCForGas?: bigint;
     /**
      * Optional override for the EIP-1559 max fee per gas (in wei).
      * @reason Gives callers direct control over total gas price to speed up or save cost.
@@ -426,25 +432,26 @@ export interface SvmExecutePayloadFields {
  * Request structure for sendUniversalTxOutbound on Push Chain
  * Used for Routes 2, 3, 4 (outbound from Push)
  *
- * NOTE: The `target` field is a LEGACY parameter for contract compatibility.
- * The deployed UniversalGatewayPC contract still expects this field, but it will
- * be removed in future contract upgrades. Pass any non-zero address (e.g., CEA address).
- * The actual destination is determined by the relay from the token's SOURCE_CHAIN_NAMESPACE.
+ * NOTE: The `target` field is raw recipient bytes for the destination chain.
+ * For EVM CEA funds-parking, use the zero recipient when `payload` is empty.
  */
 export interface UniversalOutboundTxRequest {
     /**
-     * LEGACY/DUMMY: Raw destination address bytes for contract compatibility.
-     * Pass any non-zero address - this value is NOT used by the relay to determine
-     * the actual transaction destination. Will be removed in future contract upgrades.
+     * Raw destination recipient bytes. EVM routes usually pass a 20-byte address;
+     * SVM routes pass a 32-byte program/account address.
      */
     target: `0x${string}`;
     /** PRC20 token address on Push Chain to burn */
     token: `0x${string}`;
     /** Amount to burn (0 for no-burn, use existing CEA balance) */
     amount: bigint;
-    /** Gas limit for fee quote (0 = default BASE_GAS_LIMIT) */
+    /** Gas limit for fee quote (0 = per-chain default resolved by UniversalCore) */
     gasLimit: bigint;
-    /** Raw ABI-encoded Multicall[] (no selector prefix) */
+    /** Gas price override for destination-chain gas (0 = UniversalCore default) */
+    gasPrice: bigint;
+    /** Max native PC that may be used for gas swap (0 = uncapped legacy behavior) */
+    maxPCForGas: bigint;
+    /** Destination execution payload; empty only for explicit funds parking */
     payload: `0x${string}`;
     /** Address to receive funds on revert */
     revertRecipient: `0x${string}`;
@@ -488,8 +495,12 @@ export interface HopDescriptor {
     gasToken?: `0x${string}`;
     /** Gas fee amount in gas token */
     gasFee?: bigint;
+    /** Destination-chain gas price quoted by UniversalCore */
+    gasPrice?: bigint;
     /** Gas limit for outbound relay */
     gasLimit: bigint;
+    /** Max native PC used for outbound gas swap (0 = uncapped) */
+    maxPCForGas: bigint;
     /** UEA address */
     ueaAddress: `0x${string}`;
     /** Address to receive funds on revert */
@@ -538,8 +549,12 @@ export interface CascadeSegment {
     gasToken?: `0x${string}`;
     /** Total gas fee for this segment */
     gasFee?: bigint;
+    /** Destination-chain gas price quoted by UniversalCore */
+    gasPrice?: bigint;
     /** Gas limit for this segment */
     gasLimit?: bigint;
+    /** Max native PC used for outbound gas swap (0 = uncapped) */
+    maxPCForGas?: bigint;
     /**
      * SDK 5.2 gas-abstraction sizing decision for this segment. When the
      * segment merges multiple hops, the strictest (highest category) sizing
@@ -756,6 +771,13 @@ export interface WaitForOutboundOptions {
      * has multiple outbound operations to different chains.
      */
     _expectedDestinationChain?: string;
+    /**
+     * @internal Zero-based index among outbound entries that match
+     * `_expectedDestinationChain`. Used when a composed cascade emits multiple
+     * outbound operations to the same chain and a later hop must track the later
+     * observed tx rather than the first one.
+     */
+    _outboundIndex?: number;
 }
 /**
  * UEA deployment and version status.

package/src/lib/orchestrator/payload-builders.d.ts

@@ -70,18 +70,19 @@ export declare function buildSendUniversalTxToUEA(ceaAddress: `0x${string}`, tok
 /**
  * Build UniversalOutboundTxRequest for Push Chain outbound
  *
- * @param target - LEGACY/DUMMY: Any non-zero address for contract compatibility.
- *                 This value is NOT used by the relay to determine the actual destination.
- *                 The relay determines the destination from the PRC-20 token's SOURCE_CHAIN_NAMESPACE.
- *                 Will be removed in future contract upgrades.
+ * @param target - Raw recipient bytes for the destination chain. For EVM CEA
+ *                 funds-parking, use the zero recipient when payload is empty.
  * @param prc20Token - PRC20 token address to burn (or address(0) for native)
  * @param amount - Amount to burn
  * @param gasLimit - Gas limit for fee calculation
- * @param payload - CEA multicall payload
+ * @param payload - Destination execution payload
  * @param revertRecipient - Address to receive funds on revert
+ * @param maxPCForGas - Max native PC used for gas swap (0 = uncapped)
+ * @param gasPrice - Destination-chain gas price override (0 = UniversalCore default)
  * @returns UniversalOutboundTxRequest object
  */
-export declare function buildOutboundRequest(target: `0x${string}`, prc20Token: `0x${string}`, amount: bigint, gasLimit: bigint, payload: `0x${string}`, revertRecipient: `0x${string}`): UniversalOutboundTxRequest;
+export declare function buildOutboundRequest(target: `0x${string}`, prc20Token: `0x${string}`, amount: bigint, gasLimit: bigint, payload: `0x${string}`, revertRecipient: `0x${string}`, maxPCForGas?: bigint, gasPrice?: bigint): UniversalOutboundTxRequest;
+export declare function assertCeaFundsParkingInvariant(recipient: `0x${string}`, payload: `0x${string}`): void;
 /**
  * Build ERC20 transfer multicall
  *