@pushchain/core 6.0.26 → 6.0.27-alpha.1

package/src/lib/agentic/presets/index.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agenticPresets = void 0;
+exports.buildPresetApi = buildPresetApi;
+const viem_1 = require("viem");
+const errors_1 = require("../errors");
+const selectors_1 = require("../codec/selectors");
+const catalog_1 = require("./catalog");
+const MAX_UINT256 = (BigInt(1) << BigInt(256)) - BigInt(1);
+const invalid = (message) => new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, message);
+function cap(value, name) {
+    if (value === undefined)
+        return BigInt(0);
+    if (typeof value !== 'bigint' || value < BigInt(0) || value > MAX_UINT256)
+        throw invalid(`${name} must be a uint256 bigint`);
+    return value;
+}
+function copyCall(call) {
+    return {
+        ...call,
+        ...(call.pins
+            ? {
+                pins: call.pins.map((pin) => {
+                    if (pin.account !== undefined)
+                        return {
+                            ...pin,
+                            ...(pin.token && typeof pin.token === 'object'
+                                ? { token: { ...pin.token } }
+                                : {}),
+                        };
+                    return {
+                        ...pin,
+                        arg: typeof pin.arg === 'number' ? pin.arg : [...pin.arg],
+                    };
+                }),
+            }
+            : {}),
+    };
+}
+function tokenAddress(token) {
+    const address = typeof token === 'string' ? token : token?.address;
+    if (typeof address !== 'string' || !address.trim())
+        throw invalid('preset asset requires a token address');
+    return address;
+}
+/** Not a public registration API. Tests inject fixtures; production uses the bundled catalog. */
+function buildPresetApi(catalog) {
+    // Detach from the input so neither a returned template nor an input mutation changes the catalog.
+    const entries = catalog.map((p) => ({
+        ...p,
+        chains: p.chains.map((c) => ({
+            ...c,
+            allowedCalls: c.allowedCalls.map(copyCall),
+            approvals: c.approvals?.map((a) => ({ ...a })),
+            swapRouters: c.swapRouters?.map((r) => ({ ...r })),
+        })),
+    }));
+    if (new Set(entries.map((e) => e.constant)).size !== entries.length ||
+        entries.some((e) => new Set(e.chains.map((c) => c.chainNamespace)).size !== e.chains.length))
+        throw invalid('duplicate preset or chain in catalog');
+    const api = {
+        list(options) {
+            if (options?.type !== undefined && options.type !== 'CATEGORY')
+                throw invalid('only CATEGORY presets are supported');
+            return {
+                presets: entries.map((p) => ({
+                    type: 'CATEGORY',
+                    constant: p.constant,
+                    name: p.name,
+                    chains: p.chains.map((c) => c.chainNamespace),
+                })),
+            };
+        },
+        get(preset, options = {}) {
+            const entry = entries.find((p) => p.constant === preset);
+            if (!entry)
+                throw invalid(`unknown preset ${String(preset)}`);
+            if (!options || typeof options !== 'object' || Array.isArray(options))
+                throw invalid('preset options must be an object');
+            if (options.agent !== undefined &&
+                (!(0, viem_1.isAddress)(options.agent, { strict: false }) ||
+                    (0, viem_1.getAddress)(options.agent) === viem_1.zeroAddress))
+                throw invalid('preset agent must be a nonzero Push address');
+            if (options.validUntil !== undefined &&
+                (!Number.isSafeInteger(options.validUntil) ||
+                    options.validUntil <= Math.floor(Date.now() / 1000) ||
+                    options.validUntil >= 2 ** 48))
+                throw invalid('preset validUntil must be a future uint48 timestamp');
+            if (options.maxGasPerCall !== undefined)
+                cap(options.maxGasPerCall, 'maxGasPerCall');
+            if (options.assets !== undefined && !Array.isArray(options.assets))
+                throw invalid('preset assets must be an array');
+            const chains = options.chainNamespace === undefined
+                ? entry.chains
+                : entry.chains.filter((c) => c.chainNamespace === options.chainNamespace);
+            if (options.chainNamespace !== undefined && !chains.length)
+                throw (0, errors_1.capabilityUnavailable)('presetChain', `preset ${preset} has no approved entry for ${options.chainNamespace}`);
+            if (!chains.length && options.assets?.length)
+                throw (0, errors_1.capabilityUnavailable)('presetCatalog', `preset ${preset} has no approved app entries`);
+            const assets = new Map();
+            for (const asset of options.assets ?? []) {
+                if (!asset || typeof asset !== 'object')
+                    throw invalid('preset asset must be an object');
+                const chain = asset.chainNamespace ?? options.chainNamespace;
+                if (!chain)
+                    throw invalid('each asset needs chainNamespace when no chain filter is supplied');
+                if (!chains.some((c) => c.chainNamespace === chain))
+                    throw invalid(`asset chain ${chain} is outside the selected preset`);
+                const address = tokenAddress(asset.token);
+                if (chain.startsWith('eip155:') &&
+                    !(0, viem_1.isAddress)(address, { strict: false }))
+                    throw invalid('EVM preset asset requires an EVM address');
+                const group = assets.get(chain) ?? [];
+                const key = chain.startsWith('eip155:')
+                    ? address.toLowerCase()
+                    : address;
+                if (group.some((a) => (chain.startsWith('eip155:')
+                    ? tokenAddress(a.token).toLowerCase()
+                    : tokenAddress(a.token)) === key))
+                    throw invalid('duplicate preset asset on the same chain');
+                group.push({
+                    token: typeof asset.token === 'string' ? asset.token : { ...asset.token },
+                    maxPerCall: cap(asset.maxPerCall, 'maxPerCall'),
+                    maxTotal: cap(asset.maxTotal, 'maxTotal'),
+                });
+                assets.set(chain, group);
+            }
+            const rules = chains.map((chain) => {
+                const calls = chain.allowedCalls.map(copyCall);
+                if (chain.swapRouters?.length) {
+                    const tokens = assets.get(chain.chainNamespace) ?? [];
+                    if (tokens.some((a) => tokenAddress(a.token) === viem_1.zeroAddress ||
+                        (typeof a.token !== 'string' && a.token.mechanism === 'native')))
+                        throw invalid('DEX token pins require explicit ERC20 addresses; use wrapped-native tokens instead of the native marker');
+                    // Keep discovery useful before a swap pair is selected. These review
+                    // calls cannot spend input tokens: the amount maximum is explicitly zero.
+                    // Re-run get with both tokens to generate the executable pair pins.
+                    if (tokens.length < 2)
+                        for (const router of chain.swapRouters)
+                            for (const exactInput of [true, false])
+                                calls.push({
+                                    target: router.address,
+                                    selector: `${exactInput ? 'exactInputSingle' : 'exactOutputSingle'}((address,address,uint24,address,uint256,uint256,uint160))`,
+                                    pins: [
+                                        ...(tokens.length
+                                            ? [
+                                                {
+                                                    arg: [0, 0],
+                                                    expected: (0, viem_1.getAddress)(tokenAddress(tokens[0].token)),
+                                                },
+                                            ]
+                                            : []),
+                                        { arg: [0, 3], expected: 'agentic:wallet' },
+                                        { arg: [0, exactInput ? 4 : 5], max: BigInt(0) },
+                                    ],
+                                    app: router.app,
+                                    label: `${exactInput ? 'Swap exact input' : 'Swap exact output'} (select two tokens to enable)`,
+                                });
+                    for (const router of chain.swapRouters)
+                        for (const input of tokens)
+                            for (const output of tokens) {
+                                if (tokenAddress(input.token).toLowerCase() ===
+                                    tokenAddress(output.token).toLowerCase())
+                                    continue;
+                                for (const exactInput of [true, false])
+                                    calls.push({
+                                        target: router.address,
+                                        selector: `${exactInput ? 'exactInputSingle' : 'exactOutputSingle'}((address,address,uint24,address,uint256,uint256,uint160))`,
+                                        pins: [
+                                            {
+                                                arg: [0, 0],
+                                                expected: (0, viem_1.getAddress)(tokenAddress(input.token)),
+                                            },
+                                            {
+                                                arg: [0, 1],
+                                                expected: (0, viem_1.getAddress)(tokenAddress(output.token)),
+                                            },
+                                            { arg: [0, 3], expected: 'agentic:wallet' },
+                                            { arg: [0, exactInput ? 4 : 5], max: input.maxPerCall },
+                                        ],
+                                        app: router.app,
+                                        label: exactInput
+                                            ? 'Swap exact input'
+                                            : 'Swap exact output',
+                                    });
+                            }
+                }
+                const approvals = new Set();
+                for (const asset of assets.get(chain.chainNamespace) ?? []) {
+                    const token = tokenAddress(asset.token);
+                    if (token === viem_1.zeroAddress ||
+                        (typeof asset.token !== 'string' &&
+                            asset.token.mechanism === 'native'))
+                        continue;
+                    for (const approval of chain.approvals ?? []) {
+                        if (!chain.chainNamespace.startsWith('eip155:'))
+                            throw (0, errors_1.capabilityUnavailable)('presetApproval', 'Solana approvals require a separately reviewed instruction template');
+                        if (approval.token &&
+                            (0, viem_1.getAddress)(token) !== (0, viem_1.getAddress)(approval.token))
+                            continue;
+                        const spender = (0, viem_1.getAddress)(approval.spender);
+                        const target = (0, viem_1.getAddress)(token);
+                        const approvalKey = `${target}:${spender}`;
+                        if (approvals.has(approvalKey))
+                            continue;
+                        approvals.add(approvalKey);
+                        calls.push({
+                            target,
+                            selector: 'approve(address,uint256)',
+                            pins: [
+                                { arg: 0, expected: spender },
+                                { arg: 1, max: asset.maxPerCall },
+                            ],
+                            app: approval.app,
+                            label: 'Approve token spending',
+                        });
+                    }
+                }
+                if (!calls.length || calls.length > 32)
+                    throw (0, errors_1.capabilityUnavailable)('presetCalls', 'preset must contain 1..32 allowed calls including approvals');
+                if (calls.reduce((n, c) => n + (c.pins?.length ?? 0), 0) > 32)
+                    throw (0, errors_1.capabilityUnavailable)('presetPins', 'preset expansion exceeds 32 pins; reduce the token list or split rules across wallets');
+                const pairs = new Map();
+                for (const call of calls) {
+                    if (!/^[A-Za-z_$][\w$]*\(.*\)$/.test(call.selector))
+                        throw invalid('preset selectors must be full signatures');
+                    const selector = chain.chainNamespace.startsWith('eip155:')
+                        ? (0, selectors_1.parseSelector)(call.selector).selector
+                        : call.selector;
+                    const pair = `${chain.chainNamespace.startsWith('eip155:')
+                        ? call.target.toLowerCase()
+                        : call.target}:${selector}`;
+                    if (pairs.has(pair) && !chain.chainNamespace.startsWith('eip155:'))
+                        throw (0, errors_1.capabilityUnavailable)('presetCalls', 'Solana does not support alternative entries for one program/instruction');
+                    if (pairs.has(pair) && (!call.pins?.length || !pairs.get(pair)))
+                        throw (0, errors_1.capabilityUnavailable)('presetCalls', 'an unpinned alternative would bypass restrictions for this target/function');
+                    pairs.set(pair, !!call.pins?.length);
+                }
+                return {
+                    chainNamespace: chain.chainNamespace,
+                    allowedCalls: calls,
+                    ...(options.agent !== undefined
+                        ? { agent: (0, viem_1.getAddress)(options.agent) }
+                        : {}),
+                    ...(options.validUntil !== undefined
+                        ? { validUntil: options.validUntil }
+                        : {}),
+                    ...(options.assets !== undefined
+                        ? { assets: assets.get(chain.chainNamespace) ?? [] }
+                        : {}),
+                    ...((options.maxGasPerCall ?? chain.maxGasPerCall) !== undefined
+                        ? {
+                            maxGasPerCall: cap(options.maxGasPerCall ?? chain.maxGasPerCall, 'maxGasPerCall'),
+                        }
+                        : {}),
+                };
+            });
+            return { rules };
+        },
+    };
+    // The overload narrows templates only when both required fields were supplied and validated.
+    return Object.freeze(api);
+}
+exports.agenticPresets = buildPresetApi(catalog_1.PRESET_CATALOG);
+//# sourceMappingURL=index.js.map

package/src/lib/agentic/presets/types.d.ts

@@ -0,0 +1,48 @@
+import type { Address } from 'viem';
+import type { Rule, RuleAsset, ForeignChainNamespace } from '../agentic.types';
+export type PresetCategory = 'DEXES' | 'LENDING' | 'STAKING' | 'PREDICTION';
+export interface Preset {
+    type: 'CATEGORY';
+    constant: PresetCategory;
+    name: string;
+    chains: ForeignChainNamespace[];
+}
+/** An editable review-screen template; both identity and expiry are required by create. */
+export type PresetRuleTemplate = Omit<Rule, 'agent' | 'validUntil'> & {
+    agent?: Address;
+    validUntil?: number;
+};
+export interface PresetAsset {
+    chainNamespace?: ForeignChainNamespace;
+    token: RuleAsset['token'];
+    /** Omitted caps are zero, by the user's October 12 decision. */
+    maxPerCall?: bigint;
+    maxTotal?: bigint;
+}
+export interface PresetOptions {
+    /** Explicit Push-PC gas budget per outbound; omitted = zero. */
+    maxGasPerCall?: bigint;
+    chainNamespace?: ForeignChainNamespace;
+    agent?: Address;
+    validUntil?: number;
+    /** DEX swaps with fewer than two tokens are zero-input-cap review templates.
+     * Call get again with a complete pair to generate token pins and amount limits. */
+    assets?: PresetAsset[];
+}
+export interface ReadyPresetOptions extends PresetOptions {
+    agent: Address;
+    validUntil: number;
+}
+export interface AgenticPresets {
+    list(options?: {
+        type?: 'CATEGORY';
+    }): {
+        presets: Preset[];
+    };
+    get(preset: PresetCategory, options: ReadyPresetOptions): {
+        rules: Rule[];
+    };
+    get(preset: PresetCategory, options?: PresetOptions): {
+        rules: PresetRuleTemplate[];
+    };
+}

package/src/lib/agentic/presets/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/src/lib/agentic/public-rule.d.ts

@@ -0,0 +1,9 @@
+import { type Address } from 'viem';
+import type { Rule, RuleInput, InternalRule, ArgumentPath } from './agentic.types';
+import type { AgenticRuntime } from './runtime';
+export declare const WALLET: "agentic:wallet";
+/** Mark authored inputs for normalization after the wallet address is fixed. */
+export declare function publicRules(rules: readonly RuleInput[]): InternalRule[];
+export declare function isPublicRule(rule: InternalRule): boolean;
+export declare function evmPinOffset(selector: Rule['allowedCalls'][number]['selector'], arg: ArgumentPath): number;
+export declare function normalizePublicRule(input: InternalRule, wallet: Address, runtime: AgenticRuntime): Promise<InternalRule>;

package/src/lib/agentic/public-rule.js

@@ -0,0 +1,326 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WALLET = void 0;
+exports.publicRules = publicRules;
+exports.isPublicRule = isPublicRule;
+exports.evmPinOffset = evmPinOffset;
+exports.normalizePublicRule = normalizePublicRule;
+const pins_1 = require("./codec/pins");
+const web3_js_1 = require("@solana/web3.js");
+const viem_1 = require("viem");
+const errors_1 = require("./errors");
+const selectors_1 = require("./codec/selectors");
+const abi_layout_1 = require("./codec/abi-layout");
+const defaults_1 = require("./codec/defaults");
+const svm_accounts_1 = require("./codec/svm-accounts");
+exports.WALLET = 'agentic:wallet';
+const PUBLIC_INPUT = Symbol('AGW public rule');
+/** Mark authored inputs for normalization after the wallet address is fixed. */
+function publicRules(rules) {
+    if (!Array.isArray(rules))
+        throw invalid('rules must be an array');
+    return rules.map((rule) => {
+        if (!rule || typeof rule !== 'object')
+            throw invalid('rule must be an object');
+        return { ...rule, [PUBLIC_INPUT]: true };
+    });
+}
+function isPublicRule(rule) {
+    return !!rule && !!rule[PUBLIC_INPUT];
+}
+function invalid(message) {
+    return new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, message);
+}
+function rejectFields(obj, fields, where) {
+    for (const field of fields)
+        if (field in obj)
+            throw invalid(`${where}.${field} is not supported by the current rule shape`);
+}
+function uint(value, name) {
+    if (typeof value !== 'bigint' || value < BigInt(0) || value > defaults_1.UINT256_MAX)
+        throw invalid(`${name} must be a uint256 bigint`);
+    return value;
+}
+function evmPinOffset(selector, arg) {
+    const parsed = (0, selectors_1.parseSelector)(selector);
+    if (parsed.valueOnly)
+        throw invalid('value-only calls cannot have argument pins');
+    if (parsed.inputs)
+        return (0, abi_layout_1.argumentLocation)(parsed.inputs, arg, 'pin').offset;
+    if (typeof arg !== 'number' ||
+        !Number.isSafeInteger(arg) ||
+        arg < 0 ||
+        4 + 32 * arg + 32 > 65535)
+        throw invalid('a raw selector needs a valid scalar ABI word index');
+    return 4 + 32 * arg;
+}
+function expectedWord(selector, arg, value) {
+    const parsed = (0, selectors_1.parseSelector)(selector);
+    if (parsed.inputs)
+        return (0, abi_layout_1.encodeArgWord)((0, abi_layout_1.argumentLocation)(parsed.inputs, arg, 'pin').param, value, 'pin');
+    if (typeof value === 'bigint')
+        return (0, viem_1.numberToHex)(uint(value, 'pin.expected'), { size: 32 });
+    if (typeof value === 'string' && (0, viem_1.isAddress)(value, { strict: false }))
+        return `0x${value.slice(2).padStart(64, '0')}`.toLowerCase();
+    if (typeof value === 'string' && (0, viem_1.isHex)(value) && value.length === 66)
+        return value.toLowerCase();
+    throw invalid('a raw EVM selector needs an address, uint256 or exact 32-byte expected word');
+}
+async function normalizePublicRule(input, wallet, runtime) {
+    const rule = input;
+    if ('format' in rule && rule.format === 'decoded')
+        return input;
+    const r = rule;
+    rejectFields(r, [
+        'target',
+        'selector',
+        'actions',
+        'pins',
+        'amount',
+        'maxCalls',
+        'maxValuePerCall',
+        'maxValueTotal',
+        'ref',
+        'allowedInstructions',
+        'outputTokens',
+    ], 'rule');
+    if (!Number.isSafeInteger(r.validUntil) ||
+        r.validUntil <= runtime.nowSeconds() ||
+        r.validUntil >= 2 ** 48)
+        throw invalid('validUntil must be a future uint48 timestamp');
+    if (!Array.isArray(r.allowedCalls) ||
+        r.allowedCalls.length < 1 ||
+        r.allowedCalls.length > 32)
+        throw invalid('allowedCalls must contain 1..32 calls');
+    for (const c of r.allowedCalls) {
+        if (!c || typeof c !== 'object')
+            throw invalid('allowedCall must be an object');
+        rejectFields(c, [
+            'beneficiary',
+            'beneficiaryOffset',
+            'amount',
+            'maxCalls',
+            'maxValuePerCall',
+            'maxValueTotal',
+            'validUntil',
+        ], 'allowedCall');
+        uint(c.maxValue ?? BigInt(0), 'allowedCall.maxValue');
+        if (c.pins !== undefined && !Array.isArray(c.pins))
+            throw invalid('pins must be an array');
+        for (const pin of c.pins ?? []) {
+            if (!pin || typeof pin !== 'object')
+                throw invalid('pin must be an object');
+            rejectFields(pin, ['offset', 'min'], 'pin');
+            if ('token' in pin && (!('account' in pin) || pin.expected !== exports.WALLET))
+                throw invalid('token is only valid on a WALLET account pin');
+            if ('arg' in pin === 'account' in pin)
+                throw invalid('pin must identify exactly one arg or account');
+            if ('expected' in pin === 'max' in pin)
+                throw invalid('pin must specify exactly one expected or max');
+        }
+    }
+    if (r.chainNamespace?.startsWith('solana:')) {
+        const { svmMetadata } = await Promise.resolve().then(() => __importStar(require('./management/svm-public')));
+        const gateway = await svmMetadata(runtime).gateway(r.chainNamespace);
+        if (gateway.chainNamespace !== r.chainNamespace)
+            throw invalid('gateway registry cluster mismatch');
+        return svmRule(r, (0, svm_accounts_1.deriveAgwSvmCea)(wallet, gateway.program).address);
+    }
+    const native = r.chainNamespace === undefined;
+    if (r.chainNamespace === runtime.pushChainNamespace)
+        throw invalid('omit chainNamespace for Push rules');
+    if (native && r.allowedCalls.length > 8)
+        throw (0, errors_1.capabilityUnavailable)('nativeActions', 'the deployed v6 wallet permits at most eight native actions');
+    if (native && (r.assets !== undefined || r.maxGasPerCall !== undefined))
+        throw invalid('native rules do not carry assets or maxGasPerCall');
+    const own = native
+        ? wallet
+        : (0, viem_1.getAddress)((await runtime.resolveCEA(wallet, r.chainNamespace)).cea);
+    const nativeActions = [];
+    const calls = [];
+    for (const call of r.allowedCalls) {
+        const pins = call.pins ?? [];
+        const wirePins = [];
+        const occupied = new Set();
+        for (const pin of pins) {
+            if ('account' in pin)
+                throw invalid('account pins only apply to Solana');
+            const offset = evmPinOffset(call.selector, pin.arg);
+            if (occupied.has(offset))
+                throw invalid('duplicate pin argument');
+            occupied.add(offset);
+            wirePins.push({
+                offset,
+                op: 'max' in pin ? 1 : 0,
+                value: 'max' in pin
+                    ? (0, viem_1.numberToHex)(uint(pin.max, 'pin.max'), { size: 32 })
+                    : expectedWord(call.selector, pin.arg, pin.expected === exports.WALLET ? own : pin.expected),
+            });
+        }
+        if (native)
+            nativeActions.push({
+                target: (0, viem_1.getAddress)(call.target),
+                selector: call.selector,
+                wirePins,
+                maxValuePerCall: call.maxValue ?? BigInt(0),
+                maxValueTotal: defaults_1.UINT256_MAX,
+                maxCalls: pins_1.UNLIMITED_CALLS,
+            });
+        else
+            calls.push({
+                target: (0, viem_1.getAddress)(call.target),
+                selector: call.selector,
+                pins: wirePins,
+                maxValue: call.maxValue ?? BigInt(0),
+            });
+    }
+    if (native)
+        return { agent: r.agent, validUntil: r.validUntil, actions: nativeActions };
+    return {
+        agent: r.agent,
+        validUntil: r.validUntil,
+        chainNamespace: r.chainNamespace,
+        assets: (r.assets ?? []).map((a) => ({
+            ...a,
+            token: a.token,
+            maxTotal: a.maxTotal ?? BigInt(0),
+        })),
+        maxGasPerCall: r.maxGasPerCall ?? BigInt(0),
+        allowedCalls: calls,
+    };
+}
+function svmType(text) {
+    const array = text.match(/^(.+)\[(\d+)\]$/);
+    if (array) {
+        const count = Number(array[2]);
+        if (!Number.isSafeInteger(count) || count < 1 || count > 128)
+            throw invalid('unsupported SVM fixed array size');
+        return { array: [svmType(array[1]), count] };
+    }
+    if ([
+        'u8',
+        'u16',
+        'u32',
+        'u64',
+        'i8',
+        'i16',
+        'i32',
+        'i64',
+        'bool',
+        'pubkey',
+    ].includes(text))
+        return text;
+    if (text === 'publicKey')
+        return 'pubkey';
+    throw (0, errors_1.capabilityUnavailable)('svmArgumentLayout', `unsupported fixed-size Solana type ${text}`);
+}
+function svmRule(rule, cea) {
+    return {
+        agent: rule.agent,
+        validUntil: rule.validUntil,
+        chainNamespace: rule.chainNamespace,
+        outputTokens: [
+            ...new Set(rule.allowedCalls.flatMap((c) => (c.pins ?? []).flatMap((p) => 'account' in p && 'token' in p && p.expected === exports.WALLET && p.token
+                ? [typeof p.token === 'string' ? p.token : p.token.address]
+                : []))),
+        ],
+        assets: (rule.assets ?? []).map((asset) => ({
+            ...asset,
+            maxTotal: asset.maxTotal ?? BigInt(0),
+        })),
+        maxGasPerCall: rule.maxGasPerCall ?? BigInt(0),
+        allowedInstructions: rule.allowedCalls.map((call) => {
+            if ((call.maxValue ?? BigInt(0)) !== BigInt(0))
+                throw (0, errors_1.capabilityUnavailable)('svmCallValue', 'native Solana instruction value is governed by its transfer/pin, not an EVM call value');
+            const full = String(call.selector).match(/^([A-Za-z_][A-Za-z0-9_]*)\((.*)\)$/);
+            const raw = /^0x[0-9a-fA-F]{16}$/.test(call.selector);
+            if (!full && !raw)
+                throw invalid('Solana selector needs a fixed-width signature or eight-byte discriminator');
+            const types = full && full[2] ? full[2].split(',').map((s) => svmType(s.trim())) : [];
+            const name = full?.[1] ?? 'raw';
+            const discriminator = raw
+                ? (0, viem_1.hexToBytes)(call.selector)
+                : (0, viem_1.hexToBytes)((0, viem_1.sha256)((0, viem_1.toHex)(`global:${name
+                    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+                    .toLowerCase()}`))).slice(0, 8);
+            const pins = call.pins ?? [];
+            const accounts = pins.filter((p) => 'account' in p);
+            if (accounts.some((p) => !Number.isInteger(p.account) || p.account < 0 || p.account >= 64))
+                throw invalid('Solana account position must be 0..63');
+            const accountCount = Math.max(0, ...accounts.map((p) => p.account + 1));
+            const idl = {
+                address: new web3_js_1.PublicKey((0, viem_1.hexToBytes)((0, svm_accounts_1.svmKey)(call.target))).toBase58(),
+                metadata: { name: 'rule_layout', version: '1', spec: '0.1.0' },
+                instructions: [
+                    {
+                        name,
+                        discriminator: Array.from(discriminator),
+                        accounts: Array.from({ length: accountCount }, (_, i) => ({
+                            name: `account${i}`,
+                        })),
+                        args: types.map((type, i) => ({ name: `arg${i}`, type })),
+                    },
+                ],
+            };
+            return {
+                maxAccounts: pins_1.ANY_ACCOUNT_COUNT,
+                program: call.target,
+                instruction: { idl, name },
+                accounts: accounts.map((p) => ({
+                    name: `account${p.account}`,
+                    expected: p.expected === exports.WALLET
+                        ? p.token
+                            ? {
+                                kind: 'walletATA',
+                                token: typeof p.token === 'string' ? p.token : p.token.address,
+                            }
+                            : { kind: 'walletCEA' }
+                        : { kind: 'address', address: p.expected },
+                })),
+                fields: pins
+                    .filter((p) => 'arg' in p)
+                    .map((p) => {
+                    const arg = p.arg;
+                    if (!Number.isInteger(arg) || arg < 0 || arg >= types.length)
+                        throw (0, errors_1.capabilityUnavailable)('svmArgumentLayout', 'argument pins need a signature with the indexed argument type; use decoded raw constraints for stored rules');
+                    if ('max' in p)
+                        return { name: `arg${arg}`, max: uint(p.max, 'pin.max') };
+                    const rawExpected = p.expected;
+                    const eq = rawExpected === exports.WALLET ? cea : rawExpected;
+                    return {
+                        name: `arg${arg}`,
+                        equals: typeof eq === 'bigint'
+                            ? eq
+                            : /^0x/.test(eq)
+                                ? eq
+                                : (0, svm_accounts_1.svmKey)(eq),
+                    };
+                }),
+            };
+        }),
+    };
+}
+//# sourceMappingURL=public-rule.js.map

package/src/lib/agentic/reads/checkpoints.d.ts

@@ -0,0 +1,17 @@
+import type { Address } from 'viem';
+import type { AgenticGeneration } from '../deployments';
+import type { ChainReader } from '../contracts/reader';
+import type { Checkpoint } from '../agentic.types';
+/**
+ * w.checkpoints(): Checkpointed events in (block, tx, log) order, checked
+ * against the wallet's checkpointCount() at the same snapshot block.
+ * `sinceBlock` is inclusive. Evaluators should compare counts — one block can
+ * hold several ticks, and allowance pulls change balances without any tick.
+ */
+export declare function readCheckpoints(reader: ChainReader, gen: AgenticGeneration, wallet: Address, sinceBlock?: bigint): Promise<{
+    checkpoints: Checkpoint[];
+    count: bigint;
+    blockNumber: bigint;
+}>;
+/** Sequence must be contiguous, end at `count`, and start at 1 for a full scan. */
+export declare function validateSequence(seqs: number[], count: bigint, fullRange: boolean): string | null;