@pushchain/core 6.0.26 → 6.0.27-alpha.1

package/src/lib/agentic/codec/svm-terms.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SVM_TERMS_PARAM = exports.FORBIDDEN_SVM_PROGRAMS = exports.UINT64_MAX = exports.SVM_LIMITS = exports.SvmDataPinMode = void 0;
+exports.svmInvalid = svmInvalid;
+exports.exactHex = exactHex;
+exports.isForbiddenSvmProgram = isForbiddenSvmProgram;
+exports.validateSvmTerms = validateSvmTerms;
+exports.encodeSvmTerms = encodeSvmTerms;
+exports.decodeSvmTerms = decodeSvmTerms;
+/** Internal v6 SVM wire representation; not a proposed public Rule API. */
+const viem_1 = require("viem");
+const errors_1 = require("../errors");
+const defaults_1 = require("./defaults");
+var SvmDataPinMode;
+(function (SvmDataPinMode) {
+    SvmDataPinMode[SvmDataPinMode["EQ"] = 0] = "EQ";
+    SvmDataPinMode[SvmDataPinMode["GTE_LE"] = 1] = "GTE_LE";
+    SvmDataPinMode[SvmDataPinMode["LTE_LE"] = 2] = "LTE_LE";
+    SvmDataPinMode[SvmDataPinMode["RATIO_GTE_LE"] = 3] = "RATIO_GTE_LE";
+})(SvmDataPinMode || (exports.SvmDataPinMode = SvmDataPinMode = {}));
+exports.SVM_LIMITS = {
+    assets: 8,
+    programs: 32,
+    pins: 16,
+    dataPins: 8,
+    ceaAccounts: 16,
+    accounts: 64,
+    ixData: 1024,
+};
+exports.UINT64_MAX = BigInt(2) ** BigInt(64) - BigInt(1);
+exports.FORBIDDEN_SVM_PROGRAMS = [
+    `0x${'00'.repeat(32)}`,
+    '0x06ddf6e1d765a193d9cbe146ceeb79ac1cb485ed5f5b37913a8cf5857eff00a9',
+    '0x06ddf6e1ee758fde18425dbce46ccddab61afc4d83b90d27febdf928d8a18bfc',
+    '0x06a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc000000000',
+    '0x02a8f6914e88a1b0e210153ef763ae2b00c2b93d16c124d2c0537a1004800000',
+    '0x0277a6af97339b7ac88d1892c90446f50002309266f62e53c118244982000000',
+];
+exports.SVM_TERMS_PARAM = {
+    type: 'tuple',
+    components: [
+        { name: 'validUntil', type: 'uint48' },
+        { name: 'expectedCEA', type: 'bytes32' },
+        { name: 'gatewayProgram', type: 'bytes32' },
+        {
+            name: 'assets',
+            type: 'tuple[]',
+            components: [
+                { name: 'token', type: 'address' },
+                { name: 'maxPerCall', type: 'uint256' },
+                { name: 'maxTotal', type: 'uint256' },
+            ],
+        },
+        { name: 'maxGasPerCall', type: 'uint256' },
+        { name: 'ceaAccounts', type: 'bytes32[]' },
+        {
+            name: 'programs',
+            type: 'tuple[]',
+            components: [
+                { name: 'program', type: 'bytes32' },
+                { name: 'discriminator', type: 'bytes8' },
+                { name: 'discriminatorLen', type: 'uint8' },
+                { name: 'dataless', type: 'bool' },
+                { name: 'maxAccounts', type: 'uint8' },
+            ],
+        },
+        {
+            name: 'pins',
+            type: 'tuple[]',
+            components: [
+                { name: 'ruleIndex', type: 'uint8' },
+                { name: 'accountIndex', type: 'uint8' },
+                { name: 'expected', type: 'bytes32' },
+            ],
+        },
+        {
+            name: 'dataPins',
+            type: 'tuple[]',
+            components: [
+                { name: 'ruleIndex', type: 'uint8' },
+                { name: 'fromEnd', type: 'bool' },
+                { name: 'offset', type: 'uint16' },
+                { name: 'offsetB', type: 'uint16' },
+                { name: 'len', type: 'uint8' },
+                { name: 'mode', type: 'uint8' },
+                { name: 'expected', type: 'bytes32' },
+                { name: 'num', type: 'uint64' },
+                { name: 'den', type: 'uint64' },
+            ],
+        },
+    ],
+};
+function svmInvalid(message) {
+    return new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, message);
+}
+function exactHex(value, bytes, field) {
+    if (typeof value !== 'string' ||
+        !new RegExp(`^0x[0-9a-fA-F]{${bytes * 2}}$`).test(value))
+        throw svmInvalid(`${field} must contain exactly ${bytes} bytes`);
+}
+function integer(value, max, field) {
+    if (!Number.isInteger(value) || value < 0 || value > max)
+        throw svmInvalid(`${field} is out of range`);
+}
+function uint(value, max, field) {
+    if (typeof value !== 'bigint' || value < BigInt(0) || value > max)
+        throw svmInvalid(`${field} is out of range`);
+}
+function isForbiddenSvmProgram(program, terms) {
+    return [
+        ...exports.FORBIDDEN_SVM_PROGRAMS,
+        terms.gatewayProgram,
+        terms.expectedCEA,
+    ].some((x) => x.toLowerCase() === program.toLowerCase());
+}
+function offsetValid(fromEnd, offset, len) {
+    return fromEnd
+        ? offset >= len && offset <= exports.SVM_LIMITS.ixData
+        : offset + len <= exports.SVM_LIMITS.ixData;
+}
+/** Grant-time structural rules. Chain/token/mint correctness requires resolved on-chain inputs. */
+function validateSvmTerms(t, nowSeconds) {
+    integer(t.validUntil, 2 ** 48 - 1, 'validUntil');
+    if (t.validUntil <= nowSeconds)
+        throw svmInvalid('validUntil must be in the future');
+    exactHex(t.expectedCEA, 32, 'expectedCEA');
+    exactHex(t.gatewayProgram, 32, 'gatewayProgram');
+    if (BigInt(t.expectedCEA) === BigInt(0) ||
+        BigInt(t.gatewayProgram) === BigInt(0))
+        throw svmInvalid('CEA/gateway cannot be zero');
+    uint(t.maxGasPerCall, defaults_1.UINT256_MAX, 'maxGasPerCall');
+    if (!t.assets.length || t.assets.length > exports.SVM_LIMITS.assets)
+        throw svmInvalid('assets must contain 1..8 entries');
+    const tokens = new Set();
+    for (const a of t.assets) {
+        if (!(0, viem_1.isAddress)(a.token, { strict: false }) || BigInt(a.token) === BigInt(0))
+            throw svmInvalid('asset token must be a non-zero PRC20');
+        if (tokens.has(a.token.toLowerCase()))
+            throw svmInvalid('duplicate asset');
+        tokens.add(a.token.toLowerCase());
+        uint(a.maxPerCall, defaults_1.UINT256_MAX, 'maxPerCall');
+        uint(a.maxTotal, defaults_1.UINT256_MAX, 'maxTotal');
+    }
+    if (!t.programs.length || t.programs.length > exports.SVM_LIMITS.programs)
+        throw svmInvalid('programs must contain 1..32 entries');
+    t.programs.forEach((r, i) => {
+        exactHex(r.program, 32, 'program');
+        exactHex(r.discriminator, 8, 'discriminator');
+        if (typeof r.dataless !== 'boolean')
+            throw svmInvalid('dataless must be boolean');
+        integer(r.discriminatorLen, 8, 'discriminatorLen');
+        if (r.maxAccounts !== 255) {
+            integer(r.maxAccounts, exports.SVM_LIMITS.accounts, 'maxAccounts');
+            if (r.maxAccounts === 0)
+                throw svmInvalid('maxAccounts must be 1..64 or 255');
+        }
+        if (r.dataless !== (r.discriminatorLen === 0))
+            throw svmInvalid('dataless and discriminator length disagree');
+        if (isForbiddenSvmProgram(r.program, t))
+            throw svmInvalid('forbidden program');
+        for (const earlier of t.programs.slice(0, i)) {
+            if (earlier.program.toLowerCase() !== r.program.toLowerCase())
+                continue;
+            const overlap = earlier.dataless || r.dataless
+                ? earlier.dataless && r.dataless
+                : earlier.discriminator
+                    .slice(0, 2 + 2 * Math.min(earlier.discriminatorLen, r.discriminatorLen))
+                    .toLowerCase() ===
+                    r.discriminator
+                        .slice(0, 2 + 2 * Math.min(earlier.discriminatorLen, r.discriminatorLen))
+                        .toLowerCase();
+            if (overlap)
+                throw svmInvalid('ambiguous instruction discriminator prefixes');
+        }
+    });
+    if (t.pins.length > exports.SVM_LIMITS.pins)
+        throw svmInvalid('too many account pins');
+    const positions = new Set(), covered = new Set();
+    for (const p of t.pins) {
+        integer(p.ruleIndex, t.programs.length - 1, 'pin ruleIndex');
+        integer(p.accountIndex, exports.SVM_LIMITS.accounts - 1, 'accountIndex');
+        exactHex(p.expected, 32, 'pin expected');
+        const count = t.programs[p.ruleIndex].maxAccounts;
+        if (count !== 255 && p.accountIndex >= count)
+            throw svmInvalid('pin outside fixed account count');
+        const key = `${p.ruleIndex}:${p.accountIndex}`;
+        if (positions.has(key))
+            throw svmInvalid('duplicate account pin');
+        positions.add(key);
+        covered.add(p.ruleIndex);
+    }
+    if (covered.size !== t.programs.length)
+        throw svmInvalid('every program rule needs an account pin');
+    if (t.dataPins.length > exports.SVM_LIMITS.dataPins)
+        throw svmInvalid('too many data pins');
+    for (const p of t.dataPins) {
+        integer(p.ruleIndex, t.programs.length - 1, 'data pin ruleIndex');
+        integer(p.mode, 3, 'data pin mode');
+        integer(p.len, p.mode === SvmDataPinMode.EQ ? 32 : 8, 'data pin len');
+        integer(p.offset, 65535, 'offset');
+        integer(p.offsetB, 65535, 'offsetB');
+        exactHex(p.expected, 32, 'data pin expected');
+        uint(p.num, exports.UINT64_MAX, 'num');
+        uint(p.den, exports.UINT64_MAX, 'den');
+        if (typeof p.fromEnd !== 'boolean' ||
+            !p.len ||
+            t.programs[p.ruleIndex].dataless ||
+            !offsetValid(p.fromEnd, p.offset, p.len))
+            throw svmInvalid('invalid data pin shape');
+        if (p.mode === SvmDataPinMode.EQ &&
+            !/^0*$/.test(p.expected.slice(2 + p.len * 2)))
+            throw svmInvalid('EQ expected must be left-aligned');
+        if ((p.mode === SvmDataPinMode.GTE_LE || p.mode === SvmDataPinMode.LTE_LE) &&
+            BigInt(p.expected) >= BigInt(1) << BigInt(p.len * 8))
+            throw svmInvalid('integer expected exceeds field width');
+        if (p.mode === SvmDataPinMode.RATIO_GTE_LE &&
+            (!p.num || !p.den || !offsetValid(p.fromEnd, p.offsetB, p.len)))
+            throw svmInvalid('invalid ratio pin');
+    }
+    if (t.ceaAccounts.length > exports.SVM_LIMITS.ceaAccounts)
+        throw svmInvalid('too many CEA accounts');
+    const accounts = new Set();
+    for (const key of t.ceaAccounts) {
+        exactHex(key, 32, 'CEA account');
+        if (BigInt(key) === BigInt(0) ||
+            accounts.has(key.toLowerCase()) ||
+            t.programs.some((p) => p.program.toLowerCase() === key.toLowerCase()))
+            throw svmInvalid('invalid CEA account list');
+        accounts.add(key.toLowerCase());
+    }
+    if (!accounts.has(t.expectedCEA.toLowerCase()))
+        throw svmInvalid('CEA account list must include expectedCEA');
+}
+function encodeSvmTerms(terms, nowSeconds) {
+    validateSvmTerms(terms, nowSeconds);
+    return (0, viem_1.encodeAbiParameters)([exports.SVM_TERMS_PARAM], [terms]);
+}
+function decodeSvmTerms(body) {
+    try {
+        return (0, viem_1.decodeAbiParameters)([exports.SVM_TERMS_PARAM], body)[0];
+    }
+    catch (cause) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED, 'malformed SVM terms', { cause });
+    }
+}
+//# sourceMappingURL=svm-terms.js.map

package/src/lib/agentic/codec/universal-terms.d.ts

@@ -0,0 +1,82 @@
+import { type ArgPinWire } from './pins';
+import { type Address, type Hex } from 'viem';
+export interface AssetCapWire {
+    token: Address;
+    maxPerCall: bigint;
+    maxTotal: bigint;
+}
+export interface AllowedCallWire {
+    pins: readonly ArgPinWire[];
+    target: Address;
+    selector: Hex;
+    beneficiaryOffset: number;
+    hasBeneficiary: boolean;
+    maxValue: bigint;
+}
+export interface UniversalTermsWire {
+    validUntil: number;
+    expectedCEA: Address;
+    assets: readonly AssetCapWire[];
+    maxGasPerCall: bigint;
+    allowedCalls: readonly AllowedCallWire[];
+}
+export declare const UNIVERSAL_TERMS_PARAM: {
+    readonly type: "tuple";
+    readonly components: readonly [{
+        readonly name: "validUntil";
+        readonly type: "uint48";
+    }, {
+        readonly name: "expectedCEA";
+        readonly type: "address";
+    }, {
+        readonly name: "assets";
+        readonly type: "tuple[]";
+        readonly components: readonly [{
+            readonly name: "token";
+            readonly type: "address";
+        }, {
+            readonly name: "maxPerCall";
+            readonly type: "uint256";
+        }, {
+            readonly name: "maxTotal";
+            readonly type: "uint256";
+        }];
+    }, {
+        readonly name: "maxGasPerCall";
+        readonly type: "uint256";
+    }, {
+        readonly name: "allowedCalls";
+        readonly type: "tuple[]";
+        readonly components: readonly [{
+            readonly name: "target";
+            readonly type: "address";
+        }, {
+            readonly name: "selector";
+            readonly type: "bytes4";
+        }, {
+            readonly name: "beneficiaryOffset";
+            readonly type: "uint16";
+        }, {
+            readonly name: "hasBeneficiary";
+            readonly type: "bool";
+        }, {
+            readonly name: "maxValue";
+            readonly type: "uint256";
+        }, {
+            readonly name: "pins";
+            readonly type: "tuple[]";
+            readonly components: readonly [{
+                readonly name: "offset";
+                readonly type: "uint16";
+            }, {
+                readonly name: "op";
+                readonly type: "uint8";
+            }, {
+                readonly name: "value";
+                readonly type: "bytes32";
+            }];
+        }];
+    }];
+};
+export declare function encodeUniversalTerms(terms: UniversalTermsWire): Hex;
+export declare function decodeUniversalTerms(body: Hex): UniversalTermsWire;

package/src/lib/agentic/codec/universal-terms.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNIVERSAL_TERMS_PARAM = void 0;
+exports.encodeUniversalTerms = encodeUniversalTerms;
+exports.decodeUniversalTerms = decodeUniversalTerms;
+const pins_1 = require("./pins");
+const viem_1 = require("viem");
+exports.UNIVERSAL_TERMS_PARAM = {
+    type: 'tuple',
+    components: [
+        { name: 'validUntil', type: 'uint48' },
+        { name: 'expectedCEA', type: 'address' },
+        {
+            name: 'assets',
+            type: 'tuple[]',
+            components: [
+                { name: 'token', type: 'address' },
+                { name: 'maxPerCall', type: 'uint256' },
+                { name: 'maxTotal', type: 'uint256' },
+            ],
+        },
+        { name: 'maxGasPerCall', type: 'uint256' },
+        {
+            name: 'allowedCalls',
+            type: 'tuple[]',
+            components: [
+                { name: 'target', type: 'address' },
+                { name: 'selector', type: 'bytes4' },
+                { name: 'beneficiaryOffset', type: 'uint16' },
+                { name: 'hasBeneficiary', type: 'bool' },
+                { name: 'maxValue', type: 'uint256' },
+                { name: 'pins', type: 'tuple[]', components: pins_1.ARG_PIN_COMPONENTS },
+            ],
+        },
+    ],
+};
+function encodeUniversalTerms(terms) {
+    return (0, viem_1.encodeAbiParameters)([exports.UNIVERSAL_TERMS_PARAM], [terms]);
+}
+function decodeUniversalTerms(body) {
+    return (0, viem_1.decodeAbiParameters)([exports.UNIVERSAL_TERMS_PARAM], body)[0];
+}
+//# sourceMappingURL=universal-terms.js.map

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

@@ -0,0 +1,14 @@
+import { type Address } from 'viem';
+import type { UniversalRule } from '../agentic.types';
+import type { RuleEncodeContext, PreparedRule } from './rules';
+import { type AssetCapWire, type UniversalTermsWire } from './universal-terms';
+export declare const MAX_ASSETS = 8;
+export declare const MAX_ALLOWED_CALLS = 32;
+export interface ResolvedUniversalRule {
+    expectedCEA: Address;
+    assets: readonly AssetCapWire[];
+}
+export declare function validateUniversalRuleShape(rule: UniversalRule, nowSeconds: number): void;
+export declare function encodeUniversalRule(rule: UniversalRule, ctx: RuleEncodeContext): PreparedRule;
+/** Source token addresses must be resolved from each PRC20 before calling this. */
+export declare function universalTermsToRule(terms: UniversalTermsWire, agent: Address, chainNamespace: UniversalRule['chainNamespace'], tokens: readonly Address[]): UniversalRule;

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

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ALLOWED_CALLS = exports.MAX_ASSETS = void 0;
+exports.validateUniversalRuleShape = validateUniversalRuleShape;
+exports.encodeUniversalRule = encodeUniversalRule;
+exports.universalTermsToRule = universalTermsToRule;
+const pins_1 = require("./pins");
+const viem_1 = require("viem");
+const capabilities_1 = require("../capabilities");
+const errors_1 = require("../errors");
+const abi_layout_1 = require("./abi-layout");
+const selectors_1 = require("./selectors");
+const defaults_1 = require("./defaults");
+const session_1 = require("./session");
+const v6_1 = require("../contracts/v6");
+const universal_terms_1 = require("./universal-terms");
+exports.MAX_ASSETS = 8;
+exports.MAX_ALLOWED_CALLS = 32;
+const CAIP2 = /^(eip155:[0-9]+|solana:[1-9A-HJ-NP-Za-km-z]{32,44})$/;
+const UINT48_MAX = 2 ** 48 - 1;
+function cap(value, what) {
+    if (typeof value !== 'bigint' || value < BigInt(0) || value > defaults_1.UINT256_MAX)
+        throw invalid(`${what} must be a uint256 bigint`);
+}
+function validateUniversalRuleShape(rule, nowSeconds) {
+    if (typeof rule.chainNamespace !== 'string' ||
+        !CAIP2.test(rule.chainNamespace))
+        throw invalid('chainNamespace must be a CAIP-2 eip155/solana chain');
+    if (!Number.isSafeInteger(rule.validUntil) ||
+        rule.validUntil <= nowSeconds ||
+        rule.validUntil > UINT48_MAX)
+        throw invalid('validUntil must be a future uint48 unix timestamp');
+    if (!Array.isArray(rule.assets) || rule.assets.length > exports.MAX_ASSETS)
+        throw invalid(`assets must be an array of at most ${exports.MAX_ASSETS} caps`);
+    cap(rule.maxGasPerCall, 'maxGasPerCall');
+    if (rule.maxGasPerCall === BigInt(0))
+        throw invalid('maxGasPerCall must be positive');
+    if (!Array.isArray(rule.allowedCalls) ||
+        rule.allowedCalls.length < 1 ||
+        rule.allowedCalls.length > exports.MAX_ALLOWED_CALLS)
+        throw invalid(`allowedCalls must contain 1..${exports.MAX_ALLOWED_CALLS} entries`);
+    const seen = new Map();
+    let pinCount = 0;
+    rule.allowedCalls.forEach((call, i) => {
+        if (!(0, viem_1.isAddress)(call.target, { strict: false }))
+            throw invalid(`allowedCalls[${i}].target is not an EVM address`);
+        const parsed = (0, selectors_1.parseSelector)(call.selector);
+        if (parsed.valueOnly)
+            throw invalid(`allowedCalls[${i}] cannot be value-only`);
+        if (call.beneficiary !== undefined && call.beneficiaryOffset !== undefined)
+            throw invalid('beneficiary and beneficiaryOffset are mutually exclusive');
+        if (call.beneficiary !== undefined) {
+            (0, abi_layout_1.argumentOffset)(parsed.inputs, call.beneficiary, `allowedCalls[${i}].beneficiary`);
+            if (parsed.inputs?.[call.beneficiary]?.type !== 'address')
+                throw invalid(`allowedCalls[${i}].beneficiary must be an address argument`);
+        }
+        if (call.beneficiaryOffset !== undefined)
+            (0, abi_layout_1.rawOffset)(call.beneficiaryOffset, `allowedCalls[${i}].beneficiary`);
+        cap(call.maxValue ?? defaults_1.AGENTIC_DEFAULTS.universal.allowedCallMaxValue.value, `allowedCalls[${i}].maxValue`);
+        try {
+            (0, pins_1.validatePins)(call.pins ?? []);
+        }
+        catch (error) {
+            throw invalid(error.message);
+        }
+        pinCount += call.pins?.length ?? 0;
+        if (pinCount > 32)
+            throw invalid('at most 32 pins across all allowed calls');
+        const key = `${call.target.toLowerCase()}:${parsed.selector}`;
+        const restricted = !!call.pins?.length ||
+            call.beneficiary !== undefined ||
+            call.beneficiaryOffset !== undefined;
+        if (seen.has(key) && (!restricted || !seen.get(key)))
+            throw invalid('an unpinned alternative would bypass restrictions for this target/selector');
+        seen.set(key, restricted);
+    });
+    const tokens = new Set();
+    rule.assets.forEach((a, i) => {
+        const address = typeof a.token === 'string' ? a.token : a.token?.address;
+        if (typeof address !== 'string')
+            throw invalid(`assets[${i}].token is missing an address`);
+        const key = address.toLowerCase();
+        if (tokens.has(key))
+            throw invalid(`assets[${i}] duplicates an earlier token`);
+        tokens.add(key);
+        cap(a.maxPerCall, `assets[${i}].maxPerCall`);
+        cap((0, defaults_1.withDefault)(a.maxTotal, defaults_1.AGENTIC_DEFAULTS.universal.assetMaxTotal), `assets[${i}].maxTotal`);
+    });
+}
+function encodeUniversalRule(rule, ctx) {
+    if (rule.chainNamespace.startsWith('solana:'))
+        (0, capabilities_1.requireCapability)(ctx.capabilities, capabilities_1.AgenticCapability.UNIVERSAL_SVM_RULES);
+    validateUniversalRuleShape(rule, ctx.nowSeconds);
+    (0, capabilities_1.requireCapability)(ctx.capabilities, rule.chainNamespace.startsWith('solana:')
+        ? capabilities_1.AgenticCapability.UNIVERSAL_SVM_RULES
+        : capabilities_1.AgenticCapability.UNIVERSAL_EVM_RULES);
+    const resolved = ctx.universal?.get(rule);
+    if (!resolved || !ctx.gateway)
+        throw invalid('universal encoding requires resolved wallet CEA, PRC20 assets and gateway context');
+    if (resolved.assets.length < 1 ||
+        resolved.assets.length > exports.MAX_ASSETS ||
+        new Set(resolved.assets.map((a) => a.token.toLowerCase())).size !==
+            resolved.assets.length)
+        throw invalid('resolved assets must be 1..8 distinct PRC20s');
+    if (!(0, viem_1.isAddress)(resolved.expectedCEA) ||
+        /^0x0{40}$/i.test(resolved.expectedCEA))
+        throw invalid('expectedCEA must be a non-zero wallet destination account');
+    const terms = {
+        validUntil: rule.validUntil,
+        expectedCEA: (0, viem_1.getAddress)(resolved.expectedCEA),
+        assets: resolved.assets,
+        maxGasPerCall: rule.maxGasPerCall,
+        allowedCalls: rule.allowedCalls.map((call) => ({
+            pins: call.pins ?? [],
+            target: (0, viem_1.getAddress)(call.target),
+            selector: (0, selectors_1.parseSelector)(call.selector).selector,
+            hasBeneficiary: call.beneficiary !== undefined || call.beneficiaryOffset !== undefined,
+            beneficiaryOffset: call.beneficiaryOffset ??
+                (call.beneficiary === undefined
+                    ? 0
+                    : (0, abi_layout_1.argumentOffset)((0, selectors_1.parseSelector)(call.selector).inputs, call.beneficiary, 'beneficiary')),
+            maxValue: (0, defaults_1.withDefault)(call.maxValue, defaults_1.AGENTIC_DEFAULTS.universal.allowedCallMaxValue),
+        })),
+    };
+    const agent = (0, viem_1.getAddress)(rule.agent);
+    return {
+        rule,
+        agent,
+        chainNamespace: rule.chainNamespace,
+        universalTerms: terms,
+        session: (0, session_1.buildSession)({
+            validator: ctx.validator,
+            agent,
+            rulesPolicy: ctx.rulesPolicy,
+            actions: [
+                {
+                    target: ctx.gateway,
+                    selector: v6_1.SEND_OUTBOUND_SELECTOR,
+                    initData: (0, session_1.encodeEnvelope)(rule.chainNamespace, (0, universal_terms_1.encodeUniversalTerms)(terms)),
+                },
+            ],
+        }),
+    };
+}
+/** Source token addresses must be resolved from each PRC20 before calling this. */
+function universalTermsToRule(terms, agent, chainNamespace, tokens) {
+    if (tokens.length !== terms.assets.length)
+        throw invalid('origin-token list does not match stored asset order');
+    return {
+        agent,
+        chainNamespace,
+        validUntil: Number(terms.validUntil),
+        maxGasPerCall: terms.maxGasPerCall,
+        assets: terms.assets.map((a, i) => ({
+            token: tokens[i],
+            maxPerCall: a.maxPerCall,
+            maxTotal: a.maxTotal,
+        })),
+        allowedCalls: terms.allowedCalls.map((c) => ({
+            pins: [...c.pins],
+            target: c.target,
+            selector: c.selector,
+            maxValue: c.maxValue,
+            ...(c.hasBeneficiary
+                ? { beneficiaryOffset: Number(c.beneficiaryOffset) }
+                : {}),
+        })),
+    };
+}
+function invalid(message) {
+    return new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, message);
+}
+//# sourceMappingURL=universal.js.map

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

@@ -0,0 +1,12 @@
+/** Public section-7 discovery constants; deployment wiring stays internal. */
+export declare const AGENTIC: Readonly<{
+    WALLET: "agentic:wallet";
+    PRESETS: Readonly<{
+        CATEGORY: Readonly<{
+            DEXES: "DEXES";
+            LENDING: "LENDING";
+            STAKING: "STAKING";
+            PREDICTION: "PREDICTION";
+        }>;
+    }>;
+}>;

package/src/lib/agentic/constants.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENTIC = void 0;
+/** Public section-7 discovery constants; deployment wiring stays internal. */
+exports.AGENTIC = Object.freeze({
+    WALLET: 'agentic:wallet',
+    PRESETS: Object.freeze({
+        CATEGORY: Object.freeze({
+            DEXES: 'DEXES',
+            LENDING: 'LENDING',
+            STAKING: 'STAKING',
+            PREDICTION: 'PREDICTION',
+        }),
+    }),
+});
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1,29 @@
+import { type Address } from 'viem';
+import { CHAIN } from '../constants/enums';
+import { type AgenticGeneration } from './deployments';
+import type { AgenticRuntime } from './runtime';
+import type { AgenticDoor } from './agentic.types';
+/**
+ * Identity of an agentic client. Three values stay separate:
+ *  - signerOrigin:        the key that signs (universal.origin)
+ *  - signerPushAccount:   its Push identity — EOA or UEA for its origin chain;
+ *                         pays Push gas and is the identity ownership checks use
+ *  - wallet:              the AGW, the execution account (universal.account)
+ */
+export interface AgenticExecutionContext {
+    wallet: Address;
+    door: AgenticDoor;
+    signerPushAccount: Address;
+    signerOrigin: {
+        chain: CHAIN;
+        address: string;
+    };
+    generation: AgenticGeneration;
+}
+/**
+ * Initialization-time resolution for `initialize(signer, { agenticWallet })`.
+ * Owner → owner door. Otherwise at least one ENABLED rule must name the
+ * signer's Push identity (expired-but-enabled still qualifies; expiry is an
+ * on-chain send check). Nothing here is cached for later sends.
+ */
+export declare function resolveAgenticContext(runtime: AgenticRuntime, walletInput: string): Promise<AgenticExecutionContext>;

package/src/lib/agentic/context.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAgenticContext = resolveAgenticContext;
+const viem_1 = require("viem");
+const capabilities_1 = require("./capabilities");
+const deployments_1 = require("./deployments");
+const errors_1 = require("./errors");
+const rules_1 = require("./reads/rules");
+const snapshot_1 = require("./reads/snapshot");
+/**
+ * Initialization-time resolution for `initialize(signer, { agenticWallet })`.
+ * Owner → owner door. Otherwise at least one ENABLED rule must name the
+ * signer's Push identity (expired-but-enabled still qualifies; expiry is an
+ * on-chain send check). Nothing here is cached for later sends.
+ */
+async function resolveAgenticContext(runtime, walletInput) {
+    let wallet;
+    try {
+        wallet = (0, viem_1.getAddress)(walletInput);
+    }
+    catch (cause) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.NOT_AGENTIC_WALLET, `"${walletInput}" is not an address`, {
+            cause,
+        });
+    }
+    const generation = await (0, deployments_1.resolveWalletGeneration)(runtime.reader, runtime.network, wallet);
+    const signerPushAccount = runtime.signerPushAccount();
+    const snap = await snapshot_1.Snapshot.at(runtime.reader);
+    const owner = (0, viem_1.getAddress)(await snap.read(wallet, generation.contracts.abis.wallet, 'owner'));
+    let door;
+    if (owner === signerPushAccount) {
+        (0, capabilities_1.requireCapability)(generation.capabilities, capabilities_1.AgenticCapability.OWNER_EXECUTE);
+        door = 'owner';
+    }
+    else {
+        (0, capabilities_1.requireCapability)(generation.capabilities, capabilities_1.AgenticCapability.AGENT_EXECUTE);
+        const active = await (0, rules_1.readActiveRules)(snap, generation, wallet);
+        if (!active.some((r) => r.agent === signerPushAccount)) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.NOT_OWNER_OR_AGENT, `${signerPushAccount} is neither the owner of ${wallet} nor the agent of an enabled rule`, {
+                hint: runtime.signerIsPushNative()
+                    ? 'Grant a rule to this Push address, or initialize with the owner signer.'
+                    : 'An external key acts through its UEA for the chain it was initialized on; grant the rule to that UEA (PushChain.utils.account.deriveExecutorAccount).',
+                details: { wallet, signerPushAccount, owner },
+            });
+        }
+        door = 'agent';
+    }
+    return {
+        wallet,
+        door,
+        signerPushAccount,
+        signerOrigin: runtime.signerOrigin(),
+        generation,
+    };
+}
+//# sourceMappingURL=context.js.map