@pushchain/core 6.0.23 → 6.0.25

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

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUEST_EXPIRED_TOPIC0 = exports.REFUND_FAILED_TOPIC0 = exports.REFUND_SENT_TOPIC0 = exports.CALLBACK_GAS_REPORTED_TOPIC0 = exports.CALLBACK_FAILED_TOPIC0 = exports.READ_FULFILLED_TOPIC0 = exports.READ_REQUESTED_TOPIC0 = exports.READ_REQUESTED_EVENT = void 0;
+exports.parseReadRequestsFromReceipt = parseReadRequestsFromReceipt;
+exports.parseFulfilOutcome = parseFulfilOutcome;
+const viem_1 = require("viem");
+const universalCallback_evm_1 = require("../constants/abi/universalCallback.evm");
+function eventItem(name) {
+    return (0, viem_1.getAbiItem)({ abi: universalCallback_evm_1.UNIVERSAL_CALLBACK_EVM, name });
+}
+exports.READ_REQUESTED_EVENT = eventItem('ReadRequested');
+exports.READ_REQUESTED_TOPIC0 = (0, viem_1.toEventSelector)(exports.READ_REQUESTED_EVENT);
+exports.READ_FULFILLED_TOPIC0 = (0, viem_1.toEventSelector)(eventItem('ReadFulfilled'));
+exports.CALLBACK_FAILED_TOPIC0 = (0, viem_1.toEventSelector)(eventItem('CallbackFailed'));
+exports.CALLBACK_GAS_REPORTED_TOPIC0 = (0, viem_1.toEventSelector)(eventItem('CallbackGasReported'));
+exports.REFUND_SENT_TOPIC0 = (0, viem_1.toEventSelector)(eventItem('RefundSent'));
+exports.REFUND_FAILED_TOPIC0 = (0, viem_1.toEventSelector)(eventItem('RefundFailed'));
+exports.REQUEST_EXPIRED_TOPIC0 = (0, viem_1.toEventSelector)(eventItem('RequestExpired'));
+function sameAddress(a, b) {
+    return a.toLowerCase() === b.toLowerCase();
+}
+function toLogIndex(v, fallback) {
+    if (v === undefined)
+        return fallback;
+    return typeof v === 'number' ? v : Number(BigInt(v));
+}
+function isTopics(t) {
+    return t.length > 0;
+}
+/**
+ * Every read a transaction requested, in log order.
+ *
+ * Filters on BOTH the contract address and topic0. The address filter is a security
+ * control (the node applies the same one in `ingest.go`): without it any contract
+ * can forge a matching log.
+ */
+function parseReadRequestsFromReceipt(receipt, universalCallback) {
+    const out = [];
+    receipt.logs.forEach((log, i) => {
+        if (!sameAddress(log.address, universalCallback))
+            return;
+        if (!isTopics(log.topics) || log.topics[0].toLowerCase() !== exports.READ_REQUESTED_TOPIC0)
+            return;
+        const { args } = (0, viem_1.decodeEventLog)({
+            abi: universalCallback_evm_1.UNIVERSAL_CALLBACK_EVM,
+            eventName: 'ReadRequested',
+            data: log.data,
+            topics: log.topics,
+        });
+        const spec = args.readSpec;
+        out.push({
+            requestId: log.topics[1].toLowerCase(),
+            requestIdUint: args.requestId,
+            callbackTarget: args.callbackTarget,
+            originalFunder: args.originalFunder,
+            spec: {
+                account: { chainNamespace: spec.account.chainNamespace, chainId: spec.account.chainId, owner: spec.account.owner },
+                query: spec.query,
+                minConfirmations: spec.minConfirmations,
+                blockNumber: spec.blockNumber,
+                expiryPushChainHeight: spec.expiryPushChainHeight,
+                maxFee: spec.maxFee,
+                revertRecipient: spec.revertRecipient,
+            },
+            callbackGasLimit: args.callbackGasLimit,
+            totalPaid: args.totalPaid,
+            protocolFee: args.protocolFee,
+            callbackBudget: args.callbackBudget,
+            logIndex: toLogIndex(log.logIndex, i),
+        });
+    });
+    return out;
+}
+/**
+ * Read the fulfil / settle / expiry logs for ONE request out of a receipt.
+ *
+ * `FULFILLED` on the node does not mean the app callback ran: the contract swallows
+ * a reverting callback into `CallbackFailed`. This is where `callbackDelivered`
+ * comes from. Note: EndBlocker-driven expiry transactions are NOT EVM-indexed —
+ * `RequestExpired` will never be seen through a receipt; use the node record.
+ */
+function parseFulfilOutcome(receipt, universalCallback, requestId) {
+    const out = {};
+    const wanted = requestId.toLowerCase();
+    for (const log of receipt.logs) {
+        if (!sameAddress(log.address, universalCallback) || !isTopics(log.topics))
+            continue;
+        if ((log.topics[1] ?? '').toLowerCase() !== wanted)
+            continue;
+        const topic0 = log.topics[0].toLowerCase();
+        const common = { abi: universalCallback_evm_1.UNIVERSAL_CALLBACK_EVM, data: log.data, topics: log.topics };
+        switch (topic0) {
+            case exports.READ_FULFILLED_TOPIC0:
+                out.delivered = true;
+                break;
+            case exports.CALLBACK_FAILED_TOPIC0: {
+                const { args } = (0, viem_1.decodeEventLog)({ ...common, eventName: 'CallbackFailed' });
+                out.delivered = false;
+                out.failReason = args.reason;
+                break;
+            }
+            case exports.CALLBACK_GAS_REPORTED_TOPIC0: {
+                const { args } = (0, viem_1.decodeEventLog)({ ...common, eventName: 'CallbackGasReported' });
+                out.gasReported = args.gasReported;
+                out.burned = args.burned;
+                out.refunded = args.refunded;
+                break;
+            }
+            case exports.REFUND_SENT_TOPIC0: {
+                const { args } = (0, viem_1.decodeEventLog)({ ...common, eventName: 'RefundSent' });
+                out.refunded = args.amount;
+                out.refundTo = args.recipient;
+                out.refundFailed = false;
+                break;
+            }
+            case exports.REFUND_FAILED_TOPIC0: {
+                const { args } = (0, viem_1.decodeEventLog)({ ...common, eventName: 'RefundFailed' });
+                out.refundTo = args.recipient;
+                out.refundFailed = true;
+                break;
+            }
+            case exports.REQUEST_EXPIRED_TOPIC0: {
+                const { args } = (0, viem_1.decodeEventLog)({ ...common, eventName: 'RequestExpired' });
+                out.expired = true;
+                out.refunded = args.refunded;
+                out.refundTo = args.revertRecipient;
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=read-events.js.map

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

@@ -0,0 +1,18 @@
+import { type Hex } from 'viem';
+import type { Orchestrator } from '../orchestrator/orchestrator';
+import type { BatchReadResponse, PreparedRead, ReadCallback } from './read-state.types';
+import { type ReadExecuteOptions } from './read-params';
+export type ReadExecutorDeps = Pick<Orchestrator, 'execute' | 'trackRead' | 'revalidateRead'> & Partial<Pick<Orchestrator, 'getProgressHook' | 'getReadBalance'>>;
+/**
+ * The custom-receiver contract of `read()` / `executeReads()`: a non-zero target and the
+ * app's request entrypoint. Pure — call it before any preflight so a malformed request
+ * fails without a network round-trip.
+ */
+export declare function assertRequestEntrypoint(callback: ReadCallback | undefined, method?: string): Required<Pick<ReadCallback, 'target' | 'abi' | 'functionName'>> & Pick<ReadCallback, 'args'>;
+/** Validate every app call before sending any transaction. */
+export declare function readCall(prepared: PreparedRead): {
+    data: Hex;
+    value: bigint;
+    to: `0x${string}`;
+};
+export declare function executeReads<const R extends readonly PreparedRead[]>(deps: ReadExecutorDeps, reads: R, options?: ReadExecuteOptions): Promise<BatchReadResponse<R>>;

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

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertRequestEntrypoint = assertRequestEntrypoint;
+exports.readCall = readCall;
+exports.executeReads = executeReads;
+const tslib_1 = require("tslib");
+const viem_1 = require("viem");
+const errors_1 = require("./errors");
+const read_params_1 = require("./read-params");
+const spec_builder_1 = require("./spec-builder");
+const progress_hook_1 = tslib_1.__importDefault(require("../progress-hook/progress-hook"));
+const progress_hook_types_1 = require("../progress-hook/progress-hook.types");
+const read_state_types_1 = require("./read-state.types");
+/**
+ * The custom-receiver contract of `read()` / `executeReads()`: a non-zero target and the
+ * app's request entrypoint. Pure — call it before any preflight so a malformed request
+ * fails without a network round-trip.
+ */
+function assertRequestEntrypoint(callback, method = 'executeReads') {
+    const { target, abi, functionName, args } = callback ?? {};
+    if (callback && 'request' in callback)
+        throw new errors_1.InvalidReadQueryError('callback.request was removed; use callback.abi, functionName and args');
+    if (!target)
+        throw new errors_1.ReadRegistryUnavailableError(method);
+    if (!(0, viem_1.isAddress)(target) || /^0x0{40}$/i.test(target))
+        throw new errors_1.InvalidReadQueryError('callback.target must be a non-zero address');
+    if (!Array.isArray(abi) || !functionName)
+        throw new errors_1.InvalidReadQueryError('callback needs abi and functionName');
+    return { target, abi, functionName, args };
+}
+/** Validate every app call before sending any transaction. */
+function readCall(prepared) {
+    const callback = assertRequestEntrypoint(prepared.callback);
+    return { to: callback.target, ...(0, spec_builder_1.toCallData)(prepared, callback) };
+}
+/** Sequential wallet fallback attaches the hashes it already mined to the error it throws. */
+function committedHashes(err) {
+    const hashes = err?.transactionHashes;
+    return Array.isArray(hashes) ? hashes : [];
+}
+async function executeReads(deps, reads, options = {}) {
+    if (reads.length === 0)
+        throw new errors_1.InvalidReadQueryError('executeReads requires at least one prepared read');
+    const hooks = new Set([deps.getProgressHook?.(), options.progressHook]);
+    const emit = (id, ...args) => {
+        for (const hook of hooks)
+            if (hook)
+                hook(progress_hook_1.default[id](...args));
+    };
+    const batch = reads.length > 1;
+    let failedAt = 0; // 0 denotes a batch-wide failure before an individual read is known.
+    if (batch)
+        emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_001, reads.length, reads.map(r => r.preflight.destination.caip2));
+    try {
+        const calls = reads.map(readCall);
+        // Validate the whole batch against current state before sending any request.
+        for (const [i, prepared] of reads.entries()) {
+            failedAt = i + 1;
+            if (batch)
+                emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_002_01, i + 1, reads.length, prepared.preflight.destination.caip2);
+            await deps.revalidateRead(prepared);
+        }
+        failedAt = 0;
+        if (deps.getReadBalance) {
+            const required = reads.reduce((sum, read) => sum + read.value, 0n);
+            const enforceGasCheck = options.advanced?.enforceGasCheck ?? false;
+            let available;
+            try {
+                available = await deps.getReadBalance();
+            }
+            catch (error) {
+                if (enforceGasCheck)
+                    throw error;
+            }
+            if (available !== undefined) {
+                emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_103_01, required, available, enforceGasCheck);
+                if (available < required && enforceGasCheck) {
+                    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_103_02, required, available);
+                    throw new errors_1.ReadStateError('INSUFFICIENT_READ_BALANCE', `read requests need ${required} UPC but the funding account has ${available} UPC`);
+                }
+            }
+        }
+        emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_01);
+        let tx;
+        try {
+            tx = await deps.execute(calls.length === 1 ? calls[0] : { to: calls[0].to, data: calls }, { enforceGasCheck: options.advanced?.enforceGasCheck, progressHook: options.progressHook });
+        }
+        catch (err) {
+            // A non-atomic batch can fail after earlier calls were mined: those reads exist,
+            // their budgets are escrowed, and only these hashes lead back to them.
+            const committed = committedHashes(err);
+            const pending = err?.pendingTransactionHash;
+            if (committed.length === 0 && !pending)
+                throw err;
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new errors_1.ReadStateError('READ_REQUEST_TX_FAILED', `read request batch failed after ${committed.length} of ${calls.length} calls were mined: ${reason}`, {
+                txHash: committed[committed.length - 1] ?? pending,
+                transactionHashes: committed,
+                pendingTransactionHash: pending,
+                hint: [
+                    committed.length ? `Resume the committed reads with trackRead({ txHash }) for: ${committed.join(', ')}` : '',
+                    pending ? `Check the receipt of broadcast transaction ${pending} before retrying; its outcome is unknown` : '',
+                ].filter(Boolean).join('; '),
+            });
+        }
+        const receipt = await tx.wait();
+        if (receipt.status !== 1)
+            throw new errors_1.ReadStateError('READ_REQUEST_TX_FAILED', 'read request transaction reverted', { txHash: tx.hash });
+        const hashes = tx.transactionHashes ?? [tx.hash];
+        const lifecycle = { ...(0, read_params_1.toLifecycleOptions)(options), progressHook: options.progressHook };
+        const groups = await Promise.all(hashes.map((txHash) => deps.trackRead({ txHash }, lifecycle)));
+        const remaining = groups.flatMap((group) => [...group].sort((a, b) => a.request.logIndex - b.request.logIndex));
+        // Each entrypoint must emit one matching request. Never silently attach another
+        // read's ABI/result to an input, even if the app emitted unexpected extra logs.
+        const ordered = reads.map((prepared, i) => {
+            const index = remaining.findIndex((r) => r.request.callbackTarget.toLowerCase() === calls[i].to.toLowerCase() &&
+                r.request.callbackGasLimit === prepared.callbackGasLimit &&
+                (0, spec_builder_1.encodeSpec)(r.request.spec).toLowerCase() === (0, spec_builder_1.encodeSpec)(prepared.spec).toLowerCase());
+            if (index < 0)
+                throw new errors_1.ReadStateError('READ_REQUEST_MISMATCH', `no matching request for prepared read ${i}; resume using the Push transaction hashes: ${hashes.join(', ')}`, { txHash: tx.hash, transactionHashes: hashes });
+            return remaining.splice(index, 1)[0];
+        });
+        if (remaining.length)
+            throw new errors_1.ReadStateError('READ_REQUEST_MISMATCH', `app emitted unexpected extra reads; resume using the Push transaction hashes: ${hashes.join(', ')}`, { txHash: tx.hash, transactionHashes: hashes });
+        const completedReadIds = new Set();
+        const emitReadComplete = (terminal, i) => {
+            if (!batch || completedReadIds.has(terminal.requestId))
+                return;
+            completedReadIds.add(terminal.requestId);
+            emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_002_99_99, i + 1, reads.length, terminal.requestId);
+        };
+        const results = await Promise.all(ordered.map(async (record, i) => {
+            try {
+                const opts = { ...lifecycle, resultShape: reads[i].resultShape };
+                const response = await deps.trackRead({ requestId: record.requestId }, opts);
+                if (options.waitForCompletion === false) {
+                    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_02, response.txHash, response.requestId, response.request.logIndex);
+                    return response;
+                }
+                const terminal = await response.wait();
+                emitReadComplete(terminal, i);
+                return terminal;
+            }
+            catch (error) {
+                if (failedAt === 0)
+                    failedAt = i + 1;
+                throw error;
+            }
+        }));
+        let emittedTerminalBatch = false;
+        const emitBatchOutcome = (terminal) => {
+            if (!batch || emittedTerminalBatch)
+                return;
+            emittedTerminalBatch = true;
+            const failed = terminal.findIndex(r => r.status !== read_state_types_1.UNIVERSAL_READ_STATUS.FULFILLED || r.callbackDelivered !== true || r.raw?.status !== read_state_types_1.READ_STATUS.SUCCESS);
+            if (failed < 0)
+                emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_999_01, terminal.length);
+            else
+                emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_999_02, failed + 1, terminal.length, terminal[failed].errorMsg || 'Read or callback did not succeed');
+        };
+        if (options.waitForCompletion !== false) {
+            emitBatchOutcome(results);
+        }
+        const typedReads = results;
+        const response = {
+            txHash: tx.hash,
+            ...(tx.transactionHashes ? { transactionHashes: [...tx.transactionHashes] } : {}),
+            reads: typedReads,
+            count: typedReads.length,
+            atomic: tx.atomic ?? hashes.length === 1,
+            wait: async (waitOpts) => {
+                let waitFailedAt = 0;
+                try {
+                    const terminal = await Promise.all(typedReads.map(async (read, i) => {
+                        try {
+                            const done = await read.wait(waitOpts);
+                            emitReadComplete(done, i);
+                            return done;
+                        }
+                        catch (error) {
+                            if (waitFailedAt === 0)
+                                waitFailedAt = i + 1;
+                            throw error;
+                        }
+                    }));
+                    emitBatchOutcome(terminal);
+                    return terminal;
+                }
+                catch (error) {
+                    if (batch) {
+                        if (error instanceof errors_1.ReadTimeoutError)
+                            emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_999_03, waitFailedAt, reads.length);
+                        else
+                            emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_999_02, waitFailedAt, reads.length, error instanceof Error ? error.message : String(error));
+                    }
+                    throw error;
+                }
+            },
+        };
+        return response;
+    }
+    catch (error) {
+        if (batch) {
+            if (error instanceof errors_1.ReadTimeoutError)
+                emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_999_03, failedAt, reads.length);
+            else
+                emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_999_02, failedAt, reads.length, error instanceof Error ? error.message : String(error));
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=read-executor.js.map

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

@@ -0,0 +1,205 @@
+/**
+ * The public `read(subject, options)` grammar → the internal `BuildReadSpecParams`.
+ *
+ *   read(user,     { chain })                          native balance (ETH / lamports)
+ *   read(user,     { chain, token })                   token balance (ERC-20 / SPL via ATA)
+ *   read(contract, { chain, abi, functionName, args }) typed call — abi encodes AND decodes
+ *   read(contract, { chain, storageSlot })             storage word
+ *   read(url,      { chain: CHAIN.WEB2, web2 })        web2
+ *
+ * Query keys are mutually exclusive; the namespace decides which are legal.
+ */
+import type { Abi, Address, Hex, ContractFunctionReturnType, ContractFunctionName, ContractFunctionArgs, ExtractAbiFunctionForArgs } from 'viem';
+import { CHAIN, PUSH_NETWORK } from '../constants/enums';
+import type { BuildReadSpecParams, ReadChain, ReadDestination, ReadLifecycleOptions, ReadQuery, ReadResultShape, Web2Extract } from './read-state.types';
+import type { ReadCallback } from './read-state.types';
+import type { ProgressEvent } from '../progress-hook/progress-hook.types';
+export interface ReadWeb2Options {
+    /**
+     * 1–16 entries; result values come back in this order. Validators vote on
+     * identical extracted bytes. A volatile API may not reach quorum until
+     * aggregation modes such as median are supported by the protocol.
+     */
+    extract: readonly Web2Extract[];
+    method?: 'GET' | 'POST';
+    /** ⚠ Written to a public event log, forever. */
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+    timeoutMs?: number;
+}
+interface ReadOptionsInput {
+    /** Destination. `CHAIN.WEB2` for https. */
+    chain: ReadChain;
+    /** Token balance of `subject`: ERC-20 `balanceOf` on EVM, the SPL ATA on SVM. */
+    token?: string;
+    /** Solana token balance only. Defaults to the original SPL Token program. */
+    tokenProgram?: 'spl-token' | 'token-2022';
+    /** Typed contract call — encodes the call and decodes the result. */
+    abi?: Abi;
+    functionName?: string;
+    args?: readonly unknown[];
+    /** EVM storage word. */
+    storageSlot?: Hex | bigint;
+    /** Web2 only — required when `chain` is web2. */
+    web2?: ReadWeb2Options;
+    blockNumber?: bigint;
+    minConfirmations?: number;
+    expiryBlocks?: bigint;
+    maxFee?: bigint;
+    callback?: ReadCallback;
+    /** ReadSpec.revertRecipient. Default: the sending account. */
+    refundTo?: Address;
+    waitForCompletion?: boolean;
+    progressHook?: (event: ProgressEvent) => void;
+    advanced?: {
+        pollingIntervalMs?: number;
+        timeout?: number;
+        enforceGasCheck?: boolean;
+    };
+}
+type NoQuery = {
+    token?: never;
+    tokenProgram?: never;
+    abi?: never;
+    functionName?: never;
+    args?: never;
+    storageSlot?: never;
+    web2?: never;
+};
+type Query<K extends keyof NoQuery, T> = Omit<NoQuery, K> & T;
+type EvmChain = Extract<CHAIN, `eip155:${string}`>;
+type SvmChain = Extract<CHAIN, `solana:${string}`>;
+export type ReadQueryOptions = ({
+    chain: EvmChain;
+} & NoQuery) | ({
+    chain: SvmChain;
+} & NoQuery) | ({
+    chain: EvmChain;
+} & Query<'token', {
+    token: string;
+}>) | ({
+    chain: SvmChain;
+} & Query<'token' | 'tokenProgram', {
+    token: string;
+    tokenProgram?: 'spl-token' | 'token-2022';
+}>) | ({
+    chain: EvmChain;
+} & Query<'abi' | 'functionName' | 'args', {
+    abi: Abi;
+    functionName: string;
+    args?: readonly unknown[];
+}>) | ({
+    chain: EvmChain;
+} & Query<'storageSlot', {
+    storageSlot: Hex | bigint;
+}>) | ({
+    chain: typeof CHAIN.WEB2;
+} & Query<'web2', {
+    web2: ReadWeb2Options;
+}>);
+export type ReadCallbackOptions = {
+    callback?: ({
+        target: Address;
+        gasLimit: bigint;
+    } & Pick<ReadCallback, 'abi' | 'functionName' | 'args'>) | {
+        target?: never;
+        gasLimit?: bigint;
+        abi?: never;
+        functionName?: never;
+        args?: never;
+    };
+};
+type SharedPrepareOptions = ReadCallbackOptions & Pick<ReadOptionsInput, 'expiryBlocks' | 'maxFee' | 'refundTo'> & {
+    advanced?: never;
+    waitForCompletion?: never;
+    progressHook?: never;
+};
+type EvmPinningOptions = Pick<ReadOptionsInput, 'blockNumber' | 'minConfirmations'>;
+type FinalizedDestinationOptions = {
+    blockNumber?: never;
+    minConfirmations?: never;
+};
+/** EVM reads expose pinning; SVM and Web2 choose their finalized/heightless references internally. */
+export type ReadPrepareOptions = SharedPrepareOptions & ((Extract<ReadQueryOptions, {
+    chain: EvmChain;
+}> & EvmPinningOptions) | (Extract<ReadQueryOptions, {
+    chain: SvmChain | typeof CHAIN.WEB2;
+}> & FinalizedDestinationOptions));
+export type ReadExecuteOptions = Pick<ReadOptionsInput, 'advanced' | 'waitForCompletion' | 'progressHook'>;
+type WithExecutionOptions<T> = T extends unknown ? Omit<T, 'advanced' | 'waitForCompletion' | 'progressHook'> & ReadExecuteOptions : never;
+export type ReadOptions = WithExecutionOptions<ReadPrepareOptions> & {
+    callback?: (Required<Pick<ReadCallback, 'target' | 'gasLimit' | 'abi' | 'functionName'>> & Pick<ReadCallback, 'args'>) | {
+        target?: never;
+        gasLimit?: bigint;
+        abi?: never;
+        functionName?: never;
+        args?: never;
+    };
+};
+export type ReadTrackOptions = {
+    advanced?: Omit<NonNullable<ReadOptionsInput['advanced']>, 'enforceGasCheck'>;
+    resultShape?: ReadResultShape;
+};
+type Web2Values = {
+    uint256: bigint;
+    int256: bigint;
+    bool: boolean;
+    bytes: Hex;
+    string: string;
+};
+type Web2Value<E extends Web2Extract> = Web2Values[E['valueType']];
+type ReadFunctionName<A extends Abi, F extends string> = F & ContractFunctionName<A, 'view' | 'pure'>;
+type ReadFunctionArgs<O, A extends Abi, F extends string> = O extends {
+    args: infer Args extends ContractFunctionArgs<A, 'view' | 'pure', ReadFunctionName<A, F>>;
+} ? Args : readonly [] extends ContractFunctionArgs<A, 'view' | 'pure', ReadFunctionName<A, F>> ? readonly [] : ContractFunctionArgs<A, 'view' | 'pure', ReadFunctionName<A, F>>;
+type ReadCallValue<A extends Abi, F extends string, Args extends ContractFunctionArgs<A, 'view' | 'pure', ReadFunctionName<A, F>>> = ExtractAbiFunctionForArgs<A, 'view' | 'pure', ReadFunctionName<A, F>, Args> extends infer Selected ? Selected extends Abi[number] & {
+    type: 'function';
+    outputs: readonly unknown[];
+} ? ContractFunctionReturnType<readonly [Selected]> : never : never;
+/** Matches the existing decoder: select the overload by args before wrapping its outputs. */
+export type ReadValue<O> = O extends {
+    abi: infer A extends Abi;
+    functionName: infer F extends string;
+} ? number extends A['length'] ? readonly unknown[] : ReadCallValue<A, F, ReadFunctionArgs<O, A, F>> : O extends {
+    web2: {
+        extract: infer E extends readonly Web2Extract[];
+    };
+} ? {
+    readonly [K in keyof E]: Web2Value<E[K]>;
+} : O extends {
+    storageSlot: unknown;
+} ? Hex : bigint;
+/** Just `balanceOf` — it also types the decoded result as uint256. */
+export declare const ERC20_BALANCE_OF_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}];
+export declare function toReadDestination(chain: ReadChain): ReadDestination;
+/** Build the internal query from the public grammar. Pure. */
+export declare function toReadQuery(subject: string, o: ReadOptionsInput): ReadQuery;
+/** Public options → the spec builder's params. Pure; throws `InvalidReadQueryError` on a malformed request. */
+export declare function toBuildReadSpecParams(subject: string, o: ReadOptionsInput, network?: PUSH_NETWORK): BuildReadSpecParams;
+/** Offline logical query key for the registry's latestResult lookup. */
+export declare function getReadQueryKey<const O extends ReadQueryOptions>(subject: string, options: O & ValidateReadCall<O>): Hex;
+export declare function toLifecycleOptions(o?: ReadTrackOptions): ReadLifecycleOptions;
+/** Restrict known ABIs to read functions and their declared argument tuple. */
+export type ValidateReadCall<O> = O extends {
+    abi: infer A extends Abi;
+    functionName: infer F extends string;
+} ? {
+    functionName: ContractFunctionName<A, 'view' | 'pure'>;
+} & (readonly [] extends ContractFunctionArgs<A, 'view' | 'pure', F & ContractFunctionName<A, 'view' | 'pure'>> ? {
+    args?: ContractFunctionArgs<A, 'view' | 'pure', F & ContractFunctionName<A, 'view' | 'pure'>>;
+} : {
+    args: ContractFunctionArgs<A, 'view' | 'pure', F & ContractFunctionName<A, 'view' | 'pure'>>;
+}) : unknown;
+export {};