@pushchain/core 6.0.24 → 6.0.26

package/src/lib/read-state/read-state.types.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TERMINAL_READ_STATUSES = exports.CONTRACT_REQUEST_STATUS = exports.READ_OUTCOME = exports.READ_ERROR_CODE = exports.READ_STATUS = exports.UNIVERSAL_READ_STATUS = void 0;
+// ---------------------------------------------------------------------------
+// Status enums (mirror ucallback.v1 protos; re-exported for the public surface)
+// ---------------------------------------------------------------------------
+var UNIVERSAL_READ_STATUS;
+(function (UNIVERSAL_READ_STATUS) {
+    UNIVERSAL_READ_STATUS[UNIVERSAL_READ_STATUS["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    UNIVERSAL_READ_STATUS[UNIVERSAL_READ_STATUS["PENDING"] = 1] = "PENDING";
+    UNIVERSAL_READ_STATUS[UNIVERSAL_READ_STATUS["VOTING"] = 2] = "VOTING";
+    /** fulfil tx succeeded — check `callbackDelivered` before trusting the result */
+    UNIVERSAL_READ_STATUS[UNIVERSAL_READ_STATUS["FULFILLED"] = 3] = "FULFILLED";
+    UNIVERSAL_READ_STATUS[UNIVERSAL_READ_STATUS["EXPIRED"] = 4] = "EXPIRED";
+    /** contract had already settled the request another way */
+    UNIVERSAL_READ_STATUS[UNIVERSAL_READ_STATUS["FAILED"] = 5] = "FAILED";
+    UNIVERSAL_READ_STATUS[UNIVERSAL_READ_STATUS["ABORTED"] = 6] = "ABORTED";
+})(UNIVERSAL_READ_STATUS || (exports.UNIVERSAL_READ_STATUS = UNIVERSAL_READ_STATUS = {}));
+var READ_STATUS;
+(function (READ_STATUS) {
+    READ_STATUS[READ_STATUS["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    READ_STATUS[READ_STATUS["SUCCESS"] = 1] = "SUCCESS";
+    READ_STATUS[READ_STATUS["ERROR"] = 2] = "ERROR";
+})(READ_STATUS || (exports.READ_STATUS = READ_STATUS = {}));
+var READ_ERROR_CODE;
+(function (READ_ERROR_CODE) {
+    READ_ERROR_CODE[READ_ERROR_CODE["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    READ_ERROR_CODE[READ_ERROR_CODE["INVALID_QUERY"] = 1] = "INVALID_QUERY";
+    READ_ERROR_CODE[READ_ERROR_CODE["UNSUPPORTED"] = 2] = "UNSUPPORTED";
+    READ_ERROR_CODE[READ_ERROR_CODE["REVERTED"] = 3] = "REVERTED";
+    READ_ERROR_CODE[READ_ERROR_CODE["NOT_FOUND"] = 4] = "NOT_FOUND";
+    READ_ERROR_CODE[READ_ERROR_CODE["INVALID_RESULT"] = 5] = "INVALID_RESULT";
+    READ_ERROR_CODE[READ_ERROR_CODE["REJECTED"] = 6] = "REJECTED";
+})(READ_ERROR_CODE || (exports.READ_ERROR_CODE = READ_ERROR_CODE = {}));
+/**
+ * SDK-derived single outcome. FULFILLED on the node only means the fulfil tx
+ * landed; this separates the ways a FULFILLED read can still not have worked.
+ */
+var READ_OUTCOME;
+(function (READ_OUTCOME) {
+    /** Not terminal yet. */
+    READ_OUTCOME["PENDING"] = "PENDING";
+    /** Source SUCCESS, callback delivered, result decoded (or no shape to decode with). */
+    READ_OUTCOME["SUCCESS"] = "SUCCESS";
+    /** FULFILLED, but the destination returned an error (`raw.errorCode`). */
+    READ_OUTCOME["SOURCE_ERROR"] = "SOURCE_ERROR";
+    /** FULFILLED, but the receiver callback reverted or ran out of gas (`callbackFailReason`). */
+    READ_OUTCOME["CALLBACK_FAILED"] = "CALLBACK_FAILED";
+    /** Delivered, but `resultData` did not match the expected shape (`decodeError`). */
+    READ_OUTCOME["DECODE_FAILED"] = "DECODE_FAILED";
+    READ_OUTCOME["EXPIRED"] = "EXPIRED";
+    READ_OUTCOME["FAILED"] = "FAILED";
+    READ_OUTCOME["ABORTED"] = "ABORTED";
+    /** FULFILLED, but the fulfil receipt was unavailable, so delivery cannot be confirmed. */
+    READ_OUTCOME["UNKNOWN"] = "UNKNOWN";
+})(READ_OUTCOME || (exports.READ_OUTCOME = READ_OUTCOME = {}));
+/** On-chain lifecycle (`RequestStatus` in ReadTypes.sol). */
+var CONTRACT_REQUEST_STATUS;
+(function (CONTRACT_REQUEST_STATUS) {
+    CONTRACT_REQUEST_STATUS[CONTRACT_REQUEST_STATUS["NONE"] = 0] = "NONE";
+    CONTRACT_REQUEST_STATUS[CONTRACT_REQUEST_STATUS["PENDING"] = 1] = "PENDING";
+    CONTRACT_REQUEST_STATUS[CONTRACT_REQUEST_STATUS["EXECUTED"] = 2] = "EXECUTED";
+    CONTRACT_REQUEST_STATUS[CONTRACT_REQUEST_STATUS["SETTLED"] = 3] = "SETTLED";
+    CONTRACT_REQUEST_STATUS[CONTRACT_REQUEST_STATUS["EXPIRED"] = 4] = "EXPIRED";
+})(CONTRACT_REQUEST_STATUS || (exports.CONTRACT_REQUEST_STATUS = CONTRACT_REQUEST_STATUS = {}));
+exports.TERMINAL_READ_STATUSES = new Set([
+    UNIVERSAL_READ_STATUS.FULFILLED,
+    UNIVERSAL_READ_STATUS.EXPIRED,
+    UNIVERSAL_READ_STATUS.FAILED,
+    UNIVERSAL_READ_STATUS.ABORTED,
+]);
+//# sourceMappingURL=read-state.types.js.map

package/src/lib/read-state/read-tracker.d.ts

@@ -0,0 +1,55 @@
+/**
+ * trackRead / wait / refresh — resume a read from its Push tx hash or requestId
+ * and follow it to a terminal status.
+ *
+ * Source of truth is the node's `ucallback.v1.Query` record. What the node
+ * does NOT tell us is parsed from the UniversalCallback logs of the Push txs it
+ * lists in `pc_tx` (fulfil → ReadFulfilled | CallbackFailed; settle →
+ * CallbackGasReported + RefundSent | RefundFailed).
+ *
+ * Two rules verified live on Donut (2026-09-09):
+ *  - FULFILLED does not mean delivered: the node sets it even when the app
+ *    callback reverted. `callbackDelivered` is the real answer (I4).
+ *  - EXPIRED has no EVM-indexed tx / receipt / logs (EndBlocker); never fetch
+ *    its `pc_tx`. The refund is confirmed from the EndBlock `tx_log` events in the
+ *    Cosmos block results instead (RefundSent / RefundFailed); if that lookup fails
+ *    the refund fields stay undefined rather than guessed.
+ */
+import { type Hex } from 'viem';
+import { PUSH_NETWORK } from '../constants/enums';
+import type { PushClient } from '../push-client/push-client';
+import { READ_OUTCOME, READ_STATUS, UNIVERSAL_READ_STATUS, type ReadLifecycleOptions, type ReadResultShape, type UniversalReadResponse } from './read-state.types';
+export type ReadHookEmitter = (hookId: string, ...args: unknown[]) => void;
+export interface TrackReadDeps {
+    pushClient: Pick<PushClient, 'getUniversalRead' | 'getReadsByTx' | 'getTransactionReceiptWithArchiveFallback' | 'getBlockResultEvents'> & {
+        publicClient: Pick<PushClient['publicClient'], 'getBlockNumber'>;
+    };
+    pushNetwork: PUSH_NETWORK;
+    /** Progress events. Wire to `fireProgressHook(ctx, …)` in the orchestrator. */
+    emit?: ReadHookEmitter;
+    /** Override for tests. */
+    now?: () => number;
+}
+export declare function trackRead(deps: TrackReadDeps, ref: {
+    txHash: Hex;
+}, opts?: ReadLifecycleOptions): Promise<UniversalReadResponse[]>;
+export declare function trackRead(deps: TrackReadDeps, ref: {
+    requestId: Hex | bigint;
+}, opts?: ReadLifecycleOptions): Promise<UniversalReadResponse>;
+/** Normalise a bigint / hex requestId to the node's lowercase 32-byte key. */
+export declare function toRequestIdHex(id: Hex | bigint): Hex;
+/**
+ * One answer to "did it work". Order matters: a source error is delivered to the
+ * callback as an ERROR result, so it is reported before any callback outcome.
+ */
+export declare function deriveReadOutcome(status: UNIVERSAL_READ_STATUS, rawStatus: READ_STATUS | undefined, callbackDelivered: boolean | undefined, decodeError: string | undefined): READ_OUTCOME;
+/** Best-effort shape from the on-chain envelope. Contract calls carry no ABI → raw. */
+export declare function inferResultShape(namespace: string, query: Hex): ReadResultShape;
+export declare function statusName(status: number): string;
+/** Default: remaining Push blocks plus observation margin, capped at 180 seconds. */
+export declare function defaultWaitTimeoutMs(currentPushHeight: bigint, expiryPushChainHeight: bigint): number;
+/**
+ * Poll until terminal. Resolves on EVERY terminal status (EXPIRED / FAILED / ABORTED
+ * are statuses, not throws — house convention); only a client timeout throws.
+ */
+export declare function waitForRead(deps: TrackReadDeps, initial: UniversalReadResponse, opts: ReadLifecycleOptions): Promise<UniversalReadResponse>;

package/src/lib/read-state/read-tracker.js

@@ -0,0 +1,481 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackRead = trackRead;
+exports.toRequestIdHex = toRequestIdHex;
+exports.deriveReadOutcome = deriveReadOutcome;
+exports.inferResultShape = inferResultShape;
+exports.statusName = statusName;
+exports.defaultWaitTimeoutMs = defaultWaitTimeoutMs;
+exports.waitForRead = waitForRead;
+/**
+ * trackRead / wait / refresh — resume a read from its Push tx hash or requestId
+ * and follow it to a terminal status.
+ *
+ * Source of truth is the node's `ucallback.v1.Query` record. What the node
+ * does NOT tell us is parsed from the UniversalCallback logs of the Push txs it
+ * lists in `pc_tx` (fulfil → ReadFulfilled | CallbackFailed; settle →
+ * CallbackGasReported + RefundSent | RefundFailed).
+ *
+ * Two rules verified live on Donut (2026-09-09):
+ *  - FULFILLED does not mean delivered: the node sets it even when the app
+ *    callback reverted. `callbackDelivered` is the real answer (I4).
+ *  - EXPIRED has no EVM-indexed tx / receipt / logs (EndBlocker); never fetch
+ *    its `pc_tx`. The refund is confirmed from the EndBlock `tx_log` events in the
+ *    Cosmos block results instead (RefundSent / RefundFailed); if that lookup fails
+ *    the refund fields stay undefined rather than guessed.
+ */
+const viem_1 = require("viem");
+const chain_1 = require("../constants/chain");
+const enums_1 = require("../constants/enums");
+const read_state_1 = require("../constants/read-state");
+const progress_hook_types_1 = require("../progress-hook/progress-hook.types");
+const destination_1 = require("./destination");
+const envelopes_1 = require("./envelopes");
+const errors_1 = require("./errors");
+const read_events_1 = require("./read-events");
+const read_state_types_1 = require("./read-state.types");
+const result_decoder_1 = require("./result-decoder");
+async function trackRead(deps, ref, opts = {}) {
+    if ('txHash' in ref) {
+        const records = await lookupWithRetry(deps, ref, opts);
+        return Promise.all(records.map((r) => buildResponse(deps, r, opts)));
+    }
+    const [record] = await lookupWithRetry(deps, ref, opts);
+    return buildResponse(deps, record, opts);
+}
+/** Normalise a bigint / hex requestId to the node's lowercase 32-byte key. */
+function toRequestIdHex(id) {
+    const hex = typeof id === 'bigint' ? id.toString(16) : id.replace(/^0x/i, '');
+    return `0x${hex.toLowerCase().padStart(64, '0')}`;
+}
+// ---------------------------------------------------------------------------
+// Lookup
+// ---------------------------------------------------------------------------
+async function fetchRecords(deps, ref) {
+    if ('txHash' in ref) {
+        const { reads } = await deps.pushClient.getReadsByTx(ref.txHash);
+        return reads;
+    }
+    const { read } = await deps.pushClient.getUniversalRead(toRequestIdHex(ref.requestId));
+    return read ? [read] : [];
+}
+/** A request is indexed when its block is processed — briefly retry a miss. */
+async function lookupWithRetry(deps, ref, opts) {
+    const now = deps.now ?? Date.now;
+    const emit = deps.emit ?? (() => undefined);
+    const interval = pollInterval(opts);
+    const start = now();
+    const hookRef = 'txHash' in ref ? { txHash: ref.txHash } : { requestId: toRequestIdHex(ref.requestId) };
+    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_03, hookRef);
+    for (;;) {
+        const records = await fetchRecords(deps, ref);
+        if (records.length > 0) {
+            for (const r of records)
+                emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_04, toRequestIdHex(r.id), statusName(r.status));
+            return records;
+        }
+        if (now() - start + interval > read_state_1.READ_TRACK_LOOKUP_TIMEOUT_MS)
+            break;
+        await sleep(interval);
+    }
+    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_05, hookRef, now() - start);
+    const label = 'txHash' in ref ? ref.txHash : toRequestIdHex(ref.requestId);
+    throw new errors_1.ReadNotFoundError(label, 'txHash' in ref ? { txHash: ref.txHash } : { requestId: label });
+}
+function pollInterval(opts) {
+    return Math.max(read_state_1.READ_TRACK_MIN_POLL_INTERVAL_MS, opts.pollingIntervalMs ?? read_state_1.READ_TRACK_POLL_INTERVAL_MS);
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// ---------------------------------------------------------------------------
+// Record → response
+// ---------------------------------------------------------------------------
+async function buildResponse(deps, record, opts) {
+    const req = record.request;
+    if (!req)
+        throw new errors_1.ReadStateError('READ_RECORD_INCOMPLETE', 'node record has no request', { requestId: record.id });
+    const requestId = toRequestIdHex(record.id);
+    const status = record.status;
+    const isTerminal = read_state_types_1.TERMINAL_READ_STATUSES.has(status);
+    const destination = (0, destination_1.resolveDestination)({ chain: req.destinationChain });
+    const callbackBudget = BigInt(req.callbackBudget || '0');
+    const spec = {
+        account: { chainNamespace: destination.chainNamespace, chainId: destination.chainId, owner: (0, viem_1.bytesToHex)(req.owner) },
+        query: (0, viem_1.bytesToHex)(req.query),
+        minConfirmations: req.minConfirmations,
+        blockNumber: BigInt(req.destinationBlockHeight),
+        expiryPushChainHeight: BigInt(req.expiryBlockHeight),
+        maxFee: BigInt(req.maxFee || '0'),
+        revertRecipient: req.revertRecipient,
+    };
+    const fees = {
+        paid: BigInt(req.feesDeposited || '0'),
+        protocolFee: BigInt(req.protocolFee || '0'),
+        callbackBudget,
+    };
+    // Settlement facts live in the logs of the node's own txs.
+    let outcome = {};
+    if (status === read_state_types_1.UNIVERSAL_READ_STATUS.EXPIRED) {
+        // EndBlocker expiry: no receipt exists. The contract pushes the full budget to
+        // refundTo, but a rejecting recipient does not prevent EXPIRED — so read the
+        // RefundSent / RefundFailed logs from the block results instead of assuming.
+        outcome = await collectExpiryOutcome(deps, record, requestId);
+        if (outcome.refunded !== undefined)
+            fees.refunded = outcome.refunded;
+        if (outcome.refundFailed !== undefined)
+            fees.refundFailed = outcome.refundFailed;
+    }
+    else if (status === read_state_types_1.UNIVERSAL_READ_STATUS.FULFILLED || status === read_state_types_1.UNIVERSAL_READ_STATUS.FAILED) {
+        outcome = await collectOutcome(deps, record, requestId);
+        if (outcome.burned !== undefined)
+            fees.burned = outcome.burned;
+        if (outcome.refunded !== undefined)
+            fees.refunded = outcome.refunded;
+        if (outcome.refundFailed !== undefined)
+            fees.refundFailed = outcome.refundFailed;
+    }
+    const raw = record.result
+        ? { status: record.result.status, resultData: (0, viem_1.bytesToHex)(record.result.resultData), errorCode: record.result.errorCode }
+        : null;
+    const callbackDelivered = status === read_state_types_1.UNIVERSAL_READ_STATUS.FULFILLED ? outcome.delivered : undefined;
+    let decoded;
+    let decodeError;
+    let value;
+    if (status === read_state_types_1.UNIVERSAL_READ_STATUS.FULFILLED && callbackDelivered && raw?.status === read_state_types_1.READ_STATUS.SUCCESS) {
+        const shape = opts.resultShape ?? inferResultShape(destination.namespace, spec.query);
+        try {
+            decoded = (0, result_decoder_1.decodeReadResult)(raw.resultData, shape);
+            value = 'values' in decoded ? decoded.values : decoded.value;
+        }
+        catch (e) {
+            decodeError = e instanceof errors_1.ReadDecodeError ? e.message : String(e);
+        }
+    }
+    const txHash = req.requestedTxHash.toLowerCase();
+    const response = {
+        requestIdUint: BigInt(requestId),
+        outcome: deriveReadOutcome(status, raw?.status, callbackDelivered, decodeError),
+        requestId,
+        txHash,
+        destination,
+        chain: chainFromCaip2(destination.caip2) ?? destination.caip2,
+        status,
+        isTerminal,
+        callbackDelivered,
+        callbackFailReason: outcome.failReason,
+        value,
+        decoded,
+        decodeError,
+        raw,
+        errorMsg: record.errorMsg,
+        fees,
+        request: {
+            spec,
+            callbackTarget: req.callbackTarget,
+            originalFunder: req.originalFunder,
+            refundTo: req.revertRecipient,
+            callbackGasLimit: BigInt(req.callbackGasLimit),
+            logIndex: req.requestedLogIndex,
+            createdAtHeight: BigInt(req.createdAtHeight),
+        },
+        pcTx: record.pcTx.map((t) => ({ txHash: t.txHash, blockHeight: t.blockHeight, status: t.status, errorMsg: t.errorMsg })),
+        explorerUrl: explorerTxUrl(deps.pushNetwork, txHash),
+        refresh: () => trackRead(deps, { requestId }, opts),
+        wait: (waitOpts) => waitForRead(deps, response, { ...opts, ...waitOpts }),
+    };
+    return response;
+}
+/**
+ * One answer to "did it work". Order matters: a source error is delivered to the
+ * callback as an ERROR result, so it is reported before any callback outcome.
+ */
+function deriveReadOutcome(status, rawStatus, callbackDelivered, decodeError) {
+    switch (status) {
+        case read_state_types_1.UNIVERSAL_READ_STATUS.EXPIRED: return read_state_types_1.READ_OUTCOME.EXPIRED;
+        case read_state_types_1.UNIVERSAL_READ_STATUS.FAILED: return read_state_types_1.READ_OUTCOME.FAILED;
+        case read_state_types_1.UNIVERSAL_READ_STATUS.ABORTED: return read_state_types_1.READ_OUTCOME.ABORTED;
+        case read_state_types_1.UNIVERSAL_READ_STATUS.FULFILLED:
+            if (rawStatus !== undefined && rawStatus !== read_state_types_1.READ_STATUS.SUCCESS)
+                return read_state_types_1.READ_OUTCOME.SOURCE_ERROR;
+            if (callbackDelivered === false)
+                return read_state_types_1.READ_OUTCOME.CALLBACK_FAILED;
+            if (callbackDelivered !== true)
+                return read_state_types_1.READ_OUTCOME.UNKNOWN;
+            if (decodeError !== undefined)
+                return read_state_types_1.READ_OUTCOME.DECODE_FAILED;
+            return rawStatus === read_state_types_1.READ_STATUS.SUCCESS ? read_state_types_1.READ_OUTCOME.SUCCESS : read_state_types_1.READ_OUTCOME.UNKNOWN;
+        default:
+            return read_state_types_1.READ_OUTCOME.PENDING;
+    }
+}
+/** Parse every pc_tx receipt (fulfil, settle) into one merged outcome. Missing receipts are skipped. */
+async function collectOutcome(deps, record, requestId) {
+    const uc = chain_1.UNIVERSAL_CALLBACK_ADDRESSES[deps.pushNetwork];
+    const merged = {};
+    // Fetch in parallel, merge in pc_tx order (settle facts overwrite fulfil facts as before).
+    const outcomes = await Promise.all(record.pcTx.map(async (t) => {
+        if (!t.txHash)
+            return undefined;
+        try {
+            const receipt = await deps.pushClient.getTransactionReceiptWithArchiveFallback(t.txHash);
+            return (0, read_events_1.parseFulfilOutcome)(receipt, uc, requestId);
+        }
+        catch {
+            return undefined; // pruned or not yet available — leave those fields undefined rather than guess
+        }
+    }));
+    for (const o of outcomes) {
+        if (!o)
+            continue;
+        for (const [k, v] of Object.entries(o)) {
+            if (v !== undefined)
+                merged[k] = v;
+        }
+    }
+    return merged;
+}
+/**
+ * Expiry runs in the EndBlocker, so its UniversalCallback logs exist only as Cosmos
+ * `tx_log` events (`mode: EndBlock`) at the sweeper's block. Each `txLog` attribute is
+ * one JSON log with base64 `data`. Any failure leaves the outcome empty (unknown).
+ */
+async function collectExpiryOutcome(deps, record, requestId) {
+    const heights = [...new Set(record.pcTx.map((t) => t.blockHeight).filter((h) => h > 0))].sort((a, b) => b - a);
+    for (const height of heights) {
+        try {
+            const events = await deps.pushClient.getBlockResultEvents(height);
+            const logs = [];
+            for (const ev of events) {
+                if (ev.type !== 'tx_log')
+                    continue;
+                if (!ev.attributes.some((a) => a.key === 'mode' && a.value === 'EndBlock'))
+                    continue;
+                for (const a of ev.attributes) {
+                    if (a.key !== 'txLog')
+                        continue;
+                    try {
+                        const log = JSON.parse(a.value);
+                        if (typeof log.address !== 'string' || !Array.isArray(log.topics) || !log.topics.every((t) => typeof t === 'string'))
+                            continue;
+                        const data = typeof log.data === 'string' && log.data.startsWith('0x') ? log.data : (0, viem_1.bytesToHex)(new Uint8Array(Buffer.from(log.data ?? '', 'base64')));
+                        logs.push({ address: log.address, topics: log.topics, data });
+                    }
+                    catch { /* An unrelated malformed log must not hide this request's refund. */ }
+                }
+            }
+            const out = (0, read_events_1.parseFulfilOutcome)({ logs }, chain_1.UNIVERSAL_CALLBACK_ADDRESSES[deps.pushNetwork], requestId);
+            // RequestExpired carries the amount the contract tried to push; only RefundSent /
+            // RefundFailed say whether it landed. Report the amount only when it did.
+            if (out.refundFailed === true)
+                return { refundFailed: true };
+            if (out.refundFailed === false)
+                return { refunded: out.refunded, refundFailed: false };
+        }
+        catch {
+            // One unavailable attempt must not hide matching logs at another height.
+        }
+    }
+    return {};
+}
+/** Best-effort shape from the on-chain envelope. Contract calls carry no ABI → raw. */
+function inferResultShape(namespace, query) {
+    try {
+        switch (namespace) {
+            case read_state_1.READ_NAMESPACE.EVM: {
+                const { queryType } = (0, envelopes_1.decodeEvmQueryEnvelope)(query);
+                if (queryType === envelopes_1.EVM_QUERY_TYPE.ACCOUNT_BALANCE)
+                    return { kind: 'uint256' };
+                if (queryType === envelopes_1.EVM_QUERY_TYPE.STORAGE_SLOT)
+                    return { kind: 'bytes32' };
+                return { kind: 'raw' };
+            }
+            case read_state_1.READ_NAMESPACE.SVM: {
+                const { queryType } = (0, envelopes_1.decodeSvmQueryEnvelope)(query);
+                return queryType === envelopes_1.SVM_QUERY_TYPE.RAW_ACCOUNT_DATA ? { kind: 'raw' } : { kind: 'uint256' };
+            }
+            case read_state_1.READ_NAMESPACE.WEB2: {
+                const { extract } = (0, envelopes_1.decodeWeb2QueryEnvelope)(query);
+                const byNumber = Object.fromEntries(Object.entries(envelopes_1.WEB2_VALUE_TYPE).map(([name, n]) => [n, name]));
+                return {
+                    kind: 'web2',
+                    extract: extract.map((e) => ({ path: e.path, valueType: byNumber[e.valueType] ?? 'bytes', decimals: e.decimals })),
+                };
+            }
+            default:
+                return { kind: 'raw' };
+        }
+    }
+    catch {
+        return { kind: 'raw' };
+    }
+}
+function chainFromCaip2(caip2) {
+    if (caip2 === enums_1.CHAIN.WEB2)
+        return enums_1.CHAIN.WEB2;
+    return Object.values(enums_1.CHAIN).includes(caip2) ? caip2 : undefined;
+}
+function explorerTxUrl(network, txHash) {
+    const chain = network === enums_1.PUSH_NETWORK.MAINNET ? enums_1.CHAIN.PUSH_MAINNET : network === enums_1.PUSH_NETWORK.LOCALNET ? enums_1.CHAIN.PUSH_LOCALNET : enums_1.CHAIN.PUSH_TESTNET_DONUT;
+    const base = chain_1.PUSH_CHAIN_INFO[chain].explorerUrl ?? 'https://donut.push.network';
+    return `${base}/tx/${txHash}`;
+}
+// ---------------------------------------------------------------------------
+// wait()
+// ---------------------------------------------------------------------------
+const STATUS_NAME = {
+    [read_state_types_1.UNIVERSAL_READ_STATUS.UNSPECIFIED]: 'UNSPECIFIED',
+    [read_state_types_1.UNIVERSAL_READ_STATUS.PENDING]: 'PENDING',
+    [read_state_types_1.UNIVERSAL_READ_STATUS.VOTING]: 'VOTING',
+    [read_state_types_1.UNIVERSAL_READ_STATUS.FULFILLED]: 'FULFILLED',
+    [read_state_types_1.UNIVERSAL_READ_STATUS.EXPIRED]: 'EXPIRED',
+    [read_state_types_1.UNIVERSAL_READ_STATUS.FAILED]: 'FAILED',
+    [read_state_types_1.UNIVERSAL_READ_STATUS.ABORTED]: 'ABORTED',
+};
+function statusName(status) {
+    return STATUS_NAME[status] ?? `UNKNOWN(${status})`;
+}
+/** Observation allowance after estimated expiry; not a guarantee of node settlement. */
+const READ_TIMEOUT_MARGIN_MS = 10_000;
+/** Default: remaining Push blocks plus observation margin, capped at 180 seconds. */
+function defaultWaitTimeoutMs(currentPushHeight, expiryPushChainHeight) {
+    const blocks = expiryPushChainHeight > currentPushHeight ? Number(expiryPushChainHeight - currentPushHeight) : 0;
+    return Math.min(read_state_1.READ_TRACK_MAX_TIMEOUT_MS, blocks * read_state_1.PUSH_BLOCK_TIME_MS + READ_TIMEOUT_MARGIN_MS);
+}
+/**
+ * Poll until terminal. Resolves on EVERY terminal status (EXPIRED / FAILED / ABORTED
+ * are statuses, not throws — house convention); only a client timeout throws.
+ */
+async function waitForRead(deps, initial, opts) {
+    const now = deps.now ?? Date.now;
+    const emit = deps.emit ?? (() => undefined);
+    const interval = pollInterval(opts);
+    const start = now();
+    let timeoutMs = opts.timeoutMs ?? read_state_1.READ_TRACK_MAX_TIMEOUT_MS;
+    // Push head at a known time; later heights are estimated from the block time (no extra RPC per poll).
+    let head;
+    // Resolve a fresh head for each wait/resume, only when a default is needed.
+    // Bound this RPC too: a stalled height lookup must not hang the promise forever.
+    if (opts.timeoutMs === undefined && !initial.isTerminal) {
+        let timer;
+        try {
+            const height = await Promise.race([
+                deps.pushClient.publicClient.getBlockNumber({ cacheTime: 0 }),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        const elapsed = now() - start;
+                        emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_03, initial.requestId, statusName(initial.status), elapsed);
+                        reject(new errors_1.ReadTimeoutError(initial.status, elapsed, { requestId: initial.requestId, txHash: initial.txHash }));
+                    }, read_state_1.READ_TRACK_MAX_TIMEOUT_MS);
+                }),
+            ]);
+            head = { height, at: now() };
+            timeoutMs = Math.min(read_state_1.READ_TRACK_MAX_TIMEOUT_MS, now() - start + defaultWaitTimeoutMs(height, initial.request.spec.expiryPushChainHeight));
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    else if (!initial.isTerminal) {
+        // Explicit timeout: the head only feeds the expiry warning, so never block on it.
+        deps.pushClient.publicClient.getBlockNumber({ cacheTime: 0 })
+            .then((height) => { head = { height, at: now() }; })
+            .catch(() => undefined);
+    }
+    let expiryWarned = false;
+    const warnNearExpiry = (r) => {
+        if (expiryWarned || !head)
+            return;
+        const estimated = head.height + BigInt(Math.floor((now() - head.at) / read_state_1.PUSH_BLOCK_TIME_MS));
+        const left = r.request.spec.expiryPushChainHeight - estimated;
+        if (left > read_state_1.READ_EXPIRY_WARNING_BLOCKS)
+            return;
+        expiryWarned = true;
+        emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_04, r.requestId, left > 0n ? left : 0n);
+    };
+    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_02, initial.txHash, initial.requestId, initial.request.logIndex);
+    // Every snapshot taken from here on is built with the wait() options, so a
+    // resultShape given to wait() decodes even a record that is already terminal.
+    let current = initial;
+    const timeout = () => {
+        const elapsed = now() - start;
+        emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_03, current.requestId, statusName(current.status), elapsed);
+        throw new errors_1.ReadTimeoutError(current.status, elapsed, { requestId: current.requestId, txHash: current.txHash });
+    };
+    // A single deadline includes RPC/receipt latency. A missing snapshot must not
+    // start trackRead's separate initial-ingestion retry window.
+    const reload = async () => {
+        const remaining = timeoutMs - (now() - start);
+        if (remaining <= 0)
+            return timeout();
+        let timer;
+        try {
+            return await Promise.race([
+                (async () => {
+                    const records = await fetchRecords(deps, { requestId: initial.requestId });
+                    return records[0] ? buildResponse(deps, records[0], opts) : current;
+                })(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        try {
+                            timeout();
+                        }
+                        catch (error) {
+                            reject(error);
+                        }
+                    }, remaining);
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    };
+    if (initial.isTerminal && opts.resultShape !== undefined)
+        current = await reload();
+    let announced;
+    for (;;) {
+        if (current.isTerminal) {
+            emitTerminal(emit, current);
+            return current;
+        }
+        if (current.status !== announced) {
+            announced = current.status;
+            if (current.status === read_state_types_1.UNIVERSAL_READ_STATUS.PENDING)
+                emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_01, current.requestId);
+            else if (current.status === read_state_types_1.UNIVERSAL_READ_STATUS.VOTING)
+                emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_02, current.requestId);
+        }
+        warnNearExpiry(current);
+        const elapsed = now() - start;
+        if (elapsed >= timeoutMs)
+            timeout();
+        await sleep(Math.min(interval, timeoutMs - elapsed));
+        current = await reload();
+    }
+}
+function emitTerminal(emit, r) {
+    if (r.status === read_state_types_1.UNIVERSAL_READ_STATUS.FULFILLED) {
+        if (r.callbackDelivered === true)
+            emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_02, r.requestId);
+        else if (r.callbackDelivered === false)
+            emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_03, r.requestId, r.callbackFailReason);
+        if (r.fees.burned !== undefined)
+            emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_04, r.requestId, r.fees.burned, r.fees.refunded ?? 0n);
+    }
+    // Refund facts exist for FULFILLED/FAILED (settle logs) and EXPIRED (EndBlock logs).
+    if (r.fees.refundFailed === true)
+        emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_06, r.requestId, r.fees.refunded, r.request.refundTo);
+    else if (r.fees.refunded !== undefined)
+        emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_05, r.requestId, r.fees.refunded, r.request.refundTo);
+    // 199-01 means it worked. A FULFILLED read that did not (source error, callback
+    // failure, undecodable, unconfirmed delivery) ends on 199-02 named by its outcome.
+    if (r.outcome === read_state_types_1.READ_OUTCOME.SUCCESS) {
+        emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_01, r.requestId, r.value, r.raw?.resultData ?? '0x', r.callbackDelivered);
+        return;
+    }
+    const ended = r.status === read_state_types_1.UNIVERSAL_READ_STATUS.FULFILLED ? r.outcome : statusName(r.status);
+    const detail = r.errorMsg || r.decodeError || '';
+    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_02, r.requestId, ended, r.raw?.errorCode, detail, r.fees.refunded);
+}
+//# sourceMappingURL=read-tracker.js.map

package/src/lib/read-state/registry.d.ts

@@ -0,0 +1,21 @@
+import { type Address, type Hex, type PublicClient } from 'viem';
+import { PUSH_NETWORK } from '../constants/enums';
+import type { ReadCallback, ReadDestination, ReadQuery } from './read-state.types';
+/** Versioned logical identity. Height, fee, expiry, refund, callback and HTTP timeout are excluded. */
+export declare function computeReadQueryKey(destination: ReadDestination, query: ReadQuery): Hex;
+export declare function getReadRegistryAddress(network: PUSH_NETWORK): Address;
+export declare function resolveReadCallback(callback: ReadCallback | undefined, network: PUSH_NETWORK, queryKey: Hex): ReadCallback & {
+    gasLimit: bigint;
+};
+/** Raw registry storage only: presence does not prove successful consensus or freshness. */
+export declare function getRegistryReadResult(client: Pick<PublicClient, 'readContract'>, network: PUSH_NETWORK, requestId: bigint): Promise<{
+    requestId: bigint;
+    resultData: `0x${string}`;
+    updatedAtBlock: bigint;
+}>;
+/** Keys are caller-supplied labels; verify the associated request before relying on its identity. */
+export declare function getLatestRegistryReadResult(client: Pick<PublicClient, 'readContract'>, network: PUSH_NETWORK, reader: Address, queryKey: Hex): Promise<{
+    requestId: bigint;
+    resultData: `0x${string}`;
+    updatedAtBlock: bigint;
+}>;