@pushchain/core 6.0.24 → 6.0.25

package/src/lib/generated/uexecutor/v1/query.js

@@ -1,12 +1,109 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QueryGetUniversalTxResponse = exports.QueryGetUniversalTxRequest = exports.protobufPackage = void 0;
+exports.QueryGetUniversalTxResponse = exports.QueryGetUniversalTxRequest = exports.QueryParamsResponse = exports.QueryParamsRequest = exports.UexecutorParams = exports.protobufPackage = void 0;
 // Minimal generated types for uexecutor.v1 Query service
 // Hand-authored to avoid requiring protoc at build time in this repo
 /* eslint-disable */
 const wire_1 = require("@bufbuild/protobuf/wire");
 const types_1 = require("./types");
 exports.protobufPackage = 'uexecutor.v1';
+function createBaseUexecutorParams() {
+    return { someValue: false, maxGaslessTxGas: BigInt(0) };
+}
+exports.UexecutorParams = {
+    encode(message, writer = new wire_1.BinaryWriter()) {
+        if (message.someValue === true)
+            writer.uint32(16).bool(message.someValue);
+        if (message.maxGaslessTxGas !== BigInt(0)) {
+            writer.uint32(24).uint64(message.maxGaslessTxGas);
+        }
+        return writer;
+    },
+    decode(input, length) {
+        const reader = input instanceof wire_1.BinaryReader ? input : new wire_1.BinaryReader(input);
+        const end = length === undefined ? reader.len : reader.pos + length;
+        const message = createBaseUexecutorParams();
+        while (reader.pos < end) {
+            const tag = reader.uint32();
+            switch (tag >>> 3) {
+                case 2:
+                    message.someValue = reader.bool();
+                    break;
+                case 3:
+                    message.maxGaslessTxGas = BigInt(reader.uint64().toString());
+                    break;
+                default:
+                    if ((tag & 7) === 4 || tag === 0)
+                        return message;
+                    reader.skip(tag & 7);
+                    break;
+            }
+        }
+        return message;
+    },
+    fromPartial(object) {
+        return {
+            someValue: object.someValue ?? false,
+            maxGaslessTxGas: object.maxGaslessTxGas ?? BigInt(0),
+        };
+    },
+};
+exports.QueryParamsRequest = {
+    encode(_message, writer = new wire_1.BinaryWriter()) {
+        return writer;
+    },
+    decode(input, length) {
+        const reader = input instanceof wire_1.BinaryReader ? input : new wire_1.BinaryReader(input);
+        const end = length === undefined ? reader.len : reader.pos + length;
+        while (reader.pos < end) {
+            const tag = reader.uint32();
+            if ((tag & 7) === 4 || tag === 0)
+                return {};
+            reader.skip(tag & 7);
+        }
+        return {};
+    },
+    fromPartial(_object) {
+        return {};
+    },
+};
+function createBaseQueryParamsResponse() {
+    return { params: undefined };
+}
+exports.QueryParamsResponse = {
+    encode(message, writer = new wire_1.BinaryWriter()) {
+        if (message.params !== undefined) {
+            exports.UexecutorParams.encode(message.params, writer.uint32(10).fork()).join();
+        }
+        return writer;
+    },
+    decode(input, length) {
+        const reader = input instanceof wire_1.BinaryReader ? input : new wire_1.BinaryReader(input);
+        const end = length === undefined ? reader.len : reader.pos + length;
+        const message = createBaseQueryParamsResponse();
+        while (reader.pos < end) {
+            const tag = reader.uint32();
+            switch (tag >>> 3) {
+                case 1:
+                    message.params = exports.UexecutorParams.decode(reader, reader.uint32());
+                    break;
+                default:
+                    if ((tag & 7) === 4 || tag === 0)
+                        return message;
+                    reader.skip(tag & 7);
+                    break;
+            }
+        }
+        return message;
+    },
+    fromPartial(object) {
+        return {
+            params: object.params === undefined
+                ? undefined
+                : exports.UexecutorParams.fromPartial(object.params),
+        };
+    },
+};
 function createBaseQueryGetUniversalTxRequest() {
     return { id: '' };
 }

package/src/lib/index.d.ts

@@ -1,4 +1,5 @@
 import { PushChain } from './push-chain/push-chain';
+export { CHAIN } from './constants/enums';
 export type { ConversionQuote } from './constants/tokens';
 export type { UniversalSigner, UniversalAccount, UniversalSignerSkeleton, SignAuthorizationParams, SignedAuthorization, DerivedExecutorAccount, ResolvedAccount, ResolvedControllerAccounts, AccountType, AccountRole, } from './universal/universal.types';
 export type { PC20TokenReference, FundsToken, PC20RegistryEntry, PC20AddressResult, } from './orchestrator/orchestrator.types';
@@ -11,4 +12,12 @@ export { DEFAULT_MAX_PC_FOR_GAS_BUFFER_BPS, MAX_PC_FOR_GAS_BUFFER_BPS_LIMIT, quo
 export type { MaxPCForGasCapInput, MaxPCForGasCapFromNativeValueInput, MaxPCForGasCapQuote, } from './orchestrator/max-pc-for-gas';
 export { getCEAAddress, getPushAccountForCEA, isCEA, chainSupportsCEA, chainSupportsOutbound, getCEAFactoryAddress, getAllCEAAddresses, } from './orchestrator/cea-utils';
 export { encodeSvmExecutePayload, isSvmChain, isValidSolanaHexAddress, buildMigrationPayload, buildErc20WithdrawalMulticall, } from './orchestrator/payload-builders';
+export type { ReadChain, ReadDestination, ResolvedDestination, ReadQuery, EvmReadQuery, SvmReadQuery, Web2ReadQuery, Web2Extract, Web2ValueType, EncodedReadQuery, ReadResultShape, DecodedReadResult, ReadPreflight, ReadSpec, ReadSpecTuple, BuildReadSpecParams, PreparedRead, ReadCallback, SimulateReadResult, ParsedReadRequest, FulfilOutcome, ReceiptLike, ReadRef, ReadLifecycleOptions, ReadFees, UniversalReadResponse, ReadResponseTuple, BatchReadResponse, } from './read-state/read-state.types';
+export type { ReadOptions, ReadPrepareOptions, ReadQueryOptions, ReadCallbackOptions, ReadValue, ValidateReadCall, ReadWeb2Options, ReadTrackOptions, ReadExecuteOptions } from './read-state/read-params';
+export { UNIVERSAL_READ_STATUS, READ_STATUS, READ_ERROR_CODE, CONTRACT_REQUEST_STATUS, TERMINAL_READ_STATUSES, } from './read-state/read-state.types';
+export { ReadStateError, InvalidReadQueryError, InvalidReadSpecError, ReadHeightUnavailableError, UnsupportedReadDestinationError, ReadDecodeError, ReadTimeoutError, ReadNotFoundError, ReadRegistryUnavailableError, } from './read-state/errors';
+export type { ReadSpecViolation } from './read-state/errors';
+export { resolveDestination, encodeReadQuery, decodeReadResult, parseReadRequestsFromReceipt, parseFulfilOutcome, buildReadSpecFromPreflight, validateReadSpec, toCallData, sizeCallbackBudget, inferResultShape, toRequestIdHex, toReadQuery, } from './read-state';
+export { UNIVERSAL_CALLBACK_EVM } from './constants/abi/universalCallback.evm';
+export { UNIVERSAL_READ_REGISTRY_EVM } from './constants/abi/universalReadRegistry.evm';
 export { PushChain };

package/src/lib/index.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PushChain = exports.buildErc20WithdrawalMulticall = exports.buildMigrationPayload = exports.isValidSolanaHexAddress = exports.isSvmChain = exports.encodeSvmExecutePayload = exports.getAllCEAAddresses = exports.getCEAFactoryAddress = exports.chainSupportsOutbound = exports.chainSupportsCEA = exports.isCEA = exports.getPushAccountForCEA = exports.getCEAAddress = exports.quoteMaxPCForGasCapFromNativeValue = exports.quoteMaxPCForGasCap = exports.MAX_PC_FOR_GAS_BUFFER_BPS_LIMIT = exports.DEFAULT_MAX_PC_FOR_GAS_BUFFER_BPS = exports.isChainTarget = exports.detectRoute = exports.TransactionRoute = exports.parseUEAVersion = exports.PC20UnsafeEmptyPayloadError = exports.PC20ExportRevertedError = exports.PC20WrapperPredictionUnavailableError = exports.PC20UnknownChainNamespaceError = exports.InsufficientPC20BalanceError = exports.UnsupportedPC20DestinationError = exports.PC20AmbiguousAddressError = exports.PC20ExpectedButPRC20Error = exports.InvalidPC20MetadataError = exports.PC20FactoryMismatchError = exports.PC20RegistryMismatchError = exports.PC20WrapperNotRegisteredError = exports.PC20TokenChainMismatchError = exports.InvalidPC20AddressError = exports.PC20Error = exports.isPC20Reference = void 0;
+exports.ReadNotFoundError = exports.ReadTimeoutError = exports.ReadDecodeError = exports.UnsupportedReadDestinationError = exports.ReadHeightUnavailableError = exports.InvalidReadSpecError = exports.InvalidReadQueryError = exports.ReadStateError = exports.TERMINAL_READ_STATUSES = exports.CONTRACT_REQUEST_STATUS = exports.READ_ERROR_CODE = exports.READ_STATUS = exports.UNIVERSAL_READ_STATUS = exports.buildErc20WithdrawalMulticall = exports.buildMigrationPayload = exports.isValidSolanaHexAddress = exports.isSvmChain = exports.encodeSvmExecutePayload = exports.getAllCEAAddresses = exports.getCEAFactoryAddress = exports.chainSupportsOutbound = exports.chainSupportsCEA = exports.isCEA = exports.getPushAccountForCEA = exports.getCEAAddress = exports.quoteMaxPCForGasCapFromNativeValue = exports.quoteMaxPCForGasCap = exports.MAX_PC_FOR_GAS_BUFFER_BPS_LIMIT = exports.DEFAULT_MAX_PC_FOR_GAS_BUFFER_BPS = exports.isChainTarget = exports.detectRoute = exports.TransactionRoute = exports.parseUEAVersion = exports.PC20UnsafeEmptyPayloadError = exports.PC20ExportRevertedError = exports.PC20WrapperPredictionUnavailableError = exports.PC20UnknownChainNamespaceError = exports.InsufficientPC20BalanceError = exports.UnsupportedPC20DestinationError = exports.PC20AmbiguousAddressError = exports.PC20ExpectedButPRC20Error = exports.InvalidPC20MetadataError = exports.PC20FactoryMismatchError = exports.PC20RegistryMismatchError = exports.PC20WrapperNotRegisteredError = exports.PC20TokenChainMismatchError = exports.InvalidPC20AddressError = exports.PC20Error = exports.isPC20Reference = exports.CHAIN = void 0;
+exports.PushChain = exports.UNIVERSAL_READ_REGISTRY_EVM = exports.UNIVERSAL_CALLBACK_EVM = exports.toReadQuery = exports.toRequestIdHex = exports.inferResultShape = exports.sizeCallbackBudget = exports.toCallData = exports.validateReadSpec = exports.buildReadSpecFromPreflight = exports.parseFulfilOutcome = exports.parseReadRequestsFromReceipt = exports.decodeReadResult = exports.encodeReadQuery = exports.resolveDestination = exports.ReadRegistryUnavailableError = void 0;
 const push_chain_1 = require("./push-chain/push-chain");
 Object.defineProperty(exports, "PushChain", { enumerable: true, get: function () { return push_chain_1.PushChain; } });
+var enums_1 = require("./constants/enums");
+Object.defineProperty(exports, "CHAIN", { enumerable: true, get: function () { return enums_1.CHAIN; } });
 var orchestrator_types_1 = require("./orchestrator/orchestrator.types");
 Object.defineProperty(exports, "isPC20Reference", { enumerable: true, get: function () { return orchestrator_types_1.isPC20Reference; } });
 var errors_1 = require("./orchestrator/internals/pc20/errors");
@@ -51,4 +54,37 @@ Object.defineProperty(exports, "isSvmChain", { enumerable: true, get: function (
 Object.defineProperty(exports, "isValidSolanaHexAddress", { enumerable: true, get: function () { return payload_builders_1.isValidSolanaHexAddress; } });
 Object.defineProperty(exports, "buildMigrationPayload", { enumerable: true, get: function () { return payload_builders_1.buildMigrationPayload; } });
 Object.defineProperty(exports, "buildErc20WithdrawalMulticall", { enumerable: true, get: function () { return payload_builders_1.buildErc20WithdrawalMulticall; } });
+var read_state_types_1 = require("./read-state/read-state.types");
+Object.defineProperty(exports, "UNIVERSAL_READ_STATUS", { enumerable: true, get: function () { return read_state_types_1.UNIVERSAL_READ_STATUS; } });
+Object.defineProperty(exports, "READ_STATUS", { enumerable: true, get: function () { return read_state_types_1.READ_STATUS; } });
+Object.defineProperty(exports, "READ_ERROR_CODE", { enumerable: true, get: function () { return read_state_types_1.READ_ERROR_CODE; } });
+Object.defineProperty(exports, "CONTRACT_REQUEST_STATUS", { enumerable: true, get: function () { return read_state_types_1.CONTRACT_REQUEST_STATUS; } });
+Object.defineProperty(exports, "TERMINAL_READ_STATUSES", { enumerable: true, get: function () { return read_state_types_1.TERMINAL_READ_STATUSES; } });
+var errors_2 = require("./read-state/errors");
+Object.defineProperty(exports, "ReadStateError", { enumerable: true, get: function () { return errors_2.ReadStateError; } });
+Object.defineProperty(exports, "InvalidReadQueryError", { enumerable: true, get: function () { return errors_2.InvalidReadQueryError; } });
+Object.defineProperty(exports, "InvalidReadSpecError", { enumerable: true, get: function () { return errors_2.InvalidReadSpecError; } });
+Object.defineProperty(exports, "ReadHeightUnavailableError", { enumerable: true, get: function () { return errors_2.ReadHeightUnavailableError; } });
+Object.defineProperty(exports, "UnsupportedReadDestinationError", { enumerable: true, get: function () { return errors_2.UnsupportedReadDestinationError; } });
+Object.defineProperty(exports, "ReadDecodeError", { enumerable: true, get: function () { return errors_2.ReadDecodeError; } });
+Object.defineProperty(exports, "ReadTimeoutError", { enumerable: true, get: function () { return errors_2.ReadTimeoutError; } });
+Object.defineProperty(exports, "ReadNotFoundError", { enumerable: true, get: function () { return errors_2.ReadNotFoundError; } });
+Object.defineProperty(exports, "ReadRegistryUnavailableError", { enumerable: true, get: function () { return errors_2.ReadRegistryUnavailableError; } });
+var read_state_1 = require("./read-state");
+Object.defineProperty(exports, "resolveDestination", { enumerable: true, get: function () { return read_state_1.resolveDestination; } });
+Object.defineProperty(exports, "encodeReadQuery", { enumerable: true, get: function () { return read_state_1.encodeReadQuery; } });
+Object.defineProperty(exports, "decodeReadResult", { enumerable: true, get: function () { return read_state_1.decodeReadResult; } });
+Object.defineProperty(exports, "parseReadRequestsFromReceipt", { enumerable: true, get: function () { return read_state_1.parseReadRequestsFromReceipt; } });
+Object.defineProperty(exports, "parseFulfilOutcome", { enumerable: true, get: function () { return read_state_1.parseFulfilOutcome; } });
+Object.defineProperty(exports, "buildReadSpecFromPreflight", { enumerable: true, get: function () { return read_state_1.buildReadSpecFromPreflight; } });
+Object.defineProperty(exports, "validateReadSpec", { enumerable: true, get: function () { return read_state_1.validateReadSpec; } });
+Object.defineProperty(exports, "toCallData", { enumerable: true, get: function () { return read_state_1.toCallData; } });
+Object.defineProperty(exports, "sizeCallbackBudget", { enumerable: true, get: function () { return read_state_1.sizeCallbackBudget; } });
+Object.defineProperty(exports, "inferResultShape", { enumerable: true, get: function () { return read_state_1.inferResultShape; } });
+Object.defineProperty(exports, "toRequestIdHex", { enumerable: true, get: function () { return read_state_1.toRequestIdHex; } });
+Object.defineProperty(exports, "toReadQuery", { enumerable: true, get: function () { return read_state_1.toReadQuery; } });
+var universalCallback_evm_1 = require("./constants/abi/universalCallback.evm");
+Object.defineProperty(exports, "UNIVERSAL_CALLBACK_EVM", { enumerable: true, get: function () { return universalCallback_evm_1.UNIVERSAL_CALLBACK_EVM; } });
+var universalReadRegistry_evm_1 = require("./constants/abi/universalReadRegistry.evm");
+Object.defineProperty(exports, "UNIVERSAL_READ_REGISTRY_EVM", { enumerable: true, get: function () { return universalReadRegistry_evm_1.UNIVERSAL_READ_REGISTRY_EVM; } });
 //# sourceMappingURL=index.js.map

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

@@ -219,8 +219,11 @@ async function buildHopDescriptor(ctx, params, route, ueaAddress) {
                 const svmFundsToken = burnAmount > BigInt(0)
                     ? params.funds?.token
                     : undefined;
-                const splMintBase58 = svmFundsToken?.mechanism === 'approve'
-                    ? svmFundsToken.address
+                const destinationFundsToken = svmFundsToken
+                    ? (0, route_handlers_1.resolveR2DestinationFundsToken)(svmFundsToken, targetChain, ctx.pushNetwork)
+                    : undefined;
+                const splMintBase58 = destinationFundsToken?.mechanism === 'approve'
+                    ? destinationFundsToken.address
                     : undefined;
                 let effectiveGasLimit = gasLimit;
                 if (prc20Token !== selectors_1.ZERO_ADDRESS) {

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

@@ -44,6 +44,12 @@ export declare class PushChainExecutionError extends Error {
         decodedError?: DecodedErrorPayload;
     });
 }
+/** Recovery metadata for a non-atomic Push batch. A pending hash is broadcast but unconfirmed. */
+export declare class PushChainBatchExecutionError extends PushChainExecutionError {
+    readonly transactionHashes: `0x${string}`[];
+    readonly pendingTransactionHash?: `0x${string}`;
+    constructor(message: string, transactionHashes: `0x${string}`[], pendingTransactionHash?: `0x${string}`);
+}
 export type PreflightPathTag = 'R2_EVM' | 'R2_SVM' | 'R3_EVM' | 'R3_SVM' | 'CASCADE';
 export type PreflightShortfallReason = 'NATIVE' | 'PRC20';
 export interface InsufficientUEABalanceErrorOpts {

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

@@ -10,7 +10,7 @@
  * callers.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InsufficientUEABalanceError = exports.PushChainExecutionError = void 0;
+exports.InsufficientUEABalanceError = exports.PushChainBatchExecutionError = exports.PushChainExecutionError = void 0;
 const formatters_1 = require("../../formatters");
 /**
  * Typed error for Route 1 Push Chain tx failures. Thrown by
@@ -39,6 +39,18 @@ class PushChainExecutionError extends Error {
     }
 }
 exports.PushChainExecutionError = PushChainExecutionError;
+/** Recovery metadata for a non-atomic Push batch. A pending hash is broadcast but unconfirmed. */
+class PushChainBatchExecutionError extends PushChainExecutionError {
+    transactionHashes;
+    pendingTransactionHash;
+    constructor(message, transactionHashes, pendingTransactionHash) {
+        super(message);
+        this.name = 'PushChainBatchExecutionError';
+        this.transactionHashes = [...transactionHashes];
+        this.pendingTransactionHash = pendingTransactionHash;
+    }
+}
+exports.PushChainBatchExecutionError = PushChainBatchExecutionError;
 /**
  * Thrown by `runPreflight` when the UEA cannot cover the required outbound
  * cost. No cosmos tx is submitted on this path — the existing silent-clamp

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

@@ -24,3 +24,4 @@ export { rescueFunds } from './rescue';
 export { executeFundsOnly } from './execute-funds-only';
 export { executeFundsWithPayload } from './execute-funds-payload';
 export { executeStandardPayload } from './execute-standard';
+export { prepareRead, simulateRead, trackRead, type TrackReadOptions } from './read-state';

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.quoteExactOutput = exports.calculateGasAmountFromAmountOutMinETH = exports.calculateNativeAmountForDeposit = exports.queryRescueGasFee = exports.queryOutboundGasFee = exports.ensureErc20Allowance = exports.detectRouteFromUniversalTxData = exports.reconstructProgressEvents = exports.transformToUniversalTxReceipt = exports.waitForInboundPushTx = exports.findChildUtxIdFromExternalTx = exports.INBOUND_MAX_TIMEOUT_MS = exports.INBOUND_INITIAL_WAIT_MS = exports.OUTBOUND_MAX_TIMEOUT_MS = exports.OUTBOUND_POLL_INTERVAL_MS = exports.OUTBOUND_INITIAL_WAIT_MS = exports.waitForAllOutboundTxsV2 = exports.waitForOutboundTx = exports.extractAllUniversalSubTxIds = exports.extractUniversalSubTxIdFromTx = exports.computeUniversalTxId = exports.getSvmGatewayLogIndexFromTx = exports.getSvmProtocolFee = exports.buildSvmUniversalTxRequestFromReq = exports.buildSvmUniversalTxRequest = exports.waitForLockerFeeConfirmation = exports.waitForSvmConfirmationsWithCountdown = exports.waitForEvmConfirmationsWithCountdown = exports.encodeUniversalPayloadSvm = exports.encodeUniversalPayload = exports.signMigrationPayload = exports.signUniversalPayload = exports.computeMigrationHash = exports.computeExecutionHash = exports.buildGatewayPayloadAndGas = exports.buildMulticallPayloadData = exports.buildUniversalTxRequest = exports.SUPPORTED_GATEWAY_CHAINS = exports.fetchOriginChainTransactionForProgress = exports.toExecuteParams = exports.bigintReplacer = exports.validateMainnetConnection = exports.getUniversalGatewayPCAddress = exports.getNativePRC20ForChain = exports.chainFromNamespace = exports.getChainNamespace = exports.getPushChainForNetwork = exports.isPushChain = exports.fireProgressHook = exports.printLog = void 0;
-exports.executeStandardPayload = exports.executeFundsWithPayload = exports.executeFundsOnly = exports.rescueFunds = exports.sendSVMTxWithFunds = exports.createCascadedBuilder = exports.composeCascade = exports.getSegmentType = exports.classifyIntoSegments = exports.buildHopDescriptor = exports.prepareTransaction = exports.buildPayloadForRoute = exports.executeCeaToCea = exports.executeCeaToPushSvm = exports.executeCeaToPush = exports.executeUoaToCeaSvm = exports.executeUoaToCea = exports.executeMultiChain = exports.extractPcTxAndTransform = exports.sendUniversalTx = exports.sendPushTx = exports.transformToUniversalTxResponse = exports.trackTransaction = exports.queryUniversalTxStatusFromGatewayTx = exports.getOriginGatewayContext = exports.lockFee = exports.sendGatewayTokenTxWithFallback = exports.sendGatewayTxWithFallback = exports.toGatewayTokenRequestV1 = exports.toGatewayRequestV1 = exports.migrateCEA = exports.fetchLatestUEAVersion = exports.upgradeAccount = exports.getAccountStatus = exports.fetchUEAVersion = exports.getUeaStatusAndNonce = exports.getUeaNonceForExecution = exports.getUEANonce = exports.computeUEA = exports.computeUEAOffchain = void 0;
+exports.trackRead = exports.simulateRead = exports.prepareRead = exports.executeStandardPayload = exports.executeFundsWithPayload = exports.executeFundsOnly = exports.rescueFunds = exports.sendSVMTxWithFunds = exports.createCascadedBuilder = exports.composeCascade = exports.getSegmentType = exports.classifyIntoSegments = exports.buildHopDescriptor = exports.prepareTransaction = exports.buildPayloadForRoute = exports.executeCeaToCea = exports.executeCeaToPushSvm = exports.executeCeaToPush = exports.executeUoaToCeaSvm = exports.executeUoaToCea = exports.executeMultiChain = exports.extractPcTxAndTransform = exports.sendUniversalTx = exports.sendPushTx = exports.transformToUniversalTxResponse = exports.trackTransaction = exports.queryUniversalTxStatusFromGatewayTx = exports.getOriginGatewayContext = exports.lockFee = exports.sendGatewayTokenTxWithFallback = exports.sendGatewayTxWithFallback = exports.toGatewayTokenRequestV1 = exports.toGatewayRequestV1 = exports.migrateCEA = exports.fetchLatestUEAVersion = exports.upgradeAccount = exports.getAccountStatus = exports.fetchUEAVersion = exports.getUeaStatusAndNonce = exports.getUeaNonceForExecution = exports.getUEANonce = exports.computeUEA = exports.computeUEAOffchain = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "printLog", { enumerable: true, get: function () { return context_1.printLog; } });
 Object.defineProperty(exports, "fireProgressHook", { enumerable: true, get: function () { return context_1.fireProgressHook; } });
@@ -135,4 +135,9 @@ var execute_funds_payload_1 = require("./execute-funds-payload");
 Object.defineProperty(exports, "executeFundsWithPayload", { enumerable: true, get: function () { return execute_funds_payload_1.executeFundsWithPayload; } });
 var execute_standard_1 = require("./execute-standard");
 Object.defineProperty(exports, "executeStandardPayload", { enumerable: true, get: function () { return execute_standard_1.executeStandardPayload; } });
+// === Read State (cross-chain reads) ===
+var read_state_1 = require("./read-state");
+Object.defineProperty(exports, "prepareRead", { enumerable: true, get: function () { return read_state_1.prepareRead; } });
+Object.defineProperty(exports, "simulateRead", { enumerable: true, get: function () { return read_state_1.simulateRead; } });
+Object.defineProperty(exports, "trackRead", { enumerable: true, get: function () { return read_state_1.trackRead; } });
 //# sourceMappingURL=index.js.map

package/src/lib/orchestrator/internals/push-chain-tx.js

@@ -32,10 +32,13 @@ async function getIndexedPushTransaction(ctx, txHash, label) {
     while (true) {
         try {
             if (!receiptWaited) {
-                await ctx.pushClient.publicClient.waitForTransactionReceipt({
+                const receipt = await ctx.pushClient.publicClient.waitForTransactionReceipt({
                     hash: txHash,
                 });
                 receiptWaited = true;
+                if (receipt.status === 'reverted') {
+                    throw new errors_1.PushChainExecutionError(`${label} — Push Chain transaction ${txHash} reverted`);
+                }
             }
             return await ctx.pushClient.getTransaction(txHash);
         }
@@ -116,75 +119,92 @@ async function sendPushTx(ctx, execute, eventBuffer, transformFn) {
             blockTag: 'pending',
         });
         let lastTxHash = '0x';
-        for (let i = 0; i < calls.length; i++) {
-            const call = calls[i];
-            let txSent = false;
-            for (let retry = 0; retry < MAX_NONCE_RETRIES && !txSent; retry++) {
-                try {
-                    (0, context_1.printLog)(ctx, `sendPushTx — executing multicall operation ${i + 1}/${calls.length} to: ${call.to} (nonce: ${nonce})`);
-                    lastTxHash = await ctx.pushClient.sendTransaction({
-                        to: call.to,
-                        data: (call.data || '0x'),
-                        value: call.value,
-                        signer: ctx.universalSigner,
-                        nonce,
-                    });
-                    txSent = true;
-                }
-                catch (err) {
-                    const msg = err?.message || err?.details || '';
-                    if (msg.includes('invalid nonce') || msg.includes('invalid sequence')) {
-                        (0, context_1.printLog)(ctx, `sendPushTx — nonce mismatch on operation ${i + 1}/${calls.length} (retry ${retry + 1}/${MAX_NONCE_RETRIES}), re-fetching nonce`);
-                        nonce = await ctx.pushClient.publicClient.getTransactionCount({
-                            address: ctx.universalSigner.account.address,
-                            blockTag: 'pending',
+        // Hashes of the calls that were mined successfully, in order. On a later
+        // failure they ride on the thrown error (`err.transactionHashes`) so the caller
+        // can resume whatever those calls committed — the batch is not atomic.
+        const transactionHashes = [];
+        let pendingTransactionHash;
+        try {
+            for (let i = 0; i < calls.length; i++) {
+                const call = calls[i];
+                let txSent = false;
+                for (let retry = 0; retry < MAX_NONCE_RETRIES && !txSent; retry++) {
+                    try {
+                        (0, context_1.printLog)(ctx, `sendPushTx — executing multicall operation ${i + 1}/${calls.length} to: ${call.to} (nonce: ${nonce})`);
+                        lastTxHash = await ctx.pushClient.sendTransaction({
+                            to: call.to,
+                            data: (call.data || '0x'),
+                            value: call.value,
+                            signer: ctx.universalSigner,
+                            nonce,
                         });
+                        txSent = true;
+                        pendingTransactionHash = lastTxHash;
                     }
-                    else {
-                        throw err;
+                    catch (err) {
+                        const msg = err?.message || err?.details || '';
+                        if (msg.includes('invalid nonce') || msg.includes('invalid sequence')) {
+                            (0, context_1.printLog)(ctx, `sendPushTx — nonce mismatch on operation ${i + 1}/${calls.length} (retry ${retry + 1}/${MAX_NONCE_RETRIES}), re-fetching nonce`);
+                            nonce = await ctx.pushClient.publicClient.getTransactionCount({
+                                address: ctx.universalSigner.account.address,
+                                blockTag: 'pending',
+                            });
+                        }
+                        else {
+                            throw err;
+                        }
                     }
                 }
-            }
-            if (!txSent) {
-                throw new Error(`sendPushTx — multicall operation ${i + 1}/${calls.length} failed after ${MAX_NONCE_RETRIES} nonce retries`);
-            }
-            const receipt = await ctx.pushClient.publicClient.waitForTransactionReceipt({
-                hash: lastTxHash,
-            });
-            if (receipt.status === 'reverted') {
-                // Simulate the failed call to extract the revert reason
-                let revertReason = 'unknown';
-                try {
-                    await ctx.pushClient.publicClient.call({
-                        to: call.to,
-                        data: (call.data || '0x'),
-                        value: call.value,
-                        account: ctx.universalSigner.account.address,
-                        blockNumber: receipt.blockNumber,
-                    });
+                if (!txSent) {
+                    throw new Error(`sendPushTx — multicall operation ${i + 1}/${calls.length} failed after ${MAX_NONCE_RETRIES} nonce retries`);
                 }
-                catch (simErr) {
-                    // viem decodes common revert reasons into shortMessage
-                    revertReason =
-                        simErr?.shortMessage || simErr?.cause?.reason || simErr?.cause?.message || simErr?.message || String(simErr);
-                    // Also log the raw revert data if available
-                    const revertData = simErr?.cause?.data || simErr?.data;
-                    if (revertData) {
-                        revertReason += ` [data: ${revertData}]`;
+                const receipt = await ctx.pushClient.publicClient.waitForTransactionReceipt({
+                    hash: lastTxHash,
+                });
+                if (receipt.status === 'reverted') {
+                    pendingTransactionHash = undefined;
+                    // Simulate the failed call to extract the revert reason
+                    let revertReason = 'unknown';
+                    try {
+                        await ctx.pushClient.publicClient.call({
+                            to: call.to,
+                            data: (call.data || '0x'),
+                            value: call.value,
+                            account: ctx.universalSigner.account.address,
+                            blockNumber: receipt.blockNumber,
+                        });
                     }
+                    catch (simErr) {
+                        // viem decodes common revert reasons into shortMessage
+                        revertReason =
+                            simErr?.shortMessage || simErr?.cause?.reason || simErr?.cause?.message || simErr?.message || String(simErr);
+                        // Also log the raw revert data if available
+                        const revertData = simErr?.cause?.data || simErr?.data;
+                        if (revertData) {
+                            revertReason += ` [data: ${revertData}]`;
+                        }
+                    }
+                    (0, context_1.printLog)(ctx, `sendPushTx — multicall operation ${i + 1}/${calls.length} reverted (to: ${call.to}, txHash: ${lastTxHash}, revertReason: ${revertReason})`);
+                    throw new Error(`sendPushTx — multicall operation ${i + 1}/${calls.length} reverted (to: ${call.to}, txHash: ${lastTxHash}, revertReason: ${revertReason})`);
                 }
-                (0, context_1.printLog)(ctx, `sendPushTx — multicall operation ${i + 1}/${calls.length} reverted (to: ${call.to}, txHash: ${lastTxHash}, revertReason: ${revertReason})`);
-                throw new Error(`sendPushTx — multicall operation ${i + 1}/${calls.length} reverted (to: ${call.to}, txHash: ${lastTxHash}, revertReason: ${revertReason})`);
+                transactionHashes.push(lastTxHash);
+                pendingTransactionHash = undefined;
+                (0, context_1.printLog)(ctx, `sendPushTx — operation ${i + 1}/${calls.length} confirmed in block ${receipt.blockNumber}`);
+                nonce++;
             }
-            (0, context_1.printLog)(ctx, `sendPushTx — operation ${i + 1}/${calls.length} confirmed in block ${receipt.blockNumber}`);
-            nonce++;
+            const txResponse = await getIndexedPushTransaction(ctx, lastTxHash, 'sendPushTx');
+            // Sequential fallback: each call was a separate tx, so the batch is NOT
+            // atomic (an earlier call can be committed while a later one reverts).
+            const resp = await transformFn(txResponse, eventBuffer);
+            resp.atomic = false;
+            resp.transactionHashes = transactionHashes;
+            return resp;
+        }
+        catch (error) {
+            // Preserve recovery data across receipt waits, nonce refresh, indexing and
+            // response construction, not only errors raised by sendTransaction().
+            throw new errors_1.PushChainBatchExecutionError((0, formatters_1.normalizePublicErrorMessage)(error), transactionHashes, pendingTransactionHash);
         }
-        const txResponse = await getIndexedPushTransaction(ctx, lastTxHash, 'sendPushTx');
-        // Sequential fallback: each call was a separate tx, so the batch is NOT
-        // atomic (an earlier call can be committed while a later one reverts).
-        const resp = await transformFn(txResponse, eventBuffer);
-        resp.atomic = false;
-        return resp;
     }
     const txHash = await ctx.pushClient.sendTransaction({
         to: execute.to,

package/src/lib/orchestrator/internals/read-state.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Read-state delegators. Thin: they bind an OrchestratorContext to the pure
+ * `read-state/` module and add nothing else.
+ */
+import type { Address, Hex } from 'viem';
+import type { BuildReadSpecParams, PreparedRead, ReadLifecycleOptions, SimulateReadResult, UniversalReadResponse } from '../../read-state/read-state.types';
+import type { ProgressEvent } from '../../progress-hook/progress-hook.types';
+import { type OrchestratorContext } from './context';
+export declare function prepareRead(ctx: OrchestratorContext, params: BuildReadSpecParams, progressHook?: (e: ProgressEvent) => void): Promise<PreparedRead>;
+export declare function simulateRead(ctx: OrchestratorContext, prepared: PreparedRead, opts: {
+    appContract: Address;
+    callbackSelector: Hex;
+    staleAfterMs?: number;
+}): Promise<SimulateReadResult>;
+export type TrackReadOptions = ReadLifecycleOptions & {
+    /** Per-call hook, additive with the init-time one (deduped by reference). */
+    progressHook?: (e: ProgressEvent) => void;
+};
+export declare function trackRead(ctx: OrchestratorContext, ref: {
+    txHash: Hex;
+}, opts?: TrackReadOptions): Promise<UniversalReadResponse[]>;
+export declare function trackRead(ctx: OrchestratorContext, ref: {
+    requestId: Hex | bigint;
+}, opts?: TrackReadOptions): Promise<UniversalReadResponse>;

package/src/lib/orchestrator/internals/read-state.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareRead = prepareRead;
+exports.simulateRead = simulateRead;
+exports.trackRead = trackRead;
+const tslib_1 = require("tslib");
+const spec_builder_1 = require("../../read-state/spec-builder");
+const read_tracker_1 = require("../../read-state/read-tracker");
+const progress_hook_1 = tslib_1.__importDefault(require("../../progress-hook/progress-hook"));
+const context_1 = require("./context");
+const uea_manager_1 = require("./uea-manager");
+function depsFrom(ctx) {
+    let defaultRefundTo;
+    try {
+        // The signer's Push-side account: its UEA for an external origin, itself on Push.
+        defaultRefundTo = (0, uea_manager_1.computeUEAOffchain)(ctx);
+    }
+    catch {
+        defaultRefundTo = undefined; // read-only clients without a resolvable account: refundTo becomes required
+    }
+    return { pushClient: ctx.pushClient, pushNetwork: ctx.pushNetwork, defaultRefundTo };
+}
+function prepareRead(ctx, params, progressHook) {
+    return (0, spec_builder_1.prepareRead)({ ...depsFrom(ctx), emit: trackDepsFrom(ctx, progressHook).emit }, params);
+}
+function simulateRead(ctx, prepared, opts) {
+    return (0, spec_builder_1.simulateRead)(depsFrom(ctx), prepared, opts);
+}
+function trackDepsFrom(ctx, perCall) {
+    const extra = perCall && perCall !== ctx.progressHook ? perCall : undefined;
+    return {
+        pushClient: ctx.pushClient,
+        pushNetwork: ctx.pushNetwork,
+        // READ-TX ids are a separate band: fireProgressHook never suppresses them (context.ts R1 set).
+        emit: (hookId, ...args) => {
+            (0, context_1.fireProgressHook)(ctx, hookId, ...args);
+            if (extra)
+                extra(progress_hook_1.default[hookId](...args));
+        },
+    };
+}
+function trackRead(ctx, ref, opts = {}) {
+    const { progressHook, ...lifecycle } = opts;
+    const deps = trackDepsFrom(ctx, progressHook);
+    return 'txHash' in ref ? (0, read_tracker_1.trackRead)(deps, ref, lifecycle) : (0, read_tracker_1.trackRead)(deps, ref, lifecycle);
+}
+//# sourceMappingURL=read-state.js.map

package/src/lib/orchestrator/internals/route-handlers.js

@@ -861,7 +861,12 @@ async function executeUoaToCeaSvm(ctx, params, target, executeFn) {
     const svmFundsToken = burnAmount > BigInt(0)
         ? params.funds?.token
         : undefined;
-    const splMintBase58 = svmFundsToken?.mechanism === 'approve' ? svmFundsToken.address : undefined;
+    const destinationFundsToken = svmFundsToken
+        ? resolveR2DestinationFundsToken(svmFundsToken, targetChain, ctx.pushNetwork)
+        : undefined;
+    const splMintBase58 = destinationFundsToken?.mechanism === 'approve'
+        ? destinationFundsToken.address
+        : undefined;
     if (prc20Token !== selectors_1.ZERO_ADDRESS) {
         (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_202_01, targetChain);
         try {

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

@@ -11,6 +11,7 @@ const tslib_1 = require("tslib");
 const web3_js_1 = require("@solana/web3.js");
 const viem_1 = require("viem");
 const universalGatewayV0_json_1 = tslib_1.__importDefault(require("../../constants/abi/universalGatewayV0.json"));
+const svm_events_1 = require("../../universal-tx-detector/svm-events");
 // ============================================================================
 // SVM Request Builders
 // ============================================================================
@@ -144,6 +145,29 @@ function isPC20EventBody(decoded) {
  * position, so it survives a change in emission order.
  */
 function getSvmGatewayLogIndexFromTx(txResp, preferPC20 = false) {
+    const cpiPayloads = (0, svm_events_1.getSvmEventCpiPayloads)(txResp, universalGatewayV0_json_1.default.address);
+    if (cpiPayloads.length > 0) {
+        let lastMatchIndex = -1;
+        let pc20MatchIndex = -1;
+        let matchCount = 0;
+        for (const { base64Data, eventIndex } of cpiPayloads) {
+            const decoded = new Uint8Array(Buffer.from(base64Data, 'base64'));
+            const discriminatorHex = (0, viem_1.bytesToHex)(decoded.slice(0, 8)).slice(2);
+            if (discriminatorHex !== SVM_GATEWAY_EVENT_DISCRIMINATOR)
+                continue;
+            matchCount++;
+            lastMatchIndex = eventIndex;
+            if (preferPC20 && pc20MatchIndex === -1 && isPC20EventBody(decoded)) {
+                pc20MatchIndex = eventIndex;
+            }
+            if (!preferPC20 && matchCount === 2)
+                return eventIndex;
+        }
+        if (preferPC20 && pc20MatchIndex !== -1)
+            return pc20MatchIndex;
+        if (lastMatchIndex !== -1)
+            return lastMatchIndex;
+    }
     const logs = (txResp?.meta?.logMessages || []);
     if (!Array.isArray(logs) || logs.length === 0)
         return 0;

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

@@ -6,6 +6,10 @@ import { PushClient } from '../push-client/push-client';
 import type { UniversalAccount, UniversalSigner } from '../universal/universal.types';
 import { ExecuteParams, UniversalExecuteParams, PreparedUniversalTx, CascadedTxResponse, CascadeExecutionOptions, TransactionExecutionOptions, RescueFundsParams } from './orchestrator.types';
 import { TransactionRoute } from './route-detector';
+import { type TrackReadOptions } from './internals';
+import type { BuildReadSpecParams, PreparedRead, SimulateReadResult, UniversalReadResponse } from '../read-state/read-state.types';
+import type { Address, Hex } from 'viem';
+type ProgressHook = (progress: ProgressEvent) => void;
 export declare class Orchestrator {
     private readonly universalSigner;
     private pushNetwork;
@@ -56,6 +60,27 @@ export declare class Orchestrator {
      * @returns Transaction response
      */
     migrateCEA(chain: CHAIN): Promise<UniversalTxResponse>;
+    /**
+     * Build a validated cross-chain ReadSpec (preflight + envelope + fee/budget) for the
+     * caller to splice into its own contract call. Works in read-only mode.
+     */
+    prepareRead(params: BuildReadSpecParams, progressHook?: ProgressHook): Promise<PreparedRead>;
+    revalidateRead(prepared: PreparedRead): Promise<void>;
+    /** Current native Push balance of the account that will fund read requests. */
+    getReadBalance(): Promise<bigint>;
+    /** eth_call requestExternalReadSelf as the app contract; decodes contract errors. */
+    simulateRead(prepared: PreparedRead, opts: {
+        appContract: Address;
+        callbackSelector: Hex;
+        staleAfterMs?: number;
+    }): Promise<SimulateReadResult>;
+    /** Resume a read by the Push tx that requested it (array) or by requestId (single). */
+    trackRead(ref: {
+        txHash: Hex;
+    }, opts?: TrackReadOptions): Promise<UniversalReadResponse[]>;
+    trackRead(ref: {
+        requestId: Hex | bigint;
+    }, opts?: TrackReadOptions): Promise<UniversalReadResponse>;
     /**
      * Rescue stuck funds on a source chain.
      * When a CEA-to-Push inbound transaction fails, tokens get locked in the
@@ -149,3 +174,4 @@ export declare class Orchestrator {
         to: MoveableToken | undefined;
     }): Promise<ConversionQuote>;
 }
+export {};