@pushchain/core 6.0.25 → 6.0.27-alpha.0

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

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

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

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

package/src/lib/agentic/reads/checkpoints.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCheckpoints = readCheckpoints;
+exports.validateSequence = validateSequence;
+const capabilities_1 = require("../capabilities");
+const errors_1 = require("../errors");
+const snapshot_1 = require("./snapshot");
+const MAX_ATTEMPTS = 2;
+/**
+ * w.checkpoints(): Checkpointed events in (block, tx, log) order, checked
+ * against the wallet's checkpointCount() at the same snapshot block.
+ * `sinceBlock` is inclusive. Evaluators should compare counts — one block can
+ * hold several ticks, and allowance pulls change balances without any tick.
+ */
+async function readCheckpoints(reader, gen, wallet, sinceBlock) {
+    (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.CHECKPOINTS);
+    let lastError;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        const snap = await snapshot_1.Snapshot.at(reader);
+        const count = BigInt(await snap.read(wallet, gen.contracts.abis.wallet, 'checkpointCount'));
+        const from = sinceBlock !== undefined && sinceBlock > gen.startBlock
+            ? sinceBlock
+            : gen.startBlock;
+        const filter = {
+            address: wallet,
+            event: gen.contracts.events.checkpointed,
+        };
+        let logs;
+        try {
+            logs = await (0, snapshot_1.scanLogs)(reader, filter, from, snap.blockNumber);
+        }
+        catch (cause) {
+            const retained = lowestRetainedHeight(cause);
+            // A fresh wallet may have its entire history after the RPC retention
+            // floor. Never treat truncation as success: the FULL sequence/count
+            // validation below must still prove every checkpoint is present.
+            if (sinceBlock !== undefined ||
+                retained === undefined ||
+                retained <= from ||
+                retained > snap.blockNumber)
+                throw cause;
+            logs = await (0, snapshot_1.scanLogs)(reader, filter, retained, snap.blockNumber);
+        }
+        const decoded = gen.contracts
+            .parseCheckpointed(logs, wallet)
+            .sort((a, b) => a.blockNumber !== b.blockNumber
+            ? a.blockNumber < b.blockNumber
+                ? -1
+                : 1
+            : a.transactionIndex !== b.transactionIndex
+                ? a.transactionIndex - b.transactionIndex
+                : a.logIndex - b.logIndex);
+        const problem = validateSequence(decoded.map((c) => c.seq), count, sinceBlock === undefined || from === gen.startBlock);
+        if (!problem) {
+            return {
+                count,
+                blockNumber: snap.blockNumber,
+                checkpoints: decoded.map(({ seq, kind, ref, blockNumber, txHash }) => ({
+                    seq,
+                    kind,
+                    ref,
+                    blockNumber,
+                    txHash,
+                })),
+            };
+        }
+        lastError = new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INCONSISTENT_READ, problem, {
+            details: { wallet, count, blockNumber: snap.blockNumber },
+        });
+    }
+    throw lastError;
+}
+/** Sequence must be contiguous, end at `count`, and start at 1 for a full scan. */
+function validateSequence(seqs, count, fullRange) {
+    for (let i = 1; i < seqs.length; i++) {
+        if (seqs[i] !== seqs[i - 1] + 1)
+            return `checkpoint sequence gap between ${seqs[i - 1]} and ${seqs[i]}`;
+    }
+    if (fullRange) {
+        if (BigInt(seqs.length) !== count) {
+            return `found ${seqs.length} Checkpointed events but checkpointCount() is ${count}`;
+        }
+        if (seqs.length > 0 && seqs[0] !== 1)
+            return `first checkpoint seq is ${seqs[0]}, expected 1`;
+        return null;
+    }
+    if (seqs.length > 0 && BigInt(seqs[seqs.length - 1]) !== count) {
+        return `last checkpoint seq ${seqs[seqs.length - 1]} does not match checkpointCount() ${count}`;
+    }
+    return null;
+}
+/** Recognize Donut/CometBFT's explicit pruning error, not arbitrary RPC failures. */
+function lowestRetainedHeight(error) {
+    const visited = new Set();
+    for (let depth = 0; depth < 8 && error && typeof error === 'object' && !visited.has(error); depth++) {
+        visited.add(error);
+        const value = error;
+        for (const text of [value.message, value.details]) {
+            if (typeof text !== 'string')
+                continue;
+            const match = /height \d+ is not available, lowest height is (\d+)/.exec(text);
+            if (match)
+                return BigInt(match[1]);
+        }
+        error = value.cause;
+    }
+    return undefined;
+}
+//# sourceMappingURL=checkpoints.js.map

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

@@ -0,0 +1,42 @@
+import { type Address, type Hex } from 'viem';
+import type { AgenticGeneration } from '../deployments';
+import type { RulesRecord } from '../agentic.types';
+import { Snapshot } from './snapshot';
+export interface ActiveRule {
+    rulesId: Hex;
+    /** agentOf(rulesId); zero means the engine no longer resolves it. */
+    agent: Address;
+    actionIds: readonly Hex[];
+    mode: number;
+    vm: number;
+    chainHash: Hex;
+}
+/** Enabled rule IDs with their agent and governed chain, all at one block. */
+export declare function readActiveRules(snap: Snapshot, gen: AgenticGeneration, wallet: Address): Promise<ActiveRule[]>;
+/** Map a stored chain hash back to its CAIP-2 string from known chains. */
+export declare function chainFromHash(hash: Hex, pushChainNamespace: string): string | undefined;
+/**
+ * Agent-door rule selection for one send (spec 2.a): enabled rules whose agent
+ * is the signer and whose chain is the destination, read uncached at one
+ * block. Expiry, caps and policy remain on-chain checks.
+ */
+export declare function selectRuleForSend(snap: Snapshot, gen: AgenticGeneration, wallet: Address, agent: Address, destinationChain: string): Promise<ActiveRule>;
+/** Decode one active rule into the public record. */
+export declare function decodeActiveRule(snap: Snapshot, gen: AgenticGeneration, wallet: Address, rule: ActiveRule, pushChainNamespace: string): Promise<RulesRecord>;
+/** Native spend counters for the update assertion. */
+export declare function readNativeSpend(snap: Snapshot, gen: AgenticGeneration, wallet: Address, rule: ActiveRule, action?: Hex): Promise<{
+    configId: Hex;
+    valueSpent: bigint;
+    amountSpent: bigint;
+    callsUsed: number;
+}>;
+export declare function readUniversalSpend(snap: Snapshot, gen: AgenticGeneration, wallet: Address, rule: ActiveRule): Promise<{
+    configId: Hex;
+    expectedSpent: bigint[];
+}>;
+export declare function listRules(snap: Snapshot, gen: AgenticGeneration, wallet: Address, pushChainNamespace: string): Promise<RulesRecord[]>;
+/**
+ * rules.get returns enabled records only. Unknown/revoked IDs are deliberately
+ * indistinguishable without historical reconstruction, which is outside v1.
+ */
+export declare function getRule(snap: Snapshot, gen: AgenticGeneration, wallet: Address, rulesId: Hex, pushChainNamespace: string): Promise<RulesRecord>;