@pushchain/core 6.0.25 → 6.0.26

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

@@ -3,13 +3,17 @@
  *
  *   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, abi, functionName, args }) typed call — abi encodes AND decodes (any mutability; eth_call simulation)
+ *   read(account,  { chain, idl, functionName? })      Anchor account, layout picked by discriminator
+ *   read(program,  { chain, idl, functionName, args }) Anchor PDA — args are its IDL-declared seeds
  *   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 type { Abi, AbiStateMutability, Address, Hex, ContractFunctionReturnType, ContractFunctionName, ContractFunctionArgs, ExtractAbiFunctionForArgs } from 'viem';
+import type { Idl, IdlAccounts } from '@coral-xyz/anchor';
+import { PublicKey } from '@solana/web3.js';
 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';
@@ -32,11 +36,23 @@ interface ReadOptionsInput {
     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';
+    /**
+     * Anchor IDL — the Solana counterpart of `abi`. The subject account is decoded
+     * with the layout whose discriminator matches its data. Reads never execute an
+     * instruction.
+     */
+    idl?: Idl;
     /** Typed contract call — encodes the call and decodes the result. */
     abi?: Abi;
+    /**
+     * With `abi`: the function to call (required). With `idl`: the account layout
+     * (optional — inferred from the discriminator; snake_case or camelCase).
+     */
     functionName?: string;
+    /**
+     * With `abi`: positional call args. With `idl` and the program id as subject:
+     * the PDA's non-constant seeds, in IDL order.
+     */
     args?: readonly unknown[];
     /** EVM storage word. */
     storageSlot?: Hex | bigint;
@@ -60,6 +76,8 @@ interface ReadOptionsInput {
 type NoQuery = {
     token?: never;
     tokenProgram?: never;
+    idl?: never;
+    accountName?: never;
     abi?: never;
     functionName?: never;
     args?: never;
@@ -79,9 +97,14 @@ export type ReadQueryOptions = ({
     token: string;
 }>) | ({
     chain: SvmChain;
-} & Query<'token' | 'tokenProgram', {
+} & Query<'token', {
     token: string;
-    tokenProgram?: 'spl-token' | 'token-2022';
+}>) | ({
+    chain: SvmChain;
+} & Query<'idl' | 'functionName' | 'args', {
+    idl: Idl;
+    functionName?: string;
+    args?: readonly unknown[];
 }>) | ({
     chain: EvmChain;
 } & Query<'abi' | 'functionName' | 'args', {
@@ -100,7 +123,7 @@ export type ReadQueryOptions = ({
 export type ReadCallbackOptions = {
     callback?: ({
         target: Address;
-        gasLimit: bigint;
+        gasLimit?: bigint;
     } & Pick<ReadCallback, 'abi' | 'functionName' | 'args'>) | {
         target?: never;
         gasLimit?: bigint;
@@ -128,7 +151,7 @@ export type ReadPrepareOptions = SharedPrepareOptions & ((Extract<ReadQueryOptio
 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'>) | {
+    callback?: (Required<Pick<ReadCallback, 'target' | 'abi' | 'functionName'>> & Pick<ReadCallback, 'gasLimit' | 'args'>) | {
         target?: never;
         gasLimit?: bigint;
         abi?: never;
@@ -148,11 +171,11 @@ type Web2Values = {
     string: string;
 };
 type Web2Value<E extends Web2Extract> = Web2Values[E['valueType']];
-type ReadFunctionName<A extends Abi, F extends string> = F & ContractFunctionName<A, 'view' | 'pure'>;
+type ReadFunctionName<A extends Abi, F extends string> = F & ContractFunctionName<A, AbiStateMutability>;
 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] & {
+    args: infer Args extends ContractFunctionArgs<A, AbiStateMutability, ReadFunctionName<A, F>>;
+} ? Args : readonly [] extends ContractFunctionArgs<A, AbiStateMutability, ReadFunctionName<A, F>> ? readonly [] : ContractFunctionArgs<A, AbiStateMutability, ReadFunctionName<A, F>>;
+type ReadCallValue<A extends Abi, F extends string, Args extends ContractFunctionArgs<A, AbiStateMutability, ReadFunctionName<A, F>>> = ExtractAbiFunctionForArgs<A, AbiStateMutability, ReadFunctionName<A, F>, Args> extends infer Selected ? Selected extends Abi[number] & {
     type: 'function';
     outputs: readonly unknown[];
 } ? ContractFunctionReturnType<readonly [Selected]> : never : never;
@@ -160,7 +183,7 @@ type ReadCallValue<A extends Abi, F extends string, Args extends ContractFunctio
 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 {
+} ? number extends A['length'] ? unknown : ReadCallValue<A, F, ReadFunctionArgs<O, A, F>> : O extends {
     web2: {
         extract: infer E extends readonly Web2Extract[];
     };
@@ -168,7 +191,19 @@ export type ReadValue<O> = O extends {
     readonly [K in keyof E]: Web2Value<E[K]>;
 } : O extends {
     storageSlot: unknown;
-} ? Hex : bigint;
+} ? Hex : O extends {
+    idl: infer I extends Idl;
+} ? IdlReadValue<I, O extends {
+    functionName: infer N extends string;
+} ? N : undefined> : bigint;
+/** snake_case / camelCase / PascalCase spellings compare equal (mirrors `idlNameKey`). */
+type IdlNameKey<S extends string> = Lowercase<S extends `${infer H}_${infer T}` ? `${H}${IdlNameKey<T>}` : S>;
+type IdlAccountName<I extends Idl> = Extract<keyof IdlAccounts<I>, string>;
+type MatchAccount<I extends Idl, N extends string> = {
+    [K in IdlAccountName<I>]: IdlNameKey<K> extends IdlNameKey<N> ? K : never;
+}[IdlAccountName<I>];
+/** A literal IDL types the account; a dynamic one (names typed `string`) yields `unknown`. */
+type IdlReadValue<I extends Idl, N extends string | undefined> = string extends IdlAccountName<I> ? unknown : N extends string ? IdlAccounts<I>[MatchAccount<I, N>] : IdlAccounts<I>[IdlAccountName<I>];
 /** Just `balanceOf` — it also types the decoded result as uint256. */
 export declare const ERC20_BALANCE_OF_ABI: readonly [{
     readonly type: "function";
@@ -185,21 +220,31 @@ export declare const ERC20_BALANCE_OF_ABI: readonly [{
 }];
 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;
+export declare function toReadQuery(subject: string, o: ReadOptionsInput, resolvedTokenProgram?: PublicKey): 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 toBuildReadSpecParams(subject: string, o: ReadOptionsInput, network?: PUSH_NETWORK, resolvedTokenProgram?: PublicKey): BuildReadSpecParams;
+/** Resolve Solana mint ownership before the otherwise-pure options conversion. */
+export declare function resolveReadSpecParams(subject: string, o: ReadOptionsInput, network: PUSH_NETWORK, rpcUrls: Partial<Record<CHAIN, string[]>>): Promise<BuildReadSpecParams>;
+/** Internal offline key helper. Solana token callers must use PreparedRead.queryKey after mint resolution. */
 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. */
+/**
+ * Restrict known ABIs to declared functions and their argument tuple. Every mutability
+ * is allowed: the read is an eth_call simulation, so state-changing functions only return data.
+ */
 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'>>;
+    functionName: ContractFunctionName<A, AbiStateMutability>;
+} & (readonly [] extends ContractFunctionArgs<A, AbiStateMutability, F & ContractFunctionName<A, AbiStateMutability>> ? {
+    args?: ContractFunctionArgs<A, AbiStateMutability, F & ContractFunctionName<A, AbiStateMutability>>;
 } : {
-    args: ContractFunctionArgs<A, 'view' | 'pure', F & ContractFunctionName<A, 'view' | 'pure'>>;
-}) : unknown;
+    args: ContractFunctionArgs<A, AbiStateMutability, F & ContractFunctionName<A, AbiStateMutability>>;
+}) : O extends {
+    idl: infer I extends Idl;
+    functionName: infer N extends string;
+} ? string extends IdlAccountName<I> ? unknown : [MatchAccount<I, N>] extends [never] ? {
+    functionName: IdlAccountName<I>;
+} : unknown : unknown;
 export {};

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

@@ -4,9 +4,13 @@ exports.ERC20_BALANCE_OF_ABI = void 0;
 exports.toReadDestination = toReadDestination;
 exports.toReadQuery = toReadQuery;
 exports.toBuildReadSpecParams = toBuildReadSpecParams;
+exports.resolveReadSpecParams = resolveReadSpecParams;
 exports.getReadQueryKey = getReadQueryKey;
 exports.toLifecycleOptions = toLifecycleOptions;
 const viem_1 = require("viem");
+const web3_js_1 = require("@solana/web3.js");
+const svm_account_1 = require("./svm-account");
+const svm_pda_1 = require("./svm-pda");
 const enums_1 = require("../constants/enums");
 const registry_1 = require("./registry");
 const read_state_1 = require("../constants/read-state");
@@ -23,14 +27,18 @@ exports.ERC20_BALANCE_OF_ABI = [
         outputs: [{ name: '', type: 'uint256' }],
     },
 ];
-const QUERY_KEYS = ['token', 'abi', 'storageSlot', 'web2'];
+const QUERY_KEYS = ['token', 'abi', 'idl', 'storageSlot', 'web2'];
 function queryKind(o) {
+    if ('tokenProgram' in o)
+        throw new errors_1.InvalidReadQueryError('tokenProgram is detected from the mint; remove options.tokenProgram');
+    if ('accountName' in o)
+        throw new errors_1.InvalidReadQueryError('accountName was removed; pass the account layout as functionName (optional — inferred from the discriminator)');
     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');
+    if ((o.functionName !== undefined || o.args !== undefined) && o.abi === undefined && o.idl === undefined) {
+        throw new errors_1.InvalidReadQueryError('functionName and args need abi or idl');
     }
     return present[0] ?? 'native';
 }
@@ -38,12 +46,9 @@ 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) {
+function toReadQuery(subject, o, resolvedTokenProgram) {
     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');
@@ -75,24 +80,52 @@ function toReadQuery(subject, o) {
                 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.
+    // SVM: token-program ownership has already been resolved by the async public path.
     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() };
+            if (!resolvedTokenProgram)
+                throw new errors_1.InvalidReadQueryError('Solana token reads need mint-owner resolution; use universal.prepareRead or universal.read');
+            return { type: 'splTokenAccount', account: (0, svm_1.deriveAssociatedTokenAddress)(subject, o.token, resolvedTokenProgram).toBase58() };
+        case 'idl':
+            return toIdlAccountQuery(subject, o);
         default:
-            throw new errors_1.InvalidReadQueryError(`unsupported query for solana: ${kind} (program reads land with idl support)`);
+            throw new errors_1.InvalidReadQueryError(`unsupported query for solana: ${kind}; use idl for account-state decoding`);
+    }
+}
+/**
+ * `idl` → a raw account read that decodes with the IDL. The subject is the account,
+ * or the program id when `args` are the seeds of the `functionName` PDA.
+ */
+function toIdlAccountQuery(subject, o) {
+    const idl = o.idl;
+    (0, svm_account_1.validateIdl)(idl);
+    const accountName = o.functionName === undefined ? undefined : (0, svm_account_1.resolveAccountName)(idl, o.functionName);
+    if ((0, svm_pda_1.isProgramSubject)(idl, subject)) {
+        if (!o.functionName)
+            throw new errors_1.InvalidReadQueryError('the subject is the program id: pass functionName (the account layout) and args (its PDA seeds) to derive the account');
+        const pda = (0, svm_pda_1.deriveIdlPda)(idl, o.functionName, o.args ?? []);
+        return { type: 'rawAccountData', account: pda.toBase58(), idl, accountName };
+    }
+    if (o.args !== undefined)
+        throw new errors_1.InvalidReadQueryError('with idl, args are PDA seeds and need the program id as the subject');
+    try {
+        new web3_js_1.PublicKey(subject);
     }
+    catch {
+        throw new errors_1.InvalidReadQueryError(`Solana subject must be a base58 pubkey, got ${subject}`);
+    }
+    return { type: 'rawAccountData', account: subject, idl, accountName };
 }
 /** 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) {
+function toBuildReadSpecParams(subject, o, network = enums_1.PUSH_NETWORK.TESTNET_DONUT, resolvedTokenProgram) {
     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 query = toReadQuery(subject, o, resolvedTokenProgram);
     const callback = (0, registry_1.resolveReadCallback)(o.callback, network, (0, registry_1.computeReadQueryKey)(destination, query));
     return {
         callback,
@@ -106,7 +139,18 @@ function toBuildReadSpecParams(subject, o, network = enums_1.PUSH_NETWORK.TESTNE
         maxFee: o.maxFee,
     };
 }
-/** Offline logical query key for the registry's latestResult lookup. */
+/** Resolve Solana mint ownership before the otherwise-pure options conversion. */
+async function resolveReadSpecParams(subject, o, network, rpcUrls) {
+    const kind = queryKind(o);
+    const namespace = (0, destination_1.resolveDestination)(toReadDestination(o.chain)).namespace;
+    if (namespace === read_state_1.READ_NAMESPACE.SVM && kind === 'token') {
+        new web3_js_1.PublicKey(subject);
+        const program = await (0, svm_account_1.detectTokenProgram)(o.token, o.chain, rpcUrls[o.chain]);
+        return toBuildReadSpecParams(subject, o, network, program);
+    }
+    return toBuildReadSpecParams(subject, o, network);
+}
+/** Internal offline key helper. Solana token callers must use PreparedRead.queryKey after mint resolution. */
 function getReadQueryKey(subject, options) {
     return (0, registry_1.computeReadQueryKey)(toReadDestination(options.chain), toReadQuery(subject, options));
 }

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

@@ -1,4 +1,5 @@
 import type { Abi, Address, Hex } from 'viem';
+import type { Idl } from '@coral-xyz/anchor';
 import type { CHAIN } from '../constants/enums';
 import type { ReadNamespace } from '../constants/read-state';
 /**
@@ -48,6 +49,8 @@ export type SvmReadQuery = {
 } | {
     type: 'rawAccountData';
     account: string | Uint8Array;
+    idl?: Idl; /** Omitted → layout inferred from the discriminator. */
+    accountName?: string;
 };
 export type Web2ValueType = 'uint256' | 'int256' | 'bool' | 'string' | 'bytes';
 export interface Web2Extract {
@@ -71,6 +74,10 @@ export interface Web2ReadQuery {
 }
 export type ReadQuery = EvmReadQuery | SvmReadQuery | Web2ReadQuery;
 export type ReadResultShape = {
+    kind: 'svmAccount';
+    idl: Idl; /** Omitted → layout inferred from the discriminator. */
+    accountName?: string;
+} | {
     kind: 'uint256';
 } | {
     kind: 'bytes32';
@@ -98,6 +105,10 @@ export interface EncodedReadQuery {
     warnings: string[];
 }
 export type DecodedReadResult = {
+    kind: 'svmAccount';
+    value: unknown; /** The IDL layout the data decoded as. */
+    accountName: string;
+} | {
     kind: 'uint256';
     value: bigint;
 } | {
@@ -314,11 +325,20 @@ export interface ReadFees {
 }
 export interface UniversalReadResponse<T = unknown> {
     requestId: Hex;
+    /** `requestId` as the `uint256` contracts key results by (e.g. registry `resultByRequestId`). */
+    requestIdUint: bigint;
     /** Push tx that carried the request */
     txHash: Hex;
     destination: ResolvedDestination;
     /** Required read destination, including `CHAIN.WEB2`. */
     chain: ReadChain;
+    /**
+     * The one field that answers "did it work": `SUCCESS` means the source read
+     * succeeded, your callback ran, and `value` is set (when a shape is known).
+     * Derived by the SDK from `status`, `raw.status`, `callbackDelivered` and
+     * `decodeError`, which stay available for debugging.
+     */
+    outcome: READ_OUTCOME;
     status: UNIVERSAL_READ_STATUS;
     isTerminal: boolean;
     /**
@@ -405,6 +425,27 @@ export declare enum READ_ERROR_CODE {
     INVALID_RESULT = 5,
     REJECTED = 6
 }
+/**
+ * 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.
+ */
+export declare enum READ_OUTCOME {
+    /** Not terminal yet. */
+    PENDING = "PENDING",
+    /** Source SUCCESS, callback delivered, result decoded (or no shape to decode with). */
+    SUCCESS = "SUCCESS",
+    /** FULFILLED, but the destination returned an error (`raw.errorCode`). */
+    SOURCE_ERROR = "SOURCE_ERROR",
+    /** FULFILLED, but the receiver callback reverted or ran out of gas (`callbackFailReason`). */
+    CALLBACK_FAILED = "CALLBACK_FAILED",
+    /** Delivered, but `resultData` did not match the expected shape (`decodeError`). */
+    DECODE_FAILED = "DECODE_FAILED",
+    EXPIRED = "EXPIRED",
+    FAILED = "FAILED",
+    ABORTED = "ABORTED",
+    /** FULFILLED, but the fulfil receipt was unavailable, so delivery cannot be confirmed. */
+    UNKNOWN = "UNKNOWN"
+}
 /** On-chain lifecycle (`RequestStatus` in ReadTypes.sol). */
 export declare enum CONTRACT_REQUEST_STATUS {
     NONE = 0,

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

@@ -1,6 +1,6 @@
 "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;
+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)
 // ---------------------------------------------------------------------------
@@ -32,6 +32,28 @@ var READ_ERROR_CODE;
     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) {

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

@@ -18,7 +18,7 @@
 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';
+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'> & {
@@ -38,6 +38,11 @@ export declare function trackRead(deps: TrackReadDeps, ref: {
 }, 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;

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.trackRead = trackRead;
 exports.toRequestIdHex = toRequestIdHex;
+exports.deriveReadOutcome = deriveReadOutcome;
 exports.inferResultShape = inferResultShape;
 exports.statusName = statusName;
 exports.defaultWaitTimeoutMs = defaultWaitTimeoutMs;
@@ -61,16 +62,23 @@ async function fetchRecords(deps, ref) {
 /** 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)
+        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 });
 }
@@ -144,6 +152,8 @@ async function buildResponse(deps, record, opts) {
     }
     const txHash = req.requestedTxHash.toLowerCase();
     const response = {
+        requestIdUint: BigInt(requestId),
+        outcome: deriveReadOutcome(status, raw?.status, callbackDelivered, decodeError),
         requestId,
         txHash,
         destination,
@@ -174,23 +184,51 @@ async function buildResponse(deps, record, opts) {
     };
     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 = {};
-    for (const t of record.pcTx) {
+    // 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)
-            continue;
+            return undefined;
         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;
-            }
+            return (0, read_events_1.parseFulfilOutcome)(receipt, uc, requestId);
         }
         catch {
-            // pruned or not yet available — leave those fields undefined rather than guess
+            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;
@@ -277,7 +315,7 @@ function chainFromCaip2(caip2) {
 }
 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';
+    const base = chain_1.PUSH_CHAIN_INFO[chain].explorerUrl ?? 'https://donut.push.network';
     return `${base}/tx/${txHash}`;
 }
 // ---------------------------------------------------------------------------
@@ -312,6 +350,8 @@ async function waitForRead(deps, initial, opts) {
     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) {
@@ -327,6 +367,7 @@ async function waitForRead(deps, initial, opts) {
                     }, 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 {
@@ -334,6 +375,23 @@ async function waitForRead(deps, initial, opts) {
                 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.
@@ -388,6 +446,7 @@ async function waitForRead(deps, initial, opts) {
             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();
@@ -403,13 +462,20 @@ function emitTerminal(emit, r) {
             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);
+    }
+    // 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;
     }
-    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_02, r.requestId, statusName(r.status), r.raw?.errorCode, r.errorMsg, r.fees.refunded);
+    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.js

@@ -28,9 +28,8 @@ 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 };
+        // Same default as the registry: unused callback budget is refunded.
+        return { ...callback, gasLimit: callback.gasLimit ?? read_state_1.REGISTRY_CALLBACK_GAS };
     }
     if (callback?.abi !== undefined || callback?.functionName !== undefined || callback?.args !== undefined) {
         throw new errors_1.InvalidReadQueryError('callback abi, functionName and args require callback.target');