@pushchain/core 6.0.23 → 6.0.25

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

@@ -0,0 +1,415 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackRead = trackRead;
+exports.toRequestIdHex = toRequestIdHex;
+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 interval = pollInterval(opts);
+    const start = now();
+    for (;;) {
+        const records = await fetchRecords(deps, ref);
+        if (records.length > 0)
+            return records;
+        if (now() - start + interval > read_state_1.READ_TRACK_LOOKUP_TIMEOUT_MS)
+            break;
+        await sleep(interval);
+    }
+    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 = {
+        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;
+}
+/** 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 = {};
+    for (const t of record.pcTx) {
+        if (!t.txHash)
+            continue;
+        try {
+            const receipt = await deps.pushClient.getTransactionReceiptWithArchiveFallback(t.txHash);
+            const o = (0, read_events_1.parseFulfilOutcome)(receipt, uc, requestId);
+            for (const [k, v] of Object.entries(o)) {
+                if (v !== undefined)
+                    merged[k] = v;
+            }
+        }
+        catch {
+            // pruned or not yet available — leave those fields undefined rather than guess
+        }
+    }
+    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://explorer.donut.push.org';
+    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;
+    // 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);
+                }),
+            ]);
+            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);
+        }
+    }
+    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);
+        }
+        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);
+        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);
+        emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_01, r.requestId, r.value, r.raw?.resultData ?? '0x', r.callbackDelivered);
+        return;
+    }
+    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_02, r.requestId, statusName(r.status), r.raw?.errorCode, r.errorMsg, 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;
+}>;

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

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeReadQueryKey = computeReadQueryKey;
+exports.getReadRegistryAddress = getReadRegistryAddress;
+exports.resolveReadCallback = resolveReadCallback;
+exports.getRegistryReadResult = getRegistryReadResult;
+exports.getLatestRegistryReadResult = getLatestRegistryReadResult;
+const viem_1 = require("viem");
+const read_state_1 = require("../constants/read-state");
+const universalReadRegistry_evm_1 = require("../constants/abi/universalReadRegistry.evm");
+const envelopes_1 = require("./envelopes");
+const destination_1 = require("./destination");
+const errors_1 = require("./errors");
+/** Versioned logical identity. Height, fee, expiry, refund, callback and HTTP timeout are excluded. */
+function computeReadQueryKey(destination, query) {
+    const dest = (0, destination_1.resolveDestination)(destination);
+    // Use fixed references in the existing canonical encoders; never hash live heights.
+    const encoded = (0, envelopes_1.encodeReadQuery)(destination, query.type === 'http' ? { ...query, timeoutMs: read_state_1.WEB2_DEFAULT_TIMEOUT_MS } : query, { blockNumber: 1n, minSlot: 0n });
+    return (0, viem_1.keccak256)((0, viem_1.encodeAbiParameters)([{ type: 'string' }, { type: 'string' }, { type: 'string' }, { type: 'bytes' }, { type: 'bytes' }], ['pushchain:universal-read:query:v1', dest.chainNamespace, dest.chainId, encoded.ownerBytes ?? '0x', encoded.encoded]));
+}
+function getReadRegistryAddress(network) {
+    const address = read_state_1.UNIVERSAL_READ_REGISTRY_ADDRESS[network];
+    if (!address)
+        throw new errors_1.ReadRegistryUnavailableError('read registry');
+    return address;
+}
+function resolveReadCallback(callback, network, queryKey) {
+    if (callback && 'request' in callback)
+        throw new errors_1.InvalidReadQueryError('callback.request was removed; use callback.abi, functionName and args');
+    if (callback?.target !== undefined) {
+        if (callback.gasLimit === undefined)
+            throw new errors_1.InvalidReadQueryError('callback.gasLimit is required for a custom target');
+        return { ...callback, gasLimit: callback.gasLimit };
+    }
+    if (callback?.abi !== undefined || callback?.functionName !== undefined || callback?.args !== undefined) {
+        throw new errors_1.InvalidReadQueryError('callback abi, functionName and args require callback.target');
+    }
+    return {
+        target: getReadRegistryAddress(network),
+        gasLimit: callback?.gasLimit ?? read_state_1.REGISTRY_CALLBACK_GAS,
+        abi: universalReadRegistry_evm_1.UNIVERSAL_READ_REGISTRY_EVM, functionName: 'read', args: (spec, gas) => [spec, queryKey, gas],
+    };
+}
+/** Raw registry storage only: presence does not prove successful consensus or freshness. */
+function getRegistryReadResult(client, network, requestId) {
+    return client.readContract({ address: getReadRegistryAddress(network), abi: universalReadRegistry_evm_1.UNIVERSAL_READ_REGISTRY_EVM,
+        functionName: 'resultByRequestId', args: [requestId] });
+}
+/** Keys are caller-supplied labels; verify the associated request before relying on its identity. */
+function getLatestRegistryReadResult(client, network, reader, queryKey) {
+    return client.readContract({ address: getReadRegistryAddress(network), abi: universalReadRegistry_evm_1.UNIVERSAL_READ_REGISTRY_EVM,
+        functionName: 'latestResult', args: [reader, queryKey] });
+}
+//# sourceMappingURL=registry.js.map

package/src/lib/read-state/result-decoder.d.ts

@@ -0,0 +1,16 @@
+import { type Hex } from 'viem';
+import type { DecodedReadResult, ReadResultShape } from './read-state.types';
+/**
+ * Decode `resultData` using the shape recorded by the query that produced it.
+ *
+ * `resultData` is not self-describing. Shapes (from the validator executors):
+ *   EVM AccountBalance / SVM LamportBalance / SVM SPLTokenAccount → abi.encode(uint256)
+ *   EVM ContractCall → raw eth_call return bytes (decoded with the recorded ABI, else raw)
+ *   EVM StorageSlot  → raw 32 bytes
+ *   SVM RawAccountData → raw account bytes
+ *   Web2 → abi.encode(v1, v2, …) — a FLAT argument list, one per extract, in order
+ *
+ * Throws `ReadDecodeError` rather than mis-decoding. Do not call this for an ERROR
+ * result (empty bytes) — check `result.status` first.
+ */
+export declare function decodeReadResult(resultData: Hex, shape: ReadResultShape): DecodedReadResult;

package/src/lib/read-state/result-decoder.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeReadResult = decodeReadResult;
+const viem_1 = require("viem");
+const errors_1 = require("./errors");
+const WEB2_ABI_TYPE = {
+    uint256: 'uint256',
+    int256: 'int256',
+    bool: 'bool',
+    string: 'string',
+    bytes: 'bytes',
+};
+/**
+ * Decode `resultData` using the shape recorded by the query that produced it.
+ *
+ * `resultData` is not self-describing. Shapes (from the validator executors):
+ *   EVM AccountBalance / SVM LamportBalance / SVM SPLTokenAccount → abi.encode(uint256)
+ *   EVM ContractCall → raw eth_call return bytes (decoded with the recorded ABI, else raw)
+ *   EVM StorageSlot  → raw 32 bytes
+ *   SVM RawAccountData → raw account bytes
+ *   Web2 → abi.encode(v1, v2, …) — a FLAT argument list, one per extract, in order
+ *
+ * Throws `ReadDecodeError` rather than mis-decoding. Do not call this for an ERROR
+ * result (empty bytes) — check `result.status` first.
+ */
+function decodeReadResult(resultData, shape) {
+    if (!(0, viem_1.isHex)(resultData))
+        throw new errors_1.ReadDecodeError('resultData is not hex');
+    const len = (0, viem_1.size)(resultData);
+    try {
+        switch (shape.kind) {
+            case 'uint256': {
+                if (len !== 32)
+                    throw new errors_1.ReadDecodeError(`expected 32 bytes for uint256, got ${len}`);
+                const [value] = (0, viem_1.decodeAbiParameters)([{ type: 'uint256' }], resultData);
+                return { kind: 'uint256', value };
+            }
+            case 'bytes32': {
+                if (len !== 32)
+                    throw new errors_1.ReadDecodeError(`expected 32 bytes for bytes32, got ${len}`);
+                return { kind: 'bytes32', value: resultData };
+            }
+            case 'raw':
+                return { kind: 'raw', value: resultData };
+            case 'evmCall': {
+                if (len === 0)
+                    throw new errors_1.ReadDecodeError('empty resultData for a contract call');
+                const item = (0, viem_1.getAbiItem)({ abi: shape.abi, name: shape.functionName });
+                if (!item)
+                    throw new errors_1.ReadDecodeError(`function not found in abi: ${shape.functionName}`);
+                const decoded = (0, viem_1.decodeFunctionResult)({ abi: shape.abi, functionName: shape.functionName, data: resultData });
+                return { kind: 'evmCall', value: decoded };
+            }
+            case 'web2': {
+                if (shape.extract.length === 0)
+                    throw new errors_1.ReadDecodeError('web2 shape has no extracts');
+                if (len === 0)
+                    throw new errors_1.ReadDecodeError('empty resultData for a web2 read');
+                const params = shape.extract.map((e) => ({ type: WEB2_ABI_TYPE[e.valueType] }));
+                const values = (0, viem_1.decodeAbiParameters)(params, resultData);
+                return { kind: 'web2', values };
+            }
+            default:
+                throw new errors_1.ReadDecodeError(`unknown result shape: ${shape.kind}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof errors_1.ReadDecodeError)
+            throw err;
+        throw new errors_1.ReadDecodeError(`resultData does not match shape ${shape.kind}: ${err.message}`);
+    }
+}
+//# sourceMappingURL=result-decoder.js.map

package/src/lib/read-state/spec-builder.d.ts

@@ -0,0 +1,47 @@
+import { type Abi, type Address, type Hex } from 'viem';
+import { type PreflightDeps } from './preflight';
+import type { BuildReadSpecParams, PreparedRead, ReadPreflight, ReadSpec, ReadSpecTuple, SimulateReadResult } from './read-state.types';
+import type { ReadHookEmitter } from './read-tracker';
+export interface PrepareReadDeps extends PreflightDeps {
+    emit?: ReadHookEmitter;
+    /** The signer's Push-side account (UEA or EOA). Used when `refundTo` is not given. */
+    defaultRefundTo?: Address;
+}
+export declare function encodeSpec(spec: ReadSpec): Hex;
+/**
+ * Assemble a `PreparedRead` from an already-fetched preflight. Pure — no network.
+ * Use directly when preparing several reads from one preflight.
+ */
+export declare function buildReadSpecFromPreflight(preflight: ReadPreflight, params: BuildReadSpecParams, defaults?: {
+    refundTo?: Address;
+}): PreparedRead;
+/**
+ * Preflight + build. Adds the `refundTo` advisory: a contract recipient that is not a
+ * UEA must have a payable receive() or the refund is forfeited to the admin rescue
+ * pool (verified live). UEAs (UEA_EVM / UEA_SVM) always have one.
+ */
+export declare function prepareRead(deps: PrepareReadDeps, params: BuildReadSpecParams): Promise<PreparedRead>;
+/**
+ * Splice the prepared spec into the app's own entrypoint.
+ * Default argument order is `(spec, callbackGasLimit)`; pass `args` to remap.
+ */
+export declare function toCallData(prepared: PreparedRead, target: {
+    abi: Abi;
+    functionName: string;
+    args?: (spec: ReadSpecTuple, callbackGasLimit: bigint) => readonly unknown[];
+}): {
+    data: Hex;
+    value: bigint;
+};
+/**
+ * eth_call `requestExternalReadSelf` with `from` = the app contract, so validation
+ * reverts surface before broadcast, decoded into the contract's custom errors.
+ * Only meaningful for the app-contract persona: `callbackTarget` becomes `msg.sender`.
+ */
+export declare function simulateRead(deps: PreflightDeps, prepared: PreparedRead, opts: {
+    appContract: Address;
+    callbackSelector: Hex;
+    staleAfterMs?: number;
+}): Promise<SimulateReadResult>;
+/** Fresh validation only: never rebuild or mutate the prepared request. */
+export declare function revalidateRead(deps: PreflightDeps, prepared: PreparedRead): Promise<void>;