@pushchain/core 6.0.26 → 6.0.27-alpha.0

package/src/lib/agentic/utils.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agenticUtils = exports.internalAgenticUtils = void 0;
+const svm_terms_1 = require("./codec/svm-terms");
+const svm_accounts_1 = require("./codec/svm-accounts");
+const viem_1 = require("viem");
+const enums_1 = require("../constants/enums");
+const tokens_1 = require("../constants/tokens");
+const prc20_address_1 = require("../universal/prc20-address");
+const capabilities_1 = require("./capabilities");
+const deployments_1 = require("./deployments");
+const ids_1 = require("./codec/ids");
+const native_1 = require("./codec/native");
+const rules_1 = require("./codec/rules");
+const selectors_1 = require("./codec/selectors");
+const session_1 = require("./codec/session");
+const errors_1 = require("./errors");
+const chain_1 = require("./chain");
+const universal_terms_1 = require("./codec/universal-terms");
+const universal_1 = require("./codec/universal");
+function nativeNamespace(ctx) {
+    if (ctx.pushChainNamespace)
+        return ctx.pushChainNamespace;
+    return (0, chain_1.pushChainNamespaceFor)(ctx.network ?? enums_1.PUSH_NETWORK.TESTNET_DONUT);
+}
+/** Internal codecs and identities — not exported from the package entry point. */
+exports.internalAgenticUtils = {
+    /** The ID a grant with this grantNonce produces. Chain is not part of the hash. */
+    rulesId(agent, grantNonce, ctx) {
+        return (0, ids_1.rulesId)({
+            validator: (0, viem_1.getAddress)(ctx.validator),
+            agent: (0, viem_1.getAddress)(agent),
+            grantNonce: BigInt(grantNonce),
+        });
+    },
+    /** Hash of one allowed call: keccak256(target ‖ selector). */
+    actionId(target, selector) {
+        return (0, ids_1.actionId)((0, viem_1.getAddress)(target), (0, selectors_1.parseSelector)(selector).selector);
+    },
+    /** Key of one allowed call's stored config under one rule on one wallet. */
+    configId(wallet, rulesId, actionId) {
+        return (0, ids_1.configId)((0, viem_1.getAddress)(wallet), rulesId, actionId);
+    },
+    /** Any-owner wallet address. */
+    deriveWallet(owner, index, ctx) {
+        return (0, ids_1.deriveWallet)({
+            factory: (0, viem_1.getAddress)(ctx.factory),
+            walletImplementation: (0, viem_1.getAddress)(ctx.walletImplementation),
+            owner: (0, viem_1.getAddress)(owner),
+            index,
+        });
+    },
+    /**
+     * Encode rules into the grant `Session` bytes, one per rule, in order.
+     * EVM universal rules require wallet/token resolution in the internal context.
+     */
+    encodeRules(rules, ctx) {
+        return (0, rules_1.prepareRules)(rules, {
+            owner: ctx.owner ? (0, viem_1.getAddress)(ctx.owner) : undefined,
+            pushChainNamespace: nativeNamespace(ctx),
+            validator: (0, viem_1.getAddress)(ctx.validator),
+            rulesPolicy: (0, viem_1.getAddress)(ctx.rulesPolicy),
+            gateway: ctx.gateway,
+            universal: ctx.universal,
+            capabilities: deployments_1.V5_CAPABILITIES,
+            nowSeconds: ctx.nowSeconds ?? Math.floor(Date.now() / 1000),
+        }).map((p) => (0, session_1.encodeSession)(p.session));
+    },
+    /** Inverse of encodeRules for one Session encoding. */
+    decodeRules(bytes, ctx = {}) {
+        if (!(0, viem_1.isHex)(bytes))
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'decodeRules expects hex bytes');
+        const session = (0, session_1.decodeSession)(bytes);
+        if (session.actions.length === 0 ||
+            session.actions.some((a) => a.actionPolicies.length !== 1)) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED, 'every action needs exactly one URP policy to be representable as a public InternalRule');
+        }
+        const agent = (0, viem_1.getAddress)(`0x${session.sessionValidatorInitData.slice(26, 66)}`);
+        const { chainNamespace, body } = (0, session_1.decodeEnvelope)(session.actions[0].actionPolicies[0].initData);
+        if (chainNamespace !== nativeNamespace(ctx) &&
+            session.actions.length !== 1) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED, 'only native rules carry more than one action');
+        }
+        if (chainNamespace !== nativeNamespace(ctx)) {
+            if (chainNamespace.startsWith('solana:')) {
+                const terms = (0, svm_terms_1.decodeSvmTerms)(body);
+                (0, svm_terms_1.validateSvmTerms)(terms, -1);
+                const assets = terms.assets.map((a) => {
+                    const chain = chainNamespace;
+                    const token = (tokens_1.MOVEABLE_TOKENS[chain] ?? []).find((candidate) => {
+                        try {
+                            return ((0, viem_1.getAddress)((0, prc20_address_1.getPRC20Address)({ chain, address: candidate.address }, { network: ctx.network ?? enums_1.PUSH_NETWORK.TESTNET_DONUT }).address) === (0, viem_1.getAddress)(a.token));
+                        }
+                        catch {
+                            return false;
+                        }
+                    });
+                    if (!token)
+                        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED, 'SVM source token is absent from the static registry; use wallet.rules.get()');
+                    return {
+                        token: token.mechanism === 'native'
+                            ? viem_1.zeroAddress
+                            : (0, svm_accounts_1.svmKey)(token.address),
+                        maxPerCall: a.maxPerCall,
+                        maxTotal: a.maxTotal,
+                    };
+                });
+                return {
+                    ...terms,
+                    format: 'decoded',
+                    agent,
+                    chainNamespace: chainNamespace,
+                    assets,
+                };
+            }
+            if (!chainNamespace.startsWith('eip155:'))
+                throw (0, errors_1.capabilityUnavailable)(capabilities_1.AgenticCapability.UNIVERSAL_SVM_RULES, 'unsupported universal chain namespace');
+            let terms;
+            try {
+                terms = (0, universal_terms_1.decodeUniversalTerms)(body);
+            }
+            catch (cause) {
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED, 'malformed universal terms', { cause });
+            }
+            const chain = chainNamespace;
+            const network = ctx.network ?? enums_1.PUSH_NETWORK.TESTNET_DONUT;
+            const tokens = terms.assets.map((asset) => {
+                const token = (tokens_1.MOVEABLE_TOKENS[chain] ?? []).find((candidate) => {
+                    try {
+                        return ((0, viem_1.getAddress)((0, prc20_address_1.getPRC20Address)({ chain, address: candidate.address }, { network }).address) === (0, viem_1.getAddress)(asset.token));
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                if (!token)
+                    throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED, `PRC20 ${asset.token} is not in the static ${chain} token registry`, {
+                        hint: 'Use wallet.rules.get() for on-chain source-token resolution.',
+                    });
+                return token.mechanism === 'native'
+                    ? viem_1.zeroAddress
+                    : (0, viem_1.getAddress)(token.address);
+            });
+            return (0, universal_1.universalTermsToRule)(terms, agent, chainNamespace, tokens);
+        }
+        // Native: one stored terms body per action, all on the native chain.
+        const terms = session.actions.map((a, i) => {
+            const env = i === 0
+                ? { chainNamespace, body }
+                : (0, session_1.decodeEnvelope)(a.actionPolicies[0].initData);
+            if (env.chainNamespace !== chainNamespace) {
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED, `action ${i} names chain ${env.chainNamespace}, not ${chainNamespace}`);
+            }
+            return (0, native_1.decodeNativeTerms)(env.body);
+        });
+        return (0, native_1.nativeActionTermsToRule)(terms, agent);
+    },
+};
+/** Public helpers requiring no contract deployment context. */
+exports.agenticUtils = {
+    actionId: exports.internalAgenticUtils.actionId,
+    configId: exports.internalAgenticUtils.configId,
+    decodeRules: exports.internalAgenticUtils.decodeRules,
+};
+//# sourceMappingURL=utils.js.map

package/src/lib/agentic/wallet.d.ts

@@ -0,0 +1,32 @@
+import type { AgenticRuntime } from './runtime';
+import type { AgenticAddress, AgenticProgressHook, AgenticWallet, Checkpoint, WalletInfo } from './agentic.types';
+import type { UniversalTxResponse } from '../orchestrator/orchestrator.types';
+/**
+ * Management handle for one wallet (spec 1.d). Reads work for any wallet;
+ * writes require the connected signer to be the owner. It never sends AS the
+ * wallet — that is PushChain.initialize(signer, { agenticWallet }).
+ */
+export declare class AgenticWalletHandle implements AgenticWallet {
+    private readonly runtime;
+    readonly address: AgenticAddress;
+    readonly rules: AgenticWallet['rules'];
+    private generation?;
+    constructor(runtime: AgenticRuntime, address: string);
+    /** Deployed wallets resolve their own generation; undeployed ones use the network's current one. */
+    private gen;
+    info(): Promise<WalletInfo>;
+    owner(): Promise<{
+        owner: AgenticAddress;
+    }>;
+    setLabel(label: string, opts?: {
+        progressHook?: AgenticProgressHook;
+    }): Promise<UniversalTxResponse>;
+    checkpoints(opts?: {
+        sinceBlock?: bigint;
+    }): Promise<{
+        checkpoints: Checkpoint[];
+    }>;
+    private listRules;
+    private getRule;
+    private signerIdentity;
+}

package/src/lib/agentic/wallet.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgenticWalletHandle = void 0;
+const public_rule_1 = require("./public-rule");
+const viem_1 = require("viem");
+const capabilities_1 = require("./capabilities");
+const deployments_1 = require("./deployments");
+const errors_1 = require("./errors");
+const rules_write_1 = require("./management/rules-write");
+const checkpoints_1 = require("./reads/checkpoints");
+const rules_1 = require("./reads/rules");
+const snapshot_1 = require("./reads/snapshot");
+const wallets_1 = require("./reads/wallets");
+const deployments_2 = require("./deployments");
+const label_1 = require("./management/label");
+/**
+ * Management handle for one wallet (spec 1.d). Reads work for any wallet;
+ * writes require the connected signer to be the owner. It never sends AS the
+ * wallet — that is PushChain.initialize(signer, { agenticWallet }).
+ */
+class AgenticWalletHandle {
+    runtime;
+    address;
+    rules;
+    generation;
+    constructor(runtime, address) {
+        this.runtime = runtime;
+        try {
+            this.address = (0, viem_1.getAddress)(address);
+        }
+        catch (cause) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.NOT_AGENTIC_WALLET, `"${address}" is not an address`, { cause });
+        }
+        this.rules = {
+            list: () => this.listRules(),
+            get: (rulesId) => this.getRule(rulesId),
+            add: async (rules, opts) => (0, rules_write_1.addRules)(this.runtime, await this.gen(), this.address, (0, public_rule_1.publicRules)(rules), opts?.progressHook),
+            update: async (params) => {
+                if (!params ||
+                    !Array.isArray(params.rules) ||
+                    params.rules.length === 0 ||
+                    params.rules.some((p) => !p ||
+                        typeof p.rulesId !== 'string' ||
+                        !/^0x[0-9a-fA-F]{64}$/.test(p.rulesId))) {
+                    throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'rules.update needs { rulesId, rule } pairs with 32-byte rule IDs');
+                }
+                const rules = params.rules.map((p) => ({
+                    ...p,
+                    rule: (0, public_rule_1.publicRules)([p.rule])[0],
+                }));
+                return (0, rules_write_1.updateRules)(this.runtime, await this.gen(), this.address, {
+                    ...params,
+                    rules,
+                });
+            },
+            delete: (async (target, opts) => {
+                // Validate the target shape before any RPC so a bare revoke costs nothing.
+                (0, rules_write_1.assertRevokeTarget)(target);
+                return (0, rules_write_1.revokeRules)(this.runtime, await this.gen(), this.address, target, opts?.progressHook);
+            }),
+        };
+    }
+    /** Deployed wallets resolve their own generation; undeployed ones use the network's current one. */
+    gen() {
+        if (!this.generation) {
+            this.generation = (0, deployments_1.resolveWalletGeneration)(this.runtime.reader, this.runtime.network, this.address);
+            this.generation.catch(() => {
+                this.generation = undefined;
+            });
+        }
+        return this.generation;
+    }
+    async info() {
+        let gen;
+        try {
+            gen = await this.gen();
+        }
+        catch (err) {
+            if (err instanceof errors_1.AgenticError &&
+                err.code === errors_1.AGENTIC_ERROR_CODE.WALLET_NOT_DEPLOYED) {
+                gen = (0, deployments_2.currentGeneration)(this.runtime.network);
+            }
+            else {
+                throw err;
+            }
+        }
+        (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.WALLET_READS);
+        return (0, wallets_1.walletInfo)(this.runtime.reader, gen, this.address, this.signerIdentity());
+    }
+    async owner() {
+        const gen = await this.gen();
+        return {
+            owner: (await (0, wallets_1.walletOwner)(this.runtime.reader, gen, this.address)),
+        };
+    }
+    async setLabel(label, opts) {
+        (0, label_1.assertLabel)(label);
+        return (0, rules_write_1.setLabel)(this.runtime, await this.gen(), this.address, label, opts?.progressHook);
+    }
+    async checkpoints(opts) {
+        const gen = await this.gen();
+        const { checkpoints } = await (0, checkpoints_1.readCheckpoints)(this.runtime.reader, gen, this.address, opts?.sinceBlock);
+        return { checkpoints };
+    }
+    async listRules() {
+        const gen = await this.gen();
+        const snap = await snapshot_1.Snapshot.at(this.runtime.reader);
+        return {
+            rules: await (0, rules_1.listRules)(snap, gen, this.address, this.runtime.pushChainNamespace),
+        };
+    }
+    async getRule(rulesId) {
+        if (typeof rulesId !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(rulesId)) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'rulesId must be a 32-byte hex string');
+        }
+        const gen = await this.gen();
+        const snap = await snapshot_1.Snapshot.at(this.runtime.reader);
+        return (0, rules_1.getRule)(snap, gen, this.address, rulesId, this.runtime.pushChainNamespace);
+    }
+    signerIdentity() {
+        try {
+            return this.runtime.signerPushAccount();
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+exports.AgenticWalletHandle = AgenticWalletHandle;
+//# sourceMappingURL=wallet.js.map

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

@@ -27,11 +27,14 @@ export declare enum CHAIN {
     SOLANA_DEVNET = "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"
 }
 /**
- * Read-only destination exposed with the OG `CHAIN.WEB2` spelling without
- * widening the blockchain enum type accepted by transaction APIs.
+ * Read-only Web2 source kept on `CHAIN` for compatibility without widening the
+ * blockchain enum type accepted by transaction APIs.
+ *
+ * @deprecated Use `PushChain.CONSTANTS.READ.CHAIN.WEB2`. Same value (`'web2'`);
+ * the legacy literal `'web2:https'` is still accepted as read input.
  */
 export declare namespace CHAIN {
-    const WEB2: "web2:https";
+    const WEB2: "web2";
 }
 /**
  * Represents the virtual machine or execution environment for a chain.

package/src/lib/constants/enums.js

@@ -35,12 +35,15 @@ var CHAIN;
     CHAIN["SOLANA_DEVNET"] = "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
 })(CHAIN || (exports.CHAIN = CHAIN = {}));
 /**
- * Read-only destination exposed with the OG `CHAIN.WEB2` spelling without
- * widening the blockchain enum type accepted by transaction APIs.
+ * Read-only Web2 source kept on `CHAIN` for compatibility without widening the
+ * blockchain enum type accepted by transaction APIs.
+ *
+ * @deprecated Use `PushChain.CONSTANTS.READ.CHAIN.WEB2`. Same value (`'web2'`);
+ * the legacy literal `'web2:https'` is still accepted as read input.
  */
 // eslint-disable-next-line @typescript-eslint/no-namespace -- declaration merging keeps Web2 out of the transaction enum union
 (function (CHAIN) {
-    CHAIN.WEB2 = 'web2:https';
+    CHAIN.WEB2 = 'web2';
 })(CHAIN || (exports.CHAIN = CHAIN = {}));
 // Namespace properties are normally enumerable after TypeScript emits them.
 // Keep blockchain enumeration (`Object.values(CHAIN)`) blockchain-only.

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

@@ -1,10 +1,37 @@
 import { CHAIN, LIBRARY, PUSH_NETWORK } from './enums';
 import { TypedDataDomain, TypedData } from '../universal/signer/signer.types';
+import { WEB2_READ_CHAIN } from './read-state';
 import { UNIVERSAL_READ_STATUS, READ_STATUS, READ_ERROR_CODE, READ_OUTCOME } from '../read-state/read-state.types';
+/**
+ * `PushChain.CONSTANTS.READ.CHAIN` — every read source: all of `CHAIN` (same
+ * string values) plus the enumerable Web2 source. A superset of CHAIN, so
+ * `read({ chain: CHAIN.X })` keeps compiling.
+ */
+export declare const READ_CHAIN: Readonly<{ [K in keyof typeof CHAIN]: (typeof CHAIN)[K]; }> & {
+    readonly WEB2: typeof WEB2_READ_CHAIN;
+};
 /** `PushChain.CONSTANTS.READ` — cross-chain read state. Values verified against the deployed UniversalCallback. */
 export declare const READ_CONSTANTS: {
-    /** Read-only Web2 destination. Equivalent to `CHAIN.WEB2`. */
-    readonly WEB2: "web2:https";
+    /** Every read source, enumerable (spec page 5 §4). */
+    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 WEB2_READ_CHAIN;
+    };
+    /** @deprecated Use `READ.CHAIN.WEB2`. Same value (`'web2'`). */
+    readonly WEB2: "web2";
     readonly NAMESPACE: {
         readonly EVM: "eip155";
         readonly SVM: "solana";
@@ -39,8 +66,26 @@ export declare const CONSTANTS: {
         TOKEN: import("./tokens").PayableTokenConstantsMap;
     };
     READ: {
-        /** Read-only Web2 destination. Equivalent to `CHAIN.WEB2`. */
-        readonly WEB2: "web2:https";
+        /** Every read source, enumerable (spec page 5 §4). */
+        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 WEB2_READ_CHAIN;
+        };
+        /** @deprecated Use `READ.CHAIN.WEB2`. Same value (`'web2'`). */
+        readonly WEB2: "web2";
         readonly NAMESPACE: {
             readonly EVM: "eip155";
             readonly SVM: "solana";
@@ -63,6 +108,17 @@ export declare const CONSTANTS: {
         readonly ERROR_CODE: typeof READ_ERROR_CODE;
         readonly OUTCOME: typeof READ_OUTCOME;
     };
+    /** Checked v5 agentic wallet deployments by Push network (Donut only). */
+    AGENTIC: Readonly<{
+        WALLET: "agentic:wallet";
+        PRESETS: Readonly<{
+            CATEGORY: Readonly<{
+                DEXES: "DEXES";
+                LENDING: "LENDING";
+                PREDICTION: "PREDICTION";
+            }>;
+        }>;
+    }>;
 };
 export type { TypedDataDomain, TypedData };
 export { CHAIN_EXPLORERS, CEA_FACTORY_ADDRESSES, UNIVERSAL_GATEWAY_ADDRESSES, VAULT_ADDRESSES, getExplorerTxUrl, getExplorerAddressUrl, } from './chain';

package/src/lib/constants/index.js

@@ -1,16 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UNIVERSAL_CALLBACK_ADDRESSES = exports.UNIVERSAL_CORE_ADDRESSES = exports.DEFAULT_CEA_TO_PUSH_GAS_LIMIT = exports.DEFAULT_OUTBOUND_GAS_LIMIT = exports.ZERO_ADDRESS = exports.TX_TYPE = exports.MIGRATION_SELECTOR = exports.UEA_MULTICALL_SELECTOR = exports.MULTICALL_SELECTOR = exports.getExplorerAddressUrl = exports.getExplorerTxUrl = exports.VAULT_ADDRESSES = exports.UNIVERSAL_GATEWAY_ADDRESSES = exports.CEA_FACTORY_ADDRESSES = exports.CHAIN_EXPLORERS = exports.CONSTANTS = exports.READ_CONSTANTS = void 0;
+exports.UNIVERSAL_CALLBACK_ADDRESSES = exports.UNIVERSAL_CORE_ADDRESSES = exports.DEFAULT_CEA_TO_PUSH_GAS_LIMIT = exports.DEFAULT_OUTBOUND_GAS_LIMIT = exports.ZERO_ADDRESS = exports.TX_TYPE = exports.MIGRATION_SELECTOR = exports.UEA_MULTICALL_SELECTOR = exports.MULTICALL_SELECTOR = exports.getExplorerAddressUrl = exports.getExplorerTxUrl = exports.VAULT_ADDRESSES = exports.UNIVERSAL_GATEWAY_ADDRESSES = exports.CEA_FACTORY_ADDRESSES = exports.CHAIN_EXPLORERS = exports.CONSTANTS = exports.READ_CONSTANTS = exports.READ_CHAIN = void 0;
 const tslib_1 = require("tslib");
 const enums_1 = require("./enums");
 const tokens_1 = require("./tokens");
 const chain_1 = require("./chain");
 const read_state_1 = require("./read-state");
 const read_state_types_1 = require("../read-state/read-state.types");
+const constants_1 = require("../agentic/constants");
+/**
+ * `PushChain.CONSTANTS.READ.CHAIN` — every read source: all of `CHAIN` (same
+ * string values) plus the enumerable Web2 source. A superset of CHAIN, so
+ * `read({ chain: CHAIN.X })` keeps compiling.
+ */
+exports.READ_CHAIN = Object.freeze({
+    ...enums_1.CHAIN,
+    WEB2: read_state_1.WEB2_READ_CHAIN,
+});
 /** `PushChain.CONSTANTS.READ` — cross-chain read state. Values verified against the deployed UniversalCallback. */
 exports.READ_CONSTANTS = {
-    /** Read-only Web2 destination. Equivalent to `CHAIN.WEB2`. */
-    WEB2: enums_1.CHAIN.WEB2,
+    /** Every read source, enumerable (spec page 5 §4). */
+    CHAIN: exports.READ_CHAIN,
+    /** @deprecated Use `READ.CHAIN.WEB2`. Same value (`'web2'`). */
+    WEB2: read_state_1.WEB2_READ_CHAIN,
     NAMESPACE: read_state_1.READ_NAMESPACE,
     MAX_CALLBACK_GAS_LIMIT: read_state_1.MAX_CALLBACK_GAS_LIMIT,
     MIN_CONFIRMATIONS_FLOOR: read_state_1.MIN_CONFIRMATIONS_FLOOR,
@@ -35,6 +47,8 @@ exports.CONSTANTS = {
     MOVEABLE: { TOKEN: tokens_1.MOVEABLE_TOKEN_CONSTANTS },
     PAYABLE: { TOKEN: tokens_1.PAYABLE_TOKEN_CONSTANTS },
     READ: exports.READ_CONSTANTS,
+    /** Checked v5 agentic wallet deployments by Push network (Donut only). */
+    AGENTIC: constants_1.AGENTIC,
 };
 // Multi-chain configuration exports
 var chain_2 = require("./chain");

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

@@ -32,6 +32,15 @@ export declare const WEB2_MAX_TIMEOUT_MS = 15000;
  * Web2 is not a blockchain and is not a `CHAIN` enum member. Reads target it via
  * an explicit destination; the node routes on namespace `web2`, id `https`.
  */
+/** Public Web2 read source (`READ.CHAIN.WEB2`). */
+export declare const WEB2_READ_CHAIN: "web2";
+/**
+ * Legacy public spelling, and the unchanged CAIP-2 wire identity validators
+ * route on. Still accepted as read input.
+ */
+export declare const LEGACY_WEB2_READ_CHAIN: "web2:https";
+/** True for either public Web2 spelling. */
+export declare function isWeb2ReadChain(chain: unknown): chain is typeof WEB2_READ_CHAIN | typeof LEGACY_WEB2_READ_CHAIN;
 export declare const WEB2_DESTINATION: {
     readonly chainNamespace: "web2";
     readonly chainId: "https";

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

@@ -7,7 +7,8 @@
  * `read-state/__tests__/abi-selectors.spec.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.READ_TRACK_LOOKUP_TIMEOUT_MS = exports.READ_EXPIRY_WARNING_BLOCKS = exports.READ_PREFLIGHT_STALE_MS = exports.READ_TRACK_MAX_TIMEOUT_MS = exports.READ_TRACK_MIN_POLL_INTERVAL_MS = exports.READ_TRACK_POLL_INTERVAL_MS = exports.PUSH_BLOCK_TIME_MS = exports.READ_NAMESPACE = exports.WEB2_DESTINATION = exports.WEB2_MAX_TIMEOUT_MS = exports.WEB2_DEFAULT_TIMEOUT_MS = exports.WEB2_MAX_EXTRACT_ENTRIES = exports.CALLBACK_BUDGET_BUFFER = exports.DEFAULT_EXPIRY_BLOCKS = exports.MIN_CONFIRMATIONS_FLOOR = exports.UNIVERSAL_READ_REGISTRY_ADDRESS = exports.REGISTRY_CALLBACK_GAS = exports.MAX_CALLBACK_GAS_LIMIT = void 0;
+exports.READ_TRACK_LOOKUP_TIMEOUT_MS = exports.READ_EXPIRY_WARNING_BLOCKS = exports.READ_PREFLIGHT_STALE_MS = exports.READ_TRACK_MAX_TIMEOUT_MS = exports.READ_TRACK_MIN_POLL_INTERVAL_MS = exports.READ_TRACK_POLL_INTERVAL_MS = exports.PUSH_BLOCK_TIME_MS = exports.READ_NAMESPACE = exports.WEB2_DESTINATION = exports.LEGACY_WEB2_READ_CHAIN = exports.WEB2_READ_CHAIN = exports.WEB2_MAX_TIMEOUT_MS = exports.WEB2_DEFAULT_TIMEOUT_MS = exports.WEB2_MAX_EXTRACT_ENTRIES = exports.CALLBACK_BUDGET_BUFFER = exports.DEFAULT_EXPIRY_BLOCKS = exports.MIN_CONFIRMATIONS_FLOOR = exports.UNIVERSAL_READ_REGISTRY_ADDRESS = exports.REGISTRY_CALLBACK_GAS = exports.MAX_CALLBACK_GAS_LIMIT = void 0;
+exports.isWeb2ReadChain = isWeb2ReadChain;
 /** Hard upper bound on the gas an app callback may declare — `ReadTypes.sol:50`. */
 exports.MAX_CALLBACK_GAS_LIMIT = 1000000n;
 /** Default callback gas (registry and custom targets); large results may need an explicit override up to the maximum. */
@@ -35,6 +36,17 @@ exports.WEB2_MAX_TIMEOUT_MS = 15_000;
  * Web2 is not a blockchain and is not a `CHAIN` enum member. Reads target it via
  * an explicit destination; the node routes on namespace `web2`, id `https`.
  */
+/** Public Web2 read source (`READ.CHAIN.WEB2`). */
+exports.WEB2_READ_CHAIN = 'web2';
+/**
+ * Legacy public spelling, and the unchanged CAIP-2 wire identity validators
+ * route on. Still accepted as read input.
+ */
+exports.LEGACY_WEB2_READ_CHAIN = 'web2:https';
+/** True for either public Web2 spelling. */
+function isWeb2ReadChain(chain) {
+    return chain === exports.WEB2_READ_CHAIN || chain === exports.LEGACY_WEB2_READ_CHAIN;
+}
 exports.WEB2_DESTINATION = {
     chainNamespace: 'web2',
     chainId: 'https',

package/src/lib/index.d.ts

@@ -7,17 +7,23 @@ export { isPC20Reference } from './orchestrator/orchestrator.types';
 export { PC20Error, InvalidPC20AddressError, PC20TokenChainMismatchError, PC20WrapperNotRegisteredError, PC20RegistryMismatchError, PC20FactoryMismatchError, InvalidPC20MetadataError, PC20ExpectedButPRC20Error, PC20AmbiguousAddressError, UnsupportedPC20DestinationError, InsufficientPC20BalanceError, PC20UnknownChainNamespaceError, PC20WrapperPredictionUnavailableError, PC20ExportRevertedError, PC20UnsafeEmptyPayloadError, } from './orchestrator/internals/pc20/errors';
 export type { ChainTarget, ChainSource, UniversalTo, TransactionRouteType, UniversalExecuteParams, UniversalOutboundTxRequest, PreparedUniversalTx, CascadedTxResponse, CascadeHopInfo, CascadeTrackOptions, CascadeProgressEvent, CascadeCompletionResult, MultiChainTxResponse, OutboundTxDetails, WaitForOutboundOptions, SvmGatewayAccountMeta, SvmExecutePayloadFields, AccountStatus, UEAStatus, RescueFundsParams, } from './orchestrator/orchestrator.types';
 export { parseUEAVersion } from './orchestrator/orchestrator.types';
-export { TransactionRoute, detectRoute, isChainTarget } from './orchestrator/route-detector';
+export { TransactionRoute, detectRoute, isChainTarget, } from './orchestrator/route-detector';
 export { DEFAULT_MAX_PC_FOR_GAS_BUFFER_BPS, MAX_PC_FOR_GAS_BUFFER_BPS_LIMIT, quoteMaxPCForGasCap, quoteMaxPCForGasCapFromNativeValue, } from './orchestrator/max-pc-for-gas';
 export type { MaxPCForGasCapInput, MaxPCForGasCapFromNativeValueInput, MaxPCForGasCapQuote, } from './orchestrator/max-pc-for-gas';
 export { getCEAAddress, getPushAccountForCEA, isCEA, chainSupportsCEA, chainSupportsOutbound, getCEAFactoryAddress, getAllCEAAddresses, } from './orchestrator/cea-utils';
 export { encodeSvmExecutePayload, isSvmChain, isValidSolanaHexAddress, buildMigrationPayload, buildErc20WithdrawalMulticall, } from './orchestrator/payload-builders';
 export type { ReadChain, ReadDestination, ResolvedDestination, ReadQuery, EvmReadQuery, SvmReadQuery, Web2ReadQuery, Web2Extract, Web2ValueType, EncodedReadQuery, ReadResultShape, DecodedReadResult, ReadPreflight, ReadSpec, ReadSpecTuple, BuildReadSpecParams, PreparedRead, ReadCallback, SimulateReadResult, ParsedReadRequest, FulfilOutcome, ReceiptLike, ReadRef, ReadLifecycleOptions, ReadFees, UniversalReadResponse, ReadResponseTuple, BatchReadResponse, } from './read-state/read-state.types';
-export type { ReadOptions, ReadPrepareOptions, ReadQueryOptions, ReadCallbackOptions, ReadValue, ValidateReadCall, ReadWeb2Options, ReadTrackOptions, ReadExecuteOptions } from './read-state/read-params';
+export type { ReadOptions, ReadPrepareOptions, ReadQueryOptions, ReadCallbackOptions, ReadValue, ValidateReadCall, ReadWeb2Options, ReadTrackOptions, ReadExecuteOptions, } from './read-state/read-params';
 export { UNIVERSAL_READ_STATUS, READ_STATUS, READ_ERROR_CODE, READ_OUTCOME, CONTRACT_REQUEST_STATUS, TERMINAL_READ_STATUSES, } from './read-state/read-state.types';
 export { ReadStateError, InvalidReadQueryError, InvalidReadSpecError, ReadHeightUnavailableError, UnsupportedReadDestinationError, ReadDecodeError, ReadTimeoutError, ReadNotFoundError, ReadRegistryUnavailableError, } from './read-state/errors';
 export type { ReadSpecViolation } from './read-state/errors';
 export { resolveDestination, encodeReadQuery, decodeReadResult, parseReadRequestsFromReceipt, parseFulfilOutcome, buildReadSpecFromPreflight, validateReadSpec, toCallData, sizeCallbackBudget, inferResultShape, toRequestIdHex, toReadQuery, } from './read-state';
 export { UNIVERSAL_CALLBACK_EVM } from './constants/abi/universalCallback.evm';
 export { UNIVERSAL_READ_REGISTRY_EVM } from './constants/abi/universalReadRegistry.evm';
+export { PushChainExecutionError, PushChainBatchExecutionError, } from './orchestrator/internals/errors';
+export type { DecodedErrorPayload } from './orchestrator/internals/errors';
+export type { PushChainInitializeOptions } from './push-chain/push-chain';
+export { AGENTIC_ERROR_CODE, AgenticError, AgenticRevertError, } from './agentic';
+export type { AgenticAddress, AgenticDoor, AgenticErrorCode, AgenticHex, AgenticNamespace, AgenticProgressHook, AgenticTxMetadata, AgenticWallet, AllowedCall, AssetCap, Checkpoint, CheckpointKind, CreateOptions, CreateResult, ForeignChainNamespace, DecodedSolanaRule, Rule, RuleInput, Pin, Spent, WalletMarker, RulesRecord, Selector, WalletInfo, WalletSummary, } from './agentic';
 export { PushChain };
+export type { Preset, PresetCategory, PresetAsset, PresetOptions, ReadyPresetOptions, PresetRuleTemplate, AgenticPresets, } from './agentic';

package/src/lib/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReadTimeoutError = exports.ReadDecodeError = exports.UnsupportedReadDestinationError = exports.ReadHeightUnavailableError = exports.InvalidReadSpecError = exports.InvalidReadQueryError = exports.ReadStateError = exports.TERMINAL_READ_STATUSES = exports.CONTRACT_REQUEST_STATUS = exports.READ_OUTCOME = exports.READ_ERROR_CODE = exports.READ_STATUS = exports.UNIVERSAL_READ_STATUS = exports.buildErc20WithdrawalMulticall = exports.buildMigrationPayload = exports.isValidSolanaHexAddress = exports.isSvmChain = exports.encodeSvmExecutePayload = exports.getAllCEAAddresses = exports.getCEAFactoryAddress = exports.chainSupportsOutbound = exports.chainSupportsCEA = exports.isCEA = exports.getPushAccountForCEA = exports.getCEAAddress = exports.quoteMaxPCForGasCapFromNativeValue = exports.quoteMaxPCForGasCap = exports.MAX_PC_FOR_GAS_BUFFER_BPS_LIMIT = exports.DEFAULT_MAX_PC_FOR_GAS_BUFFER_BPS = exports.isChainTarget = exports.detectRoute = exports.TransactionRoute = exports.parseUEAVersion = exports.PC20UnsafeEmptyPayloadError = exports.PC20ExportRevertedError = exports.PC20WrapperPredictionUnavailableError = exports.PC20UnknownChainNamespaceError = exports.InsufficientPC20BalanceError = exports.UnsupportedPC20DestinationError = exports.PC20AmbiguousAddressError = exports.PC20ExpectedButPRC20Error = exports.InvalidPC20MetadataError = exports.PC20FactoryMismatchError = exports.PC20RegistryMismatchError = exports.PC20WrapperNotRegisteredError = exports.PC20TokenChainMismatchError = exports.InvalidPC20AddressError = exports.PC20Error = exports.isPC20Reference = exports.CHAIN = void 0;
-exports.PushChain = exports.UNIVERSAL_READ_REGISTRY_EVM = exports.UNIVERSAL_CALLBACK_EVM = exports.toReadQuery = exports.toRequestIdHex = exports.inferResultShape = exports.sizeCallbackBudget = exports.toCallData = exports.validateReadSpec = exports.buildReadSpecFromPreflight = exports.parseFulfilOutcome = exports.parseReadRequestsFromReceipt = exports.decodeReadResult = exports.encodeReadQuery = exports.resolveDestination = exports.ReadRegistryUnavailableError = exports.ReadNotFoundError = void 0;
+exports.PushChain = exports.AgenticRevertError = exports.AgenticError = exports.AGENTIC_ERROR_CODE = exports.PushChainBatchExecutionError = exports.PushChainExecutionError = exports.UNIVERSAL_READ_REGISTRY_EVM = exports.UNIVERSAL_CALLBACK_EVM = exports.toReadQuery = exports.toRequestIdHex = exports.inferResultShape = exports.sizeCallbackBudget = exports.toCallData = exports.validateReadSpec = exports.buildReadSpecFromPreflight = exports.parseFulfilOutcome = exports.parseReadRequestsFromReceipt = exports.decodeReadResult = exports.encodeReadQuery = exports.resolveDestination = exports.ReadRegistryUnavailableError = exports.ReadNotFoundError = void 0;
 const push_chain_1 = require("./push-chain/push-chain");
 Object.defineProperty(exports, "PushChain", { enumerable: true, get: function () { return push_chain_1.PushChain; } });
 var enums_1 = require("./constants/enums");
@@ -88,4 +88,12 @@ var universalCallback_evm_1 = require("./constants/abi/universalCallback.evm");
 Object.defineProperty(exports, "UNIVERSAL_CALLBACK_EVM", { enumerable: true, get: function () { return universalCallback_evm_1.UNIVERSAL_CALLBACK_EVM; } });
 var universalReadRegistry_evm_1 = require("./constants/abi/universalReadRegistry.evm");
 Object.defineProperty(exports, "UNIVERSAL_READ_REGISTRY_EVM", { enumerable: true, get: function () { return universalReadRegistry_evm_1.UNIVERSAL_READ_REGISTRY_EVM; } });
+// Structured execution errors (base class of AgenticRevertError)
+var errors_3 = require("./orchestrator/internals/errors");
+Object.defineProperty(exports, "PushChainExecutionError", { enumerable: true, get: function () { return errors_3.PushChainExecutionError; } });
+Object.defineProperty(exports, "PushChainBatchExecutionError", { enumerable: true, get: function () { return errors_3.PushChainBatchExecutionError; } });
+var agentic_1 = require("./agentic");
+Object.defineProperty(exports, "AGENTIC_ERROR_CODE", { enumerable: true, get: function () { return agentic_1.AGENTIC_ERROR_CODE; } });
+Object.defineProperty(exports, "AgenticError", { enumerable: true, get: function () { return agentic_1.AgenticError; } });
+Object.defineProperty(exports, "AgenticRevertError", { enumerable: true, get: function () { return agentic_1.AgenticRevertError; } });
 //# sourceMappingURL=index.js.map

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

@@ -39,11 +39,18 @@ export declare class PushChainExecutionError extends Error {
     readonly code: "PUSH_CHAIN_EXECUTION_FAILED";
     readonly gatewayTxHash?: string;
     readonly decodedError?: DecodedErrorPayload;
+    /** Underlying transport/RPC error, kept so raw revert data is not lost. */
+    readonly cause?: unknown;
     constructor(message: string, opts?: {
         gatewayTxHash?: string;
         decodedError?: DecodedErrorPayload;
+        cause?: unknown;
     });
 }
+/** @internal A caller required an atomic native batch; sequential fallback is forbidden. */
+export declare class AtomicBatchUnavailableError extends PushChainExecutionError {
+    constructor(message: string, cause?: unknown);
+}
 /** Recovery metadata for a non-atomic Push batch. A pending hash is broadcast but unconfirmed. */
 export declare class PushChainBatchExecutionError extends PushChainExecutionError {
     readonly transactionHashes: `0x${string}`[];