@pushchain/core 6.0.25 → 6.0.27-alpha.0

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

@@ -3,15 +3,19 @@
  *
  *   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 { BuildReadSpecParams, ReadChain, ReadDestination, ReadLifecycleOptions, ReadQuery, ReadResultShape, Web2Extract, Web2ReadChain } from './read-state.types';
 import type { ReadCallback } from './read-state.types';
 import type { ProgressEvent } from '../progress-hook/progress-hook.types';
 export interface ReadWeb2Options {
@@ -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', {
@@ -93,14 +116,14 @@ export type ReadQueryOptions = ({
 } & Query<'storageSlot', {
     storageSlot: Hex | bigint;
 }>) | ({
-    chain: typeof CHAIN.WEB2;
+    chain: Web2ReadChain;
 } & Query<'web2', {
     web2: ReadWeb2Options;
 }>);
 export type ReadCallbackOptions = {
     callback?: ({
         target: Address;
-        gasLimit: bigint;
+        gasLimit?: bigint;
     } & Pick<ReadCallback, 'abi' | 'functionName' | 'args'>) | {
         target?: never;
         gasLimit?: bigint;
@@ -123,12 +146,12 @@ type FinalizedDestinationOptions = {
 export type ReadPrepareOptions = SharedPrepareOptions & ((Extract<ReadQueryOptions, {
     chain: EvmChain;
 }> & EvmPinningOptions) | (Extract<ReadQueryOptions, {
-    chain: SvmChain | typeof CHAIN.WEB2;
+    chain: SvmChain | Web2ReadChain;
 }> & 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'>) | {
+    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,27 +27,29 @@ 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';
 }
 function toReadDestination(chain) {
-    return chain === enums_1.CHAIN.WEB2 ? read_state_1.WEB2_DESTINATION : { chain };
+    // Both public spellings normalize to the unchanged wire identity web2:https.
+    return (0, read_state_1.isWeb2ReadChain)(chain) ? 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');
@@ -52,7 +58,7 @@ function toReadQuery(subject, o) {
         return { type: 'http', url: subject, ...o.web2 };
     }
     if (kind === 'web2')
-        throw new errors_1.InvalidReadQueryError('`web2` is only valid with chain CHAIN.WEB2');
+        throw new errors_1.InvalidReadQueryError('`web2` is only valid with chain READ.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}`);
@@ -75,24 +81,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 +140,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,11 +1,14 @@
 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';
 /**
  * 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;
+/** Web2 read source: `READ.CHAIN.WEB2` (`'web2'`) or the legacy `'web2:https'` literal. */
+export type Web2ReadChain = 'web2' | 'web2:https';
+export type ReadChain = CHAIN | Web2ReadChain;
 export type ReadDestination = {
     chain: ReadChain;
 } | {
@@ -48,6 +51,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 +76,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 +107,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 +327,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 +427,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;