@pushchain/core 6.0.26 → 6.0.27-alpha.0

package/src/lib/orchestrator/internals/errors.js

@@ -10,7 +10,7 @@
  * callers.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InsufficientUEABalanceError = exports.PushChainBatchExecutionError = exports.PushChainExecutionError = void 0;
+exports.InsufficientUEABalanceError = exports.PushChainBatchExecutionError = exports.AtomicBatchUnavailableError = exports.PushChainExecutionError = void 0;
 const formatters_1 = require("../../formatters");
 /**
  * Typed error for Route 1 Push Chain tx failures. Thrown by
@@ -31,14 +31,26 @@ class PushChainExecutionError extends Error {
     code = 'PUSH_CHAIN_EXECUTION_FAILED';
     gatewayTxHash;
     decodedError;
+    /** Underlying transport/RPC error, kept so raw revert data is not lost. */
+    cause;
     constructor(message, opts = {}) {
         super((0, formatters_1.normalizePublicErrorMessage)(message));
         this.name = 'PushChainExecutionError';
         this.gatewayTxHash = opts.gatewayTxHash;
         this.decodedError = opts.decodedError;
+        if (opts.cause !== undefined)
+            this.cause = opts.cause;
     }
 }
 exports.PushChainExecutionError = PushChainExecutionError;
+/** @internal A caller required an atomic native batch; sequential fallback is forbidden. */
+class AtomicBatchUnavailableError extends PushChainExecutionError {
+    constructor(message, cause) {
+        super(message, { cause });
+        this.name = 'AtomicBatchUnavailableError';
+    }
+}
+exports.AtomicBatchUnavailableError = AtomicBatchUnavailableError;
 /** Recovery metadata for a non-atomic Push batch. A pending hash is broadcast but unconfirmed. */
 class PushChainBatchExecutionError extends PushChainExecutionError {
     transactionHashes;

package/src/lib/orchestrator/internals/execute-standard.d.ts

@@ -3,4 +3,6 @@ import type { ExecuteParams, UniversalTxResponse } from '../orchestrator.types';
 import type { OrchestratorContext } from './context';
 import { type ResponseBuilderCallbacks } from './response-builder';
 export declare function resolveRequiredFunds(requiredGasFee: bigint, executeValue: bigint, requiredFundsOverride?: bigint): bigint;
-export declare function executeStandardPayload(ctx: OrchestratorContext, execute: ExecuteParams, eventBuffer: ProgressEvent[], getResponseCallbacks: () => ResponseBuilderCallbacks): Promise<UniversalTxResponse>;
+export declare function executeStandardPayload(ctx: OrchestratorContext, execute: ExecuteParams, eventBuffer: ProgressEvent[], getResponseCallbacks: () => ResponseBuilderCallbacks, policy?: {
+    requireAtomicBatch: boolean;
+}): Promise<UniversalTxResponse>;

package/src/lib/orchestrator/internals/execute-standard.js

@@ -83,7 +83,7 @@ function resolveRequiredFunds(requiredGasFee, executeValue, requiredFundsOverrid
         ? requiredFundsOverride
         : baseRequiredFunds;
 }
-async function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks) {
+async function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks, policy) {
     const transformFn = (tx, buf = []) => (0, response_builder_1.transformToUniversalTxResponse)(ctx, tx, buf, getResponseCallbacks());
     // Set default value for value if undefined
     if (execute.value === undefined) {
@@ -104,7 +104,7 @@ async function executeStandardPayload(ctx, execute, eventBuffer, getResponseCall
         (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_107);
         let tx;
         try {
-            tx = await (0, push_chain_tx_1.sendPushTx)(ctx, execute, eventBuffer, transformFn);
+            tx = await (0, push_chain_tx_1.sendPushTx)(ctx, execute, eventBuffer, transformFn, policy?.requireAtomicBatch);
         }
         catch (err) {
             // Push Chain broadcast failed. Wallet rejection surfaces as 104-04;
@@ -116,7 +116,7 @@ async function executeStandardPayload(ctx, execute, eventBuffer, getResponseCall
             // outer orchestrator catch doesn't emit a second 199-02 on top.
             ctx._routeTerminalEmitted = true;
             if (!isUserDecline && !(err instanceof push_chain_tx_1.PushChainExecutionError)) {
-                throw new push_chain_tx_1.PushChainExecutionError(errMsg);
+                throw new push_chain_tx_1.PushChainExecutionError(errMsg, { cause: err });
             }
             throw err;
         }

package/src/lib/orchestrator/internals/outbound-sync.js

@@ -9,8 +9,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OutboundFailedError = exports.OutboundTimeoutError = exports.INBOUND_INITIAL_WAIT_MS = exports.INBOUND_MAX_TIMEOUT_MS = exports.OUTBOUND_MAX_TIMEOUT_MS = exports.OUTBOUND_POLL_INTERVAL_MS = exports.OUTBOUND_INITIAL_WAIT_MS = void 0;
 exports.waitForOutboundTx = waitForOutboundTx;
 exports.waitForAllOutboundTxsV2 = waitForAllOutboundTxsV2;
+const tslib_1 = require("tslib");
 const tracking_1 = require("./pc20/tracking");
 const viem_1 = require("viem");
+const web3_js_1 = require("@solana/web3.js");
+const bs58_1 = tslib_1.__importDefault(require("bs58"));
 const chain_1 = require("../../constants/chain");
 const enums_1 = require("../../constants/enums");
 const types_1 = require("../../generated/uexecutor/v1/types");
@@ -90,11 +93,11 @@ exports.OutboundFailedError = OutboundFailedError;
  * (preserves the silent-success bug fix); if no receipt yet or RPC failure,
  * we keep polling.
  *
- * EVM-only — SVM tiebreaker would need a separate signature lookup path.
+ * EVM receipts and confirmed/finalized Solana signatures are supported.
  */
-async function verifyExternalEvmReceipt(ctx, destinationChain, externalTxHash) {
+async function verifyExternalReceipt(ctx, destinationChain, externalTxHash) {
     const chainInfo = chain_1.CHAIN_INFO[destinationChain];
-    if (!chainInfo || chainInfo.vm !== enums_1.VM.EVM) {
+    if (!chainInfo || (chainInfo.vm !== enums_1.VM.EVM && chainInfo.vm !== enums_1.VM.SVM)) {
         return 'unsupported';
     }
     // Guard against unit-test contexts that don't pass a real rpcUrls map —
@@ -106,6 +109,45 @@ async function verifyExternalEvmReceipt(ctx, destinationChain, externalTxHash) {
         : chainInfo.defaultRPC;
     if (!rpcUrls?.length)
         return 'unsupported';
+    if (chainInfo.vm === enums_1.VM.SVM) {
+        let signature;
+        try {
+            const bytes = externalTxHash.startsWith('0x')
+                ? /^0x[0-9a-fA-F]{128}$/.test(externalTxHash)
+                    ? Buffer.from(externalTxHash.slice(2), 'hex')
+                    : new Uint8Array()
+                : bs58_1.default.decode(externalTxHash);
+            if (bytes.length !== 64)
+                return 'pending';
+            signature = bs58_1.default.encode(bytes);
+        }
+        catch {
+            return 'pending';
+        }
+        for (const url of rpcUrls) {
+            try {
+                const connection = new web3_js_1.Connection(url, 'confirmed');
+                if (`solana:${(await connection.getGenesisHash()).slice(0, 32)}` !==
+                    destinationChain)
+                    continue;
+                const result = await connection.getSignatureStatuses([signature], {
+                    searchTransactionHistory: true,
+                });
+                const status = result.value[0];
+                // A processed vote can still disappear. Never report success/failure
+                // before the signature is confirmed or finalized on the right cluster.
+                if (!status ||
+                    (status.confirmationStatus !== 'confirmed' &&
+                        status.confirmationStatus !== 'finalized'))
+                    return 'pending';
+                return status.err ? 'reverted' : 'success';
+            }
+            catch (error) {
+                (0, context_1.printLog)(ctx, `[verifyExternalReceipt] SVM RPC unavailable: ${error instanceof Error ? error.name : 'unknown'}`);
+            }
+        }
+        return 'pending';
+    }
     try {
         const client = (0, viem_1.createPublicClient)({
             transport: (0, viem_1.fallback)(rpcUrls.map((url) => (0, viem_1.http)(url))),
@@ -128,7 +170,7 @@ async function verifyExternalEvmReceipt(ctx, destinationChain, externalTxHash) {
         if (/not found|TransactionReceiptNotFound|could not be found/i.test(msg)) {
             return 'pending';
         }
-        (0, context_1.printLog)(ctx, `[verifyExternalEvmReceipt] RPC error for ${destinationChain} tx ${externalTxHash}: ${msg}`);
+        (0, context_1.printLog)(ctx, `[verifyExternalReceipt] RPC error for ${destinationChain} tx ${externalTxHash}: ${msg}`);
         return 'pending';
     }
 }
@@ -268,7 +310,7 @@ async function waitForOutboundTx(ctx, pushChainTxHash, options = {}) {
                     const isCosmosObserved = ob.outboundStatus === types_2.OutboundStatus.OBSERVED;
                     if (!isCosmosObserved) {
                         // Tiebreaker: ask the destination-chain RPC directly.
-                        const verdict = await verifyExternalEvmReceipt(ctx, chain, ob.observedTx.txHash);
+                        const verdict = await verifyExternalReceipt(ctx, chain, ob.observedTx.txHash);
                         if (verdict === 'reverted') {
                             (0, context_1.printLog)(ctx, `[waitForOutboundTx] Source-chain RPC reports REVERTED for ${ob.destinationChain} tx ${ob.observedTx.txHash} (cosmos still ${types_1.UniversalTxStatus[statusNum] ?? statusNum})`);
                             progressHook?.({
@@ -313,7 +355,10 @@ async function waitForOutboundTx(ctx, pushChainTxHash, options = {}) {
                         // created, and a repeat export deploys no wrapper so nothing is
                         // ever observed to backfill it. Resolve from UniversalCore instead,
                         // keyed by the Push-native source token.
-                        const pc20Wrapper = await (0, tracking_1.resolvePC20WrapperForReceipt)(ctx, ob, { network: ctx.pushNetwork, rpcUrls: ctx.rpcUrls });
+                        const pc20Wrapper = await (0, tracking_1.resolvePC20WrapperForReceipt)(ctx, ob, {
+                            network: ctx.pushNetwork,
+                            rpcUrls: ctx.rpcUrls,
+                        });
                         const details = {
                             externalTxHash: ob.observedTx.txHash,
                             destinationChain: chain,
@@ -477,7 +522,7 @@ async function waitForAllOutboundTxsV2(ctx, pushChainTxHash, outboundHops, optio
                             continue;
                         const isCosmosObserved = ob.outboundStatus === types_2.OutboundStatus.OBSERVED;
                         if (!isCosmosObserved) {
-                            const verdict = await verifyExternalEvmReceipt(ctx, chain, externalTxHash);
+                            const verdict = await verifyExternalReceipt(ctx, chain, externalTxHash);
                             if (verdict === 'reverted') {
                                 for (const targetHop of pendingTargetHops) {
                                     targetHop.status = 'failed';

package/src/lib/orchestrator/internals/push-chain-tx.d.ts

@@ -20,7 +20,7 @@ type TransformToResponseFn = (tx: TxResponse, eventBuffer: ProgressEvent[]) => P
  * For multicall arrays: executes each call as a separate transaction with
  * local nonce management and per-tx receipt confirmation.
  */
-export declare function sendPushTx(ctx: OrchestratorContext, execute: ExecuteParams, eventBuffer: ProgressEvent[], transformFn: TransformToResponseFn): Promise<UniversalTxResponse>;
+export declare function sendPushTx(ctx: OrchestratorContext, execute: ExecuteParams, eventBuffer: ProgressEvent[], transformFn: TransformToResponseFn, requireAtomicBatch?: boolean): Promise<UniversalTxResponse>;
 export type ResignUniversalPayloadFn = () => Promise<{
     universalPayload: UniversalPayload;
     verificationData: `0x${string}`;

package/src/lib/orchestrator/internals/push-chain-tx.js

@@ -66,7 +66,7 @@ async function getIndexedPushTransaction(ctx, txHash, label) {
  * For multicall arrays: executes each call as a separate transaction with
  * local nonce management and per-tx receipt confirmation.
  */
-async function sendPushTx(ctx, execute, eventBuffer, transformFn) {
+async function sendPushTx(ctx, execute, eventBuffer, transformFn, requireAtomicBatch = false) {
     if (Array.isArray(execute.data)) {
         const calls = execute.data;
         // Reject a zero `to` BEFORE route selection so behaviour is identical
@@ -82,6 +82,15 @@ async function sendPushTx(ctx, execute, eventBuffer, transformFn) {
         // (b) a wallet that can sign a 7702 authorization. When either is missing we
         // fall back to the legacy non-atomic per-call loop below.
         const executor = (0, chain_1.getBatchExecutorAddress)(ctx.universalSigner.account.chain);
+        if (requireAtomicBatch) {
+            if (!executor || !ctx.universalSigner.signAuthorization) {
+                throw new errors_1.AtomicBatchUnavailableError('This operation requires a sender-preserving atomic batch; the signer/network does not support EIP-7702.');
+            }
+            const code = await ctx.pushClient.publicClient.getCode({ address: executor });
+            if (!code || code === '0x') {
+                throw new errors_1.AtomicBatchUnavailableError(`Atomic batch executor ${executor} is not deployed on the connected network.`);
+            }
+        }
         if (executor && ctx.universalSigner.signAuthorization) {
             try {
                 (0, context_1.printLog)(ctx, `sendPushTx — executing ${calls.length} call(s) atomically via EIP-7702 (executor: ${executor})`);
@@ -100,6 +109,9 @@ async function sendPushTx(ctx, execute, eventBuffer, transformFn) {
                 // (e.g. a real revert) must surface.
                 if (!(err instanceof evm_client_1.EIP7702NotSupportedError))
                     throw err;
+                if (requireAtomicBatch) {
+                    throw new errors_1.AtomicBatchUnavailableError('The signer could not authorize EIP-7702; no sequential transactions were sent.', err);
+                }
                 (0, context_1.printLog)(ctx, `sendPushTx — wallet cannot sign EIP-7702 authorization; falling back to sequential execution`);
                 // eslint-disable-next-line no-console
                 console.warn('[push-chain] Wallet cannot produce an EIP-7702 authorization — batch ' +

package/src/lib/orchestrator/orchestrator.d.ts

@@ -97,6 +97,9 @@ export declare class Orchestrator {
      * Route 1 (Push Chain) dispatches to extracted sub-flow modules.
      */
     execute(params: ExecuteParams | UniversalExecuteParams, options?: TransactionExecutionOptions): Promise<UniversalTxResponse>;
+    /** @internal Sender-preserving batch. Never uses the native sequential fallback. */
+    executeAtomicBatch(params: ExecuteParams, options?: TransactionExecutionOptions): Promise<UniversalTxResponse>;
+    private executeWithPolicy;
     /**
      * Prepare a universal transaction without executing it.
      * Returns a PreparedUniversalTx that can be chained with thenOn() or sent with send().

package/src/lib/orchestrator/orchestrator.js

@@ -157,6 +157,16 @@ class Orchestrator {
      * Route 1 (Push Chain) dispatches to extracted sub-flow modules.
      */
     async execute(params, options) {
+        return this.executeWithPolicy(params, options, false);
+    }
+    /** @internal Sender-preserving batch. Never uses the native sequential fallback. */
+    async executeAtomicBatch(params, options) {
+        if (typeof params.to !== 'string' || !Array.isArray(params.data) || params.data.length < 2 || params.funds) {
+            throw new Error('executeAtomicBatch requires multiple Push calls and no signer funds');
+        }
+        return this.executeWithPolicy(params, options, true);
+    }
+    async executeWithPolicy(params, options, requireAtomicBatch) {
         const inlineProgressHook = params.progressHook;
         if (options || inlineProgressHook) {
             params = {
@@ -312,7 +322,9 @@ class Orchestrator {
                         ? await (0, internals_1.executeFundsOnly)(this.ctx, legacy, eventBuffer, rcb)
                         : await (0, internals_1.executeFundsWithPayload)(this.ctx, legacy, eventBuffer, rcb));
                 }
-                return attachPerCallHookForWait(await (0, internals_1.executeStandardPayload)(this.ctx, execute, eventBuffer, rcb));
+                return attachPerCallHookForWait(await (requireAtomicBatch
+                    ? (0, internals_1.executeStandardPayload)(this.ctx, execute, eventBuffer, rcb, { requireAtomicBatch: true })
+                    : (0, internals_1.executeStandardPayload)(this.ctx, execute, eventBuffer, rcb)));
             }
             catch (err) {
                 const errMessage = (0, formatters_1.normalizePublicErrorMessage)(err);

package/src/lib/orchestrator/orchestrator.types.d.ts

@@ -374,6 +374,14 @@ export interface UniversalTxResponse {
     childTxHash?: string;
     /** Transaction route (UOA_TO_PUSH, UOA_TO_CEA, CEA_TO_PUSH, CEA_TO_CEA) */
     route?: TransactionRouteType;
+    /**
+     * Agentic wallet (AGW) context, present when the transaction executed
+     * through an AGW. `from` is then the wallet and `origin` stays the signer;
+     * `agentic.rawTo` / `rawData` hold the wrapped call the signer sent.
+     * Outbound to/data/value summarize the first encoded destination call;
+     * `agentic.destinationCalls` retains the complete ordered call list.
+     */
+    agentic?: import('../agentic/agentic.types').AgenticTxMetadata;
     /**
      * @internal True when this response was produced by `trackTransaction` and
      * its progress events have already been replayed via the registered hook.

package/src/lib/orchestrator/route-detector.js

@@ -19,6 +19,7 @@ exports.detectRoute = detectRoute;
 exports.validateRouteParams = validateRouteParams;
 exports.getRouteInfo = getRouteInfo;
 const enums_1 = require("../constants/enums");
+const read_state_1 = require("../constants/read-state");
 const tokens_1 = require("../constants/tokens");
 const orchestrator_types_1 = require("./orchestrator.types");
 const payload_builders_1 = require("./payload-builders");
@@ -215,8 +216,8 @@ function detectRoute(params) {
  */
 function validateRouteParams(params, context) {
     const toChain = isChainTarget(params.to) ? String(params.to.chain) : undefined;
-    if (String(params.from?.chain ?? '') === enums_1.CHAIN.WEB2 || toChain === enums_1.CHAIN.WEB2) {
-        throw new RouteValidationError('CHAIN.WEB2 is a read-only destination and cannot be used with transaction APIs');
+    if ((0, read_state_1.isWeb2ReadChain)(String(params.from?.chain ?? '')) || (0, read_state_1.isWeb2ReadChain)(toChain)) {
+        throw new RouteValidationError('READ.CHAIN.WEB2 is a read-only destination and cannot be used with transaction APIs');
     }
     const route = detectRoute(params);
     // Validate from.chain is supported external chain (Routes 3, 4)

package/src/lib/orchestrator/svm-idl/resolve.d.ts

@@ -12,3 +12,5 @@ export interface ResolvedSvmCall {
     ixData: Uint8Array;
 }
 export declare function resolveSvmCall(input: ResolveInput): ResolvedSvmCall;
+/** Internal AGW seam: use its registry-derived authority, not the signer's CEA. */
+export declare function resolveSvmCallForCea(input: ResolveInput, ceaAuthority: `0x${string}`): ResolvedSvmCall;

package/src/lib/orchestrator/svm-idl/resolve.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveSvmCall = resolveSvmCall;
+exports.resolveSvmCallForCea = resolveSvmCallForCea;
 const web3_js_1 = require("@solana/web3.js");
 const buffer_1 = require("buffer");
 const account_1 = require("../../universal/account/account");
@@ -13,6 +14,15 @@ const CEA_AUTHORITY_NAMES = new Set([
     'ceaSigner',
 ]);
 function resolveSvmCall(input) {
+    return resolveCall(input);
+}
+/** Internal AGW seam: use its registry-derived authority, not the signer's CEA. */
+function resolveSvmCallForCea(input, ceaAuthority) {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(ceaAuthority))
+        throw new Error('SVM CEA authority must be 32 bytes');
+    return resolveCall(input, ceaAuthority);
+}
+function resolveCall(input, authority) {
     const idl = (0, registry_1.getIdl)(input.programAddress);
     if (!idl) {
         throw new Error(`resolveSvmCall: no IDL found for ${input.programAddress}. ` +
@@ -30,7 +40,7 @@ function resolveSvmCall(input) {
         throw new Error(`resolveSvmCall: no instruction in IDL '${idl.metadata?.name ?? idl.address}' matches discriminator [${Array.from(disc).join(',')}]`);
     }
     const programPk = new web3_js_1.PublicKey(buffer_1.Buffer.from(input.programAddress.slice(2), 'hex'));
-    const { address: ceaPdaHex } = (0, account_1.deriveSvmCeaPda)(input.senderUea, input.targetChain, true);
+    const ceaPdaHex = authority ?? (0, account_1.deriveSvmCeaPda)(input.senderUea, input.targetChain, true).address;
     const accounts = [];
     for (const item of ix.accounts) {
         if ('accounts' in item) {

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,16 @@ 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";
+                    PREDICTION: "PREDICTION";
+                }>;
+            }>;
+        }>;
     };
     /**
      * @static
@@ -246,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.
@@ -292,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.
@@ -311,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>;
 }