@pushchain/core 6.0.25 → 6.0.26

package/CHANGELOG.md

@@ -1,3 +1,69 @@
+@pushchain/core@6.0.26 (2026-09-23)
+
+- docs: changelog for read-state docs parity
+- feat: align read-state API with the Universal Read docs
+- fix: race prune and archive for Push receipts and block results
+- feat: add Solana account reads and update read registry
+
+---
+
+@pushchain/core (unreleased)
+
+Changes on `feature/readstate-docs-parity` since 6.0.25, aligning Universal Read with the
+push-chain-website docs (PR #1244).
+
+### Breaking
+
+- Solana token reads detect SPL Token vs Token-2022 from the mint's owner. The
+  `tokenProgram` option is removed and now throws.
+- The Donut Universal Read Registry default is
+  `0x00000000000000000000000000000000000000b2`. Results stored on the previous
+  registry stay there; tracking by request ID still works.
+- `READ-TX-199-01` (level SUCCESS) now fires only when `outcome` is `SUCCESS`. A
+  FULFILLED read that did not work (source error, callback failure, undecodable
+  result, unconfirmed delivery) ends on `READ-TX-199-02`, whose `status` is the
+  outcome name.
+
+### Added
+
+- Solana account reads with `idl`, the counterpart of `abi`. The account layout is
+  picked by its 8-byte discriminator; the optional `functionName` names the layout
+  (snake, camel or Pascal case) and types `value`. With the program id as the
+  subject, `functionName` plus positional `args` derive the PDA from the seeds the
+  IDL declares. `accountName` is not supported and throws with a hint.
+- EVM contract-call reads accept any ABI function, including `nonpayable` and
+  `payable`. Validators run the call as an `eth_call` simulation at the pinned
+  block, so it returns data and never executes.
+- `response.outcome` (`PushChain.CONSTANTS.READ.OUTCOME`): one answer to "did it
+  work" — `SUCCESS`, `SOURCE_ERROR`, `CALLBACK_FAILED`, `DECODE_FAILED`,
+  `EXPIRED`, `FAILED`, `ABORTED`, `PENDING`, or `UNKNOWN` (delivery unconfirmed).
+- `response.requestIdUint`: the request ID as the `uint256` contracts key results by.
+- Progress events: `READ-TX-104-03` Looking Up Request, `104-04` Request Found,
+  `104-05` Request Not Found (lookup timeout), `105-04` Approaching Expiry (once per
+  `wait()`, at 30 or fewer Push blocks left) and `102-04` Preflight Stale (a read
+  prepared more than 60 s before `executeReads`).
+
+### Improved
+
+- `trackRead` on a settled read returns in about 1 s instead of about 19 s on
+  Donut. Fulfil and settle receipts are fetched in parallel, and Push receipts
+  are requested from the prune RPC and the archive at the same time.
+- `callback.gasLimit` is optional for custom targets and defaults to `500_000n`,
+  like the registry. Unused callback budget is refunded.
+- Refund events `READ-TX-106-05/06` also fire for expired reads.
+- `value` is typed `unknown` for ABIs not declared `as const`; a single-output
+  function decodes to the bare value, not an array.
+
+### Fixed
+
+- `explorerUrl` and Donut's viem `blockExplorers` pointed at
+  `explorer.donut.push.org`, which does not resolve. They now use
+  `https://donut.push.network`.
+- Refunds of expired reads older than the prune window came back `undefined`.
+  Cosmos block results now fall back to the archive RPC.
+
+---
+
 @pushchain/core@6.0.25 (2026-09-16)
 
 - docs: document read-state and transaction fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushchain/core",
-  "version": "6.0.25",
+  "version": "6.0.26",
   "homepage": "https://push.org",
   "keywords": [
     "pushchain",

package/src/lib/constants/chain.js

@@ -210,7 +210,7 @@ exports.CHAIN_INFO = {
         confirmations: 1,
         fastConfirmations: 0,
         timeout: 30000,
-        explorerUrl: 'https://explorer.donut.push.org',
+        explorerUrl: 'https://donut.push.network',
         // Push Chain AMM - Uniswap V3
         // Source: https://push.org/agents/contract-addresses.json
         dex: {

package/src/lib/constants/index.d.ts

@@ -1,6 +1,6 @@
 import { CHAIN, LIBRARY, PUSH_NETWORK } from './enums';
 import { TypedDataDomain, TypedData } from '../universal/signer/signer.types';
-import { UNIVERSAL_READ_STATUS, READ_STATUS, READ_ERROR_CODE } from '../read-state/read-state.types';
+import { UNIVERSAL_READ_STATUS, READ_STATUS, READ_ERROR_CODE, READ_OUTCOME } from '../read-state/read-state.types';
 /** `PushChain.CONSTANTS.READ` — cross-chain read state. Values verified against the deployed UniversalCallback. */
 export declare const READ_CONSTANTS: {
     /** Read-only Web2 destination. Equivalent to `CHAIN.WEB2`. */
@@ -16,7 +16,7 @@ export declare const READ_CONSTANTS: {
     readonly CALLBACK_BUDGET_BUFFER: 3;
     readonly REGISTRY_CALLBACK_GAS: 500000n;
     readonly UNIVERSAL_READ_REGISTRY_ADDRESS: {
-        readonly TESTNET_DONUT: "0x91b09DAd1774bAfDE679F9ebB5F9046AE2b928C8";
+        readonly TESTNET_DONUT: "0x00000000000000000000000000000000000000b2";
     };
     readonly WEB2_MAX_EXTRACT_ENTRIES: 16;
     readonly WEB2_DEFAULT_TIMEOUT_MS: 5000;
@@ -25,6 +25,7 @@ export declare const READ_CONSTANTS: {
     readonly STATUS: typeof UNIVERSAL_READ_STATUS;
     readonly RESULT_STATUS: typeof READ_STATUS;
     readonly ERROR_CODE: typeof READ_ERROR_CODE;
+    readonly OUTCOME: typeof READ_OUTCOME;
 };
 export type { MoveableToken, PayableToken, PushChainMoveableToken, ChainSuffixAccessor, UsdcChainSuffixAccessor, PushChainMoveableTokenAccessor, MoveableTokenConstantsMap, PayableTokenConstantsMap, } from './tokens';
 export declare const CONSTANTS: {
@@ -51,7 +52,7 @@ export declare const CONSTANTS: {
         readonly CALLBACK_BUDGET_BUFFER: 3;
         readonly REGISTRY_CALLBACK_GAS: 500000n;
         readonly UNIVERSAL_READ_REGISTRY_ADDRESS: {
-            readonly TESTNET_DONUT: "0x91b09DAd1774bAfDE679F9ebB5F9046AE2b928C8";
+            readonly TESTNET_DONUT: "0x00000000000000000000000000000000000000b2";
         };
         readonly WEB2_MAX_EXTRACT_ENTRIES: 16;
         readonly WEB2_DEFAULT_TIMEOUT_MS: 5000;
@@ -60,6 +61,7 @@ export declare const CONSTANTS: {
         readonly STATUS: typeof UNIVERSAL_READ_STATUS;
         readonly RESULT_STATUS: typeof READ_STATUS;
         readonly ERROR_CODE: typeof READ_ERROR_CODE;
+        readonly OUTCOME: typeof READ_OUTCOME;
     };
 };
 export type { TypedDataDomain, TypedData };

package/src/lib/constants/index.js

@@ -25,6 +25,7 @@ exports.READ_CONSTANTS = {
     STATUS: read_state_types_1.UNIVERSAL_READ_STATUS,
     RESULT_STATUS: read_state_types_1.READ_STATUS,
     ERROR_CODE: read_state_types_1.READ_ERROR_CODE,
+    OUTCOME: read_state_types_1.READ_OUTCOME,
 };
 // NOTE - Only include enums & constants which need to be exported to end user.
 exports.CONSTANTS = {

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

@@ -7,11 +7,11 @@
  */
 /** Hard upper bound on the gas an app callback may declare — `ReadTypes.sol:50`. */
 export declare const MAX_CALLBACK_GAS_LIMIT = 1000000n;
-/** Registry default; large results may need an explicit override up to the maximum. */
+/** Default callback gas (registry and custom targets); large results may need an explicit override up to the maximum. */
 export declare const REGISTRY_CALLBACK_GAS = 500000n;
 /** Verified proxy on Donut. Other networks intentionally have no default receiver. */
 export declare const UNIVERSAL_READ_REGISTRY_ADDRESS: {
-    readonly TESTNET_DONUT: "0x91b09DAd1774bAfDE679F9ebB5F9046AE2b928C8";
+    readonly TESTNET_DONUT: "0x00000000000000000000000000000000000000b2";
 };
 /** Contract rejects anything below this — `ReadTypes.sol:43`. */
 export declare const MIN_CONFIRMATIONS_FLOOR = 1;
@@ -49,5 +49,9 @@ export declare const READ_TRACK_POLL_INTERVAL_MS = 2000;
 export declare const READ_TRACK_MIN_POLL_INTERVAL_MS = 500;
 /** Default `wait()` timeout is `expiryBlocks × PUSH_BLOCK_TIME_MS`, capped here. */
 export declare const READ_TRACK_MAX_TIMEOUT_MS = 180000;
+/** A prepared read older than this is announced stale (READ-TX-102-04) and revalidated against fresh preflight. */
+export declare const READ_PREFLIGHT_STALE_MS = 60000;
+/** `wait()` announces READ-TX-105-04 once this few Push blocks (~40 s) remain before expiry. */
+export declare const READ_EXPIRY_WARNING_BLOCKS = 30n;
 /** How long `trackRead` keeps looking for a record the node has not ingested yet. */
 export declare const READ_TRACK_LOOKUP_TIMEOUT_MS = 30000;

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

@@ -7,14 +7,14 @@
  * `read-state/__tests__/abi-selectors.spec.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.READ_TRACK_LOOKUP_TIMEOUT_MS = exports.READ_TRACK_MAX_TIMEOUT_MS = exports.READ_TRACK_MIN_POLL_INTERVAL_MS = exports.READ_TRACK_POLL_INTERVAL_MS = exports.PUSH_BLOCK_TIME_MS = exports.READ_NAMESPACE = exports.WEB2_DESTINATION = exports.WEB2_MAX_TIMEOUT_MS = exports.WEB2_DEFAULT_TIMEOUT_MS = exports.WEB2_MAX_EXTRACT_ENTRIES = exports.CALLBACK_BUDGET_BUFFER = exports.DEFAULT_EXPIRY_BLOCKS = exports.MIN_CONFIRMATIONS_FLOOR = exports.UNIVERSAL_READ_REGISTRY_ADDRESS = exports.REGISTRY_CALLBACK_GAS = exports.MAX_CALLBACK_GAS_LIMIT = void 0;
+exports.READ_TRACK_LOOKUP_TIMEOUT_MS = exports.READ_EXPIRY_WARNING_BLOCKS = exports.READ_PREFLIGHT_STALE_MS = exports.READ_TRACK_MAX_TIMEOUT_MS = exports.READ_TRACK_MIN_POLL_INTERVAL_MS = exports.READ_TRACK_POLL_INTERVAL_MS = exports.PUSH_BLOCK_TIME_MS = exports.READ_NAMESPACE = exports.WEB2_DESTINATION = exports.WEB2_MAX_TIMEOUT_MS = exports.WEB2_DEFAULT_TIMEOUT_MS = exports.WEB2_MAX_EXTRACT_ENTRIES = exports.CALLBACK_BUDGET_BUFFER = exports.DEFAULT_EXPIRY_BLOCKS = exports.MIN_CONFIRMATIONS_FLOOR = exports.UNIVERSAL_READ_REGISTRY_ADDRESS = exports.REGISTRY_CALLBACK_GAS = exports.MAX_CALLBACK_GAS_LIMIT = void 0;
 /** Hard upper bound on the gas an app callback may declare — `ReadTypes.sol:50`. */
 exports.MAX_CALLBACK_GAS_LIMIT = 1000000n;
-/** Registry default; large results may need an explicit override up to the maximum. */
+/** Default callback gas (registry and custom targets); large results may need an explicit override up to the maximum. */
 exports.REGISTRY_CALLBACK_GAS = 500000n;
 /** Verified proxy on Donut. Other networks intentionally have no default receiver. */
 exports.UNIVERSAL_READ_REGISTRY_ADDRESS = {
-    TESTNET_DONUT: '0x91b09DAd1774bAfDE679F9ebB5F9046AE2b928C8',
+    TESTNET_DONUT: '0x00000000000000000000000000000000000000b2',
 };
 /** Contract rejects anything below this — `ReadTypes.sol:43`. */
 exports.MIN_CONFIRMATIONS_FLOOR = 1;
@@ -54,6 +54,10 @@ exports.READ_TRACK_POLL_INTERVAL_MS = 2_000;
 exports.READ_TRACK_MIN_POLL_INTERVAL_MS = 500;
 /** Default `wait()` timeout is `expiryBlocks × PUSH_BLOCK_TIME_MS`, capped here. */
 exports.READ_TRACK_MAX_TIMEOUT_MS = 180_000;
+/** A prepared read older than this is announced stale (READ-TX-102-04) and revalidated against fresh preflight. */
+exports.READ_PREFLIGHT_STALE_MS = 60_000;
+/** `wait()` announces READ-TX-105-04 once this few Push blocks (~40 s) remain before expiry. */
+exports.READ_EXPIRY_WARNING_BLOCKS = 30n;
 /** How long `trackRead` keeps looking for a record the node has not ingested yet. */
 exports.READ_TRACK_LOOKUP_TIMEOUT_MS = 30_000;
 //# sourceMappingURL=read-state.js.map

package/src/lib/index.d.ts

@@ -14,7 +14,7 @@ export { getCEAAddress, getPushAccountForCEA, isCEA, chainSupportsCEA, chainSupp
 export { encodeSvmExecutePayload, isSvmChain, isValidSolanaHexAddress, buildMigrationPayload, buildErc20WithdrawalMulticall, } from './orchestrator/payload-builders';
 export type { ReadChain, ReadDestination, ResolvedDestination, ReadQuery, EvmReadQuery, SvmReadQuery, Web2ReadQuery, Web2Extract, Web2ValueType, EncodedReadQuery, ReadResultShape, DecodedReadResult, ReadPreflight, ReadSpec, ReadSpecTuple, BuildReadSpecParams, PreparedRead, ReadCallback, SimulateReadResult, ParsedReadRequest, FulfilOutcome, ReceiptLike, ReadRef, ReadLifecycleOptions, ReadFees, UniversalReadResponse, ReadResponseTuple, BatchReadResponse, } from './read-state/read-state.types';
 export type { ReadOptions, ReadPrepareOptions, ReadQueryOptions, ReadCallbackOptions, ReadValue, ValidateReadCall, ReadWeb2Options, ReadTrackOptions, ReadExecuteOptions } from './read-state/read-params';
-export { UNIVERSAL_READ_STATUS, READ_STATUS, READ_ERROR_CODE, CONTRACT_REQUEST_STATUS, TERMINAL_READ_STATUSES, } from './read-state/read-state.types';
+export { UNIVERSAL_READ_STATUS, READ_STATUS, READ_ERROR_CODE, READ_OUTCOME, CONTRACT_REQUEST_STATUS, TERMINAL_READ_STATUSES, } from './read-state/read-state.types';
 export { ReadStateError, InvalidReadQueryError, InvalidReadSpecError, ReadHeightUnavailableError, UnsupportedReadDestinationError, ReadDecodeError, ReadTimeoutError, ReadNotFoundError, ReadRegistryUnavailableError, } from './read-state/errors';
 export type { ReadSpecViolation } from './read-state/errors';
 export { resolveDestination, encodeReadQuery, decodeReadResult, parseReadRequestsFromReceipt, parseFulfilOutcome, buildReadSpecFromPreflight, validateReadSpec, toCallData, sizeCallbackBudget, inferResultShape, toRequestIdHex, toReadQuery, } from './read-state';

package/src/lib/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReadNotFoundError = exports.ReadTimeoutError = exports.ReadDecodeError = exports.UnsupportedReadDestinationError = exports.ReadHeightUnavailableError = exports.InvalidReadSpecError = exports.InvalidReadQueryError = exports.ReadStateError = exports.TERMINAL_READ_STATUSES = exports.CONTRACT_REQUEST_STATUS = exports.READ_ERROR_CODE = exports.READ_STATUS = exports.UNIVERSAL_READ_STATUS = exports.buildErc20WithdrawalMulticall = exports.buildMigrationPayload = exports.isValidSolanaHexAddress = exports.isSvmChain = exports.encodeSvmExecutePayload = exports.getAllCEAAddresses = exports.getCEAFactoryAddress = exports.chainSupportsOutbound = exports.chainSupportsCEA = exports.isCEA = exports.getPushAccountForCEA = exports.getCEAAddress = exports.quoteMaxPCForGasCapFromNativeValue = exports.quoteMaxPCForGasCap = exports.MAX_PC_FOR_GAS_BUFFER_BPS_LIMIT = exports.DEFAULT_MAX_PC_FOR_GAS_BUFFER_BPS = exports.isChainTarget = exports.detectRoute = exports.TransactionRoute = exports.parseUEAVersion = exports.PC20UnsafeEmptyPayloadError = exports.PC20ExportRevertedError = exports.PC20WrapperPredictionUnavailableError = exports.PC20UnknownChainNamespaceError = exports.InsufficientPC20BalanceError = exports.UnsupportedPC20DestinationError = exports.PC20AmbiguousAddressError = exports.PC20ExpectedButPRC20Error = exports.InvalidPC20MetadataError = exports.PC20FactoryMismatchError = exports.PC20RegistryMismatchError = exports.PC20WrapperNotRegisteredError = exports.PC20TokenChainMismatchError = exports.InvalidPC20AddressError = exports.PC20Error = exports.isPC20Reference = exports.CHAIN = void 0;
-exports.PushChain = exports.UNIVERSAL_READ_REGISTRY_EVM = exports.UNIVERSAL_CALLBACK_EVM = exports.toReadQuery = exports.toRequestIdHex = exports.inferResultShape = exports.sizeCallbackBudget = exports.toCallData = exports.validateReadSpec = exports.buildReadSpecFromPreflight = exports.parseFulfilOutcome = exports.parseReadRequestsFromReceipt = exports.decodeReadResult = exports.encodeReadQuery = exports.resolveDestination = exports.ReadRegistryUnavailableError = void 0;
+exports.ReadTimeoutError = exports.ReadDecodeError = exports.UnsupportedReadDestinationError = exports.ReadHeightUnavailableError = exports.InvalidReadSpecError = exports.InvalidReadQueryError = exports.ReadStateError = exports.TERMINAL_READ_STATUSES = exports.CONTRACT_REQUEST_STATUS = exports.READ_OUTCOME = exports.READ_ERROR_CODE = exports.READ_STATUS = exports.UNIVERSAL_READ_STATUS = exports.buildErc20WithdrawalMulticall = exports.buildMigrationPayload = exports.isValidSolanaHexAddress = exports.isSvmChain = exports.encodeSvmExecutePayload = exports.getAllCEAAddresses = exports.getCEAFactoryAddress = exports.chainSupportsOutbound = exports.chainSupportsCEA = exports.isCEA = exports.getPushAccountForCEA = exports.getCEAAddress = exports.quoteMaxPCForGasCapFromNativeValue = exports.quoteMaxPCForGasCap = exports.MAX_PC_FOR_GAS_BUFFER_BPS_LIMIT = exports.DEFAULT_MAX_PC_FOR_GAS_BUFFER_BPS = exports.isChainTarget = exports.detectRoute = exports.TransactionRoute = exports.parseUEAVersion = exports.PC20UnsafeEmptyPayloadError = exports.PC20ExportRevertedError = exports.PC20WrapperPredictionUnavailableError = exports.PC20UnknownChainNamespaceError = exports.InsufficientPC20BalanceError = exports.UnsupportedPC20DestinationError = exports.PC20AmbiguousAddressError = exports.PC20ExpectedButPRC20Error = exports.InvalidPC20MetadataError = exports.PC20FactoryMismatchError = exports.PC20RegistryMismatchError = exports.PC20WrapperNotRegisteredError = exports.PC20TokenChainMismatchError = exports.InvalidPC20AddressError = exports.PC20Error = exports.isPC20Reference = exports.CHAIN = void 0;
+exports.PushChain = exports.UNIVERSAL_READ_REGISTRY_EVM = exports.UNIVERSAL_CALLBACK_EVM = exports.toReadQuery = exports.toRequestIdHex = exports.inferResultShape = exports.sizeCallbackBudget = exports.toCallData = exports.validateReadSpec = exports.buildReadSpecFromPreflight = exports.parseFulfilOutcome = exports.parseReadRequestsFromReceipt = exports.decodeReadResult = exports.encodeReadQuery = exports.resolveDestination = exports.ReadRegistryUnavailableError = exports.ReadNotFoundError = void 0;
 const push_chain_1 = require("./push-chain/push-chain");
 Object.defineProperty(exports, "PushChain", { enumerable: true, get: function () { return push_chain_1.PushChain; } });
 var enums_1 = require("./constants/enums");
@@ -58,6 +58,7 @@ var read_state_types_1 = require("./read-state/read-state.types");
 Object.defineProperty(exports, "UNIVERSAL_READ_STATUS", { enumerable: true, get: function () { return read_state_types_1.UNIVERSAL_READ_STATUS; } });
 Object.defineProperty(exports, "READ_STATUS", { enumerable: true, get: function () { return read_state_types_1.READ_STATUS; } });
 Object.defineProperty(exports, "READ_ERROR_CODE", { enumerable: true, get: function () { return read_state_types_1.READ_ERROR_CODE; } });
+Object.defineProperty(exports, "READ_OUTCOME", { enumerable: true, get: function () { return read_state_types_1.READ_OUTCOME; } });
 Object.defineProperty(exports, "CONTRACT_REQUEST_STATUS", { enumerable: true, get: function () { return read_state_types_1.CONTRACT_REQUEST_STATUS; } });
 Object.defineProperty(exports, "TERMINAL_READ_STATUSES", { enumerable: true, get: function () { return read_state_types_1.TERMINAL_READ_STATUSES; } });
 var errors_2 = require("./read-state/errors");

package/src/lib/progress-hook/progress-hook.js

@@ -1058,6 +1058,27 @@ const RAW_HOOKS_READ = {
         response: { txHash, requestId, logIndex },
         level: 'SUCCESS',
     }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_03]: (ref) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_03,
+        title: 'Looking Up Request',
+        message: `Looking up ${'requestId' in ref ? `read ${ref.requestId}` : `reads in ${ref.txHash}`} on Push Chain`,
+        response: { ...ref },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_04]: (requestId, status) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_04,
+        title: 'Request Found',
+        message: `Read ${requestId} found (status ${status})`,
+        response: { requestId, status },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_05]: (ref, elapsedMs) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_05,
+        title: 'Request Not Found',
+        message: `No read found for ${'requestId' in ref ? ref.requestId : ref.txHash} after ${Math.round(elapsedMs / 1000)}s`,
+        response: { ...ref, elapsedMs },
+        level: 'ERROR',
+    }),
     [progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_01]: (requestId) => ({
         id: progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_01,
         title: 'Awaiting Quorum',

package/src/lib/progress-hook/progress-hook.types.d.ts

@@ -106,6 +106,9 @@ export declare enum PROGRESS_HOOK {
     READ_TX_103_03 = "READ-TX-103-03",
     READ_TX_104_01 = "READ-TX-104-01",
     READ_TX_104_02 = "READ-TX-104-02",
+    READ_TX_104_03 = "READ-TX-104-03",
+    READ_TX_104_04 = "READ-TX-104-04",
+    READ_TX_104_05 = "READ-TX-104-05",
     READ_TX_105_01 = "READ-TX-105-01",
     READ_TX_105_02 = "READ-TX-105-02",
     READ_TX_105_03 = "READ-TX-105-03",
@@ -138,5 +141,5 @@ export type PROGRESS_HOOK_R2 = PROGRESS_HOOK.SEND_TX_201 | PROGRESS_HOOK.SEND_TX
 export type PROGRESS_HOOK_R3 = PROGRESS_HOOK.SEND_TX_301 | PROGRESS_HOOK.SEND_TX_302_01 | PROGRESS_HOOK.SEND_TX_302_02 | PROGRESS_HOOK.SEND_TX_303_01 | PROGRESS_HOOK.SEND_TX_303_02 | PROGRESS_HOOK.SEND_TX_303_03_01 | PROGRESS_HOOK.SEND_TX_303_03_02 | PROGRESS_HOOK.SEND_TX_303_03_03 | PROGRESS_HOOK.SEND_TX_303_04 | PROGRESS_HOOK.SEND_TX_303_05 | PROGRESS_HOOK.SEND_TX_303_06 | PROGRESS_HOOK.SEND_TX_304_01 | PROGRESS_HOOK.SEND_TX_304_02 | PROGRESS_HOOK.SEND_TX_304_03 | PROGRESS_HOOK.SEND_TX_304_04 | PROGRESS_HOOK.SEND_TX_307 | PROGRESS_HOOK.SEND_TX_309_01 | PROGRESS_HOOK.SEND_TX_309_02 | PROGRESS_HOOK.SEND_TX_309_03 | PROGRESS_HOOK.SEND_TX_310_01 | PROGRESS_HOOK.SEND_TX_310_02 | PROGRESS_HOOK.SEND_TX_399_01 | PROGRESS_HOOK.SEND_TX_399_02 | PROGRESS_HOOK.SEND_TX_399_03 | PROGRESS_HOOK.SEND_TX_399_99;
 export type PROGRESS_HOOK_MULTICHAIN = PROGRESS_HOOK.SEND_TX_001 | PROGRESS_HOOK.SEND_TX_002_01 | PROGRESS_HOOK.SEND_TX_002_99_99 | PROGRESS_HOOK.SEND_TX_003_03 | PROGRESS_HOOK.SEND_TX_003_04 | PROGRESS_HOOK.SEND_TX_003_05 | PROGRESS_HOOK.SEND_TX_999_01 | PROGRESS_HOOK.SEND_TX_999_02 | PROGRESS_HOOK.SEND_TX_999_03;
 export type PROGRESS_HOOK_MIG = PROGRESS_HOOK.UEA_MIG_01 | PROGRESS_HOOK.UEA_MIG_02 | PROGRESS_HOOK.UEA_MIG_03 | PROGRESS_HOOK.UEA_MIG_9901 | PROGRESS_HOOK.UEA_MIG_9902 | PROGRESS_HOOK.UEA_MIG_9903;
-export type PROGRESS_HOOK_READ = PROGRESS_HOOK.READ_TX_101 | PROGRESS_HOOK.READ_TX_102_01 | PROGRESS_HOOK.READ_TX_102_02 | PROGRESS_HOOK.READ_TX_102_03 | PROGRESS_HOOK.READ_TX_102_04 | PROGRESS_HOOK.READ_TX_102_05 | PROGRESS_HOOK.READ_TX_103_01 | PROGRESS_HOOK.READ_TX_103_02 | PROGRESS_HOOK.READ_TX_103_03 | PROGRESS_HOOK.READ_TX_104_01 | PROGRESS_HOOK.READ_TX_104_02 | PROGRESS_HOOK.READ_TX_105_01 | PROGRESS_HOOK.READ_TX_105_02 | PROGRESS_HOOK.READ_TX_105_03 | PROGRESS_HOOK.READ_TX_105_04 | PROGRESS_HOOK.READ_TX_106_01 | PROGRESS_HOOK.READ_TX_106_02 | PROGRESS_HOOK.READ_TX_106_03 | PROGRESS_HOOK.READ_TX_106_04 | PROGRESS_HOOK.READ_TX_106_05 | PROGRESS_HOOK.READ_TX_106_06 | PROGRESS_HOOK.READ_TX_199_01 | PROGRESS_HOOK.READ_TX_199_02 | PROGRESS_HOOK.READ_TX_199_03 | PROGRESS_HOOK.READ_TX_199_99 | PROGRESS_HOOK.READ_TX_001 | PROGRESS_HOOK.READ_TX_002_01 | PROGRESS_HOOK.READ_TX_002_99_99 | PROGRESS_HOOK.READ_TX_999_01 | PROGRESS_HOOK.READ_TX_999_02 | PROGRESS_HOOK.READ_TX_999_03;
+export type PROGRESS_HOOK_READ = PROGRESS_HOOK.READ_TX_101 | PROGRESS_HOOK.READ_TX_102_01 | PROGRESS_HOOK.READ_TX_102_02 | PROGRESS_HOOK.READ_TX_102_03 | PROGRESS_HOOK.READ_TX_102_04 | PROGRESS_HOOK.READ_TX_102_05 | PROGRESS_HOOK.READ_TX_103_01 | PROGRESS_HOOK.READ_TX_103_02 | PROGRESS_HOOK.READ_TX_103_03 | PROGRESS_HOOK.READ_TX_104_01 | PROGRESS_HOOK.READ_TX_104_02 | PROGRESS_HOOK.READ_TX_104_03 | PROGRESS_HOOK.READ_TX_104_04 | PROGRESS_HOOK.READ_TX_104_05 | PROGRESS_HOOK.READ_TX_105_01 | PROGRESS_HOOK.READ_TX_105_02 | PROGRESS_HOOK.READ_TX_105_03 | PROGRESS_HOOK.READ_TX_105_04 | PROGRESS_HOOK.READ_TX_106_01 | PROGRESS_HOOK.READ_TX_106_02 | PROGRESS_HOOK.READ_TX_106_03 | PROGRESS_HOOK.READ_TX_106_04 | PROGRESS_HOOK.READ_TX_106_05 | PROGRESS_HOOK.READ_TX_106_06 | PROGRESS_HOOK.READ_TX_199_01 | PROGRESS_HOOK.READ_TX_199_02 | PROGRESS_HOOK.READ_TX_199_03 | PROGRESS_HOOK.READ_TX_199_99 | PROGRESS_HOOK.READ_TX_001 | PROGRESS_HOOK.READ_TX_002_01 | PROGRESS_HOOK.READ_TX_002_99_99 | PROGRESS_HOOK.READ_TX_999_01 | PROGRESS_HOOK.READ_TX_999_02 | PROGRESS_HOOK.READ_TX_999_03;
 export {};

package/src/lib/progress-hook/progress-hook.types.js

@@ -117,6 +117,9 @@ var PROGRESS_HOOK;
     PROGRESS_HOOK["READ_TX_103_03"] = "READ-TX-103-03";
     PROGRESS_HOOK["READ_TX_104_01"] = "READ-TX-104-01";
     PROGRESS_HOOK["READ_TX_104_02"] = "READ-TX-104-02";
+    PROGRESS_HOOK["READ_TX_104_03"] = "READ-TX-104-03";
+    PROGRESS_HOOK["READ_TX_104_04"] = "READ-TX-104-04";
+    PROGRESS_HOOK["READ_TX_104_05"] = "READ-TX-104-05";
     PROGRESS_HOOK["READ_TX_105_01"] = "READ-TX-105-01";
     PROGRESS_HOOK["READ_TX_105_02"] = "READ-TX-105-02";
     PROGRESS_HOOK["READ_TX_105_03"] = "READ-TX-105-03";

package/src/lib/push-chain/push-chain.d.ts

@@ -48,7 +48,7 @@ export declare class PushChain {
             readonly CALLBACK_BUDGET_BUFFER: 3;
             readonly REGISTRY_CALLBACK_GAS: 500000n;
             readonly UNIVERSAL_READ_REGISTRY_ADDRESS: {
-                readonly TESTNET_DONUT: "0x91b09DAd1774bAfDE679F9ebB5F9046AE2b928C8";
+                readonly TESTNET_DONUT: "0x00000000000000000000000000000000000000b2";
             };
             readonly WEB2_MAX_EXTRACT_ENTRIES: 16;
             readonly WEB2_DEFAULT_TIMEOUT_MS: 5000;
@@ -57,6 +57,7 @@ export declare class PushChain {
             readonly STATUS: typeof import("../read-state/read-state.types").UNIVERSAL_READ_STATUS;
             readonly RESULT_STATUS: typeof import("../read-state/read-state.types").READ_STATUS;
             readonly ERROR_CODE: typeof import("../read-state/read-state.types").READ_ERROR_CODE;
+            readonly OUTCOME: typeof import("../read-state/read-state.types").READ_OUTCOME;
         };
     };
     /**

package/src/lib/push-chain/push-chain.js

@@ -120,7 +120,7 @@ class PushChain {
             },
             // Only read()/executeReads() send transactions; prepare/simulate/track remain read-only.
             read: async (subject, options) => {
-                const params = (0, read_params_1.toBuildReadSpecParams)(subject, options, orchestrator.getNetwork());
+                const params = await (0, read_params_1.resolveReadSpecParams)(subject, options, orchestrator.getNetwork(), orchestrator.getRpcUrls());
                 (0, read_executor_1.assertRequestEntrypoint)(params.callback, 'read');
                 if (this.isReadMode)
                     throw new Error('Read only mode cannot call read function');
@@ -128,8 +128,9 @@ class PushChain {
                 const { reads: [response] } = await (0, read_executor_1.executeReads)(orchestrator, [prepared], options);
                 return response;
             },
-            prepareRead: (subject, options) => {
-                return orchestrator.prepareRead.bind(orchestrator)((0, read_params_1.toBuildReadSpecParams)(subject, options, orchestrator.getNetwork()));
+            prepareRead: async (subject, options) => {
+                const params = await (0, read_params_1.resolveReadSpecParams)(subject, options, orchestrator.getNetwork(), orchestrator.getRpcUrls());
+                return orchestrator.prepareRead(params);
             },
             executeReads: (async (reads, options) => {
                 reads.forEach((r) => (0, read_executor_1.assertRequestEntrypoint)(r.callback));

package/src/lib/push-client/push-client.d.ts

@@ -54,6 +54,13 @@ export declare class PushClient extends EvmClient {
      */
     private readonly archiveTendermintRpc;
     private readonly archivePublicClient?;
+    /**
+     * Prune endpoints with transport retries off, raced against the archive. A
+     * receipt miss on the prune node answers -32002 "Requested resource not
+     * available" after ~8 s (measured on Donut 2026-09-23), and the shared
+     * client's `http({ retryCount: 5 })` would retry that on top.
+     */
+    private readonly pruneProbeClient?;
     constructor(clientOptions: PushClientOptions);
     /**
      * Executes an operation with automatic fallback to next RPC endpoint on failure.

package/src/lib/push-client/push-client.js

@@ -48,6 +48,13 @@ class PushClient extends evm_client_1.EvmClient {
      */
     archiveTendermintRpc;
     archivePublicClient;
+    /**
+     * Prune endpoints with transport retries off, raced against the archive. A
+     * receipt miss on the prune node answers -32002 "Requested resource not
+     * available" after ~8 s (measured on Donut 2026-09-23), and the shared
+     * client's `http({ retryCount: 5 })` would retry that on top.
+     */
+    pruneProbeClient;
     constructor(clientOptions) {
         const pushChainKey = pushNetworkToChain(clientOptions.network);
         const chain = clientOptions.chain ?? (0, chain_1.getPushViemChain)(pushChainKey);
@@ -66,6 +73,10 @@ class PushClient extends evm_client_1.EvmClient {
                 chain,
                 transport: (0, viem_1.fallback)(archiveEvmUrls.map((url) => (0, viem_1.http)(url, { retryCount: 5, retryDelay: 500 }))),
             });
+            this.pruneProbeClient = (0, viem_1.createPublicClient)({
+                chain,
+                transport: (0, viem_1.fallback)(clientOptions.rpcUrls.map((url) => (0, viem_1.http)(url, { retryCount: 0 }))),
+            });
         }
         this.ephemeralKey = (0, accounts_1.generatePrivateKey)();
         this.ephemeralAccount = (0, accounts_1.privateKeyToAccount)(this.ephemeralKey);
@@ -357,17 +368,20 @@ class PushClient extends evm_client_1.EvmClient {
      * no EVM-indexed tx or receipt. Attribute values are plain strings.
      */
     async getBlockResultEvents(height) {
-        return this.executeWithRpcFallback(async (rpcUrl) => {
+        // Prune nodes drop old heights ("height N is not available"); the archive keeps them.
+        return this.executeWithArchiveFallback(async (rpcUrl) => {
             const url = `${rpcUrl.replace(/\/+$/, '')}/block_results?height=${height}`;
             const res = await fetch(url);
-            if (!res.ok)
-                throw new Error(`HTTP request failed: ${res.status} ${url}`);
-            const body = (await res.json());
-            if (body.error)
+            // CometBFT answers a pruned height with HTTP 500 plus a JSON-RPC error. Surface that
+            // error so it reads as a definite miss (→ archive), not a transient HTTP failure to retry.
+            const body = (await res.json().catch(() => undefined));
+            if (body?.error)
                 throw new Error(`block_results ${height}: ${body.error.data ?? body.error.message ?? 'error'}`);
+            if (!res.ok || !body)
+                throw new Error(`HTTP request failed: ${res.status} ${url}`);
             const events = body.result?.finalize_block_events ?? body.result?.end_block_events ?? [];
             return events;
-        }, 'getBlockResultEvents');
+        }, 'getBlockResultEvents', () => false);
     }
     /**
      * Queries x/ucallback for every read a Push transaction requested. One tx can emit
@@ -479,17 +493,29 @@ class PushClient extends evm_client_1.EvmClient {
      * Prune first; on not-found, retry the archive EVM client if configured.
      */
     async getTransactionReceiptWithArchiveFallback(txHash) {
-        try {
-            return await this.publicClient.getTransactionReceipt({ hash: txHash });
-        }
-        catch (error) {
-            if (!this.hasArchiveEvm)
-                throw error;
-            return this.archivePublicClient.getTransactionReceipt({
-                hash: txHash,
-            });
+        if (!this.hasArchiveEvm || !this.pruneProbeClient) {
+            return this.publicClient.getTransactionReceipt({ hash: txHash });
         }
+        // Race prune and archive; the first receipt wins. A pruned receipt costs one
+        // archive round trip, a fresh one the prune round trip (if the archive lags).
+        const prune = this.pruneProbeClient.getTransactionReceipt({ hash: txHash });
+        const archive = this.archivePublicClient.getTransactionReceipt({
+            hash: txHash,
+        });
+        return firstFulfilled([archive, prune]);
     }
 }
 exports.PushClient = PushClient;
+/** First promise to resolve; if all reject, the last rejection. */
+function firstFulfilled(promises) {
+    return new Promise((resolve, reject) => {
+        let pending = promises.length;
+        for (const p of promises) {
+            p.then(resolve, (error) => {
+                if (--pending === 0)
+                    reject(error);
+            });
+        }
+    });
+}
 //# sourceMappingURL=push-client.js.map

package/src/lib/read-state/envelopes/evm.js

@@ -104,9 +104,8 @@ function encodeEvmQueryEnvelope(query, options) {
                 if (!item || item.type !== 'function') {
                     throw new errors_1.InvalidReadQueryError(`function not found in abi: ${query.functionName}`);
                 }
-                if (item.stateMutability !== 'view' && item.stateMutability !== 'pure') {
-                    throw new errors_1.InvalidReadQueryError(`${query.functionName} is ${item.stateMutability}; reads must target view/pure functions`);
-                }
+                // Any mutability: validators run the call as an eth_call simulation at the
+                // pinned block, so nonpayable/payable functions return data and never execute.
                 callData = (0, viem_1.encodeFunctionData)({
                     abi: query.abi,
                     functionName: query.functionName,

package/src/lib/read-state/envelopes/svm.js

@@ -11,6 +11,7 @@ const bs58_1 = tslib_1.__importDefault(require("bs58"));
 const viem_1 = require("viem");
 const read_state_1 = require("../../constants/read-state");
 const errors_1 = require("../errors");
+const svm_account_1 = require("../svm-account");
 /** `universalClient/externalchains/svm/read_envelope.go` — solanaQueryType. */
 exports.SVM_QUERY_TYPE = {
     LAMPORT_BALANCE: 0,
@@ -83,7 +84,16 @@ function encodeSvmQueryEnvelope(query, options = {}) {
             break;
         case 'rawAccountData':
             queryType = exports.SVM_QUERY_TYPE.RAW_ACCOUNT_DATA;
-            resultShape = { kind: 'raw' };
+            if (query.idl !== undefined) {
+                (0, svm_account_1.validateIdl)(query.idl);
+                const accountName = query.accountName === undefined ? undefined : (0, svm_account_1.resolveAccountName)(query.idl, query.accountName);
+                resultShape = accountName === undefined ? { kind: 'svmAccount', idl: query.idl } : { kind: 'svmAccount', idl: query.idl, accountName };
+            }
+            else if (query.accountName !== undefined) {
+                throw new errors_1.InvalidReadQueryError('accountName needs idl');
+            }
+            else
+                resultShape = { kind: 'raw' };
             break;
         default:
             throw new errors_1.InvalidReadQueryError(`unknown SVM query type: ${query.type}`);

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

@@ -11,6 +11,7 @@ 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");
+const read_state_1 = require("../constants/read-state");
 /**
  * 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
@@ -58,6 +59,9 @@ async function executeReads(deps, reads, options = {}) {
             failedAt = i + 1;
             if (batch)
                 emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_002_01, i + 1, reads.length, prepared.preflight.destination.caip2);
+            const ageMs = Date.now() - prepared.preflight.fetchedAt;
+            if (ageMs > read_state_1.READ_PREFLIGHT_STALE_MS)
+                emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_04, prepared.preflight.fetchedAt, ageMs);
             await deps.revalidateRead(prepared);
         }
         failedAt = 0;