@pushchain/core 6.0.23 → 6.0.25

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

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERC20_BALANCE_OF_ABI = void 0;
+exports.toReadDestination = toReadDestination;
+exports.toReadQuery = toReadQuery;
+exports.toBuildReadSpecParams = toBuildReadSpecParams;
+exports.getReadQueryKey = getReadQueryKey;
+exports.toLifecycleOptions = toLifecycleOptions;
+const viem_1 = require("viem");
+const enums_1 = require("../constants/enums");
+const registry_1 = require("./registry");
+const read_state_1 = require("../constants/read-state");
+const destination_1 = require("./destination");
+const svm_1 = require("./envelopes/svm");
+const errors_1 = require("./errors");
+/** Just `balanceOf` — it also types the decoded result as uint256. */
+exports.ERC20_BALANCE_OF_ABI = [
+    {
+        type: 'function',
+        name: 'balanceOf',
+        stateMutability: 'view',
+        inputs: [{ name: 'account', type: 'address' }],
+        outputs: [{ name: '', type: 'uint256' }],
+    },
+];
+const QUERY_KEYS = ['token', 'abi', 'storageSlot', 'web2'];
+function queryKind(o) {
+    const present = QUERY_KEYS.filter((k) => o[k] !== undefined);
+    if (present.length > 1) {
+        throw new errors_1.InvalidReadQueryError(`query keys are mutually exclusive, got ${present.join(' + ')}`);
+    }
+    if ((o.functionName !== undefined || o.args !== undefined) && o.abi === undefined) {
+        throw new errors_1.InvalidReadQueryError('functionName and args need abi');
+    }
+    return present[0] ?? 'native';
+}
+function toReadDestination(chain) {
+    return chain === enums_1.CHAIN.WEB2 ? read_state_1.WEB2_DESTINATION : { chain };
+}
+/** Build the internal query from the public grammar. Pure. */
+function toReadQuery(subject, o) {
+    const dest = (0, destination_1.resolveDestination)(toReadDestination(o.chain));
+    const kind = queryKind(o);
+    if (o.tokenProgram !== undefined && (dest.namespace !== read_state_1.READ_NAMESPACE.SVM || kind !== 'token' || !['spl-token', 'token-2022'].includes(o.tokenProgram))) {
+        throw new errors_1.InvalidReadQueryError('tokenProgram requires a Solana token balance query and must be spl-token or token-2022');
+    }
+    if (dest.namespace === read_state_1.READ_NAMESPACE.WEB2) {
+        if (kind !== 'web2' || !o.web2)
+            throw new errors_1.InvalidReadQueryError('a web2 read needs the `web2` option and no other query key');
+        if (!/^https:\/\//i.test(subject))
+            throw new errors_1.InvalidReadQueryError('web2 subject must be an https:// URL');
+        return { type: 'http', url: subject, ...o.web2 };
+    }
+    if (kind === 'web2')
+        throw new errors_1.InvalidReadQueryError('`web2` is only valid with chain CHAIN.WEB2');
+    if (dest.namespace === read_state_1.READ_NAMESPACE.EVM) {
+        if (!(0, viem_1.isAddress)(subject))
+            throw new errors_1.InvalidReadQueryError(`EVM subject must be an address, got ${subject}`);
+        switch (kind) {
+            case 'native':
+                return { type: 'accountBalance', target: subject };
+            case 'token': {
+                const token = o.token;
+                if (!(0, viem_1.isAddress)(token))
+                    throw new errors_1.InvalidReadQueryError(`token must be an address, got ${token}`);
+                return { type: 'contractCall', target: token, abi: exports.ERC20_BALANCE_OF_ABI, functionName: 'balanceOf', args: [subject] };
+            }
+            case 'abi':
+                if (!o.functionName)
+                    throw new errors_1.InvalidReadQueryError('abi needs functionName');
+                return { type: 'contractCall', target: subject, abi: o.abi, functionName: o.functionName, args: o.args };
+            case 'storageSlot':
+                return { type: 'storageSlot', target: subject, slot: o.storageSlot };
+            default:
+                throw new errors_1.InvalidReadQueryError(`unsupported query for eip155: ${kind}`);
+        }
+    }
+    // SVM: the account rides in ReadSpec.account.owner; the ATA is derived here, no network.
+    switch (kind) {
+        case 'native':
+            return { type: 'lamportBalance', account: subject };
+        case 'token':
+            return { type: 'splTokenAccount', account: (0, svm_1.deriveAssociatedTokenAddress)(subject, o.token, o.tokenProgram === 'token-2022' ? svm_1.TOKEN_2022_PROGRAM_ID : svm_1.TOKEN_PROGRAM_ID).toBase58() };
+        default:
+            throw new errors_1.InvalidReadQueryError(`unsupported query for solana: ${kind} (program reads land with idl support)`);
+    }
+}
+/** Public options → the spec builder's params. Pure; throws `InvalidReadQueryError` on a malformed request. */
+function toBuildReadSpecParams(subject, o, network = enums_1.PUSH_NETWORK.TESTNET_DONUT) {
+    const destination = toReadDestination(o.chain);
+    const namespace = (0, destination_1.resolveDestination)(destination).namespace;
+    if (namespace !== read_state_1.READ_NAMESPACE.EVM && (o.blockNumber !== undefined || o.minConfirmations !== undefined)) {
+        throw new errors_1.InvalidReadQueryError(`${namespace} reads do not expose blockNumber or minConfirmations; the SDK selects the read reference internally`);
+    }
+    const query = toReadQuery(subject, o);
+    const callback = (0, registry_1.resolveReadCallback)(o.callback, network, (0, registry_1.computeReadQueryKey)(destination, query));
+    return {
+        callback,
+        destination,
+        query,
+        callbackGasLimit: callback.gasLimit,
+        refundTo: o.refundTo,
+        minConfirmations: o.minConfirmations,
+        blockNumber: o.blockNumber,
+        expiryBlocks: o.expiryBlocks,
+        maxFee: o.maxFee,
+    };
+}
+/** Offline logical query key for the registry's latestResult lookup. */
+function getReadQueryKey(subject, options) {
+    return (0, registry_1.computeReadQueryKey)(toReadDestination(options.chain), toReadQuery(subject, options));
+}
+function toLifecycleOptions(o) {
+    return {
+        pollingIntervalMs: o?.advanced?.pollingIntervalMs,
+        timeoutMs: o?.advanced?.timeout,
+        resultShape: o?.resultShape,
+    };
+}
+//# sourceMappingURL=read-params.js.map

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

@@ -0,0 +1,417 @@
+import type { Abi, Address, Hex } from 'viem';
+import type { CHAIN } from '../constants/enums';
+import type { ReadNamespace } from '../constants/read-state';
+/**
+ * Where a read goes. `CHAIN` enum values are CAIP-2 and split cleanly; the
+ * explicit form is the low-level escape hatch; the public API uses `CHAIN.WEB2`.
+ */
+export type ReadChain = CHAIN | typeof CHAIN.WEB2;
+export type ReadDestination = {
+    chain: ReadChain;
+} | {
+    chainNamespace: string;
+    chainId: string;
+};
+export type ResolvedDestination = {
+    chainNamespace: string;
+    chainId: string;
+    /** `${chainNamespace}:${chainId}` — the key the oracle and the node route on. */
+    caip2: string;
+    namespace: ReadNamespace;
+};
+export type EvmReadQuery = {
+    type: 'accountBalance';
+    target: Address;
+} | {
+    type: 'contractCall';
+    target: Address;
+    callData: Hex;
+} | {
+    type: 'contractCall';
+    target: Address;
+    /** encodes the call AND decodes the result */
+    abi: Abi;
+    functionName: string;
+    args?: readonly unknown[];
+} | {
+    type: 'storageSlot';
+    target: Address;
+    slot: Hex | bigint;
+};
+/** The account being read rides in `ReadSpec.account.owner` as a raw 32-byte pubkey, not in the envelope. */
+export type SvmReadQuery = {
+    type: 'lamportBalance';
+    account: string | Uint8Array;
+} | {
+    type: 'splTokenAccount';
+    account: string | Uint8Array;
+} | {
+    type: 'rawAccountData';
+    account: string | Uint8Array;
+};
+export type Web2ValueType = 'uint256' | 'int256' | 'bool' | 'string' | 'bytes';
+export interface Web2Extract {
+    /** JSONPath, e.g. "$.data.price" */
+    path: string;
+    valueType: Web2ValueType;
+    /** Numeric only. Value × 10^decimals, TRUNCATED before encoding. */
+    decimals?: number;
+}
+export interface Web2ReadQuery {
+    type: 'http';
+    method?: 'GET' | 'POST';
+    url: string;
+    /** ⚠ Written to a public event log, forever. */
+    headers?: Record<string, string>;
+    /** POST only */
+    body?: string | Uint8Array;
+    timeoutMs?: number;
+    /** 1–16 entries; result values come back in this order. */
+    extract: readonly Web2Extract[];
+}
+export type ReadQuery = EvmReadQuery | SvmReadQuery | Web2ReadQuery;
+export type ReadResultShape = {
+    kind: 'uint256';
+} | {
+    kind: 'bytes32';
+} | {
+    kind: 'raw';
+} | {
+    kind: 'evmCall';
+    abi: Abi;
+    functionName: string;
+} | {
+    kind: 'web2';
+    extract: readonly Web2Extract[];
+};
+export interface EncodedReadQuery {
+    namespace: ReadNamespace;
+    queryType: number;
+    /** abi.encode(envelope tuple) — goes into ReadSpec.query */
+    encoded: Hex;
+    /** EVM: pinned block. SVM: minSlot floor. Web2: 0. Mirrored into ReadSpec.blockNumber by the spec builder. */
+    blockRef: bigint;
+    resultShape: ReadResultShape;
+    /** SVM only: the raw 32-byte pubkey that MUST go in ReadSpec.account.owner. */
+    ownerBytes?: Hex;
+    /** Non-fatal advisories (e.g. a sensitive-looking web2 header). */
+    warnings: string[];
+}
+export type DecodedReadResult = {
+    kind: 'uint256';
+    value: bigint;
+} | {
+    kind: 'bytes32';
+    value: Hex;
+} | {
+    kind: 'raw';
+    value: Hex;
+} | {
+    kind: 'evmCall';
+    value: unknown;
+} | {
+    kind: 'web2';
+    values: readonly unknown[];
+};
+export interface ReadPreflight {
+    destination: ResolvedDestination;
+    /** `UniversalCallback.estimateFee(ns, chainId)` — the protocol fee ONLY. 0 on Donut today. */
+    protocolFee: bigint;
+    /**
+     * `UniversalCore.chainHeightByChainNamespace(caip2)` — the oracle-observed height of the
+     * destination and the ceiling for `blockNumber`. Lags the real head. 0 for heightless
+     * namespaces (web2), where `blockNumber` must then be 0.
+     */
+    observedChainHeight: bigint;
+    /** Current Push Chain height, for expiry. */
+    pushBlockNumber: bigint;
+    /** Push gas price used to size the callback budget. */
+    pushGasPrice: bigint;
+    universalCallback: Address;
+    universalCore: Address;
+    /** Date.now() at fetch — pushBlockNumber moves every block; a stale preflight can miss expiry. */
+    fetchedAt: number;
+}
+export interface ReadSpec {
+    account: {
+        chainNamespace: string;
+        chainId: string;
+        owner: Hex;
+    };
+    query: Hex;
+    /** uint16, ≥ 1 */
+    minConfirmations: number;
+    /** uint64. Heightless namespaces (web2) MUST be 0; else 1..oracleHeight */
+    blockNumber: bigint;
+    /** uint64, > current Push height */
+    expiryPushChainHeight: bigint;
+    /** ≥ msg.value */
+    maxFee: bigint;
+    /** ≠ 0. Refunds are PUSHED here. */
+    revertRecipient: Address;
+}
+/** Positional form for `encodeFunctionData` / `encodeAbiParameters`. */
+export type ReadSpecTuple = readonly [
+    readonly [string, string, Hex],
+    Hex,
+    number,
+    bigint,
+    bigint,
+    bigint,
+    Address
+];
+export interface ReadCallback {
+    target?: Address;
+    /** Gas for the result callback, not the request entrypoint. */
+    gasLimit?: bigint;
+    /** Public payable request entrypoint on the application contract. */
+    abi?: Abi;
+    functionName?: string;
+    /** Defaults to (spec, callbackGasLimit). Must request exactly one read with this spec. */
+    args?: (spec: ReadSpecTuple, callbackGasLimit: bigint) => readonly unknown[];
+}
+export interface BuildReadSpecParams {
+    callback?: ReadCallback;
+    destination: ReadDestination;
+    query: ReadQuery;
+    /** 1n..1_000_000n. Execution bound on YOUR callback; also sizes the budget. */
+    callbackGasLimit: bigint;
+    /**
+     * Where unspent budget is PUSHED (ReadSpec.revertRecipient). Required by the contract.
+     * Default: the sending account (a UEA has a payable receive()). A non-UEA contract
+     * without one forfeits the refund — prepareRead warns.
+     */
+    refundTo?: Address;
+    /** EVM/web2 only: ReadSpec.account.owner. Ignored by validators for EVM; defaults to refundTo. SVM derives it from the query. */
+    owner?: Hex;
+    /** ≥ 1. Default 1. */
+    minConfirmations?: number;
+    /** Pinned destination height. Default observedChainHeight − minConfirmations (≥ 1). Web2: forced to 0. */
+    blockNumber?: bigint;
+    /** Default 300n. */
+    expiryBlocks?: bigint;
+    /** Absolute override for expiryBlocks. */
+    expiryPushChainHeight?: bigint;
+    /** Escrowed on top of the protocol fee. Default sizeCallbackBudget(gasLimit, gasPrice). Must be > 0. */
+    callbackBudget?: bigint;
+    /** Multiplier used by the default budget. */
+    budgetBuffer?: number;
+    /** Cap on msg.value. Default value × (1 + maxFeeBufferBps/10_000). */
+    maxFee?: bigint;
+    maxFeeBufferBps?: number;
+}
+declare const preparedReadValue: unique symbol;
+export interface PreparedRead<T = unknown> {
+    /** SDK logical query identity, independent of pinning and payment. */
+    queryKey: Hex;
+    /** Type-only result metadata retained through preparation and execution. */
+    readonly [preparedReadValue]?: T;
+    /** App request entrypoint retained for read()/executeReads(). */
+    callback?: ReadCallback;
+    /** Public destination identifier used to prepare this read. */
+    chain: ReadChain;
+    spec: ReadSpec;
+    /** Positional form for viem calls. */
+    specTuple: ReadSpecTuple;
+    /** abi.encode(spec) for hand-assembled calldata. */
+    encodedSpec: Hex;
+    /** msg.value to send: protocolFee + callbackBudget. */
+    value: bigint;
+    protocolFee: bigint;
+    callbackBudget: bigint;
+    /** The same three numbers, grouped: `total` === `value`. */
+    fees: {
+        protocolFee: bigint;
+        callbackBudget: bigint;
+        total: bigint;
+    };
+    callbackGasLimit: bigint;
+    /** Carries the result shape for decoding, and any encoder warnings. */
+    encodedQuery: EncodedReadQuery;
+    /** Public decoder description retained through execution. */
+    resultShape: ReadResultShape;
+    preflight: ReadPreflight;
+    /** Advisories: sensitive headers, refundTo is a non-UEA contract, … */
+    warnings: string[];
+}
+export type SimulateReadResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    errorName?: string;
+    args?: readonly unknown[];
+};
+export interface ParsedReadRequest {
+    /** 32-byte topic hex, lowercase — the node's primary key */
+    requestId: Hex;
+    requestIdUint: bigint;
+    callbackTarget: Address;
+    originalFunder: Address;
+    spec: ReadSpec;
+    callbackGasLimit: bigint;
+    totalPaid: bigint;
+    protocolFee: bigint;
+    callbackBudget: bigint;
+    logIndex: number;
+}
+/** What the fulfil / settle / expiry transactions said, parsed from UniversalCallback logs. */
+export interface FulfilOutcome {
+    /** true = ReadFulfilled, false = CallbackFailed, undefined = neither seen in this receipt */
+    delivered?: boolean;
+    /** revert data from CallbackFailed */
+    failReason?: Hex;
+    gasReported?: bigint;
+    burned?: bigint;
+    refunded?: bigint;
+    refundTo?: Address;
+    /** RefundFailed seen — budget forfeited to the admin rescue pool */
+    refundFailed?: boolean;
+    /** RequestExpired seen */
+    expired?: boolean;
+}
+/** Minimal structural receipt — works with viem receipts and `cast receipt --json`. */
+export interface ReceiptLike {
+    logs: readonly {
+        address: string;
+        topics: readonly string[];
+        data: string;
+        logIndex?: number | string;
+    }[];
+}
+export type ReadRef = {
+    txHash: Hex;
+} | {
+    requestId: Hex | bigint;
+};
+export interface ReadLifecycleOptions {
+    /** Default `expiryBlocks × PUSH_BLOCK_TIME_MS`, capped at READ_TRACK_MAX_TIMEOUT_MS. */
+    timeoutMs?: number;
+    /** Default READ_TRACK_POLL_INTERVAL_MS; floor READ_TRACK_MIN_POLL_INTERVAL_MS. */
+    pollingIntervalMs?: number;
+    /**
+     * How to decode `resultData`. When omitted the tracker infers it from the on-chain
+     * envelope (balances → uint256, storage → bytes32, web2 → its extract list); a
+     * contract call has no ABI on chain and decodes to raw bytes unless given here.
+     */
+    resultShape?: ReadResultShape;
+}
+/** Accounting for one read, assembled from the request record and the settlement logs. */
+export interface ReadFees {
+    /** msg.value at request time (`feesDeposited`) */
+    paid: bigint;
+    /** gone at request time, never refunded */
+    protocolFee: bigint;
+    /** escrowed for the callback */
+    callbackBudget: bigint;
+    /** consumed by the callback — `CallbackGasReported` */
+    burned?: bigint;
+    /** pushed back to `refundTo` — `RefundSent` / `RequestExpired` */
+    /** Unknown for EndBlock expiry: EXPIRED does not prove the recipient accepted payment. */
+    refunded?: bigint;
+    /** the push was rejected — budget sits in the admin rescue pool */
+    refundFailed?: boolean;
+}
+export interface UniversalReadResponse<T = unknown> {
+    requestId: Hex;
+    /** Push tx that carried the request */
+    txHash: Hex;
+    destination: ResolvedDestination;
+    /** Required read destination, including `CHAIN.WEB2`. */
+    chain: ReadChain;
+    status: UNIVERSAL_READ_STATUS;
+    isTerminal: boolean;
+    /**
+     * FULFILLED only. true = `ReadFulfilled`; false = `CallbackFailed` (your callback
+     * reverted / ran out of gas). FULFILLED does NOT imply delivered — check both.
+     */
+    callbackDelivered?: boolean;
+    /** Revert data from `CallbackFailed`. */
+    callbackFailReason?: Hex;
+    /** Decoded result. Present iff FULFILLED && callbackDelivered && result SUCCESS && decodable. */
+    value?: T;
+    decoded?: DecodedReadResult;
+    /** Why `value` is absent although the read succeeded (shape mismatch). */
+    decodeError?: string;
+    /** Consensus bytes — what ⅔ of validators voted on. `null` before a result exists. */
+    raw: {
+        status: READ_STATUS;
+        resultData: Hex;
+        errorCode: READ_ERROR_CODE;
+    } | null;
+    errorMsg: string;
+    fees: ReadFees;
+    request: {
+        spec: ReadSpec;
+        callbackTarget: Address;
+        /** who paid (msg.sender at request) — NOT where refunds go */
+        originalFunder: Address;
+        /** where refunds go */
+        refundTo: Address;
+        callbackGasLimit: bigint;
+        logIndex: number;
+        createdAtHeight: bigint;
+    };
+    /** Push txs the node sent for this read (fulfil, settle, expiry sweep). */
+    pcTx: readonly {
+        txHash: Hex;
+        blockHeight: number;
+        status: string;
+        errorMsg: string;
+    }[];
+    explorerUrl: string;
+    /** Poll until terminal (or already terminal → resolves at once). Only a timeout throws. */
+    wait(opts?: ReadLifecycleOptions): Promise<UniversalReadResponse<T>>;
+    /** One fresh snapshot, no polling. */
+    refresh(): Promise<UniversalReadResponse<T>>;
+}
+export type ReadResponseTuple<R extends readonly PreparedRead[]> = {
+    -readonly [K in keyof R]: UniversalReadResponse<R[K] extends PreparedRead<infer T> ? T : unknown>;
+};
+/** One execution containing one or more independently settled read requests. */
+export interface BatchReadResponse<R extends readonly PreparedRead[] = readonly PreparedRead[]> {
+    /** Primary Push transaction hash. For sequential fallback, see `transactionHashes`. */
+    txHash: Hex;
+    /** All request transactions in submission order when execution was non-atomic. */
+    transactionHashes?: readonly Hex[];
+    reads: ReadResponseTuple<R>;
+    count: number;
+    atomic: boolean;
+    /** Wait until every read is terminal. Terminal failures resolve; only timeout throws. */
+    wait(opts?: Omit<ReadLifecycleOptions, 'resultShape'>): Promise<ReadResponseTuple<R>>;
+}
+export declare enum UNIVERSAL_READ_STATUS {
+    UNSPECIFIED = 0,
+    PENDING = 1,
+    VOTING = 2,
+    /** fulfil tx succeeded — check `callbackDelivered` before trusting the result */
+    FULFILLED = 3,
+    EXPIRED = 4,
+    /** contract had already settled the request another way */
+    FAILED = 5,
+    ABORTED = 6
+}
+export declare enum READ_STATUS {
+    UNSPECIFIED = 0,
+    SUCCESS = 1,
+    ERROR = 2
+}
+export declare enum READ_ERROR_CODE {
+    UNSPECIFIED = 0,
+    INVALID_QUERY = 1,
+    UNSUPPORTED = 2,
+    REVERTED = 3,
+    NOT_FOUND = 4,
+    INVALID_RESULT = 5,
+    REJECTED = 6
+}
+/** On-chain lifecycle (`RequestStatus` in ReadTypes.sol). */
+export declare enum CONTRACT_REQUEST_STATUS {
+    NONE = 0,
+    PENDING = 1,
+    EXECUTED = 2,
+    SETTLED = 3,
+    EXPIRED = 4
+}
+export declare const TERMINAL_READ_STATUSES: ReadonlySet<UNIVERSAL_READ_STATUS>;
+export {};

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

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TERMINAL_READ_STATUSES = exports.CONTRACT_REQUEST_STATUS = 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 = {}));
+/** 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,50 @@
+/**
+ * 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 { 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;
+/** 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>;