@pushchain/core 5.1.3 → 5.1.4-alpha.1

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

@@ -0,0 +1,945 @@
+"use strict";
+/**
+ * Cascade composition functions extracted from Orchestrator.
+ *
+ * Covers: prepareTransaction, buildHopDescriptor, classifyIntoSegments,
+ * getSegmentType, composeCascade, createCascadedBuilder, createChainedBuilder.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareTransaction = prepareTransaction;
+exports.buildHopDescriptor = buildHopDescriptor;
+exports.classifyIntoSegments = classifyIntoSegments;
+exports.getSegmentType = getSegmentType;
+exports.composeCascade = composeCascade;
+exports.createCascadedBuilder = createCascadedBuilder;
+const tslib_1 = require("tslib");
+const web3_js_1 = require("@solana/web3.js");
+const viem_1 = require("viem");
+const erc20_evm_1 = require("../../constants/abi/erc20.evm");
+const chain_1 = require("../../constants/chain");
+const selectors_1 = require("../../constants/selectors");
+const route_detector_1 = require("../route-detector");
+const cea_utils_1 = require("../cea-utils");
+const payload_builders_1 = require("../payload-builders");
+const push_chain_1 = require("../../push-chain/push-chain");
+const helpers_1 = require("./helpers");
+const payload_builder_1 = require("./payload-builder");
+const uea_manager_1 = require("./uea-manager");
+const gas_calculator_1 = require("./gas-calculator");
+const route_handlers_1 = require("./route-handlers");
+// ============================================================================
+// prepareTransaction
+// ============================================================================
+function prepareTransaction(ctx, params, callbacks) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        (0, route_detector_1.validateRouteParams)(params, {
+            clientChain: ctx.universalSigner.account.chain,
+        });
+        const route = (0, route_detector_1.detectRoute)(params);
+        // Skip getCode if accountStatusCache already confirmed deployment
+        let nonce;
+        const deployedHintCascade = (_b = (_a = ctx.accountStatusCache) === null || _a === void 0 ? void 0 : _a.uea) === null || _b === void 0 ? void 0 : _b.deployed;
+        const ueaAddress = (0, uea_manager_1.computeUEAOffchain)(ctx);
+        if (deployedHintCascade) {
+            nonce = yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress);
+        }
+        else {
+            const status = yield (0, uea_manager_1.getUeaStatusAndNonce)(ctx);
+            nonce = status.nonce;
+        }
+        // Build the payload based on route
+        const { payload, gatewayRequest } = yield (0, route_handlers_1.buildPayloadForRoute)(ctx, params, route, nonce);
+        const gasEstimate = params.gasLimit || selectors_1.DEFAULT_OUTBOUND_GAS_LIMIT;
+        const deadline = params.deadline || BigInt(Math.floor(Date.now() / 1000) + 3600);
+        // Build the HopDescriptor with all metadata needed for cascade nesting
+        const hop = yield buildHopDescriptor(ctx, params, route, ueaAddress);
+        const prepared = {
+            route,
+            payload,
+            gatewayRequest,
+            estimatedGas: gasEstimate,
+            nonce,
+            deadline,
+            _hop: hop,
+            thenOn: (nextTx) => createCascadedBuilder(ctx, [prepared, nextTx], callbacks),
+            send: () => callbacks.executeFn(params),
+        };
+        return prepared;
+    });
+}
+// ============================================================================
+// buildHopDescriptor
+// ============================================================================
+function buildHopDescriptor(ctx, params, route, ueaAddress) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        // Pass 0 when user omits gasLimit → contract uses per-chain baseGasLimitByChainNamespace
+        const gasLimit = (_a = params.gasLimit) !== null && _a !== void 0 ? _a : BigInt(0);
+        const routeStr = route;
+        const baseDescriptor = {
+            params,
+            route: routeStr,
+            gasLimit,
+            ueaAddress,
+            revertRecipient: ueaAddress,
+        };
+        switch (route) {
+            case route_detector_1.TransactionRoute.UOA_TO_PUSH: {
+                // Route 1: Build Push Chain multicalls
+                const executeParams = (0, helpers_1.toExecuteParams)(params);
+                const pushMulticalls = (0, payload_builders_1.buildExecuteMulticall)({
+                    execute: executeParams,
+                    ueaAddress,
+                });
+                return Object.assign(Object.assign({}, baseDescriptor), { pushMulticalls });
+            }
+            case route_detector_1.TransactionRoute.UOA_TO_CEA: {
+                // Route 2: Build outbound metadata
+                const target = params.to;
+                const targetChain = target.chain;
+                // Branch: SVM vs EVM
+                if ((0, payload_builders_1.isSvmChain)(targetChain)) {
+                    // SVM path: no CEA lookup, build SVM payload
+                    const hasSvmExecute = !!params.svmExecute;
+                    let svmPayload = '0x';
+                    if (hasSvmExecute) {
+                        const exec = params.svmExecute;
+                        svmPayload = (0, payload_builders_1.encodeSvmExecutePayload)({
+                            targetProgram: exec.targetProgram,
+                            accounts: exec.accounts,
+                            ixData: exec.ixData,
+                            instructionId: 2,
+                        });
+                    }
+                    let prc20Token = selectors_1.ZERO_ADDRESS;
+                    let burnAmount = BigInt(0);
+                    if ((_b = params.funds) === null || _b === void 0 ? void 0 : _b.amount) {
+                        const token = params.funds.token;
+                        if (token) {
+                            prc20Token = push_chain_1.PushChain.utils.tokens.getPRC20Address(token);
+                            burnAmount = params.funds.amount;
+                        }
+                    }
+                    else if (params.value && params.value > BigInt(0)) {
+                        prc20Token = (0, helpers_1.getNativePRC20ForChain)(targetChain, ctx.pushNetwork);
+                        burnAmount = params.value;
+                    }
+                    else if (hasSvmExecute) {
+                        prc20Token = (0, helpers_1.getNativePRC20ForChain)(targetChain, ctx.pushNetwork);
+                        burnAmount = BigInt(1);
+                    }
+                    let gasToken = selectors_1.ZERO_ADDRESS;
+                    let gasFee = BigInt(0);
+                    if (prc20Token !== selectors_1.ZERO_ADDRESS) {
+                        const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit);
+                        gasToken = result.gasToken;
+                        gasFee = result.gasFee;
+                    }
+                    return Object.assign(Object.assign({}, baseDescriptor), { targetChain, isSvmTarget: true, svmPayload,
+                        prc20Token,
+                        burnAmount,
+                        gasToken,
+                        gasFee });
+                }
+                // EVM path: Resolve CEA address + build CEA multicalls
+                const { cea: ceaAddress } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, targetChain, (_c = ctx.rpcUrls[targetChain]) === null || _c === void 0 ? void 0 : _c[0]);
+                // Migration path: raw MIGRATION_SELECTOR payload, no multicall wrapping
+                if (params.migration) {
+                    const prc20Token = (0, helpers_1.getNativePRC20ForChain)(targetChain, ctx.pushNetwork);
+                    const burnAmount = BigInt(0); // Migration is logic-only — no funds. CEA rejects msg.value != 0.
+                    let gasToken = selectors_1.ZERO_ADDRESS;
+                    let gasFee = BigInt(0);
+                    if (prc20Token !== selectors_1.ZERO_ADDRESS) {
+                        const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit);
+                        gasToken = result.gasToken;
+                        gasFee = result.gasFee;
+                    }
+                    return Object.assign(Object.assign({}, baseDescriptor), { targetChain,
+                        ceaAddress, ceaMulticalls: [], prc20Token,
+                        burnAmount,
+                        gasToken,
+                        gasFee, isMigration: true });
+                }
+                // Build CEA multicalls
+                const ceaMulticalls = [];
+                if (params.data) {
+                    if (Array.isArray(params.data)) {
+                        ceaMulticalls.push(...params.data);
+                    }
+                    else {
+                        // When ERC-20 funds are provided with a single payload, auto-prepend a
+                        // transfer() call so the tokens minted to the CEA are forwarded to the
+                        // target address. This mirrors the Route 1 behavior in buildExecuteMulticall.
+                        if ((_d = params.funds) === null || _d === void 0 ? void 0 : _d.amount) {
+                            const token = params.funds.token;
+                            if (token && token.mechanism !== 'native') {
+                                const erc20Transfer = (0, viem_1.encodeFunctionData)({
+                                    abi: erc20_evm_1.ERC20_EVM,
+                                    functionName: 'transfer',
+                                    args: [target.address, params.funds.amount],
+                                });
+                                ceaMulticalls.push({
+                                    to: token.address,
+                                    value: BigInt(0),
+                                    data: erc20Transfer,
+                                });
+                            }
+                        }
+                        // Single call with data. Forward native value (if any) so the target
+                        // contract receives it alongside the payload call. The vault deposits
+                        // native value to the CEA, and the multicall forwards it to the target.
+                        ceaMulticalls.push({
+                            to: target.address,
+                            value: (_e = params.value) !== null && _e !== void 0 ? _e : BigInt(0),
+                            data: params.data,
+                        });
+                    }
+                }
+                else if (params.value) {
+                    // Skip multicall when sending native value to own CEA — gateway deposits directly.
+                    // Self-call with value would revert (CEA._handleMulticall rejects it).
+                    if (target.address.toLowerCase() !== ceaAddress.toLowerCase()) {
+                        ceaMulticalls.push({
+                            to: target.address,
+                            value: params.value,
+                            data: '0x',
+                        });
+                    }
+                }
+                // Determine PRC-20 token and burn amount
+                let prc20Token = selectors_1.ZERO_ADDRESS;
+                let burnAmount = BigInt(0);
+                if ((_f = params.funds) === null || _f === void 0 ? void 0 : _f.amount) {
+                    const token = params.funds.token;
+                    if (token) {
+                        prc20Token = push_chain_1.PushChain.utils.tokens.getPRC20Address(token);
+                        burnAmount = params.funds.amount;
+                    }
+                }
+                else if (params.value && params.value > BigInt(0)) {
+                    prc20Token = (0, helpers_1.getNativePRC20ForChain)(targetChain, ctx.pushNetwork);
+                    burnAmount = params.value;
+                }
+                else if (params.data) {
+                    prc20Token = (0, helpers_1.getNativePRC20ForChain)(targetChain, ctx.pushNetwork);
+                    burnAmount = BigInt(1); // Minimum for precompile
+                }
+                // Query gas fee
+                let gasToken = selectors_1.ZERO_ADDRESS;
+                let gasFee = BigInt(0);
+                if (prc20Token !== selectors_1.ZERO_ADDRESS) {
+                    const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit);
+                    gasToken = result.gasToken;
+                    gasFee = result.gasFee;
+                }
+                return Object.assign(Object.assign({}, baseDescriptor), { targetChain,
+                    ceaAddress,
+                    ceaMulticalls,
+                    prc20Token,
+                    burnAmount,
+                    gasToken,
+                    gasFee });
+            }
+            case route_detector_1.TransactionRoute.CEA_TO_PUSH: {
+                // Route 3: Build CEA multicalls for sendUniversalTxFromCEA
+                const sourceChain = params.from.chain;
+                // SVM chains use PDA-based CEA, not factory-deployed CEA
+                if ((0, payload_builders_1.isSvmChain)(sourceChain)) {
+                    const lockerContract = chain_1.CHAIN_INFO[sourceChain].lockerContract;
+                    if (!lockerContract) {
+                        throw new Error(`No SVM gateway program configured for chain ${sourceChain}`);
+                    }
+                    const programPk = new web3_js_1.PublicKey(lockerContract);
+                    const gatewayProgramHex = ('0x' +
+                        Buffer.from(programPk.toBytes()).toString('hex'));
+                    // Derive CEA PDA
+                    const ueaBytes = Buffer.from(ueaAddress.slice(2), 'hex');
+                    const [ceaPda] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from('push_identity'), ueaBytes], programPk);
+                    const ceaPdaHex = ('0x' +
+                        Buffer.from(ceaPda.toBytes()).toString('hex'));
+                    let amount = BigInt(0);
+                    let prc20Token;
+                    if (((_g = params.funds) === null || _g === void 0 ? void 0 : _g.amount) && params.funds.amount > BigInt(0)) {
+                        amount = params.funds.amount;
+                        const token = params.funds.token;
+                        if (token && token.address) {
+                            prc20Token = push_chain_1.PushChain.utils.tokens.getPRC20Address(token);
+                        }
+                        else {
+                            prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
+                        }
+                    }
+                    else if (params.value && params.value > BigInt(0)) {
+                        amount = params.value;
+                        prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
+                    }
+                    else {
+                        // Payload-only Route 3 SVM
+                        prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
+                    }
+                    let gasToken = selectors_1.ZERO_ADDRESS;
+                    let gasFee = BigInt(0);
+                    if (prc20Token !== selectors_1.ZERO_ADDRESS) {
+                        const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit);
+                        gasToken = result.gasToken;
+                        gasFee = result.gasFee;
+                    }
+                    return Object.assign(Object.assign({}, baseDescriptor), { sourceChain, ceaAddress: ceaPdaHex, isSvmTarget: true, prc20Token, burnAmount: amount > BigInt(0) ? amount : BigInt(1), gasToken,
+                        gasFee });
+                }
+                const { cea: ceaAddress, isDeployed } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, sourceChain, (_h = ctx.rpcUrls[sourceChain]) === null || _h === void 0 ? void 0 : _h[0]);
+                // Determine token/amount for the inbound
+                let tokenAddress = selectors_1.ZERO_ADDRESS;
+                let amount = BigInt(0);
+                let nativeValue = BigInt(0);
+                if ((_j = params.funds) === null || _j === void 0 ? void 0 : _j.amount) {
+                    const token = params.funds.token;
+                    if (token) {
+                        if (token.mechanism === 'native') {
+                            amount = params.funds.amount;
+                            nativeValue = params.funds.amount;
+                        }
+                        else {
+                            tokenAddress = token.address;
+                            amount = params.funds.amount;
+                        }
+                    }
+                }
+                else if (params.value && params.value > BigInt(0)) {
+                    amount = params.value;
+                    nativeValue = params.value;
+                }
+                // The PRC-20 for the outbound wrapper (Route 2 to source chain)
+                const prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
+                let gasToken = selectors_1.ZERO_ADDRESS;
+                let gasFee = BigInt(0);
+                if (prc20Token !== selectors_1.ZERO_ADDRESS) {
+                    const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit);
+                    gasToken = result.gasToken;
+                    gasFee = result.gasFee;
+                }
+                return Object.assign(Object.assign({}, baseDescriptor), { sourceChain,
+                    ceaAddress,
+                    prc20Token, burnAmount: amount > BigInt(0) ? amount : BigInt(1), gasToken,
+                    gasFee });
+            }
+            default:
+                return baseDescriptor;
+        }
+    });
+}
+// ============================================================================
+// classifyIntoSegments
+// ============================================================================
+function classifyIntoSegments(hops) {
+    if (hops.length === 0)
+        return [];
+    const segments = [];
+    let currentSegment = null;
+    for (const hop of hops) {
+        const segType = getSegmentType(hop.route);
+        const chain = hop.targetChain || hop.sourceChain;
+        const canMerge = currentSegment &&
+            currentSegment.type === segType &&
+            // Same-chain merging for OUTBOUND_TO_CEA (EVM only — SVM hops are atomic)
+            (segType === 'OUTBOUND_TO_CEA'
+                ? currentSegment.targetChain === hop.targetChain && !hop.isSvmTarget
+                : segType === 'PUSH_EXECUTION');
+        if (canMerge && currentSegment) {
+            // Merge into current segment
+            currentSegment.hops.push(hop);
+            if (segType === 'OUTBOUND_TO_CEA') {
+                currentSegment.mergedCeaMulticalls = [
+                    ...(currentSegment.mergedCeaMulticalls || []),
+                    ...(hop.ceaMulticalls || []),
+                ];
+                currentSegment.totalBurnAmount =
+                    (currentSegment.totalBurnAmount || BigInt(0)) +
+                        (hop.burnAmount || BigInt(0));
+                // Gas fee: take the max gasLimit across merged hops
+                if (hop.gasLimit > (currentSegment.gasLimit || BigInt(0))) {
+                    currentSegment.gasLimit = hop.gasLimit;
+                }
+                // Accumulate gas fees
+                currentSegment.gasFee =
+                    (currentSegment.gasFee || BigInt(0)) + (hop.gasFee || BigInt(0));
+            }
+            else if (segType === 'PUSH_EXECUTION') {
+                currentSegment.mergedPushMulticalls = [
+                    ...(currentSegment.mergedPushMulticalls || []),
+                    ...(hop.pushMulticalls || []),
+                ];
+            }
+        }
+        else {
+            // Start a new segment
+            currentSegment = {
+                type: segType,
+                hops: [hop],
+                targetChain: hop.targetChain,
+                sourceChain: hop.sourceChain,
+                mergedCeaMulticalls: segType === 'OUTBOUND_TO_CEA'
+                    ? [...(hop.ceaMulticalls || [])]
+                    : undefined,
+                mergedPushMulticalls: segType === 'PUSH_EXECUTION'
+                    ? [...(hop.pushMulticalls || [])]
+                    : undefined,
+                totalBurnAmount: hop.burnAmount,
+                prc20Token: hop.prc20Token,
+                gasToken: hop.gasToken,
+                gasFee: hop.gasFee,
+                gasLimit: hop.gasLimit,
+            };
+            segments.push(currentSegment);
+        }
+    }
+    return segments;
+}
+// ============================================================================
+// getSegmentType
+// ============================================================================
+function getSegmentType(route) {
+    switch (route) {
+        case 'UOA_TO_PUSH':
+            return 'PUSH_EXECUTION';
+        case 'UOA_TO_CEA':
+            return 'OUTBOUND_TO_CEA';
+        case 'CEA_TO_PUSH':
+            return 'INBOUND_FROM_CEA';
+        default:
+            return 'PUSH_EXECUTION';
+    }
+}
+// ============================================================================
+// composeCascade
+// ============================================================================
+function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    let accumulatedPushMulticalls = [];
+    const gatewayPcAddress = (0, helpers_1.getUniversalGatewayPCAddress)();
+    // Compute per-outbound nativeValueForGas from UEA balance
+    // Each outbound segment needs native value for the gas swap on the destination chain.
+    // The contract refunds excess, so over-allocating is safe.
+    const numOutbounds = segments.filter((s) => s.type !== 'PUSH_EXECUTION').length;
+    const CASCADE_GAS_RESERVE = BigInt(3e18); // 3 PC reserve for gas costs
+    let perOutboundNativeValue;
+    if (ueaBalance && numOutbounds > 0 && ueaBalance > CASCADE_GAS_RESERVE) {
+        perOutboundNativeValue =
+            (ueaBalance - CASCADE_GAS_RESERVE) / BigInt(numOutbounds);
+    }
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const segment = segments[i];
+        switch (segment.type) {
+            case 'PUSH_EXECUTION': {
+                // Prepend Push Chain multicalls to accumulated
+                accumulatedPushMulticalls = [
+                    ...(segment.mergedPushMulticalls || []),
+                    ...accumulatedPushMulticalls,
+                ];
+                break;
+            }
+            case 'OUTBOUND_TO_CEA': {
+                const firstHop = segment.hops[0];
+                const isSvmSegment = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.isSvmTarget) === true;
+                let outboundPayload;
+                let targetForOutbound;
+                const isMigration = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.isMigration) === true;
+                if (isSvmSegment) {
+                    // SVM: use the pre-built SVM payload from the hop descriptor
+                    outboundPayload = (_a = firstHop.svmPayload) !== null && _a !== void 0 ? _a : '0x';
+                    // For SVM, target is the recipient/program from the hop params
+                    const svmTarget = firstHop.params.to;
+                    targetForOutbound =
+                        (_c = (_b = firstHop.params.svmExecute) === null || _b === void 0 ? void 0 : _b.targetProgram) !== null && _c !== void 0 ? _c : svmTarget.address;
+                }
+                else if (isMigration) {
+                    // Migration: use raw 4-byte MIGRATION_SELECTOR, no multicall wrapping
+                    outboundPayload = (0, payload_builders_1.buildMigrationPayload)();
+                    targetForOutbound = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.ceaAddress) || ueaAddress;
+                }
+                else {
+                    // EVM: build CEA payload from merged multicalls
+                    outboundPayload = (0, payload_builders_1.buildCeaMulticallPayload)(segment.mergedCeaMulticalls || []);
+                    // Get CEA address from the first hop
+                    targetForOutbound = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.ceaAddress) || ueaAddress;
+                }
+                // Build outbound request
+                const outboundReq = (0, payload_builders_1.buildOutboundRequest)(targetForOutbound, segment.prc20Token || selectors_1.ZERO_ADDRESS, segment.totalBurnAmount || BigInt(0), (_d = segment.gasLimit) !== null && _d !== void 0 ? _d : BigInt(0), outboundPayload, ueaAddress);
+                // Build approval + outbound multicalls
+                const segGasFee = segment.gasFee || BigInt(0);
+                const outboundMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
+                    prc20Token: segment.prc20Token || selectors_1.ZERO_ADDRESS,
+                    gasToken: segment.gasToken || selectors_1.ZERO_ADDRESS,
+                    burnAmount: segment.totalBurnAmount || BigInt(0),
+                    gasFee: segGasFee,
+                    nativeValueForGas: perOutboundNativeValue !== null && perOutboundNativeValue !== void 0 ? perOutboundNativeValue : segGasFee * BigInt(1000),
+                    gatewayPcAddress,
+                    outboundRequest: outboundReq,
+                });
+                // Prepend to accumulated
+                accumulatedPushMulticalls = [
+                    ...outboundMulticalls,
+                    ...accumulatedPushMulticalls,
+                ];
+                break;
+            }
+            case 'INBOUND_FROM_CEA': {
+                // The accumulated multicalls = what runs on Push Chain AFTER inbound arrives.
+                // Wrap in UniversalPayload struct with correct UEA nonce for the relay.
+                // Build push multicalls from this hop's own data (e.g., counter.increment())
+                // This is the Route 3 hop's payload that executes on Push Chain after inbound.
+                const hop0 = segment.hops[0];
+                if ((_e = hop0 === null || hop0 === void 0 ? void 0 : hop0.params) === null || _e === void 0 ? void 0 : _e.data) {
+                    const hopPushMulticalls = (0, payload_builders_1.buildExecuteMulticall)({
+                        execute: {
+                            to: hop0.params.to,
+                            value: hop0.params.value,
+                            data: hop0.params.data,
+                        },
+                        ueaAddress,
+                    });
+                    // Prepend the Route 3's own push calls before subsequent hops
+                    accumulatedPushMulticalls = [
+                        ...hopPushMulticalls,
+                        ...accumulatedPushMulticalls,
+                    ];
+                }
+                let intermediatePayload = '0x';
+                if (accumulatedPushMulticalls.length > 0) {
+                    const multicallPayload = (0, payload_builder_1.buildMulticallPayloadData)(ctx, ueaAddress, accumulatedPushMulticalls);
+                    // +1: the outbound tx consumes one nonce via execute()
+                    intermediatePayload = (0, payload_builders_1.buildInboundUniversalPayload)(multicallPayload, { nonce: (ueaNonce !== null && ueaNonce !== void 0 ? ueaNonce : BigInt(0)) + BigInt(1) });
+                }
+                const hop = segment.hops[0];
+                const sourceChain = hop.sourceChain;
+                const ceaAddress = hop.ceaAddress || ueaAddress;
+                // SVM chains: build SVM CPI payload instead of EVM CEA multicall
+                if ((0, payload_builders_1.isSvmChain)(sourceChain)) {
+                    const lockerContract = chain_1.CHAIN_INFO[sourceChain].lockerContract;
+                    if (!lockerContract) {
+                        throw new Error(`No SVM gateway program configured for chain ${sourceChain}`);
+                    }
+                    const programPk = new web3_js_1.PublicKey(lockerContract);
+                    const gatewayProgramHex = ('0x' +
+                        Buffer.from(programPk.toBytes()).toString('hex'));
+                    let drainAmount = BigInt(0);
+                    let tokenMintHex;
+                    const params = hop.params;
+                    if (((_f = params.funds) === null || _f === void 0 ? void 0 : _f.amount) && params.funds.amount > BigInt(0)) {
+                        drainAmount = params.funds.amount;
+                        const token = params.funds.token;
+                        if (token && token.address) {
+                            const mintPk = new web3_js_1.PublicKey(token.address);
+                            tokenMintHex = ('0x' +
+                                Buffer.from(mintPk.toBytes()).toString('hex'));
+                        }
+                    }
+                    else if (params.value && params.value > BigInt(0)) {
+                        drainAmount = params.value;
+                    }
+                    // Derive CEA PDA as revert recipient
+                    const ueaBytes = Buffer.from(ueaAddress.slice(2), 'hex');
+                    const [ceaPda] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from('push_identity'), ueaBytes], programPk);
+                    const ceaPdaHex = ('0x' +
+                        Buffer.from(ceaPda.toBytes()).toString('hex'));
+                    // Build SVM payload with intermediate Push Chain payload embedded
+                    const svmPayload = (0, payload_builders_1.encodeSvmCeaToUeaPayload)({
+                        gatewayProgramHex,
+                        drainAmount,
+                        tokenMintHex,
+                        revertRecipientHex: ceaPdaHex,
+                        extraPayload: intermediatePayload !== '0x'
+                            ? new Uint8Array(Buffer.from(intermediatePayload.slice(2), 'hex'))
+                            : undefined,
+                    });
+                    const burnAmount = BigInt(1);
+                    const outboundReq = (0, payload_builders_1.buildOutboundRequest)(gatewayProgramHex, segment.prc20Token ||
+                        (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork), burnAmount, (_g = segment.gasLimit) !== null && _g !== void 0 ? _g : BigInt(0), svmPayload, ueaAddress);
+                    const inboundGasFee = segment.gasFee || BigInt(0);
+                    const outboundMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
+                        prc20Token: segment.prc20Token ||
+                            (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork),
+                        gasToken: segment.gasToken || selectors_1.ZERO_ADDRESS,
+                        burnAmount,
+                        gasFee: inboundGasFee,
+                        nativeValueForGas: perOutboundNativeValue !== null && perOutboundNativeValue !== void 0 ? perOutboundNativeValue : inboundGasFee * BigInt(1000),
+                        gatewayPcAddress,
+                        outboundRequest: outboundReq,
+                    });
+                    accumulatedPushMulticalls = [...outboundMulticalls];
+                    break;
+                }
+                // EVM path: Build CEA multicall: [approve?, sendUniversalTxFromCEA(payload)]
+                const ceaMulticalls = [];
+                // Add hop's own CEA operations if any
+                // (e.g., approve + swap before bridging back)
+                if (hop.ceaMulticalls && hop.ceaMulticalls.length > 0) {
+                    ceaMulticalls.push(...hop.ceaMulticalls);
+                }
+                // Determine token/amount for inbound
+                let tokenAddress = selectors_1.ZERO_ADDRESS;
+                let amount = BigInt(0);
+                const params = hop.params;
+                if ((_h = params.funds) === null || _h === void 0 ? void 0 : _h.amount) {
+                    const token = params.funds.token;
+                    if (token) {
+                        if (token.mechanism === 'native') {
+                            amount = params.funds.amount;
+                        }
+                        else {
+                            tokenAddress = token.address;
+                            amount = params.funds.amount;
+                            // Add approve for ERC20 (CEA approves gateway)
+                            const gatewayAddr = chain_1.UNIVERSAL_GATEWAY_ADDRESSES[sourceChain];
+                            if (!gatewayAddr) {
+                                throw new Error(`No UniversalGateway address configured for chain ${sourceChain}`);
+                            }
+                            // Reset allowance to 0 first for USDT-style tokens
+                            const approveZeroData = (0, viem_1.encodeFunctionData)({
+                                abi: erc20_evm_1.ERC20_EVM,
+                                functionName: 'approve',
+                                args: [gatewayAddr, BigInt(0)],
+                            });
+                            ceaMulticalls.push({
+                                to: tokenAddress,
+                                value: BigInt(0),
+                                data: approveZeroData,
+                            });
+                            const approveData = (0, viem_1.encodeFunctionData)({
+                                abi: erc20_evm_1.ERC20_EVM,
+                                functionName: 'approve',
+                                args: [gatewayAddr, amount],
+                            });
+                            ceaMulticalls.push({
+                                to: tokenAddress,
+                                value: BigInt(0),
+                                data: approveData,
+                            });
+                        }
+                    }
+                }
+                else if (params.value && params.value > BigInt(0)) {
+                    amount = params.value;
+                }
+                // Build sendUniversalTxToUEA self-call on CEA (to=CEA, value=0)
+                const sendCall = (0, payload_builders_1.buildSendUniversalTxToUEA)(ceaAddress, tokenAddress, amount, intermediatePayload, ceaAddress);
+                ceaMulticalls.push(sendCall);
+                // Wrap CEA multicall in outbound from Push Chain
+                const ceaPayload = (0, payload_builders_1.buildCeaMulticallPayload)(ceaMulticalls);
+                const outboundReq = (0, payload_builders_1.buildOutboundRequest)(ceaAddress, segment.prc20Token ||
+                    (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork), segment.totalBurnAmount || BigInt(1), (_j = segment.gasLimit) !== null && _j !== void 0 ? _j : BigInt(0), ceaPayload, ueaAddress);
+                const inboundGasFee = segment.gasFee || BigInt(0);
+                const outboundMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
+                    prc20Token: segment.prc20Token ||
+                        (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork),
+                    gasToken: segment.gasToken || selectors_1.ZERO_ADDRESS,
+                    burnAmount: segment.totalBurnAmount || BigInt(1),
+                    gasFee: inboundGasFee,
+                    nativeValueForGas: perOutboundNativeValue !== null && perOutboundNativeValue !== void 0 ? perOutboundNativeValue : inboundGasFee * BigInt(1000),
+                    gatewayPcAddress,
+                    outboundRequest: outboundReq,
+                });
+                // Reset accumulated -- everything is now inside this outbound
+                accumulatedPushMulticalls = [...outboundMulticalls];
+                break;
+            }
+        }
+    }
+    return accumulatedPushMulticalls;
+}
+// ============================================================================
+// createCascadedBuilder
+// ============================================================================
+function createCascadedBuilder(ctx, preparedTxs, callbacks) {
+    return {
+        thenOn: (nextTx) => createCascadedBuilder(ctx, [...preparedTxs, nextTx], callbacks),
+        send: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const ueaAddress = (0, uea_manager_1.computeUEAOffchain)(ctx);
+            // Extract HopDescriptors
+            const hops = preparedTxs.map((tx) => tx._hop);
+            // Classify into segments
+            const segments = classifyIntoSegments(hops);
+            // Check if this is a single-hop Route 1 (no composition needed)
+            if (preparedTxs.length === 1 &&
+                preparedTxs[0].route === 'UOA_TO_PUSH') {
+                const response = yield callbacks.executeFn(hops[0].params);
+                const singleRoute1Result = {
+                    initialTxHash: response.hash,
+                    initialTxResponse: response,
+                    hops: [
+                        {
+                            hopIndex: 0,
+                            route: hops[0].route,
+                            executionChain: (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork),
+                            status: 'confirmed',
+                            txHash: response.hash,
+                        },
+                    ],
+                    hopCount: 1,
+                    waitForAll: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                        return ({
+                            success: true,
+                            hops: [
+                                {
+                                    hopIndex: 0,
+                                    route: hops[0].route,
+                                    executionChain: (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork),
+                                    status: 'confirmed',
+                                    txHash: response.hash,
+                                },
+                            ],
+                        });
+                    }),
+                    wait: (opts) => tslib_1.__awaiter(this, void 0, void 0, function* () { return singleRoute1Result.waitForAll(opts); }),
+                };
+                return singleRoute1Result;
+            }
+            // Check if single-hop Route 2 (just execute directly)
+            if (preparedTxs.length === 1 &&
+                preparedTxs[0].route === 'UOA_TO_CEA') {
+                const response = yield callbacks.executeFn(hops[0].params);
+                const targetChain = hops[0].targetChain || (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork);
+                const singleRoute2Result = {
+                    initialTxHash: response.hash,
+                    initialTxResponse: response,
+                    hops: [
+                        {
+                            hopIndex: 0,
+                            route: hops[0].route,
+                            executionChain: targetChain,
+                            status: 'confirmed',
+                            txHash: response.hash,
+                        },
+                    ],
+                    hopCount: 1,
+                    waitForAll: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                        return ({
+                            success: true,
+                            hops: [
+                                {
+                                    hopIndex: 0,
+                                    route: hops[0].route,
+                                    executionChain: targetChain,
+                                    status: 'confirmed',
+                                    txHash: response.hash,
+                                },
+                            ],
+                        });
+                    }),
+                    wait: (opts) => tslib_1.__awaiter(this, void 0, void 0, function* () { return singleRoute2Result.waitForAll(opts); }),
+                };
+                return singleRoute2Result;
+            }
+            // Multi-hop: compose cascade bottom-to-top
+            // Fetch UEA balance + nonce so composeCascade can allocate native value and build inbound payloads
+            const ueaBalance = yield ctx.pushClient.getBalance(ueaAddress);
+            const ueaCodeCascade = yield ctx.pushClient.publicClient.getCode({
+                address: ueaAddress,
+            });
+            const ueaNonceCascade = ueaCodeCascade !== undefined
+                ? yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress)
+                : BigInt(0);
+            const composedMulticalls = composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonceCascade);
+            // Execute the composed multicall as a single Push Chain tx
+            const executeParams = {
+                to: ueaAddress,
+                data: composedMulticalls,
+            };
+            const response = yield callbacks.executeFn(executeParams);
+            // Build hop info for tracking
+            const hopInfos = hops.map((hop, index) => ({
+                hopIndex: index,
+                route: hop.route,
+                executionChain: hop.targetChain || hop.sourceChain || (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork),
+                status: 'pending',
+            }));
+            // Mark first hop as submitted
+            if (hopInfos.length > 0) {
+                hopInfos[0].status = 'submitted';
+                hopInfos[0].txHash = response.hash;
+            }
+            const cascadeResponse = {
+                initialTxHash: response.hash,
+                initialTxResponse: response,
+                hops: hopInfos,
+                hopCount: hops.length,
+                waitForAll: (opts) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    const { pollingIntervalMs = 10000, timeout = 300000, progressHook: cascadeProgressHook, } = opts || {};
+                    const startTime = Date.now();
+                    try {
+                        // 1. Wait for initial Push Chain tx confirmation
+                        cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
+                            hopIndex: 0,
+                            route: ((_a = hopInfos[0]) === null || _a === void 0 ? void 0 : _a.route) || 'UOA_TO_PUSH',
+                            chain: (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork),
+                            status: 'waiting',
+                            elapsed: Date.now() - startTime,
+                        });
+                        yield response.wait();
+                        // Mark all Push Chain (Route 1) hops as confirmed
+                        for (const hop of hopInfos) {
+                            if (hop.route === 'UOA_TO_PUSH') {
+                                hop.status = 'confirmed';
+                                hop.txHash = response.hash;
+                                cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
+                                    hopIndex: hop.hopIndex,
+                                    route: hop.route,
+                                    chain: (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork),
+                                    status: 'confirmed',
+                                    txHash: response.hash,
+                                    elapsed: Date.now() - startTime,
+                                });
+                            }
+                        }
+                        // 2. Track outbound hops (Route 2: UOA_TO_CEA)
+                        // Hops after a CEA_TO_PUSH are "child outbounds" — they execute inside
+                        // the inbound payload on Push Chain and live under a DIFFERENT utx_id
+                        // (the inbound UTX, not the parent). We can't track them via the parent
+                        // utx_id polling, so we auto-confirm them.
+                        const ceaToPushIndex = hopInfos.findIndex((h) => h.route === 'CEA_TO_PUSH');
+                        const outboundHops = hopInfos.filter((h, i) => {
+                            if (h.route !== 'UOA_TO_CEA')
+                                return false;
+                            // Child outbounds (after CEA_TO_PUSH) live under the inbound UTX,
+                            // not the parent — auto-confirm since we can't poll them here.
+                            if (ceaToPushIndex >= 0 && i > ceaToPushIndex) {
+                                h.status = 'confirmed';
+                                cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
+                                    hopIndex: h.hopIndex,
+                                    route: h.route,
+                                    chain: h.executionChain,
+                                    status: 'confirmed',
+                                    elapsed: Date.now() - startTime,
+                                });
+                                return false;
+                            }
+                            return true;
+                        });
+                        if (outboundHops.length > 0) {
+                            if (outboundHops.length === 1) {
+                                // Single direct outbound hop: use the existing V1-based tracking
+                                const hop = outboundHops[0];
+                                const remainingTimeout = timeout - (Date.now() - startTime);
+                                if (remainingTimeout <= 0) {
+                                    hop.status = 'failed';
+                                    cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
+                                        hopIndex: hop.hopIndex,
+                                        route: hop.route,
+                                        chain: hop.executionChain,
+                                        status: 'timeout',
+                                        elapsed: Date.now() - startTime,
+                                    });
+                                    return {
+                                        success: false,
+                                        hops: hopInfos,
+                                        failedAt: hop.hopIndex,
+                                    };
+                                }
+                                cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
+                                    hopIndex: hop.hopIndex,
+                                    route: hop.route,
+                                    chain: hop.executionChain,
+                                    status: 'polling',
+                                    elapsed: Date.now() - startTime,
+                                });
+                                try {
+                                    const outboundDetails = yield callbacks.waitForOutboundTxFn(response.hash, {
+                                        initialWaitMs: Math.min(60000, remainingTimeout),
+                                        pollingIntervalMs,
+                                        timeout: remainingTimeout,
+                                        progressHook: (event) => {
+                                            cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
+                                                hopIndex: hop.hopIndex,
+                                                route: hop.route,
+                                                chain: hop.executionChain,
+                                                status: event.status,
+                                                elapsed: Date.now() - startTime,
+                                            });
+                                        },
+                                    });
+                                    hop.status = 'confirmed';
+                                    hop.txHash = outboundDetails.externalTxHash;
+                                    hop.outboundDetails = outboundDetails;
+                                    cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
+                                        hopIndex: hop.hopIndex,
+                                        route: hop.route,
+                                        chain: hop.executionChain,
+                                        status: 'confirmed',
+                                        txHash: outboundDetails.externalTxHash,
+                                        elapsed: Date.now() - startTime,
+                                    });
+                                }
+                                catch (err) {
+                                    hop.status = 'failed';
+                                    cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
+                                        hopIndex: hop.hopIndex,
+                                        route: hop.route,
+                                        chain: hop.executionChain,
+                                        status: 'failed',
+                                        elapsed: Date.now() - startTime,
+                                    });
+                                    return {
+                                        success: false,
+                                        hops: hopInfos,
+                                        failedAt: hop.hopIndex,
+                                    };
+                                }
+                            }
+                            else {
+                                // Multiple outbound hops: use V2 API which returns outboundTx[]
+                                const allOutboundDetails = yield callbacks.waitForAllOutboundTxsFn(response.hash, outboundHops, {
+                                    initialWaitMs: Math.min(60000, timeout - (Date.now() - startTime)),
+                                    pollingIntervalMs,
+                                    timeout: timeout - (Date.now() - startTime),
+                                    progressHook: (event) => {
+                                        cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
+                                            hopIndex: event.hopIndex,
+                                            route: event.route,
+                                            chain: event.chain,
+                                            status: event.status,
+                                            txHash: event.txHash,
+                                            elapsed: Date.now() - startTime,
+                                        });
+                                    },
+                                });
+                                if (!allOutboundDetails.success) {
+                                    return {
+                                        success: false,
+                                        hops: hopInfos,
+                                        failedAt: allOutboundDetails.failedAt,
+                                    };
+                                }
+                            }
+                        }
+                        // 3. Route 3 (CEA_TO_PUSH) tracking - mark as submitted
+                        const inboundHops = hopInfos.filter((h) => h.route === 'CEA_TO_PUSH');
+                        for (const inboundHop of inboundHops) {
+                            inboundHop.status = 'submitted';
+                            cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
+                                hopIndex: inboundHop.hopIndex,
+                                route: inboundHop.route,
+                                chain: inboundHop.executionChain,
+                                status: 'waiting',
+                                elapsed: Date.now() - startTime,
+                            });
+                        }
+                        return { success: true, hops: hopInfos };
+                    }
+                    catch (err) {
+                        const failedIdx = hopInfos.findIndex((h) => h.status !== 'confirmed');
+                        return {
+                            success: false,
+                            hops: hopInfos,
+                            failedAt: failedIdx >= 0 ? failedIdx : 0,
+                        };
+                    }
+                }),
+                wait: (opts) => tslib_1.__awaiter(this, void 0, void 0, function* () { return cascadeResponse.waitForAll(opts); }),
+            };
+            return cascadeResponse;
+        }),
+    };
+}
+//# sourceMappingURL=cascade.js.map