@pushchain/core 6.0.26 → 6.0.27-alpha.1

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

@@ -1233,6 +1233,68 @@ const RAW_HOOKS_READ = {
         level: 'ERROR',
     }),
 };
+const RAW_HOOKS_AGENTIC = {
+    [progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_101]: (address, index, deployed) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_101,
+        title: 'Agentic Wallet Derived',
+        message: `Wallet ${address} at index ${index} (${deployed ? 'deployed' : 'not deployed'}).`,
+        response: { address, index, deployed },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_102]: (address, strategy) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_102,
+        title: 'Deploy Step Added',
+        message: `Deploying agentic wallet ${address} (${strategy}).`,
+        response: { address, strategy },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_104]: (rulesIds) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_104,
+        title: 'Rules Granted',
+        message: `Granted ${rulesIds.length} rule${rulesIds.length === 1 ? '' : 's'}.`,
+        response: { rulesIds },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_105]: (target) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_105,
+        title: 'Rules Revoked',
+        message: 'all' in target
+            ? 'Revoked every rule on the wallet.'
+            : `Revoked ${target.rulesIds.length} rule${target.rulesIds.length === 1 ? '' : 's'}.`,
+        response: target,
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_106]: (label) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_106,
+        title: 'Label Set',
+        message: `Wallet label set to "${label}".`,
+        response: { label },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_107]: (rulesId, chainNamespace, door) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_107,
+        title: 'Rule Resolved',
+        message: door === 'owner'
+            ? `Owner door on ${chainNamespace}; no rule applies.`
+            : `Agent door on ${chainNamespace} under rule ${rulesId}.`,
+        response: { rulesId: rulesId ?? null, chainNamespace, door },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_199_01]: (operation, txHash) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_199_01,
+        title: 'Agentic Operation Done',
+        message: `${operation} completed.`,
+        response: { operation, txHash: txHash ?? null },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_199_02]: (operation, code, message, decodedError) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_199_02,
+        title: 'Agentic Operation Failed',
+        message: `${operation} failed: ${message}`,
+        response: { operation, code, decodedError: decodedError ?? null },
+        level: 'ERROR',
+    }),
+};
 // Combine all routes into the master record
 const RAW_HOOKS = {
     ...RAW_HOOKS_R1,
@@ -1241,6 +1303,7 @@ const RAW_HOOKS = {
     ...RAW_HOOKS_MULTICHAIN,
     ...RAW_HOOKS_MIG,
     ...RAW_HOOKS_READ,
+    ...RAW_HOOKS_AGENTIC,
 };
 // Build final hooks with timestamp injection
 const PROGRESS_HOOKS = Object.fromEntries(Object.entries(RAW_HOOKS).map(([key, value]) => [key, withTimestamp(value)]));

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

@@ -134,7 +134,15 @@ export declare enum PROGRESS_HOOK {
     UEA_MIG_03 = "UEA-MIG-03",
     UEA_MIG_9901 = "UEA-MIG-9901",
     UEA_MIG_9902 = "UEA-MIG-9902",
-    UEA_MIG_9903 = "UEA-MIG-9903"
+    UEA_MIG_9903 = "UEA-MIG-9903",
+    AGENTIC_TX_101 = "AGENTIC-TX-101",
+    AGENTIC_TX_102 = "AGENTIC-TX-102",
+    AGENTIC_TX_104 = "AGENTIC-TX-104",
+    AGENTIC_TX_105 = "AGENTIC-TX-105",
+    AGENTIC_TX_106 = "AGENTIC-TX-106",
+    AGENTIC_TX_107 = "AGENTIC-TX-107",
+    AGENTIC_TX_199_01 = "AGENTIC-TX-199-01",
+    AGENTIC_TX_199_02 = "AGENTIC-TX-199-02"
 }
 export type PROGRESS_HOOK_R1 = PROGRESS_HOOK.SEND_TX_101 | PROGRESS_HOOK.SEND_TX_102_01 | PROGRESS_HOOK.SEND_TX_103_01 | PROGRESS_HOOK.SEND_TX_103_02 | PROGRESS_HOOK.SEND_TX_103_03 | PROGRESS_HOOK.SEND_TX_103_03_01 | PROGRESS_HOOK.SEND_TX_103_03_02 | PROGRESS_HOOK.SEND_TX_103_03_03 | PROGRESS_HOOK.SEND_TX_103_03_04 | PROGRESS_HOOK.SEND_TX_104_01 | PROGRESS_HOOK.SEND_TX_104_02 | PROGRESS_HOOK.SEND_TX_104_03 | PROGRESS_HOOK.SEND_TX_104_04 | PROGRESS_HOOK.SEND_TX_105_01 | PROGRESS_HOOK.SEND_TX_105_02 | PROGRESS_HOOK.SEND_TX_106_01 | PROGRESS_HOOK.SEND_TX_106_02 | PROGRESS_HOOK.SEND_TX_106_03 | PROGRESS_HOOK.SEND_TX_106_03_01 | PROGRESS_HOOK.SEND_TX_106_03_02 | PROGRESS_HOOK.SEND_TX_106_04 | PROGRESS_HOOK.SEND_TX_106_05 | PROGRESS_HOOK.SEND_TX_106_06 | PROGRESS_HOOK.SEND_TX_107 | PROGRESS_HOOK.SEND_TX_199_01 | PROGRESS_HOOK.SEND_TX_199_02 | PROGRESS_HOOK.SEND_TX_199_03 | PROGRESS_HOOK.SEND_TX_199_99;
 export type PROGRESS_HOOK_R2 = PROGRESS_HOOK.SEND_TX_201 | PROGRESS_HOOK.SEND_TX_202_01 | PROGRESS_HOOK.SEND_TX_202_02 | PROGRESS_HOOK.SEND_TX_203_01 | PROGRESS_HOOK.SEND_TX_203_02 | PROGRESS_HOOK.SEND_TX_203_03 | PROGRESS_HOOK.SEND_TX_203_04 | PROGRESS_HOOK.SEND_TX_203_05 | PROGRESS_HOOK.SEND_TX_204_01 | PROGRESS_HOOK.SEND_TX_204_02 | PROGRESS_HOOK.SEND_TX_204_03 | PROGRESS_HOOK.SEND_TX_204_04 | PROGRESS_HOOK.SEND_TX_207 | PROGRESS_HOOK.SEND_TX_209_01 | PROGRESS_HOOK.SEND_TX_209_02 | PROGRESS_HOOK.SEND_TX_299_01 | PROGRESS_HOOK.SEND_TX_299_02 | PROGRESS_HOOK.SEND_TX_299_03 | PROGRESS_HOOK.SEND_TX_299_99;
@@ -142,4 +150,5 @@ export type PROGRESS_HOOK_R3 = PROGRESS_HOOK.SEND_TX_301 | PROGRESS_HOOK.SEND_TX
 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_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 type PROGRESS_HOOK_AGENTIC = PROGRESS_HOOK.AGENTIC_TX_101 | PROGRESS_HOOK.AGENTIC_TX_102 | PROGRESS_HOOK.AGENTIC_TX_104 | PROGRESS_HOOK.AGENTIC_TX_105 | PROGRESS_HOOK.AGENTIC_TX_106 | PROGRESS_HOOK.AGENTIC_TX_107 | PROGRESS_HOOK.AGENTIC_TX_199_01 | PROGRESS_HOOK.AGENTIC_TX_199_02;
 export {};

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

@@ -147,5 +147,15 @@ var PROGRESS_HOOK;
     PROGRESS_HOOK["UEA_MIG_9901"] = "UEA-MIG-9901";
     PROGRESS_HOOK["UEA_MIG_9902"] = "UEA-MIG-9902";
     PROGRESS_HOOK["UEA_MIG_9903"] = "UEA-MIG-9903";
+    // Agentic wallet (AGW) — AGENTIC-TX (PROPOSED in the AGW SDK spec 3.f).
+    // AGENTIC-TX-103 was removed by the spec (create no longer funds).
+    PROGRESS_HOOK["AGENTIC_TX_101"] = "AGENTIC-TX-101";
+    PROGRESS_HOOK["AGENTIC_TX_102"] = "AGENTIC-TX-102";
+    PROGRESS_HOOK["AGENTIC_TX_104"] = "AGENTIC-TX-104";
+    PROGRESS_HOOK["AGENTIC_TX_105"] = "AGENTIC-TX-105";
+    PROGRESS_HOOK["AGENTIC_TX_106"] = "AGENTIC-TX-106";
+    PROGRESS_HOOK["AGENTIC_TX_107"] = "AGENTIC-TX-107";
+    PROGRESS_HOOK["AGENTIC_TX_199_01"] = "AGENTIC-TX-199-01";
+    PROGRESS_HOOK["AGENTIC_TX_199_02"] = "AGENTIC-TX-199-02";
 })(PROGRESS_HOOK || (exports.PROGRESS_HOOK = PROGRESS_HOOK = {}));
 //# sourceMappingURL=progress-hook.types.js.map

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";
@@ -59,6 +94,17 @@ export declare class PushChain {
             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";
+                    STAKING: "STAKING";
+                    PREDICTION: "PREDICTION";
+                }>;
+            }>;
+        }>;
     };
     /**
      * @static
@@ -246,6 +292,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.
@@ -292,13 +346,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.
@@ -311,11 +359,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,62 +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 = await (0, read_params_1.resolveReadSpecParams)(subject, options, orchestrator.getNetwork(), orchestrator.getRpcUrls());
+                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: async (subject, options) => {
-                const params = await (0, read_params_1.resolveReadSpecParams)(subject, options, orchestrator.getNetwork(), orchestrator.getRpcUrls());
+                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 };
@@ -451,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;
     }
     /**
@@ -481,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/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/read-params.d.ts

@@ -15,7 +15,7 @@ import type { Abi, AbiStateMutability, Address, Hex, ContractFunctionReturnType,
 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 {
@@ -116,7 +116,7 @@ export type ReadQueryOptions = ({
 } & Query<'storageSlot', {
     storageSlot: Hex | bigint;
 }>) | ({
-    chain: typeof CHAIN.WEB2;
+    chain: Web2ReadChain;
 } & Query<'web2', {
     web2: ReadWeb2Options;
 }>);
@@ -146,7 +146,7 @@ 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;

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

@@ -43,7 +43,8 @@ function queryKind(o) {
     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, resolvedTokenProgram) {
@@ -57,7 +58,7 @@ function toReadQuery(subject, o, resolvedTokenProgram) {
         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}`);

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

@@ -6,7 +6,9 @@ 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;
 } | {

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

@@ -309,8 +309,8 @@ function inferResultShape(namespace, query) {
     }
 }
 function chainFromCaip2(caip2) {
-    if (caip2 === enums_1.CHAIN.WEB2)
-        return enums_1.CHAIN.WEB2;
+    if ((0, read_state_1.isWeb2ReadChain)(caip2))
+        return read_state_1.WEB2_READ_CHAIN;
     return Object.values(enums_1.CHAIN).includes(caip2) ? caip2 : undefined;
 }
 function explorerTxUrl(network, txHash) {

package/src/lib/read-state/spec-builder.js

@@ -106,7 +106,7 @@ function buildReadSpecFromPreflight(preflight, params, defaults = {}) {
     return {
         callback: params.callback,
         queryKey: (0, registry_1.computeReadQueryKey)(params.destination, params.query),
-        chain: dest.caip2,
+        chain: (isWeb2 ? read_state_1.WEB2_READ_CHAIN : dest.caip2),
         spec,
         specTuple: toTuple(spec),
         encodedSpec: encodeSpec(spec),

package/src/lib/universal/prc20-address.d.ts

@@ -0,0 +1,15 @@
+import { CHAIN, PUSH_NETWORK } from '../constants/enums';
+import { type MoveableToken } from '../constants/tokens';
+/** Shared pure origin-to-PRC20 mapping; no signer or network reads. */
+export declare function getPRC20Address(token: MoveableToken | {
+    chain: string;
+    address: string;
+}, options?: {
+    network?: PUSH_NETWORK;
+}): {
+    address: `0x${string}`;
+    chain: CHAIN;
+    symbol: string;
+    decimals: number;
+    network: PUSH_NETWORK;
+};

package/src/lib/universal/prc20-address.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPRC20Address = getPRC20Address;
+const enums_1 = require("../constants/enums");
+const tokens_1 = require("../constants/tokens");
+const chain_1 = require("../constants/chain");
+/** Shared pure origin-to-PRC20 mapping; no signer or network reads. */
+function getPRC20Address(token, options) {
+    const network = options?.network ?? enums_1.PUSH_NETWORK.TESTNET_DONUT;
+    const assertDeployed = (addr, ctx) => {
+        if (!addr || addr === '0xTBD') {
+            throw new Error(`PRC20 address not available for ${ctx} on network ${network}`);
+        }
+        return addr;
+    };
+    // PushChainMoveableToken (pETH, pSOL, pUSDT(BNB), …) carries its PRC-20 address
+    // and origin `sourceChain` directly — no registry lookup needed.
+    const pcToken = token;
+    if (pcToken.prc20Address) {
+        return {
+            address: assertDeployed(pcToken.prc20Address, `${pcToken.symbol ?? 'token'} (${pcToken.sourceChain ?? 'unknown'})`),
+            chain: pcToken.sourceChain,
+            symbol: pcToken.symbol,
+            decimals: pcToken.decimals,
+            network,
+        };
+    }
+    // Infer origin chain, symbol, decimals by matching against MOVEABLE_TOKENS
+    let originChain;
+    let tokenSymbol;
+    let tokenDecimals;
+    if ('symbol' in token) {
+        // MoveableToken path: infer chain by symbol + address
+        for (const [key, list] of Object.entries(tokens_1.MOVEABLE_TOKENS)) {
+            const k = key;
+            const match = (list ?? []).find((t) => t.symbol === token.symbol && t.address === token.address);
+            if (match) {
+                originChain = k;
+                tokenSymbol = match.symbol;
+                tokenDecimals = match.decimals;
+                break;
+            }
+        }
+    }
+    else {
+        // { chain, address } path: trust the provided chain and resolve symbol via registry
+        originChain = token.chain;
+        const list = tokens_1.MOVEABLE_TOKENS[originChain] ?? [];
+        const match = list.find((t) => t.address === token.address);
+        if (match) {
+            tokenSymbol = match.symbol;
+            tokenDecimals = match.decimals;
+        }
+    }
+    if (!originChain || !tokenSymbol || tokenDecimals === undefined) {
+        throw new Error('Unable to infer origin chain or token symbol for token');
+    }
+    const map = chain_1.SYNTHETIC_PUSH_ERC20[network];
+    if (!map) {
+        throw new Error(`No PRC20 address map configured for network: ${network}`);
+    }
+    // Map token → synthetic key by origin chain family
+    const isEthFamily = originChain === enums_1.CHAIN.ETHEREUM_MAINNET ||
+        originChain === enums_1.CHAIN.ETHEREUM_SEPOLIA;
+    const isArbFamily = originChain === enums_1.CHAIN.ARBITRUM_SEPOLIA;
+    const isBaseFamily = originChain === enums_1.CHAIN.BASE_SEPOLIA;
+    const isBnbFamily = originChain === enums_1.CHAIN.BNB_TESTNET;
+    const isSolFamily = originChain === enums_1.CHAIN.SOLANA_DEVNET;
+    let key;
+    switch (tokenSymbol) {
+        case 'ETH': {
+            if (isEthFamily)
+                key = 'pETH';
+            else if (isArbFamily)
+                key = 'pETH_ARB';
+            else if (isBaseFamily)
+                key = 'pETH_BASE';
+            else
+                throw new Error('Unsupported ETH origin chain for synthetic mapping');
+            break;
+        }
+        case 'SOL': {
+            if (!isSolFamily)
+                throw new Error('SOL token provided but origin is not Solana');
+            key = 'pSOL';
+            break;
+        }
+        case 'BNB': {
+            if (!isBnbFamily)
+                throw new Error('BNB token provided but origin is not BNB Testnet');
+            key = 'pBNB';
+            break;
+        }
+        case 'USDT': {
+            if (isEthFamily)
+                key = 'USDT_ETH';
+            else if (isArbFamily)
+                key = 'USDT_ARB';
+            else if (isBaseFamily)
+                key = 'USDT_BASE';
+            else if (isBnbFamily)
+                key = 'USDT_BSC';
+            else if (isSolFamily)
+                key = 'USDT_SOL';
+            else
+                throw new Error('Unsupported USDT origin chain for synthetic mapping');
+            break;
+        }
+        case 'USDC': {
+            if (isEthFamily)
+                key = 'USDC_ETH';
+            else if (isArbFamily)
+                key = 'USDC_ARB';
+            else if (isBaseFamily)
+                key = 'USDC_BASE';
+            else if (isBnbFamily)
+                key = 'USDC_BSC';
+            else if (isSolFamily)
+                key = 'USDC_SOL';
+            else
+                throw new Error('Unsupported USDC origin chain for synthetic mapping');
+            break;
+        }
+        default:
+            throw new Error(`Unsupported token symbol: ${tokenSymbol}`);
+    }
+    return {
+        address: assertDeployed(map[key], `${tokenSymbol} on ${originChain}`),
+        chain: originChain,
+        symbol: tokenSymbol,
+        decimals: tokenDecimals,
+        network,
+    };
+}
+//# sourceMappingURL=prc20-address.js.map