@pushchain/core 6.0.25 → 6.0.27-alpha.0

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

@@ -10,6 +10,24 @@ import type { PreparedUniversalTx, CascadedTxResponse, CascadeExecutionOptions }
 import type { Hex } from 'viem';
 import type { BatchReadResponse, PreparedRead, UniversalReadResponse } from '../read-state/read-state.types';
 import { type ReadOptions, type ReadPrepareOptions, type ReadValue, type ValidateReadCall, type ReadTrackOptions, type ReadExecuteOptions } from '../read-state/read-params';
+import type { AgenticNamespace } from '../agentic/agentic.types';
+/** Options accepted by `PushChain.initialize` / `reinitialize`. */
+export interface PushChainInitializeOptions {
+    network: PUSH_NETWORK;
+    rpcUrls?: Partial<Record<CHAIN, string[]>>;
+    blockExplorers?: Partial<Record<CHAIN, string[]>>;
+    printTraces?: boolean;
+    progressHook?: (progress: ProgressEvent) => void;
+    /**
+     * Act as this agentic wallet (AGW). The signer decides the door: the owner
+     * sends through `execute`, an agent named in an enabled rule through
+     * `executeAsAgent`; anyone else fails with NOT_OWNER_OR_AGENT.
+     * `universal.account` becomes the wallet; `universal.origin`,
+     * `getAccountStatus()` and gas stay the signer's. Not inherited by
+     * `reinitialize` — pass it again to keep acting as the wallet.
+     */
+    agenticWallet?: `0x${string}`;
+}
 /**
  * @class PushChain
  *
@@ -36,7 +54,24 @@ export declare class PushChain {
             TOKEN: import("../constants").PayableTokenConstantsMap;
         };
         READ: {
-            readonly WEB2: "web2:https";
+            readonly CHAIN: Readonly<{
+                readonly PUSH_MAINNET: CHAIN.PUSH_MAINNET;
+                readonly PUSH_TESTNET: CHAIN.PUSH_TESTNET;
+                readonly PUSH_TESTNET_DONUT: CHAIN.PUSH_TESTNET;
+                readonly PUSH_LOCALNET: CHAIN.PUSH_LOCALNET;
+                readonly ETHEREUM_MAINNET: CHAIN.ETHEREUM_MAINNET;
+                readonly ETHEREUM_SEPOLIA: CHAIN.ETHEREUM_SEPOLIA;
+                readonly ARBITRUM_SEPOLIA: CHAIN.ARBITRUM_SEPOLIA;
+                readonly BASE_SEPOLIA: CHAIN.BASE_SEPOLIA;
+                readonly BNB_TESTNET: CHAIN.BNB_TESTNET;
+                readonly SOLANA_MAINNET: CHAIN.SOLANA_MAINNET;
+                readonly SOLANA_TESTNET: CHAIN.SOLANA_TESTNET;
+                readonly SOLANA_DEVNET: CHAIN.SOLANA_DEVNET;
+                readonly WEB2: "web2";
+            }> & {
+                readonly WEB2: typeof import("../constants").WEB2_READ_CHAIN;
+            };
+            readonly WEB2: "web2";
             readonly NAMESPACE: {
                 readonly EVM: "eip155";
                 readonly SVM: "solana";
@@ -48,7 +83,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,7 +92,18 @@ 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;
         };
+        AGENTIC: Readonly<{
+            WALLET: "agentic:wallet";
+            PRESETS: Readonly<{
+                CATEGORY: Readonly<{
+                    DEXES: "DEXES";
+                    LENDING: "LENDING";
+                    PREDICTION: "PREDICTION";
+                }>;
+            }>;
+        }>;
     };
     /**
      * @static
@@ -245,6 +291,14 @@ export declare class PushChain {
             to: MoveableToken | undefined;
         }) => Promise<ConversionQuote>;
     };
+    /**
+     * Agentic wallet management (AGW): derive, create, list and per-wallet
+     * handles. Ownership is the connected signer's Push identity.
+     */
+    agentic: AgenticNamespace;
+    /** @internal AGW execution context when initialized with `agenticWallet`. */
+    private agenticContext?;
+    private readonly agenticRuntime;
     /**
      * Account status including UEA deployment state and version info.
      * Initially unloaded — call getAccountStatus() to populate.
@@ -291,13 +345,7 @@ export declare class PushChain {
      *
      * @returns An initialized instance of PushChain.
      */
-    static initialize: (universalSigner: UniversalSigner | UniversalAccount, options?: {
-        network: PUSH_NETWORK;
-        rpcUrls?: Partial<Record<CHAIN, string[]>>;
-        blockExplorers?: Partial<Record<CHAIN, string[]>>;
-        printTraces?: boolean;
-        progressHook?: (progress: ProgressEvent) => void;
-    }) => Promise<PushChain>;
+    static initialize: (universalSigner: UniversalSigner | UniversalAccount, options?: PushChainInitializeOptions) => Promise<PushChain>;
     /**
      * @method reinitialize
      * Reinitializes the PushChain SDK with a new universal signer and optional config.
@@ -310,11 +358,5 @@ export declare class PushChain {
      *
      * @returns A new initialized instance of PushChain.
      */
-    reinitialize: (universalSigner: UniversalSigner | UniversalAccount, options?: {
-        network: PUSH_NETWORK;
-        rpcUrls?: Partial<Record<CHAIN, string[]>>;
-        blockExplorers?: Partial<Record<CHAIN, string[]>>;
-        printTraces?: boolean;
-        progressHook?: (progress: ProgressEvent) => void;
-    }) => Promise<PushChain>;
+    reinitialize: (universalSigner: UniversalSigner | UniversalAccount, options?: PushChainInitializeOptions) => Promise<PushChain>;
 }

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

@@ -13,6 +13,12 @@ const evm_client_1 = require("../vm-client/evm-client");
 const tokens_1 = require("../constants/tokens");
 const read_params_1 = require("../read-state/read-params");
 const read_executor_1 = require("../read-state/read-executor");
+const agentic_1 = require("../agentic/agentic");
+const context_1 = require("../agentic/context");
+const send_1 = require("../agentic/execution/send");
+const guards_1 = require("../agentic/execution/guards");
+const response_1 = require("../agentic/response");
+const runtime_1 = require("../agentic/runtime");
 /**
  * @class PushChain
  *
@@ -52,6 +58,14 @@ class PushChain {
     moveable;
     payable;
     funds;
+    /**
+     * Agentic wallet management (AGW): derive, create, list and per-wallet
+     * handles. Ownership is the connected signer's Push identity.
+     */
+    agentic;
+    /** @internal AGW execution context when initialized with `agenticWallet`. */
+    agenticContext;
+    agenticRuntime;
     /**
      * Account status including UEA deployment state and version info.
      * Initially unloaded — call getAccountStatus() to populate.
@@ -81,61 +95,96 @@ class PushChain {
         };
         // Default — overwritten in createInstance() with the background fetch
         this.accountStatusReady = Promise.resolve();
+        this.agenticRuntime = (0, runtime_1.createAgenticRuntime)(orchestrator, isReadMode);
+        this.agentic = new agentic_1.AgenticNamespaceImpl(this.agenticRuntime);
+        // eslint-disable-next-line @typescript-eslint/no-this-alias -- getters below need the instance
+        const self = this;
+        // In agenticWallet mode, request transactions execute through the wallet
+        // and the wallet pays the request value, so its balance gates the read.
+        const readDeps = () => {
+            const actx = self.agenticContext;
+            if (!actx)
+                return orchestrator;
+            return {
+                execute: (params, options) => (0, send_1.agenticSend)(self.agenticRuntime, actx, params, options),
+                trackRead: orchestrator.trackRead.bind(orchestrator),
+                revalidateRead: orchestrator.revalidateRead.bind(orchestrator),
+                getProgressHook: orchestrator.getProgressHook.bind(orchestrator),
+                getReadBalance: () => self.agenticRuntime.reader.getBalance({ address: actx.wallet }),
+            };
+        };
+        // Unspent read budget returns to whoever paid it: the wallet in agentic mode.
+        const withReadRefund = (options) => self.agenticContext && options.refundTo === undefined
+            ? { ...options, refundTo: self.agenticContext.wallet }
+            : options;
         this.universal = {
             get origin() {
                 return orchestrator.getUOA();
             },
             get account() {
-                return orchestrator.computeUEAOffchain();
+                return self.agenticContext?.wallet ?? orchestrator.computeUEAOffchain();
             },
             sendTransaction: (...args) => {
                 if (this.isReadMode) {
                     throw new Error('Read only mode cannot call sendTransaction function');
                 }
+                if (this.agenticContext) {
+                    return (0, send_1.agenticSend)(this.agenticRuntime, this.agenticContext, ...args);
+                }
                 return orchestrator.execute.bind(orchestrator)(...args);
             },
             prepareTransaction: (params, options) => {
+                if (this.agenticContext)
+                    throw (0, guards_1.notAllowedInAgenticMode)('prepareTransaction');
                 return orchestrator.prepareTransaction.bind(orchestrator)(params, options);
             },
             executeTransactions: async (txs, options) => {
                 if (this.isReadMode) {
                     throw new Error('Read only mode cannot call executeTransactions function');
                 }
+                if (this.agenticContext)
+                    throw (0, guards_1.notAllowedInAgenticMode)('executeTransactions');
                 return orchestrator.createCascadedBuilder(txs, options).send();
             },
-            trackTransaction: (txHash, options) => {
-                return orchestrator.trackTransaction.bind(orchestrator)(txHash, options);
+            trackTransaction: async (txHash, options) => {
+                const tracked = await orchestrator.trackTransaction.bind(orchestrator)(txHash, options);
+                return (0, response_1.adaptTrackedResponse)(this.agenticRuntime, tracked);
             },
             migrateCEA: (chain) => {
                 if (this.isReadMode) {
                     throw new Error('Read only mode cannot call migrateCEA function');
                 }
+                if (this.agenticContext)
+                    throw (0, guards_1.notAllowedInAgenticMode)('migrateCEA');
                 return orchestrator.migrateCEA.bind(orchestrator)(chain);
             },
             rescueFunds: (params) => {
                 if (this.isReadMode) {
                     throw new Error('Read only mode cannot call rescueFunds function');
                 }
+                if (this.agenticContext)
+                    throw (0, guards_1.notAllowedInAgenticMode)('rescueFunds');
                 return orchestrator.rescueFunds.bind(orchestrator)(params);
             },
             // 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, withReadRefund(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');
                 const prepared = await orchestrator.prepareRead(params, options.progressHook);
-                const { reads: [response] } = await (0, read_executor_1.executeReads)(orchestrator, [prepared], options);
+                const { reads: [response] } = await (0, read_executor_1.executeReads)(readDeps(), [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, withReadRefund(options), orchestrator.getNetwork(), orchestrator.getRpcUrls());
+                return orchestrator.prepareRead(params);
             },
             executeReads: (async (reads, options) => {
                 reads.forEach((r) => (0, read_executor_1.assertRequestEntrypoint)(r.callback));
                 if (this.isReadMode)
                     throw new Error('Read only mode cannot call executeReads function');
-                return (0, read_executor_1.executeReads)(orchestrator, reads, options);
+                return (0, read_executor_1.executeReads)(readDeps(), reads, options);
             }),
             trackRead: ((ref, options) => {
                 const opts = { ...(0, read_params_1.toLifecycleOptions)(options), progressHook: options?.progressHook };
@@ -450,6 +499,12 @@ class PushChain {
         });
         // Let execute() await the background fetch instead of re-fetching
         orchestrator.accountStatusReadyPromise = instance.accountStatusReady;
+        // Agentic mode: validate the wallet, its generation and the signer's door
+        // before returning a client. A read-only client may hold the context (so
+        // universal.account shows the wallet) but every signing path stays closed.
+        if (options?.agenticWallet !== undefined) {
+            instance.agenticContext = await (0, context_1.resolveAgenticContext)(instance.agenticRuntime, options.agenticWallet);
+        }
         return instance;
     }
     /**
@@ -480,12 +535,17 @@ class PushChain {
      * @returns A new initialized instance of PushChain.
      */
     reinitialize = async (universalSigner, options) => {
+        // agenticWallet is NOT inherited: an omitted value yields an ordinary
+        // client, and a supplied one reruns every wallet/role check.
         const mergedOptions = {
             network: options?.network ?? this.orchestrator.getNetwork(),
             rpcUrls: options?.rpcUrls ?? this.orchestrator.getRpcUrls(),
             blockExplorers: options?.blockExplorers ?? this.blockExplorers,
             printTraces: options?.printTraces ?? this.orchestrator.getPrintTraces(),
             progressHook: options?.progressHook ?? this.orchestrator.getProgressHook(),
+            ...(options?.agenticWallet !== undefined
+                ? { agenticWallet: options.agenticWallet }
+                : {}),
         };
         return PushChain.createInstance(universalSigner, mergedOptions);
     };

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/destination.js

@@ -17,7 +17,12 @@ const KNOWN = new Set(Object.values(read_state_1.READ_NAMESPACE));
 function resolveDestination(dest) {
     let chainNamespace;
     let chainId;
-    if ('chain' in dest) {
+    if ('chain' in dest && dest.chain === read_state_1.WEB2_READ_CHAIN) {
+        // The public 'web2' spelling has no ':'; its wire identity is web2:https.
+        chainNamespace = read_state_1.WEB2_DESTINATION.chainNamespace;
+        chainId = read_state_1.WEB2_DESTINATION.chainId;
+    }
+    else if ('chain' in dest) {
         const idx = dest.chain.indexOf(':');
         if (idx <= 0) {
             throw new errors_1.UnsupportedReadDestinationError(`chain is not CAIP-2: ${dest.chain}`);

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;