@pushchain/core 6.0.25 → 6.0.27-alpha.0

package/src/lib/agentic/management/prepare.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareWalletRules = prepareWalletRules;
+const public_rule_1 = require("../public-rule");
+const svm_public_1 = require("./svm-public");
+const viem_1 = require("viem");
+const enums_1 = require("../../constants/enums");
+const chain_1 = require("../../constants/chain");
+const defaults_1 = require("../codec/defaults");
+const rules_1 = require("../codec/rules");
+const universal_1 = require("../codec/universal");
+const deployments_1 = require("../deployments");
+const capabilities_1 = require("../capabilities");
+const errors_1 = require("../errors");
+const prc20_metadata_1 = require("../contracts/prc20-metadata");
+/** Resolve wallet-dependent wire inputs without signing or mutating authority. */
+async function prepareWalletRules(runtime, gen, owner, wallet, inputs, snap) {
+    const rules = await Promise.all(inputs.map((rule) => (0, public_rule_1.isPublicRule)(rule) ? (0, public_rule_1.normalizePublicRule)(rule, wallet, runtime) : rule));
+    if (rules.length)
+        await (0, deployments_1.verifyPolicyVersion)(runtime.reader, gen);
+    const svm = new Map();
+    const universal = new Map();
+    for (const rule of rules) {
+        if (rule && (0, rules_1.isSolanaRule)(rule)) {
+            (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.UNIVERSAL_SVM_RULES);
+            svm.set(rule, await (0, svm_public_1.preparePublicSvmRule)(runtime, snap, wallet, rule));
+            continue;
+        }
+        if (!(0, rules_1.isUniversalRule)(rule))
+            continue;
+        if (rule.chainNamespace.startsWith('solana:'))
+            (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.UNIVERSAL_SVM_RULES);
+        (0, universal_1.validateUniversalRuleShape)(rule, runtime.nowSeconds());
+        (0, capabilities_1.requireCapability)(gen.capabilities, rule.chainNamespace.startsWith('solana:')
+            ? capabilities_1.AgenticCapability.UNIVERSAL_SVM_RULES
+            : capabilities_1.AgenticCapability.UNIVERSAL_EVM_RULES);
+        const chain = rule.chainNamespace;
+        if (chain_1.CHAIN_INFO[chain]?.vm !== enums_1.VM.EVM)
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `unsupported EVM rule chain ${chain}`);
+        const { cea } = await runtime.resolveCEA(wallet, chain);
+        const assets = rule.assets.length
+            ? rule.assets.map((a) => ({
+                token: typeof a.token === 'string' && (0, viem_1.getAddress)(a.token) === viem_1.zeroAddress
+                    ? undefined
+                    : a.token,
+                maxPerCall: a.maxPerCall,
+                maxTotal: (0, defaults_1.withDefault)(a.maxTotal, defaults_1.AGENTIC_DEFAULTS.universal.assetMaxTotal),
+            }))
+            : [{ token: undefined, maxPerCall: BigInt(0), maxTotal: BigInt(0) }];
+        const resolved = [];
+        for (const asset of assets) {
+            const token = asset.token === undefined
+                ? await (0, prc20_metadata_1.readGasPrc20)(snap, chain)
+                : runtime.resolvePrc20(asset.token, chain);
+            if (token === viem_1.zeroAddress)
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `no gas PRC20 registered for ${chain}`);
+            const namespace = await snap.read(token, prc20_metadata_1.PRC20_SOURCE_ABI, 'SOURCE_CHAIN_NAMESPACE');
+            if (namespace !== chain)
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.ASSET_CHAIN_MISMATCH, `PRC20 ${token} belongs to ${namespace}, not ${chain}`);
+            if (asset.token !== undefined) {
+                const expected = typeof asset.token === 'string'
+                    ? (0, viem_1.getAddress)(asset.token)
+                    : (0, viem_1.getAddress)(asset.token.address);
+                if (expected === viem_1.zeroAddress) {
+                    if ((await (0, prc20_metadata_1.readGasPrc20)(snap, chain)) !== (0, viem_1.getAddress)(token))
+                        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'resolved token is not the registered native gas token');
+                }
+                else {
+                    const source = await (0, prc20_metadata_1.readOriginToken)(snap, token, chain);
+                    if (source !== expected)
+                        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `PRC20 ${token} represents ${source}, not requested token ${expected}`);
+                }
+            }
+            resolved.push({
+                token: (0, viem_1.getAddress)(token),
+                maxPerCall: asset.maxPerCall,
+                maxTotal: asset.maxTotal,
+            });
+        }
+        universal.set(rule, { expectedCEA: (0, viem_1.getAddress)(cea), assets: resolved });
+    }
+    return (0, rules_1.prepareRules)(rules, {
+        owner,
+        pushChainNamespace: runtime.pushChainNamespace,
+        validator: gen.addresses.sessionValidator,
+        rulesPolicy: gen.addresses.rulesPolicy,
+        gateway: gen.addresses.gateway,
+        capabilities: gen.capabilities,
+        nowSeconds: runtime.nowSeconds(),
+        forbiddenTargets: (0, deployments_1.forbiddenTargets)(gen, wallet),
+        universal,
+        svm,
+    });
+}
+//# sourceMappingURL=prepare.js.map

package/src/lib/agentic/management/rules-write.d.ts

@@ -0,0 +1,42 @@
+import type { Address } from 'viem';
+import type { UniversalTxResponse } from '../../orchestrator/orchestrator.types';
+import { type AgenticGeneration } from '../deployments';
+import type { AgenticRuntime } from '../runtime';
+import type { AgenticHex, AgenticProgressHook, InternalRule } from '../agentic.types';
+/** w.rules.add(rules): owner grants on an existing wallet, IDs in input order. */
+export declare function addRules(runtime: AgenticRuntime, gen: AgenticGeneration, wallet: Address, rules: readonly InternalRule[], hook?: AgenticProgressHook): Promise<{
+    rulesIds: AgenticHex[];
+    tx: UniversalTxResponse;
+}>;
+/** Bare revoke (no IDs, empty list, or anything but { all: true }) is refused. */
+export declare function assertRevokeTarget(target: unknown): {
+    all: boolean;
+    ids?: AgenticHex[];
+};
+/** w.rules.delete(ids) / w.rules.delete({ all: true }). Bare revoke is refused. */
+export declare function revokeRules(runtime: AgenticRuntime, gen: AgenticGeneration, wallet: Address, target: AgenticHex[] | {
+    all: true;
+    progressHook?: AgenticProgressHook;
+} | undefined, hook?: AgenticProgressHook): Promise<UniversalTxResponse>;
+/**
+ * w.rules.update({ rules: [{ rulesId, rule }] }): for every pair, inside ONE
+ * owner `execute` batch: assertSpent(expected) → revokeRules(old) →
+ * grantRules(new). Never falls back to sequential sends. An agent spending
+ * between the read and inclusion makes the whole batch revert; retry needs a
+ * fresh read and a new owner signature. New counters start at zero.
+ */
+export declare function updateRules(runtime: AgenticRuntime, gen: AgenticGeneration, wallet: Address, params: {
+    rules: {
+        rulesId: AgenticHex;
+        rule: InternalRule;
+    }[];
+    progressHook?: AgenticProgressHook;
+}): Promise<{
+    rules: {
+        rulesId: AgenticHex;
+        replaced: AgenticHex;
+    }[];
+    tx: UniversalTxResponse;
+}>;
+/** Direct owner rename; empty resets the default label without a checkpoint. */
+export declare function setLabel(runtime: AgenticRuntime, gen: AgenticGeneration, wallet: Address, label: string, hook?: AgenticProgressHook): Promise<UniversalTxResponse>;

package/src/lib/agentic/management/rules-write.js

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addRules = addRules;
+exports.assertRevokeTarget = assertRevokeTarget;
+exports.revokeRules = revokeRules;
+exports.updateRules = updateRules;
+exports.setLabel = setLabel;
+const duplicates_1 = require("./duplicates");
+const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
+const capabilities_1 = require("../capabilities");
+const ids_1 = require("../codec/ids");
+const prepare_1 = require("./prepare");
+const label_1 = require("./label");
+const errors_1 = require("../errors");
+const rules_1 = require("../reads/rules");
+const snapshot_1 = require("../reads/snapshot");
+const common_1 = require("./common");
+const MODE_NATIVE = 1;
+async function finish(runtime, hook, operation, run) {
+    try {
+        const result = await run();
+        (0, common_1.emitAgentic)(runtime, hook, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_199_01, operation, result.tx.hash);
+        return result;
+    }
+    catch (err) {
+        const wrapped = (0, common_1.wrapSendError)(err);
+        (0, common_1.emitAgentic)(runtime, hook, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_199_02, operation, wrapped?.code ?? 'UNKNOWN', wrapped?.message ?? String(err), wrapped?.decodedError);
+        throw wrapped;
+    }
+}
+/** w.rules.add(rules): owner grants on an existing wallet, IDs in input order. */
+async function addRules(runtime, gen, wallet, rules, hook) {
+    (0, common_1.assertCanSign)(runtime, 'rules.add');
+    if (!Array.isArray(rules) || rules.length === 0) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'rules.add needs at least one rule');
+    }
+    const snap = await snapshot_1.Snapshot.at(runtime.reader);
+    const owner = await (0, common_1.assertOwner)(runtime, gen, wallet, snap);
+    const prepared = await (0, prepare_1.prepareWalletRules)(runtime, gen, owner, wallet, rules, snap);
+    (0, duplicates_1.assertNoDuplicateRules)(prepared, await (0, rules_1.readActiveRules)(snap, gen, wallet));
+    const nonce = BigInt(await snap.read(wallet, gen.contracts.abis.wallet, 'grantNonce'));
+    const predicted = prepared.map((p, i) => (0, ids_1.rulesId)({
+        validator: gen.addresses.sessionValidator,
+        agent: p.agent,
+        grantNonce: nonce + BigInt(i),
+    }));
+    // One rule: a direct owner grant (one RULES_GRANTED tick). Several: one
+    // owner `execute` batch of self-calls, so the grants are atomic and need a
+    // single signature on every signer type (each grant then also ticks one
+    // OWNER_ACTION before its RULES_GRANTED).
+    const grants = prepared.map((p) => gen.contracts.encodeGrantRules(p.session));
+    const calls = grants.length === 1
+        ? [{ to: wallet, value: BigInt(0), data: grants[0] }]
+        : [
+            {
+                to: wallet,
+                value: BigInt(0),
+                data: gen.contracts.encodeExecute(grants.map((data) => ({ target: wallet, value: BigInt(0), data }))),
+            },
+        ];
+    return finish(runtime, hook, 'rules.add', async () => {
+        const tx = await (0, common_1.sendOwnerCalls)(runtime, calls, hook);
+        const { logs } = await (0, common_1.confirmedLogs)(runtime, tx);
+        const granted = gen.contracts
+            .parseRulesGranted(logs, wallet)
+            .map((g) => g.rulesId);
+        if (!sameIds(granted, predicted)) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RECEIPT_MISMATCH, 'RulesGranted events do not match the requested rules in order (a concurrent grant may have raced)', { details: { granted, predicted, txHash: tx.hash } });
+        }
+        (0, common_1.emitAgentic)(runtime, hook, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_104, granted);
+        return { rulesIds: granted, tx };
+    });
+}
+/** Bare revoke (no IDs, empty list, or anything but { all: true }) is refused. */
+function assertRevokeTarget(target) {
+    const all = !!target &&
+        !Array.isArray(target) &&
+        target.all === true;
+    const ids = Array.isArray(target) ? target : undefined;
+    if (!all && (!ids || ids.length === 0)) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.DELETE_NEEDS_TARGET, 'rules.delete needs explicit rule IDs or { all: true }', {
+            hint: 'A bare revoke that wipes every rule is too easy to make by mistake.',
+        });
+    }
+    return { all, ids };
+}
+/** w.rules.delete(ids) / w.rules.delete({ all: true }). Bare revoke is refused. */
+async function revokeRules(runtime, gen, wallet, target, hook) {
+    const { all, ids } = assertRevokeTarget(target);
+    if (all)
+        hook =
+            target.progressHook ?? hook;
+    (0, common_1.assertCanSign)(runtime, 'rules.delete');
+    const snap = await snapshot_1.Snapshot.at(runtime.reader);
+    await (0, common_1.assertOwner)(runtime, gen, wallet, snap);
+    let calls;
+    if (all) {
+        calls = [
+            {
+                to: wallet,
+                value: BigInt(0),
+                data: gen.contracts.encodeRevokeAllRules(),
+            },
+        ];
+    }
+    else {
+        const unique = new Set(ids.map((i) => i.toLowerCase()));
+        if (unique.size !== ids.length) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'rules.delete got the same rule ID twice');
+        }
+        for (const id of ids) {
+            const enabled = await snap.read(gen.addresses.sessionEngine, gen.contracts.abis.engine, 'isPermissionEnabled', [id, wallet]);
+            if (!enabled) {
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_NOT_FOUND, `rule ${id} is not enabled on ${wallet}`);
+            }
+        }
+        // Several IDs go through one owner `execute` batch so revocation is atomic
+        // regardless of signer batching support.
+        calls =
+            ids.length === 1
+                ? [
+                    {
+                        to: wallet,
+                        value: BigInt(0),
+                        data: gen.contracts.encodeRevokeRules(ids[0]),
+                    },
+                ]
+                : [
+                    {
+                        to: wallet,
+                        value: BigInt(0),
+                        data: gen.contracts.encodeExecute(ids.map((id) => ({
+                            target: wallet,
+                            value: BigInt(0),
+                            data: gen.contracts.encodeRevokeRules(id),
+                        }))),
+                    },
+                ];
+    }
+    const result = await finish(runtime, hook, 'rules.delete', async () => {
+        const tx = await (0, common_1.sendOwnerCalls)(runtime, calls, hook);
+        const { logs } = await (0, common_1.confirmedLogs)(runtime, tx);
+        const revoked = gen.contracts
+            .parseRulesRevoked(logs, wallet)
+            .map((r) => r.rulesId);
+        (0, common_1.emitAgentic)(runtime, hook, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_105, all ? { all: true } : { rulesIds: revoked });
+        return { tx };
+    });
+    return result.tx;
+}
+/**
+ * w.rules.update({ rules: [{ rulesId, rule }] }): for every pair, inside ONE
+ * owner `execute` batch: assertSpent(expected) → revokeRules(old) →
+ * grantRules(new). Never falls back to sequential sends. An agent spending
+ * between the read and inclusion makes the whole batch revert; retry needs a
+ * fresh read and a new owner signature. New counters start at zero.
+ */
+async function updateRules(runtime, gen, wallet, params) {
+    const hook = params?.progressHook;
+    (0, common_1.assertCanSign)(runtime, 'rules.update');
+    if (!params || !Array.isArray(params.rules) || params.rules.length === 0) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'rules.update needs at least one { rulesId, rule } pair');
+    }
+    (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.OWNER_EXECUTE);
+    const oldIds = params.rules.map((p) => p.rulesId.toLowerCase());
+    if (new Set(oldIds).size !== oldIds.length) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'rules.update names the same old rule twice');
+    }
+    const snap = await snapshot_1.Snapshot.at(runtime.reader);
+    const owner = await (0, common_1.assertOwner)(runtime, gen, wallet, snap);
+    const active = await (0, rules_1.readActiveRules)(snap, gen, wallet);
+    const byId = new Map(active.map((r) => [r.rulesId.toLowerCase(), r]));
+    const assertions = [];
+    for (const pair of params.rules) {
+        const old = byId.get(pair.rulesId.toLowerCase());
+        if (!old)
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_NOT_FOUND, `rule ${pair.rulesId} is not enabled on ${wallet}`);
+        if (old.mode === MODE_NATIVE) {
+            (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.ASSERT_SPENT_NATIVE);
+            const guards = [];
+            for (const action of old.actionIds) {
+                const spend = await (0, rules_1.readNativeSpend)(snap, gen, wallet, old, action);
+                guards.push({
+                    configId: spend.configId,
+                    data: gen.contracts.encodeAssertSpentNative(spend.configId, wallet, spend),
+                });
+            }
+            assertions.push(guards);
+        }
+        else {
+            (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.ASSERT_SPENT_UNIVERSAL_MULTI);
+            const spend = await (0, rules_1.readUniversalSpend)(snap, gen, wallet, old);
+            assertions.push([
+                {
+                    configId: spend.configId,
+                    data: gen.contracts.encodeAssertSpentUniversal(spend.configId, wallet, spend.expectedSpent),
+                },
+            ]);
+        }
+    }
+    const prepared = await (0, prepare_1.prepareWalletRules)(runtime, gen, owner, wallet, params.rules.map((p) => p.rule), snap);
+    const nonce = BigInt(await snap.read(wallet, gen.contracts.abis.wallet, 'grantNonce'));
+    const predicted = prepared.map((p, i) => (0, ids_1.rulesId)({
+        validator: gen.addresses.sessionValidator,
+        agent: p.agent,
+        grantNonce: nonce + BigInt(i),
+    }));
+    const batch = params.rules.flatMap((pair, i) => [
+        ...assertions[i].map((a) => ({
+            target: gen.addresses.rulesPolicy,
+            value: BigInt(0),
+            data: a.data,
+        })),
+        {
+            target: wallet,
+            value: BigInt(0),
+            data: gen.contracts.encodeRevokeRules(pair.rulesId),
+        },
+        {
+            target: wallet,
+            value: BigInt(0),
+            data: gen.contracts.encodeGrantRules(prepared[i].session),
+        },
+    ]);
+    const call = {
+        to: wallet,
+        value: BigInt(0),
+        data: gen.contracts.encodeExecute(batch),
+    };
+    return finish(runtime, hook, 'rules.update', async () => {
+        const tx = await (0, common_1.sendOwnerCalls)(runtime, [call], hook);
+        const { logs } = await (0, common_1.confirmedLogs)(runtime, tx);
+        const granted = gen.contracts
+            .parseRulesGranted(logs, wallet)
+            .map((g) => g.rulesId);
+        const revoked = gen.contracts
+            .parseRulesRevoked(logs, wallet)
+            .map((r) => r.rulesId.toLowerCase());
+        if (!sameIds(granted, predicted) ||
+            !sameIds(revoked, oldIds)) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RECEIPT_MISMATCH, 'rules.update receipt does not show the expected revoke/grant pairs', { details: { granted, predicted, revoked, txHash: tx.hash } });
+        }
+        (0, common_1.emitAgentic)(runtime, hook, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_105, {
+            rulesIds: params.rules.map((p) => p.rulesId),
+        });
+        (0, common_1.emitAgentic)(runtime, hook, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_104, granted);
+        return {
+            tx,
+            rules: granted.map((id, i) => ({
+                rulesId: id,
+                replaced: params.rules[i].rulesId,
+            })),
+        };
+    });
+}
+function sameIds(a, b) {
+    return (a.length === b.length &&
+        a.every((x, i) => x.toLowerCase() === b[i].toLowerCase()));
+}
+/** Direct owner rename; empty resets the default label without a checkpoint. */
+async function setLabel(runtime, gen, wallet, label, hook) {
+    (0, label_1.assertLabel)(label);
+    (0, common_1.assertCanSign)(runtime, 'setLabel');
+    (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.SET_LABEL);
+    return finish(runtime, hook, 'setLabel', async () => {
+        await (0, common_1.assertOwner)(runtime, gen, wallet, await snapshot_1.Snapshot.at(runtime.reader));
+        const tx = await (0, common_1.sendOwnerCalls)(runtime, [
+            {
+                to: wallet,
+                value: BigInt(0),
+                data: gen.contracts.encodeSetLabel(label),
+            },
+        ], hook);
+        await (0, common_1.confirmedLogs)(runtime, tx);
+        (0, common_1.emitAgentic)(runtime, hook, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_106, label);
+        return { tx };
+    }).then(({ tx }) => tx);
+}
+//# sourceMappingURL=rules-write.js.map

package/src/lib/agentic/management/svm-context.d.ts

@@ -0,0 +1,25 @@
+/** Internal resolved context; no public Rule schema or cluster assumptions. */
+import { type Address, type Hex } from 'viem';
+import { PUSH_NETWORK } from '../../constants/enums';
+import { type SvmTokenAccountInput, type ResolvedSvmAsset } from '../codec/svm-accounts';
+import type { AssetCapWire } from '../codec/universal-terms';
+import type { Snapshot } from '../reads/snapshot';
+export interface SvmMetadataProvider {
+    /** Must identify the requested full CAIP-2 cluster; no global gateway default. */
+    gateway(chainNamespace: `solana:${string}`): Promise<{
+        chainNamespace: string;
+        program: string;
+    }>;
+    /** RPC-backed mint owner (legacy SPL or Token-2022), not an assumed default. */
+    mint(chainNamespace: `solana:${string}`, address: Hex): Promise<{
+        mint: string;
+        tokenProgram: string;
+    }>;
+}
+export declare function resolveSvmAssets(snap: Snapshot, chain: `solana:${string}`, caps: readonly AssetCapWire[], metadata: SvmMetadataProvider, network?: PUSH_NETWORK): Promise<ResolvedSvmAsset[]>;
+export declare function resolveSvmContext(snap: Snapshot, wallet: Address, chain: `solana:${string}`, caps: readonly AssetCapWire[], metadata: SvmMetadataProvider, outputs?: readonly SvmTokenAccountInput[], network?: PUSH_NETWORK): Promise<{
+    assets: AssetCapWire[];
+    expectedCEA: Hex;
+    gatewayProgram: Hex;
+    ceaAccounts: Hex[];
+}>;

package/src/lib/agentic/management/svm-context.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSvmAssets = resolveSvmAssets;
+exports.resolveSvmContext = resolveSvmContext;
+/** Internal resolved context; no public Rule schema or cluster assumptions. */
+const viem_1 = require("viem");
+const enums_1 = require("../../constants/enums");
+const errors_1 = require("../errors");
+const prc20_metadata_1 = require("../contracts/prc20-metadata");
+const svm_accounts_1 = require("../codec/svm-accounts");
+const ZERO_KEY = `0x${'00'.repeat(32)}`;
+async function resolveSvmAssets(snap, chain, caps, metadata, network = enums_1.PUSH_NETWORK.TESTNET_DONUT) {
+    const gas = await (0, prc20_metadata_1.readGasPrc20)(snap, chain);
+    const out = [];
+    for (const cap of caps) {
+        const token = (0, viem_1.getAddress)(cap.token);
+        const namespace = await snap.read(token, prc20_metadata_1.PRC20_SOURCE_ABI, 'SOURCE_CHAIN_NAMESPACE');
+        if (namespace !== chain)
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.ASSET_CHAIN_MISMATCH, `PRC20 ${token} belongs to ${namespace}, not ${chain}`);
+        const source = await (0, prc20_metadata_1.readSvmSourceToken)(snap, token, chain, network);
+        const native = source === ZERO_KEY;
+        if (native) {
+            if (token !== gas)
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'native marker is not the registered gas PRC20');
+            out.push({ kind: 'native', cap: { ...cap, token } });
+        }
+        else {
+            const key = (0, svm_accounts_1.svmKey)(source);
+            const mint = await metadata.mint(chain, key);
+            if ((0, svm_accounts_1.svmKey)(mint.mint) !== key)
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'mint resolver returned a different mint');
+            out.push({ kind: 'spl', cap: { ...cap, token }, ...mint });
+        }
+    }
+    return out;
+}
+async function resolveSvmContext(snap, wallet, chain, caps, metadata, outputs = [], network = enums_1.PUSH_NETWORK.TESTNET_DONUT) {
+    const gateway = await metadata.gateway(chain);
+    if (gateway.chainNamespace !== chain)
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'gateway registry cluster mismatch');
+    const assets = await resolveSvmAssets(snap, chain, caps, metadata, network);
+    const resolvedOutputs = [];
+    for (const output of outputs) {
+        const key = (0, svm_accounts_1.svmKey)(output.mint);
+        const resolved = await metadata.mint(chain, key);
+        if ((0, svm_accounts_1.svmKey)(resolved.mint) !== key ||
+            (output.tokenProgram &&
+                (0, svm_accounts_1.svmKey)(output.tokenProgram) !== (0, svm_accounts_1.svmKey)(resolved.tokenProgram)))
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'output mint/token-program mismatch');
+        resolvedOutputs.push(resolved);
+    }
+    // Derivation validates token programs and covers every mint/output.
+    return (0, svm_accounts_1.resolveAgwSvmRuleContext)(wallet, gateway.program, assets, resolvedOutputs);
+}
+//# sourceMappingURL=svm-context.js.map

package/src/lib/agentic/management/svm-metadata.d.ts

@@ -0,0 +1,10 @@
+import { Connection } from '@solana/web3.js';
+import type { SvmMetadataProvider } from './svm-context';
+export interface SvmClusterConfig {
+    gatewayProgram: string;
+    rpcUrls: readonly string[];
+}
+type MintRpc = Pick<Connection, 'getGenesisHash' | 'getAccountInfo'>;
+/** Explicit cluster configuration; HTTP reads only, no signing/subscriptions. */
+export declare function createSvmMetadataProvider(clusters: Readonly<Partial<Record<`solana:${string}`, SvmClusterConfig>>>, connect?: (url: string) => MintRpc): SvmMetadataProvider;
+export {};

package/src/lib/agentic/management/svm-metadata.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSvmMetadataProvider = createSvmMetadataProvider;
+const web3_js_1 = require("@solana/web3.js");
+const svm_accounts_1 = require("../codec/svm-accounts");
+const svm_terms_1 = require("../codec/svm-terms");
+const errors_1 = require("../errors");
+const SPL = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
+const TOKEN_2022 = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';
+/** Explicit cluster configuration; HTTP reads only, no signing/subscriptions. */
+function createSvmMetadataProvider(clusters, connect = (url) => new web3_js_1.Connection(url, 'confirmed')) {
+    function config(chain) {
+        const c = clusters[chain];
+        if (!c || !c.rpcUrls.length)
+            throw (0, svm_terms_1.svmInvalid)(`no SVM registry/RPC configuration for ${chain}`);
+        (0, svm_accounts_1.svmKey)(c.gatewayProgram);
+        return c;
+    }
+    async function read(chain, fn) {
+        const c = config(chain);
+        let last;
+        for (const url of c.rpcUrls) {
+            try {
+                const rpc = connect(url);
+                // CAIP-2 Solana references are the first 32 characters of genesisHash.
+                if (`solana:${(await rpc.getGenesisHash()).slice(0, 32)}` !== chain)
+                    throw (0, svm_terms_1.svmInvalid)('SVM RPC genesis/cluster mismatch');
+                return await fn(rpc);
+            }
+            catch (error) {
+                last = error;
+            }
+        }
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `SVM metadata lookup failed for ${chain}`, { cause: last });
+    }
+    return {
+        gateway: async (chain) => read(chain, async () => ({
+            chainNamespace: chain,
+            program: config(chain).gatewayProgram,
+        })),
+        mint: async (chain, address) => read(chain, async (rpc) => {
+            const mint = new web3_js_1.PublicKey(Buffer.from((0, svm_accounts_1.svmKey)(address).slice(2), 'hex'));
+            const info = await rpc.getAccountInfo(mint, 'confirmed');
+            if (!info || info.executable)
+                throw (0, svm_terms_1.svmInvalid)('mint account missing or executable');
+            const owner = info.owner.toBase58(), data = info.data;
+            const legacy = owner === SPL && data.length === 82;
+            const extended = owner === TOKEN_2022 &&
+                (data.length === 82 || (data.length >= 166 && data[165] === 1));
+            if ((!legacy && !extended) || data[45] !== 1)
+                throw (0, svm_terms_1.svmInvalid)('account is not an initialized supported SPL mint');
+            return { mint: mint.toBase58(), tokenProgram: owner };
+        }),
+    };
+}
+//# sourceMappingURL=svm-metadata.js.map

package/src/lib/agentic/management/svm-public.d.ts

@@ -0,0 +1,6 @@
+import type { Address } from 'viem';
+import type { SolanaRule, DecodedSolanaRule } from '../agentic.types';
+import type { AgenticRuntime } from '../runtime';
+import type { Snapshot } from '../reads/snapshot';
+export declare function svmMetadata(runtime: AgenticRuntime): import("./svm-context").SvmMetadataProvider;
+export declare function preparePublicSvmRule(runtime: AgenticRuntime, snap: Snapshot, wallet: Address, rule: SolanaRule | DecodedSolanaRule): Promise<import("../codec/svm-terms").SvmTermsWire>;