@pushchain/core 6.0.26 → 6.0.27-alpha.0

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

@@ -0,0 +1,51 @@
+/**
+ * THE single home for omitted-limit defaults. Native PC defaults are zero as
+ * confirmed on October 7. Nothing else in the SDK may invent
+ * a fallback for these fields; update this table for future changes.
+ *
+ * Explicit zero always stays zero. In the native policy a zero value/amount
+ * cap forbids positive value/amount, while maxCalls = 0 means unlimited.
+ */
+export declare const UINT256_MAX: bigint;
+export interface DefaultRow {
+    value: bigint;
+    meaning: string;
+    source: 'product' | 'v5';
+}
+export declare const AGENTIC_DEFAULTS: {
+    readonly native: {
+        readonly maxValuePerCall: {
+            readonly value: bigint;
+            readonly meaning: "no native value transfer";
+            readonly source: "product";
+        };
+        readonly maxValueTotal: {
+            readonly value: bigint;
+            readonly meaning: "no native value transfer";
+            readonly source: "product";
+        };
+        readonly amountMaxTotal: {
+            readonly value: bigint;
+            readonly meaning: "unlimited metered total";
+            readonly source: "product";
+        };
+        readonly maxCalls: {
+            readonly value: bigint;
+            readonly meaning: "unlimited calls until expiry";
+            readonly source: "product";
+        };
+    };
+    readonly universal: {
+        readonly assetMaxTotal: {
+            readonly value: bigint;
+            readonly meaning: "omitted or zero forbids token movement";
+            readonly source: "product";
+        };
+        readonly allowedCallMaxValue: {
+            readonly value: bigint;
+            readonly meaning: "no native value attached to the destination call";
+            readonly source: "product";
+        };
+    };
+};
+export declare function withDefault(value: bigint | undefined, row: DefaultRow): bigint;

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

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENTIC_DEFAULTS = exports.UINT256_MAX = void 0;
+exports.withDefault = withDefault;
+/**
+ * THE single home for omitted-limit defaults. Native PC defaults are zero as
+ * confirmed on October 7. Nothing else in the SDK may invent
+ * a fallback for these fields; update this table for future changes.
+ *
+ * Explicit zero always stays zero. In the native policy a zero value/amount
+ * cap forbids positive value/amount, while maxCalls = 0 means unlimited.
+ */
+exports.UINT256_MAX = BigInt(2) ** BigInt(256) - BigInt(1);
+exports.AGENTIC_DEFAULTS = {
+    native: {
+        maxValuePerCall: {
+            value: BigInt(0),
+            meaning: 'no native value transfer',
+            source: 'product',
+        },
+        maxValueTotal: {
+            value: BigInt(0),
+            meaning: 'no native value transfer',
+            source: 'product',
+        },
+        amountMaxTotal: {
+            value: exports.UINT256_MAX,
+            meaning: 'unlimited metered total',
+            source: 'product',
+        },
+        maxCalls: {
+            value: BigInt(0),
+            meaning: 'unlimited calls until expiry',
+            source: 'product',
+        },
+    },
+    universal: {
+        assetMaxTotal: {
+            value: BigInt(0),
+            meaning: 'omitted or zero forbids token movement',
+            source: 'product',
+        },
+        allowedCallMaxValue: {
+            value: BigInt(0),
+            meaning: 'no native value attached to the destination call',
+            source: 'product',
+        },
+    },
+};
+function withDefault(value, row) {
+    return value === undefined ? row.value : value;
+}
+//# sourceMappingURL=defaults.js.map

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

@@ -0,0 +1,35 @@
+import { type Address, type Hex } from 'viem';
+/**
+ * Pure identity helpers mirroring the pinned AGW generation (v5):
+ *   smartsessions IdLib.toActionId / toConfigId / toPermissionId and
+ *   AGWFactory._predict (OZ Clones immutable-args CREATE2).
+ * Every input that changes the result is explicit — validator, factory and
+ * implementation are internal generation context.
+ */
+/** keccak256(abi.encodePacked(address target, bytes4 selector)). */
+export declare function actionId(target: Address, selector: Hex): Hex;
+/** keccak256(abi.encodePacked(wallet, keccak256(abi.encodePacked(rulesId, actionId)))). */
+export declare function configId(wallet: Address, rulesId: Hex, action: Hex): Hex;
+/** sessionValidatorInitData for the agent validator: abi.encode(address agent). */
+export declare function agentConfig(agent: Address): Hex;
+/**
+ * The rules ID a grant produces:
+ *   keccak256(abi.encode(validator, bytes abi.encode(agent), bytes32(grantNonce))).
+ * Chain is NOT part of the hash; records are keyed by wallet + rulesId.
+ */
+export declare function rulesId(ctx: {
+    validator: Address;
+    agent: Address;
+    grantNonce: bigint;
+}): Hex;
+/**
+ * Counterfactual wallet address: CREATE2 by the factory proxy of an OZ clone
+ * of `walletImplementation` with immutable args (owner ‖ factory), salt
+ * keccak256(abi.encode(owner, uint96 index)).
+ */
+export declare function deriveWallet(ctx: {
+    factory: Address;
+    walletImplementation: Address;
+    owner: Address;
+    index: bigint | number;
+}): Address;

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

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.actionId = actionId;
+exports.configId = configId;
+exports.agentConfig = agentConfig;
+exports.rulesId = rulesId;
+exports.deriveWallet = deriveWallet;
+const viem_1 = require("viem");
+const errors_1 = require("../errors");
+/**
+ * Pure identity helpers mirroring the pinned AGW generation (v5):
+ *   smartsessions IdLib.toActionId / toConfigId / toPermissionId and
+ *   AGWFactory._predict (OZ Clones immutable-args CREATE2).
+ * Every input that changes the result is explicit — validator, factory and
+ * implementation are internal generation context.
+ */
+/** keccak256(abi.encodePacked(address target, bytes4 selector)). */
+function actionId(target, selector) {
+    return (0, viem_1.keccak256)((0, viem_1.encodePacked)(['address', 'bytes4'], [target, selector]));
+}
+/** keccak256(abi.encodePacked(wallet, keccak256(abi.encodePacked(rulesId, actionId)))). */
+function configId(wallet, rulesId, action) {
+    const inner = (0, viem_1.keccak256)((0, viem_1.encodePacked)(['bytes32', 'bytes32'], [rulesId, action]));
+    return (0, viem_1.keccak256)((0, viem_1.encodePacked)(['address', 'bytes32'], [wallet, inner]));
+}
+/** sessionValidatorInitData for the agent validator: abi.encode(address agent). */
+function agentConfig(agent) {
+    return (0, viem_1.encodeAbiParameters)([{ type: 'address' }], [agent]);
+}
+/**
+ * The rules ID a grant produces:
+ *   keccak256(abi.encode(validator, bytes abi.encode(agent), bytes32(grantNonce))).
+ * Chain is NOT part of the hash; records are keyed by wallet + rulesId.
+ */
+function rulesId(ctx) {
+    if (ctx.grantNonce < BigInt(0) || ctx.grantNonce >= BigInt(2) ** BigInt(64)) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'grantNonce must fit uint64');
+    }
+    return (0, viem_1.keccak256)((0, viem_1.encodeAbiParameters)([{ type: 'address' }, { type: 'bytes' }, { type: 'bytes32' }], [
+        ctx.validator,
+        agentConfig(ctx.agent),
+        (0, viem_1.numberToHex)(ctx.grantNonce, { size: 32 }),
+    ]));
+}
+const UINT96_MAX = BigInt(2) ** BigInt(96) - BigInt(1);
+/**
+ * Counterfactual wallet address: CREATE2 by the factory proxy of an OZ clone
+ * of `walletImplementation` with immutable args (owner ‖ factory), salt
+ * keccak256(abi.encode(owner, uint96 index)).
+ */
+function deriveWallet(ctx) {
+    const index = BigInt(ctx.index);
+    if (index < BigInt(0) || index > UINT96_MAX) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'wallet index must fit uint96');
+    }
+    const salt = (0, viem_1.keccak256)((0, viem_1.encodeAbiParameters)([{ type: 'address' }, { type: 'uint96' }], [ctx.owner, index]));
+    const args = (0, viem_1.encodePacked)(['address', 'address'], [ctx.owner, ctx.factory]);
+    const argsLength = (args.length - 2) / 2;
+    const initCode = (0, viem_1.concat)([
+        '0x61',
+        (0, viem_1.numberToHex)(argsLength + 0x2d, { size: 2 }),
+        '0x3d81600a3d39f3363d3d373d3d3d363d73',
+        ctx.walletImplementation,
+        '0x5af43d82803e903d91602b57fd5bf3',
+        args,
+    ]);
+    return (0, viem_1.getAddress)((0, viem_1.getContractAddress)({
+        opcode: 'CREATE2',
+        from: ctx.factory,
+        salt,
+        bytecodeHash: (0, viem_1.keccak256)(initCode),
+    }));
+}
+//# sourceMappingURL=ids.js.map

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

@@ -0,0 +1,75 @@
+import { type AbiParameter, type Address, type Hex } from 'viem';
+import type { NativeAction, NativeRule, NativeSingleRule } from '../agentic.types';
+import { type ParsedSelector } from './selectors';
+/** URP native limits at v5 (Types.sol MAX_PINS, AGW MAX_NATIVE_ACTIONS). */
+export declare const MAX_PINS = 8;
+export declare const MAX_NATIVE_ACTIONS = 8;
+/** NativeTerms (Types.sol:354-363 at v5). */
+export interface NativeTermsWire {
+    validUntil: number;
+    target: Address;
+    selector: Hex;
+    maxValuePerCall: bigint;
+    maxValueTotal: bigint;
+    amount: {
+        enabled: boolean;
+        offset: number;
+        maxPerCall: bigint;
+        maxTotal: bigint;
+    };
+    maxCalls: number;
+    pins: readonly {
+        offset: number;
+        expected: Hex;
+    }[];
+}
+export declare const NATIVE_TERMS_PARAM: AbiParameter;
+export interface NativeEncodeContext {
+    /** Current unix time in seconds; grants with validUntil <= now are rejected. */
+    nowSeconds: number;
+}
+/**
+ * The actions a native rule allows: the single-action shorthand, or the
+ * explicit `actions` list (1..8). Each carries its effective `validUntil`.
+ */
+export declare function nativeActionsOf(rule: NativeRule): (NativeAction & {
+    validUntil: number;
+})[];
+/**
+ * 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.
+ */
+export declare function nativeRuleToActionTerms(rule: NativeRule, ctx: NativeEncodeContext): {
+    terms: NativeTermsWire;
+    parsed: ParsedSelector;
+}[];
+/** Single-action convenience; multi-action rules use nativeRuleToActionTerms. */
+export declare function nativeRuleToTerms(rule: NativeRule, ctx: NativeEncodeContext): {
+    terms: NativeTermsWire;
+    parsed: ParsedSelector;
+};
+/** Normalize and validate one native action into wire terms. Pure. */
+export declare function nativeActionToTerms(rule: NativeAction & {
+    validUntil: number;
+}, ctx: NativeEncodeContext): {
+    terms: NativeTermsWire;
+    parsed: ParsedSelector;
+};
+export declare function encodeNativeTerms(terms: NativeTermsWire): Hex;
+export declare function decodeNativeTerms(body: Hex): NativeTermsWire;
+/**
+ * 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.
+ */
+export declare function nativeTermsToRule(terms: NativeTermsWire, agent: Address): NativeSingleRule;
+/**
+ * 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.
+ */
+export declare function nativeActionTermsToRule(termsList: readonly NativeTermsWire[], agent: Address): NativeRule;
+export declare function isUnlimited(value: bigint): boolean;

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

@@ -0,0 +1,328 @@
+"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 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 v5 (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: [
+                { name: 'offset', type: 'uint16' },
+                { name: 'expected', type: 'bytes32' },
+            ],
+        },
+    ],
+};
+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',
+    '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,
+            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.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');
+    }
+    return {
+        parsed,
+        terms: {
+            validUntil: rule.validUntil,
+            target: (0, viem_1.getAddress)(rule.target),
+            selector: parsed.selector,
+            maxValuePerCall,
+            maxValueTotal,
+            amount,
+            maxCalls,
+            pins,
+        },
+    };
+}
+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.pins = terms.pins.map((p) => ({
+            offset: Number(p.offset),
+            expected: p.expected.toLowerCase(),
+        }));
+    }
+    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/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. V5 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[];