@pushchain/core 6.0.26 → 6.0.27-alpha.1

package/src/lib/agentic/codec/abi-layout.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDynamic = isDynamic;
+exports.headSize = headSize;
+exports.isSingleWordStatic = isSingleWordStatic;
+exports.argumentOffset = argumentOffset;
+exports.encodeArgWord = encodeArgWord;
+exports.rawOffset = rawOffset;
+exports.argumentLocation = argumentLocation;
+const viem_1 = require("viem");
+const errors_1 = require("../errors");
+/**
+ * ABI head layout for argument-position terms (native pins/amount, universal
+ * beneficiary). Contracts take ABSOLUTE byte offsets into calldata with the
+ * 4-byte selector included and read exactly one 32-byte word there, so only a
+ * single-word static elementary argument can be addressed. Preceding
+ * arguments may be dynamic (one head word: the offset pointer) or static
+ * tuples / fixed arrays (several head words); both are accounted for here.
+ */
+const UINT16_MAX = 0xffff;
+function components(p) {
+    return p.components ?? [];
+}
+/** Parse a trailing fixed/dynamic array suffix: 'uint256[3]' → base 'uint256', length 3. */
+function arraySuffix(type) {
+    const m = /^(.*)\[(\d*)\]$/.exec(type);
+    if (!m)
+        return null;
+    return { base: m[1], length: m[2] === '' ? null : Number(m[2]) };
+}
+function isDynamic(p) {
+    const arr = arraySuffix(p.type);
+    if (arr) {
+        if (arr.length === null)
+            return true;
+        return isDynamic({ ...p, type: arr.base });
+    }
+    if (p.type === 'bytes' || p.type === 'string')
+        return true;
+    if (p.type === 'tuple')
+        return components(p).some(isDynamic);
+    return false;
+}
+/** Bytes this parameter occupies in the head of an encoding. */
+function headSize(p) {
+    if (isDynamic(p))
+        return 32;
+    const arr = arraySuffix(p.type);
+    if (arr && arr.length !== null) {
+        return arr.length * headSize({ ...p, type: arr.base });
+    }
+    if (p.type === 'tuple') {
+        return components(p).reduce((sum, c) => sum + headSize(c), 0);
+    }
+    return 32;
+}
+const ELEMENTARY = /^(address|bool|u?int(8|16|24|32|40|48|56|64|72|80|88|96|104|112|120|128|136|144|152|160|168|176|184|192|200|208|216|224|232|240|248|256)?|bytes([1-9]|[12][0-9]|3[0-2]))$/;
+function isSingleWordStatic(p) {
+    return ELEMENTARY.test(p.type);
+}
+/**
+ * Absolute calldata byte offset (selector included) of argument `arg`.
+ * Rejects out-of-range indexes and any argument that is not one static word.
+ */
+function argumentOffset(inputs, arg, what) {
+    if (!inputs) {
+        throw invalid(`${what} needs the function signature (e.g. 'supply(address,uint256,address,uint16)'), not a bare 4-byte selector`);
+    }
+    if (!Number.isInteger(arg) || arg < 0 || arg >= inputs.length) {
+        throw invalid(`${what} argument index ${arg} is out of range (0..${inputs.length - 1})`);
+    }
+    const target = inputs[arg];
+    if (!isSingleWordStatic(target)) {
+        throw invalid(`${what} argument ${arg} has type ${target.type}; only single-word static arguments can be pinned`);
+    }
+    let offset = 4;
+    for (let i = 0; i < arg; i++)
+        offset += headSize(inputs[i]);
+    if (offset + 32 > UINT16_MAX) {
+        throw invalid(`${what} argument ${arg} lies beyond the uint16 offset range`);
+    }
+    return offset;
+}
+/** Encode a pin's expected value as the exact 32-byte calldata word. */
+function encodeArgWord(param, expected, what) {
+    try {
+        const isWord = typeof expected === 'string' && (0, viem_1.isHex)(expected) && expected.length === 66;
+        if (param.type === 'address' && !isWord) {
+            if (typeof expected !== 'string' ||
+                !(0, viem_1.isAddress)(expected, { strict: false })) {
+                throw new Error('expected an address');
+            }
+        }
+        else if (param.type.startsWith('bytes') && !isWord) {
+            if (typeof expected !== 'string' || !(0, viem_1.isHex)(expected))
+                throw new Error('expected hex');
+        }
+        // An already-encoded 32-byte word (as decoded rules return) is accepted
+        // when it is a canonical encoding of this argument type.
+        if (typeof expected === 'string' &&
+            (0, viem_1.isHex)(expected) &&
+            expected.length === 66 &&
+            param.type !== 'bytes32') {
+            const [value] = (0, viem_1.decodeAbiParameters)([param], expected);
+            if ((0, viem_1.encodeAbiParameters)([param], [value]).toLowerCase() !==
+                expected.toLowerCase()) {
+                throw new Error('word is not a canonical encoding');
+            }
+            return expected.toLowerCase();
+        }
+        return (0, viem_1.encodeAbiParameters)([param], [expected]);
+    }
+    catch (cause) {
+        throw invalid(`${what} expected value does not encode as ${param.type}: ${cause instanceof Error ? cause.message : String(cause)}`, cause);
+    }
+}
+/** Validate a raw calldata offset given directly (offset form). */
+function rawOffset(offset, what) {
+    if (!Number.isInteger(offset) || offset < 4 || offset + 32 > UINT16_MAX) {
+        throw invalid(`${what} offset ${offset} must be an integer in [4, ${UINT16_MAX - 32}] (selector included)`);
+    }
+    return offset;
+}
+function invalid(message, cause) {
+    return new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, message, { cause });
+}
+/** Absolute location of a scalar reached through static tuple/fixed-array indexes. */
+function argumentLocation(inputs, arg, what) {
+    if (!inputs)
+        throw invalid(`${what} paths require a full function signature`);
+    const path = typeof arg === 'number' ? [arg] : arg;
+    if (!Array.isArray(path) ||
+        path.length === 0 ||
+        path.length > 16 ||
+        path.some((i) => !Number.isSafeInteger(i) || i < 0))
+        throw invalid(`${what} has an invalid argument path`);
+    if (path[0] >= inputs.length)
+        throw invalid(`${what} argument path is out of range`);
+    let offset = 4 + inputs.slice(0, path[0]).reduce((n, p) => n + headSize(p), 0);
+    let param = inputs[path[0]];
+    for (const index of path.slice(1)) {
+        if (isDynamic(param))
+            throw invalid(`${what} cannot descend into a dynamic argument`);
+        const arr = arraySuffix(param.type);
+        if (arr && arr.length !== null) {
+            if (!Number.isSafeInteger(arr.length) || index >= arr.length)
+                throw invalid(`${what} fixed-array index is out of range`);
+            const child = { ...param, type: arr.base };
+            offset += index * headSize(child);
+            param = child;
+        }
+        else if (param.type === 'tuple') {
+            const fields = components(param);
+            if (index >= fields.length)
+                throw invalid(`${what} tuple index is out of range`);
+            offset += fields.slice(0, index).reduce((n, p) => n + headSize(p), 0);
+            param = fields[index];
+        }
+        else
+            throw invalid(`${what} path descends into a scalar`);
+    }
+    if (!isSingleWordStatic(param) ||
+        !Number.isSafeInteger(offset) ||
+        offset + 32 > UINT16_MAX)
+        throw invalid(`${what} must identify one static ABI word within the uint16 offset range`);
+    return { offset, param };
+}
+//# sourceMappingURL=abi-layout.js.map

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 = uint32 maximum means unlimited.
+ */
+export declare const UINT256_MAX: bigint;
+export interface DefaultRow {
+    value: bigint;
+    meaning: string;
+    source: 'product' | 'v6';
+}
+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 = uint32 maximum 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(0xffffffff),
+            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 (v6):
+ *   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 (v6):
+ *   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,73 @@
+import { type ArgPinWire } from './pins';
+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 v6 (Types.sol MAX_PINS, AGW MAX_NATIVE_ACTIONS). */
+export declare const MAX_PINS = 8;
+export declare const MAX_NATIVE_ACTIONS = 8;
+/** NativeTerms in the pinned v6 Types.sol. */
+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 ArgPinWire[];
+}
+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;