@pushchain/core 6.0.24 → 6.0.26

package/src/lib/orchestrator/orchestrator.js

@@ -9,6 +9,7 @@ const formatters_1 = require("../formatters");
 const route_detector_1 = require("./route-detector");
 const data_utils_1 = require("./data-utils");
 const internals_1 = require("./internals");
+const spec_builder_1 = require("../read-state/spec-builder");
 const gate_1 = require("./internals/pc20/gate");
 class Orchestrator {
     universalSigner;
@@ -117,6 +118,27 @@ class Orchestrator {
     async migrateCEA(chain) {
         return (0, internals_1.migrateCEA)(this.ctx, chain, this.execute.bind(this));
     }
+    /**
+     * 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.
+     */
+    async prepareRead(params, progressHook) {
+        return (0, internals_1.prepareRead)(this.ctx, params, progressHook);
+    }
+    async revalidateRead(prepared) {
+        return (0, spec_builder_1.revalidateRead)({ pushClient: this.ctx.pushClient, pushNetwork: this.ctx.pushNetwork }, prepared);
+    }
+    /** Current native Push balance of the account that will fund read requests. */
+    async getReadBalance() {
+        return this.ctx.pushClient.getBalance(this.computeUEAOffchain());
+    }
+    /** eth_call requestExternalReadSelf as the app contract; decodes contract errors. */
+    async simulateRead(prepared, opts) {
+        return (0, internals_1.simulateRead)(this.ctx, prepared, opts);
+    }
+    trackRead(ref, opts) {
+        return 'txHash' in ref ? (0, internals_1.trackRead)(this.ctx, ref, opts) : (0, internals_1.trackRead)(this.ctx, ref, opts);
+    }
     /**
      * Rescue stuck funds on a source chain.
      * When a CEA-to-Push inbound transaction fails, tokens get locked in the

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

@@ -352,6 +352,8 @@ export interface UniversalTxResponse {
      * (separate per-call txs — an earlier call can commit while a later one reverts).
      */
     atomic: boolean;
+    /** All Push hashes in submission order when a batch uses sequential fallback. */
+    transactionHashes?: `0x${string}`[];
     signature: Signature;
     raw?: {
         from: string;

package/src/lib/orchestrator/route-detector.js

@@ -214,6 +214,10 @@ function detectRoute(params) {
  * @throws ChainNotSupportedError if chain is not supported
  */
 function validateRouteParams(params, context) {
+    const toChain = isChainTarget(params.to) ? String(params.to.chain) : undefined;
+    if (String(params.from?.chain ?? '') === enums_1.CHAIN.WEB2 || toChain === enums_1.CHAIN.WEB2) {
+        throw new RouteValidationError('CHAIN.WEB2 is a read-only destination and cannot be used with transaction APIs');
+    }
     const route = detectRoute(params);
     // Validate from.chain is supported external chain (Routes 3, 4)
     if (params.from?.chain) {

package/src/lib/progress-hook/progress-hook.js

@@ -4,6 +4,16 @@ exports.classifyDeclineError = classifyDeclineError;
 const formatters_1 = require("../formatters");
 const utils_1 = require("../utils");
 const progress_hook_types_1 = require("./progress-hook.types");
+function serializeReadValue(value) {
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (Array.isArray(value))
+        return value.map(serializeReadValue);
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, serializeReadValue(item)]));
+    }
+    return value;
+}
 // Helper to wrap a hook function with timestamp
 const withTimestamp = (fn) => {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -942,6 +952,287 @@ const RAW_HOOKS_MULTICHAIN = {
         level: 'ERROR',
     }),
 };
+// ---------------------------------------------------------------------------
+// Read state (cross-chain reads) — READ-TX band.
+// Copy is locked by __tests__/read-tx-spec-strings.spec.ts; change both together.
+// `response` objects carry the machine-readable values (bigints as strings).
+// ---------------------------------------------------------------------------
+const str = (v) => v === undefined ? undefined : v.toString();
+const RAW_HOOKS_READ = {
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_101]: (chain, namespace, queryType) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_101,
+        title: `${friendlyChain(chain)} Read Requested`,
+        message: `Preparing a ${namespace} read (query type ${queryType}) of ${chain}`,
+        response: { chain, namespace, queryType },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_01]: (chain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_01,
+        title: 'Fetching Destination Height & Fee',
+        message: `Reading the oracle height and protocol fee for ${chain}`,
+        response: { chain, stage: 'preflight' },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_02]: (protocolFee, callbackBudget, total, blockNumber, expiryPushChainHeight) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_02,
+        title: 'Read Spec Assembled',
+        message: `Pinned at block ${blockNumber}, expires at Push height ${expiryPushChainHeight}; fee ${protocolFee} + budget ${callbackBudget} = ${total} UPC`,
+        response: {
+            protocolFee: str(protocolFee),
+            callbackBudget: str(callbackBudget),
+            totalValue: str(total),
+            blockNumber: str(blockNumber),
+            expiryPushChainHeight: str(expiryPushChainHeight),
+        },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_03]: (chain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_03,
+        title: 'Destination Height Unavailable',
+        message: `The oracle has no height for ${chain} — this chain is not readable`,
+        response: { chain },
+        level: 'ERROR',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_04]: (fetchedAt, ageMs) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_04,
+        title: 'Preflight Stale, Refetching',
+        message: `Preflight is ${Math.round(ageMs / 1000)}s old — refetching the Push height`,
+        response: { fetchedAt, ageMs },
+        level: 'WARNING',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_05]: (refundTo) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_05,
+        title: 'Refund Target Is A Contract',
+        message: `${refundTo} is a contract that is not a UEA — it needs a payable receive() or the unspent budget is forfeited`,
+        response: { refundTo },
+        level: 'WARNING',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_103_01]: (required, available, enforceGasCheck = false) => {
+        const sufficient = available >= required;
+        const shortfall = sufficient ? BigInt(0) : required - available;
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_103_01,
+            title: 'Checking Balance Requirements',
+            message: sufficient
+                ? `Balance ${available} UPC covers the ${required} UPC read`
+                : `Balance ${available} UPC is ${shortfall} UPC short of ${required} UPC`,
+            response: {
+                required: str(required),
+                available: str(available),
+                sufficient,
+                shortfall: str(shortfall),
+                enforceGasCheck,
+            },
+            level: sufficient ? 'INFO' : 'WARNING',
+        };
+    },
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_103_02]: (required, available) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_103_02,
+        title: 'Insufficient Balance',
+        message: `Need ${required} UPC, have ${available} UPC`,
+        response: {
+            required: str(required),
+            available: str(available),
+            shortfall: str(required - available),
+        },
+        level: 'ERROR',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_103_03]: (matchedHeaders) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_103_03,
+        title: 'Sensitive Header Detected',
+        message: `Headers are written to a public event log forever: ${matchedHeaders.join(', ')}`,
+        response: { matchedHeaders },
+        level: 'WARNING',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_01]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_01,
+        title: 'Broadcasting Read Request',
+        message: 'Sending the read request to Push Chain',
+        response: { stage: 'broadcasting' },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_02]: (txHash, requestId, logIndex) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_02,
+        title: 'Request Confirmed, Read Detected',
+        message: `Read ${requestId} requested in ${txHash} (log ${logIndex})`,
+        response: { txHash, requestId, logIndex },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_03]: (ref) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_03,
+        title: 'Looking Up Request',
+        message: `Looking up ${'requestId' in ref ? `read ${ref.requestId}` : `reads in ${ref.txHash}`} on Push Chain`,
+        response: { ...ref },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_04]: (requestId, status) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_04,
+        title: 'Request Found',
+        message: `Read ${requestId} found (status ${status})`,
+        response: { requestId, status },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_05]: (ref, elapsedMs) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_05,
+        title: 'Request Not Found',
+        message: `No read found for ${'requestId' in ref ? ref.requestId : ref.txHash} after ${Math.round(elapsedMs / 1000)}s`,
+        response: { ...ref, elapsedMs },
+        level: 'ERROR',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_01]: (requestId) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_01,
+        title: 'Awaiting Quorum',
+        message: `Validators are observing the destination for ${requestId}`,
+        response: { requestId, status: 'PENDING' },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_02]: (requestId) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_02,
+        title: 'Voting In Progress',
+        message: `Validators are voting on the result of ${requestId}`,
+        response: { requestId, status: 'VOTING' },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_03]: (requestId, current, required) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_03,
+        title: 'Awaiting Destination Confirmations',
+        message: `${current} of ${required} confirmations on the destination for ${requestId}`,
+        response: { requestId, current: str(current), required: str(required) },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_04]: (requestId, pushBlocksRemaining) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_04,
+        title: 'Approaching Expiry',
+        message: `${pushBlocksRemaining} Push blocks until ${requestId} expires`,
+        response: { requestId, pushBlocksRemaining: str(pushBlocksRemaining) },
+        level: 'WARNING',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_01]: (requestId, callbackTarget) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_01,
+        title: 'Quorum Reached, Executing Callback',
+        message: `Delivering the result of ${requestId} to ${callbackTarget}`,
+        response: { requestId, callbackTarget },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_02]: (requestId) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_02,
+        title: 'Callback Delivered',
+        message: `ReadFulfilled emitted for ${requestId}`,
+        response: { requestId },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_03]: (requestId, reason) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_03,
+        title: 'Callback Reverted',
+        message: `CallbackFailed for ${requestId} — the read is still FULFILLED but your callback did not run`,
+        response: { requestId, reason: reason ?? null },
+        level: 'WARNING',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_04]: (requestId, burned, refunded) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_04,
+        title: 'Callback Gas Settled',
+        message: `Burned ${burned} UPC, refunding ${refunded} UPC for ${requestId}`,
+        response: { requestId, burned: str(burned), refunded: str(refunded) },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_05]: (requestId, amount, refundTo) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_05,
+        title: 'Refund Sent',
+        message: `${amount} UPC pushed to ${refundTo}`,
+        response: { requestId, amount: str(amount), refundTo },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_06]: (requestId, amount, refundTo) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_06,
+        title: 'Refund Rejected',
+        message: `${refundTo} rejected the refund — it sits in the admin rescue pool`,
+        response: { requestId, amount: str(amount) ?? null, refundTo },
+        level: 'WARNING',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_01]: (requestId, value, resultData, callbackDelivered) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_01,
+        title: 'Read Fulfilled',
+        message: callbackDelivered
+            ? `Read ${requestId} fulfilled and delivered`
+            : `Read ${requestId} fulfilled — callback not delivered`,
+        response: {
+            requestId,
+            value: serializeReadValue(value) ?? null,
+            resultData,
+            callbackDelivered: callbackDelivered ?? null,
+        },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_02]: (requestId, status, errorCode, errorMsg, refunded) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_02,
+        title: 'Read Failed / Expired / Aborted',
+        message: `Read ${requestId} ended ${status}${errorMsg ? `: ${errorMsg}` : ''}`,
+        response: {
+            requestId,
+            status,
+            errorCode: errorCode ?? null,
+            errorMsg,
+            refunded: str(refunded) ?? null,
+        },
+        level: 'ERROR',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_03]: (requestId, lastStatus, elapsedMs) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_03,
+        title: 'Read Timeout',
+        message: `Gave up waiting for ${requestId} after ${Math.round(elapsedMs / 1000)}s (last status ${lastStatus}) — resume with trackRead`,
+        response: { requestId, lastStatus, elapsedMs },
+        level: 'ERROR',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_99]: (requestId, txHash) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_99,
+        title: 'Intermediate Read Step Completed',
+        message: `Read ${requestId} advanced in ${txHash}`,
+        response: { requestId, txHash },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_001]: (count, chains) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_001,
+        title: 'Batch Read Initiated',
+        message: `Preparing ${count} reads across ${chains.join(', ')}`,
+        response: { count, chains },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_002_01]: (n, total, chain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_002_01,
+        title: `Starting Read #${n}/${total}`,
+        message: `Read ${n} of ${total} targets ${chain}`,
+        response: { n, total, chain },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_002_99_99]: (n, total, requestId) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_002_99_99,
+        title: `Read #${n}/${total} Complete`,
+        message: `Read ${n} of ${total} settled as ${requestId}`,
+        response: { n, total, requestId },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_999_01]: (count) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_999_01,
+        title: 'All Reads Fulfilled',
+        message: `All ${count} reads fulfilled`,
+        response: { count },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_999_02]: (failedAt, total, error) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_999_02,
+        title: 'Batch Reads Failed',
+        message: `Batch failed at read ${failedAt} of ${total}: ${error}`,
+        response: { failedAt, total, error },
+        level: 'ERROR',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_999_03]: (failedAt, total) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_999_03,
+        title: 'Batch Reads Timeout',
+        message: `Batch timed out at read ${failedAt} of ${total}`,
+        response: { failedAt, total, error: 'read timeout' },
+        level: 'ERROR',
+    }),
+};
 // Combine all routes into the master record
 const RAW_HOOKS = {
     ...RAW_HOOKS_R1,
@@ -949,6 +1240,7 @@ const RAW_HOOKS = {
     ...RAW_HOOKS_R3,
     ...RAW_HOOKS_MULTICHAIN,
     ...RAW_HOOKS_MIG,
+    ...RAW_HOOKS_READ,
 };
 // Build final hooks with timestamp injection
 const PROGRESS_HOOKS = Object.fromEntries(Object.entries(RAW_HOOKS).map(([key, value]) => [key, withTimestamp(value)]));

package/src/lib/progress-hook/progress-hook.types.d.ts

@@ -95,6 +95,40 @@ export declare enum PROGRESS_HOOK {
     SEND_TX_999_01 = "SEND-TX-999-01",
     SEND_TX_999_02 = "SEND-TX-999-02",
     SEND_TX_999_03 = "SEND-TX-999-03",
+    READ_TX_101 = "READ-TX-101",
+    READ_TX_102_01 = "READ-TX-102-01",
+    READ_TX_102_02 = "READ-TX-102-02",
+    READ_TX_102_03 = "READ-TX-102-03",
+    READ_TX_102_04 = "READ-TX-102-04",
+    READ_TX_102_05 = "READ-TX-102-05",
+    READ_TX_103_01 = "READ-TX-103-01",
+    READ_TX_103_02 = "READ-TX-103-02",
+    READ_TX_103_03 = "READ-TX-103-03",
+    READ_TX_104_01 = "READ-TX-104-01",
+    READ_TX_104_02 = "READ-TX-104-02",
+    READ_TX_104_03 = "READ-TX-104-03",
+    READ_TX_104_04 = "READ-TX-104-04",
+    READ_TX_104_05 = "READ-TX-104-05",
+    READ_TX_105_01 = "READ-TX-105-01",
+    READ_TX_105_02 = "READ-TX-105-02",
+    READ_TX_105_03 = "READ-TX-105-03",
+    READ_TX_105_04 = "READ-TX-105-04",
+    READ_TX_106_01 = "READ-TX-106-01",
+    READ_TX_106_02 = "READ-TX-106-02",
+    READ_TX_106_03 = "READ-TX-106-03",
+    READ_TX_106_04 = "READ-TX-106-04",
+    READ_TX_106_05 = "READ-TX-106-05",
+    READ_TX_106_06 = "READ-TX-106-06",
+    READ_TX_199_01 = "READ-TX-199-01",
+    READ_TX_199_02 = "READ-TX-199-02",
+    READ_TX_199_03 = "READ-TX-199-03",
+    READ_TX_199_99 = "READ-TX-199-99",
+    READ_TX_001 = "READ-TX-001",
+    READ_TX_002_01 = "READ-TX-002-01",
+    READ_TX_002_99_99 = "READ-TX-002-99-99",
+    READ_TX_999_01 = "READ-TX-999-01",
+    READ_TX_999_02 = "READ-TX-999-02",
+    READ_TX_999_03 = "READ-TX-999-03",
     UEA_MIG_01 = "UEA-MIG-01",
     UEA_MIG_02 = "UEA-MIG-02",
     UEA_MIG_03 = "UEA-MIG-03",
@@ -107,4 +141,5 @@ export type PROGRESS_HOOK_R2 = PROGRESS_HOOK.SEND_TX_201 | PROGRESS_HOOK.SEND_TX
 export type PROGRESS_HOOK_R3 = PROGRESS_HOOK.SEND_TX_301 | PROGRESS_HOOK.SEND_TX_302_01 | PROGRESS_HOOK.SEND_TX_302_02 | PROGRESS_HOOK.SEND_TX_303_01 | PROGRESS_HOOK.SEND_TX_303_02 | PROGRESS_HOOK.SEND_TX_303_03_01 | PROGRESS_HOOK.SEND_TX_303_03_02 | PROGRESS_HOOK.SEND_TX_303_03_03 | PROGRESS_HOOK.SEND_TX_303_04 | PROGRESS_HOOK.SEND_TX_303_05 | PROGRESS_HOOK.SEND_TX_303_06 | PROGRESS_HOOK.SEND_TX_304_01 | PROGRESS_HOOK.SEND_TX_304_02 | PROGRESS_HOOK.SEND_TX_304_03 | PROGRESS_HOOK.SEND_TX_304_04 | PROGRESS_HOOK.SEND_TX_307 | PROGRESS_HOOK.SEND_TX_309_01 | PROGRESS_HOOK.SEND_TX_309_02 | PROGRESS_HOOK.SEND_TX_309_03 | PROGRESS_HOOK.SEND_TX_310_01 | PROGRESS_HOOK.SEND_TX_310_02 | PROGRESS_HOOK.SEND_TX_399_01 | PROGRESS_HOOK.SEND_TX_399_02 | PROGRESS_HOOK.SEND_TX_399_03 | PROGRESS_HOOK.SEND_TX_399_99;
 export type PROGRESS_HOOK_MULTICHAIN = PROGRESS_HOOK.SEND_TX_001 | PROGRESS_HOOK.SEND_TX_002_01 | PROGRESS_HOOK.SEND_TX_002_99_99 | PROGRESS_HOOK.SEND_TX_003_03 | PROGRESS_HOOK.SEND_TX_003_04 | PROGRESS_HOOK.SEND_TX_003_05 | PROGRESS_HOOK.SEND_TX_999_01 | PROGRESS_HOOK.SEND_TX_999_02 | PROGRESS_HOOK.SEND_TX_999_03;
 export type PROGRESS_HOOK_MIG = PROGRESS_HOOK.UEA_MIG_01 | PROGRESS_HOOK.UEA_MIG_02 | PROGRESS_HOOK.UEA_MIG_03 | PROGRESS_HOOK.UEA_MIG_9901 | PROGRESS_HOOK.UEA_MIG_9902 | PROGRESS_HOOK.UEA_MIG_9903;
+export type PROGRESS_HOOK_READ = PROGRESS_HOOK.READ_TX_101 | PROGRESS_HOOK.READ_TX_102_01 | PROGRESS_HOOK.READ_TX_102_02 | PROGRESS_HOOK.READ_TX_102_03 | PROGRESS_HOOK.READ_TX_102_04 | PROGRESS_HOOK.READ_TX_102_05 | PROGRESS_HOOK.READ_TX_103_01 | PROGRESS_HOOK.READ_TX_103_02 | PROGRESS_HOOK.READ_TX_103_03 | PROGRESS_HOOK.READ_TX_104_01 | PROGRESS_HOOK.READ_TX_104_02 | PROGRESS_HOOK.READ_TX_104_03 | PROGRESS_HOOK.READ_TX_104_04 | PROGRESS_HOOK.READ_TX_104_05 | PROGRESS_HOOK.READ_TX_105_01 | PROGRESS_HOOK.READ_TX_105_02 | PROGRESS_HOOK.READ_TX_105_03 | PROGRESS_HOOK.READ_TX_105_04 | PROGRESS_HOOK.READ_TX_106_01 | PROGRESS_HOOK.READ_TX_106_02 | PROGRESS_HOOK.READ_TX_106_03 | PROGRESS_HOOK.READ_TX_106_04 | PROGRESS_HOOK.READ_TX_106_05 | PROGRESS_HOOK.READ_TX_106_06 | PROGRESS_HOOK.READ_TX_199_01 | PROGRESS_HOOK.READ_TX_199_02 | PROGRESS_HOOK.READ_TX_199_03 | PROGRESS_HOOK.READ_TX_199_99 | PROGRESS_HOOK.READ_TX_001 | PROGRESS_HOOK.READ_TX_002_01 | PROGRESS_HOOK.READ_TX_002_99_99 | PROGRESS_HOOK.READ_TX_999_01 | PROGRESS_HOOK.READ_TX_999_02 | PROGRESS_HOOK.READ_TX_999_03;
 export {};

package/src/lib/progress-hook/progress-hook.types.js

@@ -103,6 +103,43 @@ var PROGRESS_HOOK;
     PROGRESS_HOOK["SEND_TX_999_01"] = "SEND-TX-999-01";
     PROGRESS_HOOK["SEND_TX_999_02"] = "SEND-TX-999-02";
     PROGRESS_HOOK["SEND_TX_999_03"] = "SEND-TX-999-03";
+    // Read state (cross-chain reads) — single read 101–199, batch 001 / 999.
+    // A distinct flow from sendTransaction: NEVER add these to the R1 suppression
+    // set in orchestrator/internals/context.ts.
+    PROGRESS_HOOK["READ_TX_101"] = "READ-TX-101";
+    PROGRESS_HOOK["READ_TX_102_01"] = "READ-TX-102-01";
+    PROGRESS_HOOK["READ_TX_102_02"] = "READ-TX-102-02";
+    PROGRESS_HOOK["READ_TX_102_03"] = "READ-TX-102-03";
+    PROGRESS_HOOK["READ_TX_102_04"] = "READ-TX-102-04";
+    PROGRESS_HOOK["READ_TX_102_05"] = "READ-TX-102-05";
+    PROGRESS_HOOK["READ_TX_103_01"] = "READ-TX-103-01";
+    PROGRESS_HOOK["READ_TX_103_02"] = "READ-TX-103-02";
+    PROGRESS_HOOK["READ_TX_103_03"] = "READ-TX-103-03";
+    PROGRESS_HOOK["READ_TX_104_01"] = "READ-TX-104-01";
+    PROGRESS_HOOK["READ_TX_104_02"] = "READ-TX-104-02";
+    PROGRESS_HOOK["READ_TX_104_03"] = "READ-TX-104-03";
+    PROGRESS_HOOK["READ_TX_104_04"] = "READ-TX-104-04";
+    PROGRESS_HOOK["READ_TX_104_05"] = "READ-TX-104-05";
+    PROGRESS_HOOK["READ_TX_105_01"] = "READ-TX-105-01";
+    PROGRESS_HOOK["READ_TX_105_02"] = "READ-TX-105-02";
+    PROGRESS_HOOK["READ_TX_105_03"] = "READ-TX-105-03";
+    PROGRESS_HOOK["READ_TX_105_04"] = "READ-TX-105-04";
+    PROGRESS_HOOK["READ_TX_106_01"] = "READ-TX-106-01";
+    PROGRESS_HOOK["READ_TX_106_02"] = "READ-TX-106-02";
+    PROGRESS_HOOK["READ_TX_106_03"] = "READ-TX-106-03";
+    PROGRESS_HOOK["READ_TX_106_04"] = "READ-TX-106-04";
+    PROGRESS_HOOK["READ_TX_106_05"] = "READ-TX-106-05";
+    PROGRESS_HOOK["READ_TX_106_06"] = "READ-TX-106-06";
+    PROGRESS_HOOK["READ_TX_199_01"] = "READ-TX-199-01";
+    PROGRESS_HOOK["READ_TX_199_02"] = "READ-TX-199-02";
+    PROGRESS_HOOK["READ_TX_199_03"] = "READ-TX-199-03";
+    PROGRESS_HOOK["READ_TX_199_99"] = "READ-TX-199-99";
+    PROGRESS_HOOK["READ_TX_001"] = "READ-TX-001";
+    PROGRESS_HOOK["READ_TX_002_01"] = "READ-TX-002-01";
+    PROGRESS_HOOK["READ_TX_002_99_99"] = "READ-TX-002-99-99";
+    PROGRESS_HOOK["READ_TX_999_01"] = "READ-TX-999-01";
+    PROGRESS_HOOK["READ_TX_999_02"] = "READ-TX-999-02";
+    PROGRESS_HOOK["READ_TX_999_03"] = "READ-TX-999-03";
     // UEA Migration hooks (unchanged)
     PROGRESS_HOOK["UEA_MIG_01"] = "UEA-MIG-01";
     PROGRESS_HOOK["UEA_MIG_02"] = "UEA-MIG-02";

package/src/lib/push-chain/push-chain.d.ts

@@ -7,6 +7,9 @@ import { ProgressEvent } from '../progress-hook/progress-hook.types';
 import type { AccountStatus } from '../orchestrator/orchestrator.types';
 import { MoveableToken, PayableToken, ConversionQuote, MoveableTokenAccessor, PayableTokenAccessor } from '../constants/tokens';
 import type { PreparedUniversalTx, CascadedTxResponse, CascadeExecutionOptions } from '../orchestrator/orchestrator.types';
+import type { Hex } from 'viem';
+import type { BatchReadResponse, PreparedRead, UniversalReadResponse } from '../read-state/read-state.types';
+import { type ReadOptions, type ReadPrepareOptions, type ReadValue, type ValidateReadCall, type ReadTrackOptions, type ReadExecuteOptions } from '../read-state/read-params';
 /**
  * @class PushChain
  *
@@ -32,6 +35,30 @@ export declare class PushChain {
         PAYABLE: {
             TOKEN: import("../constants").PayableTokenConstantsMap;
         };
+        READ: {
+            readonly WEB2: "web2:https";
+            readonly NAMESPACE: {
+                readonly EVM: "eip155";
+                readonly SVM: "solana";
+                readonly WEB2: "web2";
+            };
+            readonly MAX_CALLBACK_GAS_LIMIT: 1000000n;
+            readonly MIN_CONFIRMATIONS_FLOOR: 1;
+            readonly DEFAULT_EXPIRY_BLOCKS: 300n;
+            readonly CALLBACK_BUDGET_BUFFER: 3;
+            readonly REGISTRY_CALLBACK_GAS: 500000n;
+            readonly UNIVERSAL_READ_REGISTRY_ADDRESS: {
+                readonly TESTNET_DONUT: "0x00000000000000000000000000000000000000b2";
+            };
+            readonly WEB2_MAX_EXTRACT_ENTRIES: 16;
+            readonly WEB2_DEFAULT_TIMEOUT_MS: 5000;
+            readonly UNIVERSAL_CORE_ADDRESSES: Record<PUSH_NETWORK, `0x${string}`>;
+            readonly UNIVERSAL_CALLBACK_ADDRESSES: Record<PUSH_NETWORK, `0x${string}`>;
+            readonly STATUS: typeof import("../read-state/read-state.types").UNIVERSAL_READ_STATUS;
+            readonly RESULT_STATUS: typeof import("../read-state/read-state.types").READ_STATUS;
+            readonly ERROR_CODE: typeof import("../read-state/read-state.types").READ_ERROR_CODE;
+            readonly OUTCOME: typeof import("../read-state/read-state.types").READ_OUTCOME;
+        };
     };
     /**
      * @static
@@ -124,6 +151,50 @@ export declare class PushChain {
          * This triggers a manual revert via TSS to release those funds.
          */
         rescueFunds: Orchestrator['rescueFunds'];
+        /**
+         * Cross-chain read state — one-shot. `read ≡ prepareRead → executeReads → wait`.
+         * Defaults to the canonical registry on Donut. For your own application receiver,
+         * pass callback.target, gasLimit, abi and functionName, plus an optional args mapper.
+         */
+        read: <const O extends ReadOptions>(subject: string, options: O & ValidateReadCall<O>) => Promise<UniversalReadResponse<ReadValue<O>>>;
+        /**
+         * Build a validated `ReadSpec` for `subject` on `options.chain`: preflight (oracle
+         * height, protocol fee, gas price), envelope encoding, budget sizing, expiry math.
+         * Works in read-only mode. Splice `prepared.spec` / `prepared.value` into your
+         * contract's entrypoint (`toCallData`), send it with `sendTransaction`, then
+         * `trackRead({ txHash })`.
+         *
+         * @example
+         * const prepared = await client.universal.prepareRead(user, {
+         *   chain: CHAIN.ETHEREUM_SEPOLIA,
+         *   callback: { target: myReadClient, gasLimit: 200_000n },
+         * });
+         */
+        prepareRead: <const O extends ReadPrepareOptions>(subject: string, options: O & ValidateReadCall<O>) => Promise<PreparedRead<ReadValue<O>>>;
+        /**
+         * Execute app request calls as a multicall; wallets without EIP-7702 support
+         * use separate transactions. Returns a typed BatchReadResponse containing
+         * transaction metadata and results in prepared order. Waits for completion
+         * unless waitForCompletion is false. Requires a signer.
+         */
+        executeReads: <const R extends readonly PreparedRead[]>(reads: R, options?: ReadExecuteOptions) => Promise<BatchReadResponse<R>>;
+        /**
+         * Resume a read by the Push tx that requested it (array — one tx can carry several)
+         * or by requestId (single). Each response has `wait()` / `refresh()`.
+         * Works in read-only mode.
+         */
+        trackRead: {
+            (ref: {
+                txHash: Hex;
+            }, options?: ReadTrackOptions & {
+                progressHook?: (e: ProgressEvent) => void;
+            }): Promise<UniversalReadResponse[]>;
+            (ref: {
+                requestId: Hex | bigint;
+            }, options?: ReadTrackOptions & {
+                progressHook?: (e: ProgressEvent) => void;
+            }): Promise<UniversalReadResponse>;
+        };
         /**
          * Signs an arbitrary message
          */

package/src/lib/push-chain/push-chain.js

@@ -11,6 +11,8 @@ const bs58_1 = require("../internal/bs58");
 const viem_1 = require("viem");
 const evm_client_1 = require("../vm-client/evm-client");
 const tokens_1 = require("../constants/tokens");
+const read_params_1 = require("../read-state/read-params");
+const read_executor_1 = require("../read-state/read-executor");
 /**
  * @class PushChain
  *
@@ -116,6 +118,32 @@ class PushChain {
                 }
                 return orchestrator.rescueFunds.bind(orchestrator)(params);
             },
+            // Only read()/executeReads() send transactions; prepare/simulate/track remain read-only.
+            read: async (subject, options) => {
+                const params = await (0, read_params_1.resolveReadSpecParams)(subject, options, orchestrator.getNetwork(), orchestrator.getRpcUrls());
+                (0, read_executor_1.assertRequestEntrypoint)(params.callback, 'read');
+                if (this.isReadMode)
+                    throw new Error('Read only mode cannot call read function');
+                const prepared = await orchestrator.prepareRead(params, options.progressHook);
+                const { reads: [response] } = await (0, read_executor_1.executeReads)(orchestrator, [prepared], options);
+                return response;
+            },
+            prepareRead: async (subject, options) => {
+                const params = await (0, read_params_1.resolveReadSpecParams)(subject, options, orchestrator.getNetwork(), orchestrator.getRpcUrls());
+                return orchestrator.prepareRead(params);
+            },
+            executeReads: (async (reads, options) => {
+                reads.forEach((r) => (0, read_executor_1.assertRequestEntrypoint)(r.callback));
+                if (this.isReadMode)
+                    throw new Error('Read only mode cannot call executeReads function');
+                return (0, read_executor_1.executeReads)(orchestrator, reads, options);
+            }),
+            trackRead: ((ref, options) => {
+                const opts = { ...(0, read_params_1.toLifecycleOptions)(options), progressHook: options?.progressHook };
+                return 'txHash' in ref
+                    ? orchestrator.trackRead.bind(orchestrator)(ref, opts)
+                    : orchestrator.trackRead.bind(orchestrator)(ref, opts);
+            }),
             signMessage: async (data) => {
                 if (this.isReadMode) {
                     throw new Error('Read only mode cannot call signMessage function');