@pushchain/core 6.0.24 → 6.0.26

package/CHANGELOG.md

@@ -1,3 +1,153 @@
+@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
+- feat: align read-state API with v3 review
+- test: consolidate read-state e2e harnesses
+- feat: integrate universal read registry
+- fix: harden gasless and cross-chain transaction handling
+- feat: align read-state API with v2 spec
+- fix: validate prepared reads and infer typed results
+- fix: preserve read-state recovery and expand test coverage
+- feat: read-state PR7 — custom-receiver read() / executeReads(), review fixes
+- feat: read-state PR6 — live e2e tree, CI `read` group, wait() option fix
+- feat: read-state PR5 — public universal surface, CONSTANTS.READ, exports
+- feat: read-state PR4 — trackRead, wait/refresh, READ-TX progress band
+- feat: prepareRead — validated ReadSpec builder, refundTo default, simulate
+- feat: read-state chain client — ucallback queries, preflight, budget sizing
+- feat: read-state foundation — envelopes, decoders, ucallback codecs, ABIs, constants
+
+---
+
+@pushchain/core (unreleased)
+
+Changes merged on 2026-09-16: [#265](https://github.com/pushchain/push-chain-sdk/pull/265), [#266](https://github.com/pushchain/push-chain-sdk/pull/266).
+
+### Added
+
+- Added Universal Read through `client.universal.read()`, `prepareRead()`,
+  `executeReads()`, and `trackRead()`. Supports EVM native/token balances, typed
+  contract calls and storage slots; Solana native/token balances, including
+  Token-2022; and HTTPS JSON extraction through `CHAIN.WEB2`.
+- Integrated the canonical UniversalReadRegistry on Donut. Reads use it by default
+  with 500,000 callback gas, configurable up to 1,000,000. Custom application
+  receivers use `callback: { target, gasLimit, abi, functionName, args? }`.
+  Other networks require an explicitly configured application receiver.
+- Added typed read results, resumable tracking by transaction hash or request ID,
+  ordered batch results, and `READ-TX-*` progress events. Read responses report
+  callback delivery/failure separately from consensus status, plus protocol fees,
+  callback budget, gas burned and observed refunds.
+- Added live read-state E2E coverage for EVM, Solana, Web2, registry storage,
+  UEA/CEA execution, batching, callback reverts, expiry and recovery, plus an
+  offline compatibility-check command: `node scripts/check-read-state-drift.mjs`.
+
+### Improved
+
+- Validate read query options and ABI argument/result types, including overloaded
+  functions. Revalidate prepared reads against current chain state before sending
+  without changing their query, block pin, expiry or payment.
+- Calculate default read polling timeouts from remaining Push blocks plus a
+  10-second observation margin, capped at 180 seconds and recalculated on resume.
+  Explicit timeouts take precedence; a client timeout does not cancel the request.
+- Preserve mined transaction hashes and any pending transaction hash when a
+  sequential batch fails, so callers can recover completed calls and check an
+  uncertain broadcast before resubmitting. Read-batch mismatches also retain all
+  transaction hashes.
+
+### Fixed
+
+- Confirm expired-read refunds from Cosmos EndBlock events across execution-attempt
+  heights. Missing blocks or unrelated malformed logs no longer hide valid refund
+  evidence; unknown refund amounts are not assumed to have been paid.
+- Respect the on-chain gasless transaction gas limit for `MsgExecutePayload`,
+  bounded by the SDK's 100-million-gas ceiling, with a cached query and fallback
+  when chain parameters are unavailable.
+- Estimate gas for empty-calldata native transfers to contracts and EIP-7702
+  delegated accounts instead of assuming 21,000 gas. Explicit gas overrides remain
+  supported.
+- Surface reverted Push transaction receipts as execution failures.
+- Decode Solana gateway events from Anchor `emit_cpi!` inner instructions while
+  retaining support for older log events. Use the gateway event index consistently
+  for transaction detection, PC20 tracking and child inbounds, and update the
+  bundled gateway IDL.
+- Resolve the destination SPL mint before calculating Solana account rent for
+  outbound transfers and cascades.
+
+### Read State notes
+
+- `FULFILLED` alone does not prove a usable result: check `raw.status` and
+  `callbackDelivered`. Terminal read failures resolve as statuses; validation,
+  transaction, RPC and timeout errors can still reject.
+- Registry query-key and storage-lookup helpers are internal. Prepared reads retain
+  `queryKey`; direct storage lookups use the exported registry ABI.
+
+---
+
 @pushchain/core@6.0.23 (2026-09-01)
 
 - docs: changelog entry for the EVM PC20 burn routing fix

package/package.json

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

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

@@ -15,3 +15,4 @@ export { UEA_FACTORY_ABI } from './uea-factory';
 export { PC20_FACTORY_EVM, PC20_WRAPPER_EVM, EXTERNAL_GATEWAY_PC20_EVM, VAULT_PC20_FACTORY_EVM, } from './pc20.evm';
 export { WPC_EVM } from './wpc.evm';
 export { UNIV3_SWAP_ROUTER_EVM } from './uniswap-v3-router.evm';
+export { UNIVERSAL_CALLBACK_EVM } from './universalCallback.evm';

package/src/lib/constants/abi/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UNIV3_SWAP_ROUTER_EVM = exports.WPC_EVM = exports.VAULT_PC20_FACTORY_EVM = exports.EXTERNAL_GATEWAY_PC20_EVM = exports.PC20_WRAPPER_EVM = exports.PC20_FACTORY_EVM = exports.UEA_FACTORY_ABI = exports.UNIVERSAL_CORE_EVM = exports.UNIVERSAL_GATEWAY_PC = exports.CEA_FACTORY_EVM = exports.CEA_EVM = exports.SVM_GATEWAY_IDL = exports.ERC20_EVM = exports.UNIVERSAL_GATEWAY_V1_SEND = exports.UNIVERSAL_GATEWAY_V0 = exports.UEA_SVM = exports.UEA_EVM = exports.FACTORY_V1 = exports.FEE_LOCKER_SVM = exports.FEE_LOCKER_EVM = void 0;
+exports.UNIVERSAL_CALLBACK_EVM = exports.UNIV3_SWAP_ROUTER_EVM = exports.WPC_EVM = exports.VAULT_PC20_FACTORY_EVM = exports.EXTERNAL_GATEWAY_PC20_EVM = exports.PC20_WRAPPER_EVM = exports.PC20_FACTORY_EVM = exports.UEA_FACTORY_ABI = exports.UNIVERSAL_CORE_EVM = exports.UNIVERSAL_GATEWAY_PC = exports.CEA_FACTORY_EVM = exports.CEA_EVM = exports.SVM_GATEWAY_IDL = exports.ERC20_EVM = exports.UNIVERSAL_GATEWAY_V1_SEND = exports.UNIVERSAL_GATEWAY_V0 = exports.UEA_SVM = exports.UEA_EVM = exports.FACTORY_V1 = exports.FEE_LOCKER_SVM = exports.FEE_LOCKER_EVM = void 0;
 const tslib_1 = require("tslib");
 var feeLocker_evm_1 = require("./feeLocker.evm");
 Object.defineProperty(exports, "FEE_LOCKER_EVM", { enumerable: true, get: function () { return feeLocker_evm_1.FEE_LOCKER_EVM; } });
@@ -42,4 +42,7 @@ var wpc_evm_1 = require("./wpc.evm");
 Object.defineProperty(exports, "WPC_EVM", { enumerable: true, get: function () { return wpc_evm_1.WPC_EVM; } });
 var uniswap_v3_router_evm_1 = require("./uniswap-v3-router.evm");
 Object.defineProperty(exports, "UNIV3_SWAP_ROUTER_EVM", { enumerable: true, get: function () { return uniswap_v3_router_evm_1.UNIV3_SWAP_ROUTER_EVM; } });
+// Read state (cross-chain reads)
+var universalCallback_evm_1 = require("./universalCallback.evm");
+Object.defineProperty(exports, "UNIVERSAL_CALLBACK_EVM", { enumerable: true, get: function () { return universalCallback_evm_1.UNIVERSAL_CALLBACK_EVM; } });
 //# sourceMappingURL=index.js.map

package/src/lib/constants/abi/prc20.evm.d.ts

@@ -430,4 +430,36 @@ export declare const UNIVERSAL_CORE_EVM: readonly [{
     readonly type: "error";
     readonly name: "NonDigitCharacter";
     readonly inputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "chainHeightByChainNamespace";
+    readonly inputs: readonly [{
+        readonly name: "chainNamespace";
+        readonly type: "string";
+        readonly internalType: "string";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "readBaseFeeByChainNamespace";
+    readonly inputs: readonly [{
+        readonly name: "chainNamespace";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "chainId";
+        readonly type: "string";
+        readonly internalType: "string";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly stateMutability: "view";
 }];

package/src/lib/constants/abi/prc20.evm.js

@@ -217,5 +217,25 @@ exports.UNIVERSAL_CORE_EVM = [
     { type: 'error', name: 'TransferFailed', inputs: [] },
     { type: 'error', name: 'EmptyString', inputs: [] },
     { type: 'error', name: 'NonDigitCharacter', inputs: [] },
+    // ---- read state (verified against UniversalCore @ 0x…C0 on Donut, 2026-09-09) ----
+    {
+        type: 'function',
+        name: 'chainHeightByChainNamespace',
+        // NOTE: despite the parameter name, the oracle keys this by the FULL CAIP-2 id
+        // ("eip155:11155111"), not the bare namespace. The SDK always passes CAIP-2.
+        inputs: [{ name: 'chainNamespace', type: 'string', internalType: 'string' }],
+        outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+        stateMutability: 'view',
+    },
+    {
+        type: 'function',
+        name: 'readBaseFeeByChainNamespace',
+        inputs: [
+            { name: 'chainNamespace', type: 'string', internalType: 'string' },
+            { name: 'chainId', type: 'string', internalType: 'string' },
+        ],
+        outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+        stateMutability: 'view',
+    },
 ];
 //# sourceMappingURL=prc20.evm.js.map

package/src/lib/constants/abi/uea-factory.d.ts

@@ -27,4 +27,35 @@ export declare const UEA_FACTORY_ABI: readonly [{
         readonly internalType: "address";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "getOriginForUEA";
+    readonly inputs: readonly [{
+        readonly name: "addr";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "account";
+        readonly type: "tuple";
+        readonly internalType: "struct UniversalAccountId";
+        readonly components: readonly [{
+            readonly name: "chainNamespace";
+            readonly type: "string";
+            readonly internalType: "string";
+        }, {
+            readonly name: "chainId";
+            readonly type: "string";
+            readonly internalType: "string";
+        }, {
+            readonly name: "owner";
+            readonly type: "bytes";
+            readonly internalType: "bytes";
+        }];
+    }, {
+        readonly name: "isUEA";
+        readonly type: "bool";
+        readonly internalType: "bool";
+    }];
+    readonly stateMutability: "view";
 }];

package/src/lib/constants/abi/uea-factory.js

@@ -21,5 +21,24 @@ exports.UEA_FACTORY_ABI = [
         outputs: [{ name: '', type: 'address', internalType: 'address' }],
         stateMutability: 'view',
     },
+    {
+        type: 'function',
+        name: 'getOriginForUEA',
+        inputs: [{ name: 'addr', type: 'address', internalType: 'address' }],
+        outputs: [
+            {
+                name: 'account',
+                type: 'tuple',
+                internalType: 'struct UniversalAccountId',
+                components: [
+                    { name: 'chainNamespace', type: 'string', internalType: 'string' },
+                    { name: 'chainId', type: 'string', internalType: 'string' },
+                    { name: 'owner', type: 'bytes', internalType: 'bytes' },
+                ],
+            },
+            { name: 'isUEA', type: 'bool', internalType: 'bool' },
+        ],
+        stateMutability: 'view',
+    },
 ];
 //# sourceMappingURL=uea-factory.js.map