@pushchain/core 6.0.26 → 6.0.27-alpha.1

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

@@ -0,0 +1,58 @@
+import { type Address } from 'viem';
+import { CHAIN, PUSH_NETWORK } from '../constants/enums';
+import type { MoveableToken } from '../constants/tokens';
+import type { Orchestrator } from '../orchestrator/orchestrator';
+import type { ExecuteParams, TransactionExecutionOptions, UniversalExecuteParams, UniversalTxResponse } from '../orchestrator/orchestrator.types';
+import type { ProgressEvent } from '../progress-hook/progress-hook.types';
+import { type ChainReader } from './contracts/reader';
+import type { SvmMetadataProvider } from './management/svm-context';
+import type { AgenticProgressHook } from './agentic.types';
+/**
+ * Everything the AGW module needs from the surrounding client. Tests supply a
+ * mock; PushChain builds the real one from its orchestrator. Keeping this
+ * explicit is what separates the signer's identity (gas, account status,
+ * ownership derivation) from the AGW execution account.
+ */
+export interface AgenticRuntime {
+    readonly network: PUSH_NETWORK;
+    /** 'eip155:<id>' of the connected Push chain — the native rule chain. */
+    readonly pushChainNamespace: string;
+    readonly reader: ChainReader;
+    readonly isReadOnly: boolean;
+    readonly svmMetadata?: SvmMetadataProvider;
+    /** Connected signer's Push identity: its EOA, or its UEA for its actual origin chain. */
+    signerPushAccount(): Address;
+    /** Connected signer's origin account (universal.origin). */
+    signerOrigin(): {
+        chain: CHAIN;
+        address: string;
+    };
+    signerIsPushNative(): boolean;
+    /** The signer's ordinary transaction path (orchestrator.execute). */
+    execute(params: ExecuteParams | UniversalExecuteParams, options?: TransactionExecutionOptions): Promise<UniversalTxResponse>;
+    /** Sender-preserving UEA/7702 transport; native sequential fallback is forbidden. */
+    executeAtomicBatch(params: ExecuteParams, options?: TransactionExecutionOptions): Promise<UniversalTxResponse>;
+    /** Emit to the init-time hook and, if different, the per-call hook. */
+    emit(event: ProgressEvent, perCallHook?: AgenticProgressHook): void;
+    /** Whether the signer's own UEA is deployed (always true for a Push EOA). */
+    signerAccountDeployed(): Promise<boolean>;
+    signerBalance(): Promise<bigint>;
+    getGasPrice(): Promise<bigint>;
+    quoteOutbound(prc20: Address, gasLimit: bigint, chain: CHAIN, svm?: {
+        wallet: Address;
+        splMintBase58?: string;
+        burnAmount: bigint;
+    }): Promise<{
+        protocolFee: bigint;
+        nativeValueForGas: bigint;
+        gasLimitUsed: bigint;
+    }>;
+    resolveCEA(account: Address, chain: CHAIN): Promise<{
+        cea: Address;
+        isDeployed: boolean;
+    }>;
+    resolvePrc20(token: MoveableToken | string | undefined, chain: CHAIN): Address;
+    nowSeconds(): number;
+}
+/** Build the runtime over an orchestrator (the orchestrator IS the internal ctx). */
+export declare function createAgenticRuntime(orchestrator: Orchestrator, isReadOnly: boolean): AgenticRuntime;

package/src/lib/agentic/runtime.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgenticRuntime = createAgenticRuntime;
+const viem_1 = require("viem");
+const enums_1 = require("../constants/enums");
+const errors_1 = require("../orchestrator/internals/errors");
+const errors_2 = require("./errors");
+const cea_utils_1 = require("../orchestrator/cea-utils");
+const uea_manager_1 = require("../orchestrator/internals/uea-manager");
+const svm_rent_1 = require("../orchestrator/internals/svm-rent");
+const gas_calculator_1 = require("../orchestrator/internals/gas-calculator");
+const helpers_1 = require("../orchestrator/internals/helpers");
+const chain_1 = require("./chain");
+const prc20_address_1 = require("../universal/prc20-address");
+const reader_1 = require("./contracts/reader");
+const svm_metadata_1 = require("./management/svm-metadata");
+const chain_2 = require("../constants/chain");
+/** Build the runtime over an orchestrator (the orchestrator IS the internal ctx). */
+function createAgenticRuntime(orchestrator, isReadOnly) {
+    const ctx = orchestrator;
+    const network = orchestrator.getNetwork();
+    return {
+        network,
+        pushChainNamespace: (0, chain_1.pushChainNamespaceFor)(network),
+        get reader() {
+            return (0, reader_1.chainReaderFromPublicClient)(ctx.pushClient.publicClient);
+        },
+        isReadOnly,
+        svmMetadata: (0, svm_metadata_1.createSvmMetadataProvider)({
+            [enums_1.CHAIN.SOLANA_DEVNET]: {
+                gatewayProgram: chain_2.CHAIN_INFO[enums_1.CHAIN.SOLANA_DEVNET].lockerContract ?? '',
+                rpcUrls: orchestrator.getRpcUrls()[enums_1.CHAIN.SOLANA_DEVNET] ??
+                    chain_2.CHAIN_INFO[enums_1.CHAIN.SOLANA_DEVNET].defaultRPC,
+            },
+        }),
+        signerPushAccount: () => (0, viem_1.getAddress)((0, uea_manager_1.computeUEAOffchain)(ctx)),
+        signerOrigin: () => orchestrator.getUOA(),
+        signerIsPushNative: () => (0, helpers_1.isPushChain)(ctx.universalSigner.account.chain),
+        execute: (params, options) => orchestrator.execute(params, options),
+        executeAtomicBatch: async (params, options) => {
+            try {
+                return await orchestrator.executeAtomicBatch(params, options);
+            }
+            catch (error) {
+                if (error instanceof errors_1.AtomicBatchUnavailableError) {
+                    throw (0, errors_2.capabilityUnavailable)('atomicNativeAgentBatch', error.message);
+                }
+                throw error;
+            }
+        },
+        emit: (event, perCallHook) => {
+            const base = orchestrator.getProgressHook();
+            base?.(event);
+            if (perCallHook && perCallHook !== base)
+                perCallHook(event);
+        },
+        signerAccountDeployed: async () => {
+            if ((0, helpers_1.isPushChain)(ctx.universalSigner.account.chain))
+                return true;
+            const status = await orchestrator.getAccountStatus();
+            return status.uea.deployed;
+        },
+        signerBalance: () => ctx.pushClient.getBalance((0, uea_manager_1.computeUEAOffchain)(ctx)),
+        getGasPrice: () => ctx.pushClient.getGasPrice(),
+        quoteOutbound: async (prc20, gasLimit, chain, svm) => {
+            let q = await (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20, gasLimit, chain);
+            if (svm) {
+                q = await (0, svm_rent_1.ensureSvmFinalizeGasBudgetQuote)({
+                    ctx,
+                    ueaAddress: svm.wallet,
+                    targetChain: chain,
+                    prc20Token: prc20,
+                    quote: q,
+                    splMintBase58: svm.splMintBase58,
+                    burnAmount: svm.burnAmount,
+                    pathTag: 'AGW_SVM',
+                });
+            }
+            return {
+                protocolFee: q.protocolFee,
+                nativeValueForGas: q.nativeValueForGas,
+                gasLimitUsed: q.gasLimitUsed,
+            };
+        },
+        resolveCEA: async (account, chain) => {
+            const r = await (0, cea_utils_1.getCEAAddress)(account, chain, orchestrator.getRpcUrls()[chain]?.[0]);
+            return { cea: (0, viem_1.getAddress)(r.cea), isDeployed: r.isDeployed };
+        },
+        resolvePrc20: (token, chain) => {
+            if (!token)
+                return (0, viem_1.getAddress)((0, helpers_1.getNativePRC20ForChain)(chain, network));
+            // Native ETH shares a symbol/address across chains. A plain token must
+            // resolve within the known destination, never the first global match.
+            if (typeof token === 'object' && 'prc20Address' in token) {
+                if (!('sourceChain' in token) || token.sourceChain !== chain)
+                    throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.ASSET_CHAIN_MISMATCH, 'Push token source chain must match the destination chain');
+                return (0, viem_1.getAddress)((0, prc20_address_1.getPRC20Address)(token, { network }).address);
+            }
+            return (0, viem_1.getAddress)((0, prc20_address_1.getPRC20Address)({ chain, address: typeof token === 'string' ? token : token.address }, { network }).address);
+        },
+        nowSeconds: () => Math.floor(Date.now() / 1000),
+    };
+}
+//# sourceMappingURL=runtime.js.map

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

@@ -0,0 +1,57 @@
+import { type Address, type Hex } from 'viem';
+import { PUSH_NETWORK } from '../constants/enums';
+import type { AgenticHex, InternalRule, Selector, DecodedSolanaRule } from './agentic.types';
+import type { UniversalRule } from './agentic.types';
+import type { ResolvedUniversalRule } from './codec/universal';
+/**
+ * Internal generation context. Harsh H4.1 (October 4): deployment inputs
+ * are implementation details, not public helper parameters.
+ */
+export interface RulesEncodeContext {
+    /** Connected Push network, or an explicit 'eip155:<id>' native chain. */
+    network?: PUSH_NETWORK;
+    pushChainNamespace?: string;
+    validator: Address;
+    rulesPolicy: Address;
+    gateway?: Address;
+    universal?: ReadonlyMap<UniversalRule, ResolvedUniversalRule>;
+    /** Wallet owner, for the AGENT_IS_OWNER check. */
+    owner?: Address;
+    /** Defaults to the current time. */
+    nowSeconds?: number;
+}
+/** Internal codecs and identities — not exported from the package entry point. */
+export declare const internalAgenticUtils: {
+    /** The ID a grant with this grantNonce produces. Chain is not part of the hash. */
+    rulesId(agent: Address, grantNonce: bigint | number, ctx: {
+        validator: Address;
+    }): AgenticHex;
+    /** Hash of one allowed call: keccak256(target ‖ selector). */
+    actionId(target: Address, selector: Selector | "value-only"): AgenticHex;
+    /** Key of one allowed call's stored config under one rule on one wallet. */
+    configId(wallet: Address, rulesId: Hex, actionId: Hex): AgenticHex;
+    /** Any-owner wallet address. */
+    deriveWallet(owner: Address, index: bigint | number, ctx: {
+        factory: Address;
+        walletImplementation: Address;
+    }): Address;
+    /**
+     * 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: readonly InternalRule[], ctx: RulesEncodeContext): AgenticHex[];
+    /** Inverse of encodeRules for one Session encoding. */
+    decodeRules(bytes: Hex, ctx?: {
+        network?: PUSH_NETWORK;
+        pushChainNamespace?: string;
+    }): InternalRule | DecodedSolanaRule;
+};
+/** Public helpers requiring no contract deployment context. */
+export declare const agenticUtils: {
+    actionId: (target: Address, selector: Selector | "value-only") => AgenticHex;
+    configId: (wallet: Address, rulesId: Hex, actionId: Hex) => AgenticHex;
+    decodeRules: (bytes: Hex, ctx?: {
+        network?: PUSH_NETWORK;
+        pushChainNamespace?: string;
+    }) => InternalRule | DecodedSolanaRule;
+};

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.V6_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.