@pushchain/core 6.0.26 → 6.0.27-alpha.1

package/src/lib/agentic/codec/native.js

@@ -0,0 +1,341 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NATIVE_TERMS_PARAM = exports.MAX_NATIVE_ACTIONS = exports.MAX_PINS = void 0;
+exports.nativeActionsOf = nativeActionsOf;
+exports.nativeRuleToActionTerms = nativeRuleToActionTerms;
+exports.nativeRuleToTerms = nativeRuleToTerms;
+exports.nativeActionToTerms = nativeActionToTerms;
+exports.encodeNativeTerms = encodeNativeTerms;
+exports.decodeNativeTerms = decodeNativeTerms;
+exports.nativeTermsToRule = nativeTermsToRule;
+exports.nativeActionTermsToRule = nativeActionTermsToRule;
+exports.isUnlimited = isUnlimited;
+const pins_1 = require("./pins");
+const viem_1 = require("viem");
+const errors_1 = require("../errors");
+const abi_layout_1 = require("./abi-layout");
+const defaults_1 = require("./defaults");
+const selectors_1 = require("./selectors");
+/** URP native limits at v6 (Types.sol MAX_PINS, AGW MAX_NATIVE_ACTIONS). */
+exports.MAX_PINS = 8;
+exports.MAX_NATIVE_ACTIONS = 8;
+const UINT32_MAX = 2 ** 32 - 1;
+const UINT48_MAX = 2 ** 48 - 1;
+exports.NATIVE_TERMS_PARAM = {
+    type: 'tuple',
+    components: [
+        { name: 'validUntil', type: 'uint48' },
+        { name: 'target', type: 'address' },
+        { name: 'selector', type: 'bytes4' },
+        { name: 'maxValuePerCall', type: 'uint256' },
+        { name: 'maxValueTotal', type: 'uint256' },
+        {
+            name: 'amount',
+            type: 'tuple',
+            components: [
+                { name: 'enabled', type: 'bool' },
+                { name: 'offset', type: 'uint16' },
+                { name: 'maxPerCall', type: 'uint256' },
+                { name: 'maxTotal', type: 'uint256' },
+            ],
+        },
+        { name: 'maxCalls', type: 'uint32' },
+        {
+            name: 'pins',
+            type: 'tuple[]',
+            components: pins_1.ARG_PIN_COMPONENTS,
+        },
+    ],
+};
+function invalid(message, details) {
+    return new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, message, {
+        details,
+    });
+}
+function assertUint(value, bits, field) {
+    if (typeof value !== 'bigint' ||
+        value < BigInt(0) ||
+        value >= BigInt(2) ** BigInt(bits)) {
+        throw invalid(`${field} must be a uint${bits} bigint`);
+    }
+}
+const SINGLE_ACTION_FIELDS = [
+    'target',
+    'selector',
+    'maxValuePerCall',
+    'maxValueTotal',
+    'maxCalls',
+    'pins',
+    'wirePins',
+    'amount',
+];
+/**
+ * The actions a native rule allows: the single-action shorthand, or the
+ * explicit `actions` list (1..8). Each carries its effective `validUntil`.
+ */
+function nativeActionsOf(rule) {
+    if (!Number.isInteger(rule.validUntil) ||
+        rule.validUntil < 1 ||
+        rule.validUntil > UINT48_MAX) {
+        throw invalid('rule validUntil must be a positive unix timestamp in seconds (uint48)');
+    }
+    if (rule.actions !== undefined) {
+        if (!Array.isArray(rule.actions) ||
+            rule.actions.length < 1 ||
+            rule.actions.length > exports.MAX_NATIVE_ACTIONS) {
+            throw invalid(`actions must contain 1..${exports.MAX_NATIVE_ACTIONS} entries (the AGW native action limit)`);
+        }
+        const mixed = SINGLE_ACTION_FIELDS.filter((f) => rule[f] !== undefined);
+        if (mixed.length > 0) {
+            throw invalid(`actions cannot be combined with top-level ${mixed.join(', ')}; put them inside each action`);
+        }
+        return rule.actions.map((a, i) => {
+            if (!a || typeof a !== 'object' || Array.isArray(a)) {
+                throw invalid(`actions[${i}] must be an action object`, { action: i });
+            }
+            return { ...a, validUntil: a.validUntil ?? rule.validUntil };
+        });
+    }
+    const single = rule;
+    return [
+        {
+            target: single.target,
+            selector: single.selector,
+            maxValuePerCall: single.maxValuePerCall,
+            maxValueTotal: single.maxValueTotal,
+            maxCalls: single.maxCalls,
+            pins: single.pins,
+            wirePins: single.wirePins,
+            amount: single.amount,
+            validUntil: single.validUntil,
+        },
+    ];
+}
+/**
+ * Normalize and validate every action of a native rule into wire terms, in
+ * input order. (target, selector) pairs must be unique — the wallet refuses
+ * duplicates (DuplicateAction) because they share one action ID. Pure.
+ */
+function nativeRuleToActionTerms(rule, ctx) {
+    if (rule.validUntil <= ctx.nowSeconds) {
+        throw invalid('rule validUntil must be a future unix timestamp in seconds (uint48)');
+    }
+    const actions = nativeActionsOf(rule);
+    const multi = rule.actions !== undefined;
+    const out = actions.map((action, i) => {
+        try {
+            return nativeActionToTerms(action, ctx);
+        }
+        catch (err) {
+            if (multi && err instanceof errors_1.AgenticError) {
+                throw new errors_1.AgenticError(err.code, `actions[${i}]: ${err.message}`, {
+                    hint: err.hint,
+                    details: { ...(err.details ?? {}), action: i },
+                    cause: err,
+                });
+            }
+            throw err;
+        }
+    });
+    const seen = new Map();
+    out.forEach(({ terms }, i) => {
+        const key = `${terms.target.toLowerCase()}:${terms.selector}`;
+        const first = seen.get(key);
+        if (first !== undefined) {
+            throw invalid(`actions[${i}] repeats the target and selector of actions[${first}]`, { action: i });
+        }
+        seen.set(key, i);
+    });
+    return out;
+}
+/** Single-action convenience; multi-action rules use nativeRuleToActionTerms. */
+function nativeRuleToTerms(rule, ctx) {
+    const all = nativeRuleToActionTerms(rule, ctx);
+    if (all.length !== 1) {
+        throw invalid('nativeRuleToTerms takes a single-action rule');
+    }
+    return all[0];
+}
+/** Normalize and validate one native action into wire terms. Pure. */
+function nativeActionToTerms(rule, ctx) {
+    if (!(0, viem_1.isAddress)(rule.target, { strict: false }) ||
+        /^0x0{40}$/i.test(rule.target)) {
+        throw invalid('native rule target must be a non-zero address');
+    }
+    if (!Number.isInteger(rule.validUntil) ||
+        rule.validUntil <= ctx.nowSeconds ||
+        rule.validUntil > UINT48_MAX) {
+        throw invalid('validUntil must be a future unix timestamp in seconds (uint48)', {
+            validUntil: rule.validUntil,
+        });
+    }
+    const parsed = (0, selectors_1.parseSelector)(rule.selector);
+    const pinsIn = rule.pins ?? [];
+    if (parsed.valueOnly &&
+        (pinsIn.length > 0 || rule.wirePins?.length || rule.amount)) {
+        throw invalid('a value-only rule cannot carry pins or an amount rule');
+    }
+    if (pinsIn.length > exports.MAX_PINS) {
+        throw invalid(`at most ${exports.MAX_PINS} pins are allowed`, {
+            pins: pinsIn.length,
+        });
+    }
+    const pins = pinsIn.map((p, i) => {
+        if (p.arg !== undefined && p.offset !== undefined)
+            throw invalid('pin arg and offset are mutually exclusive');
+        if (p.offset !== undefined) {
+            if (typeof p.expected !== 'string' ||
+                !(0, viem_1.isHex)(p.expected) ||
+                p.expected.length !== 66) {
+                throw invalid(`pins[${i}].expected must be the exact 32-byte calldata word in offset form`);
+            }
+            return {
+                offset: (0, abi_layout_1.rawOffset)(p.offset, `pins[${i}]`),
+                expected: p.expected.toLowerCase(),
+            };
+        }
+        if (typeof p.arg !== 'number')
+            throw invalid('pin requires arg or offset');
+        const offset = (0, abi_layout_1.argumentOffset)(parsed.inputs, p.arg, `pins[${i}]`);
+        const param = parsed.inputs[p.arg];
+        return { offset, expected: (0, abi_layout_1.encodeArgWord)(param, p.expected, `pins[${i}]`) };
+    });
+    const offsets = new Set(pins.map((p) => p.offset));
+    if (offsets.size !== pins.length)
+        throw invalid('two pins address the same argument');
+    let amount = {
+        enabled: false,
+        offset: 0,
+        maxPerCall: BigInt(0),
+        maxTotal: BigInt(0),
+    };
+    if (rule.amount) {
+        let offset;
+        if (rule.amount.arg !== undefined && rule.amount.offset !== undefined)
+            throw invalid('amount arg and offset are mutually exclusive');
+        if (rule.amount.offset !== undefined) {
+            offset = (0, abi_layout_1.rawOffset)(rule.amount.offset, 'amount');
+        }
+        else {
+            if (typeof rule.amount.arg !== 'number')
+                throw invalid('amount requires arg or offset');
+            offset = (0, abi_layout_1.argumentOffset)(parsed.inputs, rule.amount.arg, 'amount');
+            const param = parsed.inputs[rule.amount.arg];
+            if (!/^uint\d*$/.test(param.type)) {
+                throw invalid(`amount argument must be an unsigned integer, got ${param.type}`);
+            }
+        }
+        if (offsets.has(offset))
+            throw invalid('amount argument is also pinned');
+        assertUint(rule.amount.maxPerCall, 256, 'amount.maxPerCall');
+        const maxTotal = (0, defaults_1.withDefault)(rule.amount.maxTotal, defaults_1.AGENTIC_DEFAULTS.native.amountMaxTotal);
+        assertUint(maxTotal, 256, 'amount.maxTotal');
+        amount = {
+            enabled: true,
+            offset,
+            maxPerCall: rule.amount.maxPerCall,
+            maxTotal,
+        };
+    }
+    const maxValuePerCall = (0, defaults_1.withDefault)(rule.maxValuePerCall, defaults_1.AGENTIC_DEFAULTS.native.maxValuePerCall);
+    const maxValueTotal = (0, defaults_1.withDefault)(rule.maxValueTotal, defaults_1.AGENTIC_DEFAULTS.native.maxValueTotal);
+    assertUint(maxValuePerCall, 256, 'maxValuePerCall');
+    assertUint(maxValueTotal, 256, 'maxValueTotal');
+    const maxCalls = rule.maxCalls === undefined
+        ? Number(defaults_1.AGENTIC_DEFAULTS.native.maxCalls.value)
+        : rule.maxCalls;
+    if (!Number.isInteger(maxCalls) || maxCalls <= 0 || maxCalls > UINT32_MAX) {
+        throw invalid('maxCalls must be a uint32 integer');
+    }
+    try {
+        (0, pins_1.validatePins)(rule.wirePins ??
+            pins.map((p) => ({
+                offset: p.offset,
+                op: 0,
+                value: p.expected,
+            })));
+    }
+    catch (error) {
+        throw invalid(error.message);
+    }
+    return {
+        parsed,
+        terms: {
+            validUntil: rule.validUntil,
+            target: (0, viem_1.getAddress)(rule.target),
+            selector: parsed.selector,
+            maxValuePerCall,
+            maxValueTotal,
+            amount,
+            maxCalls,
+            pins: rule.wirePins ??
+                pins.map((p) => ({
+                    offset: p.offset,
+                    op: 0,
+                    value: p.expected,
+                })),
+        },
+    };
+}
+function encodeNativeTerms(terms) {
+    return (0, viem_1.encodeAbiParameters)([exports.NATIVE_TERMS_PARAM], [terms]);
+}
+function decodeNativeTerms(body) {
+    const [terms] = (0, viem_1.decodeAbiParameters)([exports.NATIVE_TERMS_PARAM], body);
+    return terms;
+}
+/**
+ * Wire terms back to the public NativeRule shape. Stored terms carry calldata
+ * offsets and exact words but no ABI, so pins and amount are returned in the
+ * raw `offset` form (never a guessed argument index) and `selector` is the
+ * 4-byte hex. The result re-encodes to the same terms.
+ */
+function nativeTermsToRule(terms, agent) {
+    const rule = {
+        agent: (0, viem_1.getAddress)(agent),
+        target: (0, viem_1.getAddress)(terms.target),
+        selector: terms.selector.toLowerCase() === selectors_1.VALUE_ONLY_SELECTOR
+            ? 'value-only'
+            : terms.selector.toLowerCase(),
+        validUntil: Number(terms.validUntil),
+        maxValuePerCall: terms.maxValuePerCall,
+        maxValueTotal: terms.maxValueTotal,
+        maxCalls: Number(terms.maxCalls),
+    };
+    if (terms.pins.length > 0)
+        rule.wirePins = terms.pins.map((p) => ({ ...p }));
+    if (terms.amount.enabled) {
+        rule.amount = {
+            offset: Number(terms.amount.offset),
+            maxPerCall: terms.amount.maxPerCall,
+            maxTotal: terms.amount.maxTotal,
+        };
+    }
+    return rule;
+}
+/**
+ * Stored action terms back to a public NativeRule: the single-action
+ * shorthand for one action, otherwise `actions` in stored order. The rule's
+ * `validUntil` is the earliest action expiry; an action expiring later keeps
+ * its own `validUntil`, so the result re-encodes to identical terms.
+ */
+function nativeActionTermsToRule(termsList, agent) {
+    if (termsList.length === 0) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED, 'a native rule needs at least one action');
+    }
+    if (termsList.length === 1)
+        return nativeTermsToRule(termsList[0], agent);
+    const decoded = termsList.map((t) => nativeTermsToRule(t, agent));
+    const validUntil = Math.min(...decoded.map((d) => d.validUntil));
+    return {
+        agent: (0, viem_1.getAddress)(agent),
+        validUntil,
+        actions: decoded.map(({ agent: _agent, validUntil: actionValidUntil, ...action }) => actionValidUntil === validUntil
+            ? action
+            : { ...action, validUntil: actionValidUntil }),
+    };
+}
+function isUnlimited(value) {
+    return value === defaults_1.UINT256_MAX;
+}
+//# sourceMappingURL=native.js.map

package/src/lib/agentic/codec/pins.d.ts

@@ -0,0 +1,20 @@
+import type { Hex } from 'viem';
+export interface ArgPinWire {
+    offset: number;
+    op: 0 | 1;
+    value: Hex;
+}
+export declare const ARG_PIN_COMPONENTS: readonly [{
+    readonly name: "offset";
+    readonly type: "uint16";
+}, {
+    readonly name: "op";
+    readonly type: "uint8";
+}, {
+    readonly name: "value";
+    readonly type: "bytes32";
+}];
+export declare const UNLIMITED_CALLS = 4294967295;
+export declare const ANY_ACCOUNT_COUNT = 255;
+/** Validate every encoded constraint before signing. */
+export declare function validatePins(pins: readonly ArgPinWire[]): void;

package/src/lib/agentic/codec/pins.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANY_ACCOUNT_COUNT = exports.UNLIMITED_CALLS = exports.ARG_PIN_COMPONENTS = void 0;
+exports.validatePins = validatePins;
+exports.ARG_PIN_COMPONENTS = [
+    { name: 'offset', type: 'uint16' },
+    { name: 'op', type: 'uint8' },
+    { name: 'value', type: 'bytes32' },
+];
+exports.UNLIMITED_CALLS = 0xffffffff;
+exports.ANY_ACCOUNT_COUNT = 255;
+/** Validate every encoded constraint before signing. */
+function validatePins(pins) {
+    if (!Array.isArray(pins) || pins.length > 8)
+        throw new Error('pins must contain at most eight constraints');
+    const seen = new Set();
+    for (const p of pins) {
+        if (!Number.isInteger(p.offset) ||
+            p.offset < 4 ||
+            p.offset + 32 > 65535 ||
+            ![0, 1].includes(p.op) ||
+            !/^0x[0-9a-fA-F]{64}$/.test(p.value))
+            throw new Error('invalid argument pin');
+        if (seen.has(p.offset))
+            throw new Error('duplicate pin offset');
+        seen.add(p.offset);
+    }
+}
+//# sourceMappingURL=pins.js.map

package/src/lib/agentic/codec/rules.d.ts

@@ -0,0 +1,45 @@
+import { type Address, type Hex } from 'viem';
+import { AgenticCapability } from '../capabilities';
+import type { InternalRule, UniversalRule, SolanaRule } from '../agentic.types';
+import { type NativeTermsWire } from './native';
+import { type SessionWire } from './session';
+import { type ResolvedUniversalRule } from './universal';
+import { type SvmTermsWire } from './svm-terms';
+import type { UniversalTermsWire } from './universal-terms';
+export declare function isSolanaRule(rule: InternalRule): rule is SolanaRule;
+export declare function isUniversalRule(rule: InternalRule): rule is UniversalRule;
+/** CAIP-2 chain a rule governs: omitted = the connected Push chain. */
+export declare function ruleChain(rule: InternalRule, pushChainNamespace: string): string;
+export declare function chainHash(chainNamespace: string): Hex;
+export interface RuleEncodeContext {
+    /** 'eip155:<pushChainId>' of the connected network. */
+    pushChainNamespace: string;
+    validator: Address;
+    rulesPolicy: Address;
+    capabilities: ReadonlySet<AgenticCapability>;
+    nowSeconds: number;
+    gateway?: Address;
+    universal?: ReadonlyMap<UniversalRule, ResolvedUniversalRule>;
+    svm?: ReadonlyMap<SolanaRule, SvmTermsWire>;
+    /**
+     * Addresses a native rule may never target (AGW _requireGrantableTarget /
+     * URP NativeTargetIsGateway): wallet, engine, policy, validator, factory,
+     * gateway. 0x0 and 0x1 are always refused.
+     */
+    forbiddenTargets?: readonly Address[];
+}
+export interface PreparedRule {
+    rule: InternalRule;
+    agent: Address;
+    chainNamespace: string;
+    session: SessionWire;
+    /** Native terms, one per action in input order, when the rule is native. */
+    nativeTerms?: NativeTermsWire[];
+    universalTerms?: UniversalTermsWire;
+    svmTerms?: SvmTermsWire;
+}
+/** Validate before signing. V6 permits several grants for the same agent/chain. */
+export declare function prepareRules(rules: readonly InternalRule[], ctx: RuleEncodeContext & {
+    /** Wallet owner; when given, an agent equal to it is AGENT_IS_OWNER. */
+    owner?: Address;
+}): PreparedRule[];

package/src/lib/agentic/codec/rules.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSolanaRule = isSolanaRule;
+exports.isUniversalRule = isUniversalRule;
+exports.ruleChain = ruleChain;
+exports.chainHash = chainHash;
+exports.prepareRules = prepareRules;
+const viem_1 = require("viem");
+const capabilities_1 = require("../capabilities");
+const errors_1 = require("../errors");
+const native_1 = require("./native");
+const session_1 = require("./session");
+const universal_1 = require("./universal");
+const svm_terms_1 = require("./svm-terms");
+const v6_1 = require("../contracts/v6");
+function isSolanaRule(rule) {
+    return (typeof rule.chainNamespace === 'string' &&
+        rule.chainNamespace.startsWith('solana:'));
+}
+function isUniversalRule(rule) {
+    return (rule.chainNamespace !== undefined && !isSolanaRule(rule));
+}
+/** CAIP-2 chain a rule governs: omitted = the connected Push chain. */
+function ruleChain(rule, pushChainNamespace) {
+    return (rule.chainNamespace ?? pushChainNamespace);
+}
+function chainHash(chainNamespace) {
+    return (0, viem_1.keccak256)((0, viem_1.toBytes)(chainNamespace));
+}
+/** Validate before signing. V6 permits several grants for the same agent/chain. */
+function prepareRules(rules, ctx) {
+    if (!Array.isArray(rules)) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'rules must be an array');
+    }
+    return rules.map((rule, i) => {
+        if (!rule || typeof rule !== 'object') {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `rules[${i}] is not an object`);
+        }
+        if (!(0, viem_1.isAddress)(rule.agent, { strict: false }) ||
+            /^0x0{40}$/i.test(rule.agent)) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `rules[${i}].agent must be a non-zero Push address`);
+        }
+        const agent = (0, viem_1.getAddress)(rule.agent);
+        if (ctx.owner && agent === (0, viem_1.getAddress)(ctx.owner)) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.AGENT_IS_OWNER, `rules[${i}].agent is the wallet owner; the owner uses the owner door`);
+        }
+        const chainNamespace = ruleChain(rule, ctx.pushChainNamespace);
+        if (isUniversalRule(rule) &&
+            rule.chainNamespace === ctx.pushChainNamespace) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `rules[${i}] names the connected Push chain; omit chainNamespace for a native rule`);
+        }
+        if ('ref' in rule) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'InternalRule ref is not supported; remove it from the input');
+        }
+        if (isSolanaRule(rule)) {
+            (0, capabilities_1.requireCapability)(ctx.capabilities, capabilities_1.AgenticCapability.UNIVERSAL_SVM_RULES);
+            const terms = ctx.svm?.get(rule);
+            if (!terms || !ctx.gateway)
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'SVM rules require resolved wallet context and validated instruction layouts');
+            return {
+                rule,
+                agent,
+                chainNamespace,
+                svmTerms: terms,
+                session: (0, session_1.buildSession)({
+                    validator: ctx.validator,
+                    rulesPolicy: ctx.rulesPolicy,
+                    agent,
+                    actions: [
+                        {
+                            target: ctx.gateway,
+                            selector: v6_1.SEND_OUTBOUND_SELECTOR,
+                            initData: (0, session_1.encodeEnvelope)(chainNamespace, (0, svm_terms_1.encodeSvmTerms)(terms, ctx.nowSeconds)),
+                        },
+                    ],
+                }),
+            };
+        }
+        if (isUniversalRule(rule)) {
+            return (0, universal_1.encodeUniversalRule)(rule, ctx);
+        }
+        (0, capabilities_1.requireCapability)(ctx.capabilities, capabilities_1.AgenticCapability.NATIVE_RULES);
+        const actions = (0, native_1.nativeRuleToActionTerms)(rule, ctx).map((a) => a.terms);
+        const forbidden = [
+            '0x0000000000000000000000000000000000000000',
+            '0x0000000000000000000000000000000000000001',
+            ...(ctx.forbiddenTargets ?? []),
+        ].map((a) => a.toLowerCase());
+        actions.forEach((terms, j) => {
+            if (forbidden.includes(terms.target.toLowerCase())) {
+                const where = actions.length > 1 ? `rules[${i}].actions[${j}]` : `rules[${i}]`;
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `${where}.target ${terms.target} is a wallet-infrastructure address the contracts refuse as a native target`);
+            }
+        });
+        // One rule, one rule ID: every action is a separate (target, selector)
+        // entry of the same session, each with its own stored terms.
+        const session = (0, session_1.buildSession)({
+            validator: ctx.validator,
+            agent,
+            rulesPolicy: ctx.rulesPolicy,
+            actions: actions.map((terms) => ({
+                target: terms.target,
+                selector: terms.selector,
+                initData: (0, session_1.encodeEnvelope)(chainNamespace, (0, native_1.encodeNativeTerms)(terms)),
+            })),
+        });
+        return { rule, agent, chainNamespace, session, nativeTerms: actions };
+    });
+}
+//# sourceMappingURL=rules.js.map

package/src/lib/agentic/codec/selectors.d.ts

@@ -0,0 +1,19 @@
+import { type AbiParameter } from 'viem';
+import type { AgenticHex, Selector } from '../agentic.types';
+/** Selector URP uses for a value-only native rule (empty calldata). */
+export declare const VALUE_ONLY_SELECTOR: "0xffffffff";
+export interface ParsedSelector {
+    /** 4-byte selector, lowercase. */
+    selector: AgenticHex;
+    /** Canonical signature when the caller supplied one. */
+    signature?: string;
+    /** ABI inputs, only available when the caller supplied a signature. */
+    inputs?: readonly AbiParameter[];
+    valueOnly: boolean;
+}
+/**
+ * Parse a public selector (`'0x617ba037'`, `'supply(address,uint256,address,uint16)'`
+ * or `'value-only'`). A signature is required wherever pins, amounts or
+ * beneficiaries need argument positions; a bare hex selector carries none.
+ */
+export declare function parseSelector(input: Selector | 'value-only'): ParsedSelector;

package/src/lib/agentic/codec/selectors.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALUE_ONLY_SELECTOR = void 0;
+exports.parseSelector = parseSelector;
+const viem_1 = require("viem");
+const errors_1 = require("../errors");
+/** Selector URP uses for a value-only native rule (empty calldata). */
+exports.VALUE_ONLY_SELECTOR = '0xffffffff';
+const HEX_SELECTOR = /^0x[0-9a-fA-F]{8}$/;
+/**
+ * Parse a public selector (`'0x617ba037'`, `'supply(address,uint256,address,uint16)'`
+ * or `'value-only'`). A signature is required wherever pins, amounts or
+ * beneficiaries need argument positions; a bare hex selector carries none.
+ */
+function parseSelector(input) {
+    if (input === 'value-only') {
+        return { selector: exports.VALUE_ONLY_SELECTOR, valueOnly: true };
+    }
+    if (typeof input !== 'string') {
+        throw invalid(`selector must be a string, got ${typeof input}`);
+    }
+    if (HEX_SELECTOR.test(input)) {
+        const selector = input.toLowerCase();
+        if (selector === exports.VALUE_ONLY_SELECTOR) {
+            return { selector, valueOnly: true };
+        }
+        return { selector, valueOnly: false };
+    }
+    let item;
+    try {
+        const parsed = (0, viem_1.parseAbiItem)(`function ${input}`);
+        if (parsed.type !== 'function')
+            throw new Error('not a function');
+        item = parsed;
+    }
+    catch (cause) {
+        throw invalid(`selector "${input}" is neither a 4-byte hex selector nor a function signature`, cause);
+    }
+    const selector = (0, viem_1.toFunctionSelector)(item).toLowerCase();
+    if (selector === exports.VALUE_ONLY_SELECTOR) {
+        throw invalid(`selector "${input}" collides with the reserved value-only selector`);
+    }
+    return {
+        selector,
+        signature: `${item.name}(${item.inputs.map(canonicalType).join(',')})`,
+        inputs: item.inputs,
+        valueOnly: false,
+    };
+}
+function canonicalType(p) {
+    if (p.type.startsWith('tuple')) {
+        const components = p.components ?? [];
+        return `(${components.map(canonicalType).join(',')})${p.type.slice(5)}`;
+    }
+    return p.type;
+}
+function invalid(message, cause) {
+    return new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, message, { cause });
+}
+//# sourceMappingURL=selectors.js.map

package/src/lib/agentic/codec/session.d.ts

@@ -0,0 +1,54 @@
+import { type AbiParameter, type Address, type Hex } from 'viem';
+/**
+ * The smartsessions `Session` a grant carries (DataTypes.sol:56-86, pinned
+ * v6). The wallet overwrites `salt` with its grant nonce, so the value
+ * sent is irrelevant; it is always zero here.
+ */
+export interface SessionWire {
+    sessionValidator: Address;
+    sessionValidatorInitData: Hex;
+    salt: Hex;
+    userOpPolicies: readonly {
+        policy: Address;
+        initData: Hex;
+    }[];
+    erc7739Policies: {
+        allowedERC7739Content: readonly {
+            appDomainSeparator: Hex;
+            contentNames: readonly string[];
+        }[];
+        erc1271Policies: readonly {
+            policy: Address;
+            initData: Hex;
+        }[];
+    };
+    actions: readonly {
+        actionTargetSelector: Hex;
+        actionTarget: Address;
+        actionPolicies: readonly {
+            policy: Address;
+            initData: Hex;
+        }[];
+    }[];
+    permitERC4337Paymaster: boolean;
+}
+export declare const SESSION_PARAM: AbiParameter;
+export declare const ENVELOPE_VERSION = 1;
+/** V6 URP envelope: abi.encode(uint16(1), string chainNamespace, bytes body). */
+export declare function encodeEnvelope(chainNamespace: string, body: Hex): Hex;
+export declare function decodeEnvelope(initData: Hex): {
+    chainNamespace: string;
+    body: Hex;
+};
+export declare function buildSession(ctx: {
+    validator: Address;
+    agent: Address;
+    rulesPolicy: Address;
+    actions: {
+        target: Address;
+        selector: Hex;
+        initData: Hex;
+    }[];
+}): SessionWire;
+export declare function encodeSession(session: SessionWire): Hex;
+export declare function decodeSession(bytes: Hex): SessionWire;