@pushchain/core 6.0.26 → 6.0.27-alpha.1

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>;

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

@@ -0,0 +1,302 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readActiveRules = readActiveRules;
+exports.chainFromHash = chainFromHash;
+exports.selectRuleForSend = selectRuleForSend;
+exports.decodeActiveRule = decodeActiveRule;
+exports.readNativeSpend = readNativeSpend;
+exports.readUniversalSpend = readUniversalSpend;
+exports.listRules = listRules;
+exports.getRule = getRule;
+const svm_1 = require("./svm");
+const prc20_metadata_1 = require("../contracts/prc20-metadata");
+const viem_1 = require("viem");
+const enums_1 = require("../../constants/enums");
+const capabilities_1 = require("../capabilities");
+const ids_1 = require("../codec/ids");
+const native_1 = require("../codec/native");
+const defaults_1 = require("../codec/defaults");
+const public_rule_1 = require("../public-rule");
+const errors_1 = require("../errors");
+const prc20_metadata_2 = require("../contracts/prc20-metadata");
+const rules_1 = require("../codec/rules");
+const errors_2 = require("../errors");
+const MODE_UNIVERSAL = 0;
+const MODE_NATIVE = 1;
+/** Enabled rule IDs with their agent and governed chain, all at one block. */
+async function readActiveRules(snap, gen, wallet) {
+    const ids = await snap.read(gen.addresses.sessionEngine, gen.contracts.abis.engine, 'getPermissionIDs', [wallet]);
+    return Promise.all(ids.map((id) => readActiveRule(snap, gen, wallet, id)));
+}
+async function readActiveRule(snap, gen, wallet, rulesId) {
+    const [agent, actionIds] = await Promise.all([
+        snap.read(wallet, gen.contracts.abis.wallet, 'agentOf', [rulesId]),
+        snap.read(gen.addresses.sessionEngine, gen.contracts.abis.engine, 'getEnabledActions', [wallet, rulesId]),
+    ]);
+    if (actionIds.length === 0) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, `enabled rule ${rulesId} has no enabled actions`);
+    }
+    const modes = await Promise.all(actionIds.map((a) => snap.read(gen.addresses.rulesPolicy, gen.contracts.abis.policy, 'getMode', [(0, ids_1.configId)(wallet, rulesId, a), wallet])));
+    const first = modes[0];
+    if (!modes.every((m) => m.initialized &&
+        m.chainHash === first.chainHash &&
+        m.mode === first.mode)) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, `rule ${rulesId} has uninitialized or mixed-chain policy configs`);
+    }
+    return {
+        rulesId,
+        agent: (0, viem_1.getAddress)(agent),
+        actionIds,
+        mode: Number(first.mode),
+        vm: Number(first.vm),
+        chainHash: first.chainHash,
+    };
+}
+/** Map a stored chain hash back to its CAIP-2 string from known chains. */
+function chainFromHash(hash, pushChainNamespace) {
+    const known = [pushChainNamespace, ...Object.values(enums_1.CHAIN)];
+    return known.find((c) => (0, rules_1.chainHash)(c) === hash);
+}
+/**
+ * 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.
+ */
+async function selectRuleForSend(snap, gen, wallet, agent, destinationChain) {
+    const active = await readActiveRules(snap, gen, wallet);
+    const want = (0, rules_1.chainHash)(destinationChain);
+    const matches = active.filter((r) => r.agent === (0, viem_1.getAddress)(agent) && r.chainHash === want);
+    if (matches.length === 0) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.NO_RULES_FOR_CHAIN, `no enabled rule on ${wallet} names ${agent} for ${destinationChain}`, {
+            details: {
+                wallet,
+                agent,
+                destinationChain,
+                blockNumber: snap.blockNumber,
+            },
+        });
+    }
+    if (matches.length > 1) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.AMBIGUOUS_RULE, `${matches.length} enabled rules on ${wallet} name ${agent} for ${destinationChain}`, {
+            hint: 'Multiple enabled rules match this agent and chain. Inspect details.rulesIds and ask the owner to resolve the overlap; no transaction was submitted.',
+            details: { rulesIds: matches.map((m) => m.rulesId) },
+        });
+    }
+    return matches[0];
+}
+/** Decode one active rule into the public record. */
+async function decodeActiveRule(snap, gen, wallet, rule, pushChainNamespace) {
+    if (rule.mode === MODE_UNIVERSAL) {
+        if (rule.vm === 1) {
+            (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.UNIVERSAL_SVM_RULES);
+            const stored = await (0, svm_1.readSvmConfig)(snap, gen, wallet, rule, pushChainNamespace);
+            const cfg = stored.config;
+            const gas = await (0, prc20_metadata_1.readGasPrc20)(snap, stored.chainNamespace);
+            const assets = await Promise.all(cfg.assets.map(async (a) => ({
+                token: (0, viem_1.getAddress)(a.token) === gas
+                    ? viem_1.zeroAddress
+                    : await (0, prc20_metadata_1.readSvmSourceToken)(snap, a.token, stored.chainNamespace, gen.network),
+                maxPerCall: a.maxPerCall,
+                maxTotal: a.maxTotal,
+            })));
+            return {
+                rulesId: rule.rulesId,
+                enabled: true,
+                agent: rule.agent,
+                chainNamespace: stored.chainNamespace,
+                validUntil: Number(cfg.validUntil),
+                spent: {
+                    kind: 'universal',
+                    assets: assets.map((a, i) => ({
+                        token: a.token,
+                        spent: cfg.assets[i].spent,
+                    })),
+                },
+                rule: {
+                    format: 'decoded',
+                    agent: rule.agent,
+                    chainNamespace: stored.chainNamespace,
+                    validUntil: Number(cfg.validUntil),
+                    expectedCEA: cfg.expectedCEA,
+                    gatewayProgram: cfg.gatewayProgram,
+                    maxGasPerCall: cfg.maxGasPerCall,
+                    assets,
+                    ceaAccounts: cfg.ceaAccounts,
+                    programs: cfg.programs,
+                    pins: cfg.pins,
+                    dataPins: cfg.dataPins,
+                },
+            };
+        }
+        if (rule.vm !== 0)
+            throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.RULE_READ_FAILED, 'unknown universal VM');
+        (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.UNIVERSAL_EVM_RULES);
+        const chain = chainFromHash(rule.chainHash, pushChainNamespace);
+        if (!chain || !chain.startsWith('eip155:'))
+            throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.RULE_READ_FAILED, 'unknown EVM rule chain');
+        const cfg = await snap.read(gen.addresses.rulesPolicy, gen.contracts.abis.policy, 'getConfig', [(0, ids_1.configId)(wallet, rule.rulesId, rule.actionIds[0]), wallet]);
+        if (!cfg.initialized)
+            throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, 'uninitialized universal rule');
+        if (!cfg.assets.length ||
+            cfg.assets.length > 8 ||
+            !cfg.allowedCalls.length ||
+            cfg.allowedCalls.length > 32 ||
+            cfg.expectedCEA === viem_1.zeroAddress)
+            throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, 'invalid stored universal rule shape');
+        const tokens = await Promise.all(cfg.assets.map((a) => (0, prc20_metadata_2.readOriginToken)(snap, a.token, chain)));
+        return {
+            rulesId: rule.rulesId,
+            enabled: true,
+            chainNamespace: chain,
+            agent: rule.agent,
+            validUntil: Number(cfg.validUntil),
+            spent: {
+                kind: 'universal',
+                assets: tokens.map((token, i) => ({
+                    token,
+                    spent: cfg.assets[i].spent,
+                })),
+            },
+            rule: {
+                agent: rule.agent,
+                chainNamespace: chain,
+                validUntil: Number(cfg.validUntil),
+                maxGasPerCall: cfg.maxGasPerCall,
+                assets: cfg.assets.map((a, i) => ({
+                    token: tokens[i],
+                    maxPerCall: a.maxPerCall,
+                    maxTotal: a.maxTotal,
+                })),
+                allowedCalls: cfg.allowedCalls.map((c) => ({
+                    target: c.target,
+                    selector: c.selector,
+                    maxValue: c.maxValue,
+                    pins: [
+                        ...c.pins.map((p) => p.op === 1
+                            ? { arg: storedArg(p.offset), max: BigInt(p.value) }
+                            : {
+                                arg: storedArg(p.offset),
+                                expected: p.value.toLowerCase() ===
+                                    `0x${cfg.expectedCEA
+                                        .slice(2)
+                                        .toLowerCase()
+                                        .padStart(64, '0')}`
+                                    ? public_rule_1.WALLET
+                                    : p.value,
+                            }),
+                        ...(c.hasBeneficiary
+                            ? [{ arg: storedArg(c.beneficiaryOffset), expected: public_rule_1.WALLET }]
+                            : []),
+                    ],
+                })),
+            },
+        };
+    }
+    if (rule.mode !== MODE_NATIVE) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.RULE_READ_FAILED, `rule ${rule.rulesId} has unknown mode ${rule.mode}`);
+    }
+    // One stored config per action, read at the same block, in engine order.
+    const configs = await Promise.all(rule.actionIds.map((action) => snap.read(gen.addresses.rulesPolicy, gen.contracts.abis.policy, 'getNativeConfig', [(0, ids_1.configId)(wallet, rule.rulesId, action), wallet])));
+    if (configs.some((c) => !c.initialized)) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, `native config for ${rule.rulesId} is not initialized`);
+    }
+    const decoded = (0, native_1.nativeActionTermsToRule)(configs, rule.agent);
+    if (configs.some((c) => c.maxValueTotal !== defaults_1.UINT256_MAX ||
+        Number(c.maxCalls) !== 0xffffffff ||
+        (c.amount.enabled && c.amount.maxTotal !== defaults_1.UINT256_MAX) ||
+        Number(c.validUntil) !== decoded.validUntil)) {
+        throw (0, errors_1.capabilityUnavailable)('nativeRuleRead', 'stored lifetime limits or differing action expiries cannot be represented by section-6 rules without losing constraints');
+    }
+    const allowedCalls = configs.map((c) => ({
+        target: (0, viem_1.getAddress)(c.target),
+        selector: c.selector === '0xffffffff' ? 'value-only' : c.selector,
+        maxValue: c.maxValuePerCall,
+        pins: [
+            ...c.pins.map((p) => p.op === 1
+                ? { arg: storedArg(p.offset), max: BigInt(p.value) }
+                : {
+                    arg: storedArg(p.offset),
+                    expected: p.value.toLowerCase() ===
+                        `0x${wallet.slice(2).toLowerCase().padStart(64, '0')}`
+                        ? public_rule_1.WALLET
+                        : p.value,
+                }),
+            ...(c.amount.enabled
+                ? [{ arg: storedArg(c.amount.offset), max: c.amount.maxPerCall }]
+                : []),
+        ],
+    }));
+    const counters = configs.map((c, i) => ({
+        target: allowedCalls[i].target,
+        selector: allowedCalls[i].selector,
+        valueSpent: c.valueSpent,
+        amountSpent: c.amountSpent,
+        callsUsed: Number(c.callsUsed),
+    }));
+    if (rule.agent === (0, viem_1.getAddress)(`0x${'00'.repeat(20)}`)) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, `enabled rule ${rule.rulesId} does not resolve to an agent`);
+    }
+    return {
+        rulesId: rule.rulesId,
+        enabled: true,
+        chainNamespace: pushChainNamespace,
+        agent: rule.agent,
+        validUntil: decoded.validUntil,
+        rule: { agent: rule.agent, validUntil: decoded.validUntil, allowedCalls },
+        spent: counters.length === 1
+            ? {
+                kind: 'native',
+                valueSpent: counters[0].valueSpent,
+                amountSpent: counters[0].amountSpent,
+                callsUsed: counters[0].callsUsed,
+            }
+            : { kind: 'native', actions: counters },
+    };
+}
+/** Native spend counters for the update assertion. */
+async function readNativeSpend(snap, gen, wallet, rule, action = rule.actionIds[0]) {
+    const id = (0, ids_1.configId)(wallet, rule.rulesId, action);
+    const cfg = await snap.read(gen.addresses.rulesPolicy, gen.contracts.abis.policy, 'getNativeConfig', [id, wallet]);
+    return {
+        configId: id,
+        valueSpent: cfg.valueSpent,
+        amountSpent: cfg.amountSpent,
+        callsUsed: Number(cfg.callsUsed),
+    };
+}
+async function readUniversalSpend(snap, gen, wallet, rule) {
+    const id = (0, ids_1.configId)(wallet, rule.rulesId, rule.actionIds[0]);
+    const fn = rule.vm === 1 ? 'getSvmConfig' : 'getConfig';
+    const cfg = await snap.read(gen.addresses.rulesPolicy, gen.contracts.abis.policy, fn, [id, wallet]);
+    if (!cfg.initialized)
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, 'uninitialized universal spend config');
+    return { configId: id, expectedSpent: cfg.assets.map((a) => a.spent) };
+}
+async function listRules(snap, gen, wallet, pushChainNamespace) {
+    (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.ACTIVE_RULE_READS);
+    const active = await readActiveRules(snap, gen, wallet);
+    const records = [];
+    for (const r of active)
+        records.push(await decodeActiveRule(snap, gen, wallet, r, pushChainNamespace));
+    return records;
+}
+/**
+ * rules.get returns enabled records only. Unknown/revoked IDs are deliberately
+ * indistinguishable without historical reconstruction, which is outside v1.
+ */
+async function getRule(snap, gen, wallet, rulesId, pushChainNamespace) {
+    (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.ACTIVE_RULE_READS);
+    const enabled = await snap.read(gen.addresses.sessionEngine, gen.contracts.abis.engine, 'isPermissionEnabled', [rulesId, wallet]);
+    if (enabled) {
+        const active = await readActiveRule(snap, gen, wallet, rulesId);
+        return decodeActiveRule(snap, gen, wallet, active, pushChainNamespace);
+    }
+    throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.RULE_NOT_FOUND, `rule ${rulesId} is not enabled on ${wallet} (unknown or revoked; v1 has no rule history)`);
+}
+/** With a raw selector, arg denotes its ABI head-word position. */
+function storedArg(offset) {
+    if (offset < 4 || (offset - 4) % 32 !== 0)
+        throw (0, errors_1.capabilityUnavailable)('argumentLayout', 'stored pin is not aligned to an ABI argument word');
+    return (offset - 4) / 32;
+}
+//# sourceMappingURL=rules.js.map

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

@@ -0,0 +1,28 @@
+import type { AbiEvent, Address, Log } from 'viem';
+import type { ChainReader } from '../contracts/reader';
+import { type AgenticErrorCode } from '../errors';
+/**
+ * All reads of one logical operation are pinned to a single block so dependent
+ * reads (enumerate IDs → per-ID config) observe one state. An RPC failure is
+ * surfaced as an error; it is never treated as "empty".
+ */
+export declare class Snapshot {
+    readonly reader: ChainReader;
+    readonly blockNumber: bigint;
+    private readonly failCode;
+    constructor(reader: ChainReader, blockNumber: bigint, failCode?: AgenticErrorCode);
+    static at(reader: ChainReader, failCode?: AgenticErrorCode): Promise<Snapshot>;
+    read<T>(address: Address, abi: readonly unknown[], functionName: string, args?: readonly unknown[]): Promise<T>;
+    code(address: Address): Promise<boolean>;
+}
+/** Max block span per eth_getLogs request. */
+export declare const LOG_PAGE_BLOCKS: bigint;
+/**
+ * Paginated log scan [fromBlock, toBlock] inclusive. A failed page fails the
+ * whole scan; partial results are never returned.
+ */
+export declare function scanLogs(reader: ChainReader, args: {
+    address: Address;
+    event: AbiEvent;
+    args?: Record<string, unknown>;
+}, fromBlock: bigint, toBlock: bigint, page?: bigint): Promise<Log[]>;

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

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOG_PAGE_BLOCKS = exports.Snapshot = void 0;
+exports.scanLogs = scanLogs;
+const errors_1 = require("../errors");
+/**
+ * All reads of one logical operation are pinned to a single block so dependent
+ * reads (enumerate IDs → per-ID config) observe one state. An RPC failure is
+ * surfaced as an error; it is never treated as "empty".
+ */
+class Snapshot {
+    reader;
+    blockNumber;
+    failCode;
+    constructor(reader, blockNumber, failCode = errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED) {
+        this.reader = reader;
+        this.blockNumber = blockNumber;
+        this.failCode = failCode;
+    }
+    static async at(reader, failCode = errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED) {
+        let block;
+        try {
+            block = await reader.getBlockNumber();
+        }
+        catch (cause) {
+            throw new errors_1.AgenticError(failCode, 'could not read the current Push block number', { cause });
+        }
+        return new Snapshot(reader, block, failCode);
+    }
+    async read(address, abi, functionName, args = []) {
+        try {
+            return (await this.reader.readContract({
+                address,
+                abi,
+                functionName,
+                args,
+                blockNumber: this.blockNumber,
+            }));
+        }
+        catch (cause) {
+            throw new errors_1.AgenticError(this.failCode, `${functionName} read on ${address} failed at block ${this.blockNumber}`, {
+                cause,
+                details: { address, functionName, blockNumber: this.blockNumber },
+            });
+        }
+    }
+    async code(address) {
+        try {
+            const code = await this.reader.getCode({
+                address,
+                blockNumber: this.blockNumber,
+            });
+            return !!code && code !== '0x';
+        }
+        catch (cause) {
+            throw new errors_1.AgenticError(this.failCode, `getCode(${address}) failed`, {
+                cause,
+            });
+        }
+    }
+}
+exports.Snapshot = Snapshot;
+/** Max block span per eth_getLogs request. */
+// Donut's public RPC limits eth_getLogs ranges to a distance of 1,000 blocks.
+exports.LOG_PAGE_BLOCKS = BigInt(1_000);
+/**
+ * Paginated log scan [fromBlock, toBlock] inclusive. A failed page fails the
+ * whole scan; partial results are never returned.
+ */
+async function scanLogs(reader, args, fromBlock, toBlock, page = exports.LOG_PAGE_BLOCKS) {
+    const out = [];
+    if (fromBlock > toBlock)
+        return out;
+    for (let start = fromBlock; start <= toBlock; start += page) {
+        const end = start + page - BigInt(1) > toBlock ? toBlock : start + page - BigInt(1);
+        try {
+            out.push(...(await reader.getLogs({ ...args, fromBlock: start, toBlock: end })));
+        }
+        catch (cause) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED, `log scan for ${args.event.name} failed for blocks ${start}-${end}`, { cause });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=snapshot.js.map

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

@@ -0,0 +1,17 @@
+/** Internal lossless SVM state shared by public reads and execution. */
+import type { Address, Hex } from 'viem';
+import type { AgenticGeneration } from '../deployments';
+import type { SvmConfigRead } from '../contracts/v6';
+import { type ActiveRule } from './rules';
+import type { Snapshot } from './snapshot';
+export interface SvmRuleSnapshot {
+    wallet: Address;
+    rulesId: Hex;
+    agent: Address;
+    chainNamespace: `solana:${string}`;
+    configId: Hex;
+    config: SvmConfigRead;
+    blockNumber: bigint;
+}
+export declare function readSvmRule(snap: Snapshot, gen: AgenticGeneration, wallet: Address, rulesId: Hex, pushChainNamespace: string): Promise<SvmRuleSnapshot>;
+export declare function readSvmConfig(snap: Snapshot, gen: AgenticGeneration, wallet: Address, active: ActiveRule, pushChainNamespace: string): Promise<SvmRuleSnapshot>;

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

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSvmRule = readSvmRule;
+exports.readSvmConfig = readSvmConfig;
+const errors_1 = require("../errors");
+const ids_1 = require("../codec/ids");
+const v6_1 = require("../contracts/v6");
+const svm_terms_1 = require("../codec/svm-terms");
+const rules_1 = require("./rules");
+async function readSvmRule(snap, gen, wallet, rulesId, pushChainNamespace) {
+    const active = (await (0, rules_1.readActiveRules)(snap, gen, wallet)).find((r) => r.rulesId.toLowerCase() === rulesId.toLowerCase());
+    if (!active)
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_NOT_FOUND, `no enabled SVM rule ${rulesId} on ${wallet}`);
+    return readSvmConfig(snap, gen, wallet, active, pushChainNamespace);
+}
+async function readSvmConfig(snap, gen, wallet, active, pushChainNamespace) {
+    const chain = (0, rules_1.chainFromHash)(active.chainHash, pushChainNamespace);
+    const expectedAction = (0, ids_1.actionId)(gen.addresses.gateway, v6_1.SEND_OUTBOUND_SELECTOR);
+    if (active.mode !== 0 ||
+        active.vm !== 1 ||
+        !chain?.startsWith('solana:') ||
+        active.actionIds.length !== 1 ||
+        active.actionIds[0].toLowerCase() !== expectedAction.toLowerCase())
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INCONSISTENT_READ, 'rule is not a single gateway SVM action');
+    const id = (0, ids_1.configId)(wallet, active.rulesId, active.actionIds[0]);
+    const cfg = await snap.read(gen.addresses.rulesPolicy, gen.contracts.abis.policy, 'getSvmConfig', [id, wallet]);
+    try {
+        if (!cfg.initialized)
+            throw new Error('uninitialized SVM config');
+        // Stored expired rules remain readable. Grant-time validation still checks expiry.
+        (0, svm_terms_1.validateSvmTerms)(cfg, -1);
+        for (const cap of cfg.assets) {
+            if (typeof cap.spent !== 'bigint' ||
+                cap.spent < BigInt(0) ||
+                cap.spent > cap.maxTotal)
+                throw new Error('invalid stored asset counter');
+        }
+    }
+    catch (cause) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INCONSISTENT_READ, 'malformed stored SVM config', { cause });
+    }
+    return {
+        wallet,
+        rulesId: active.rulesId,
+        agent: active.agent,
+        chainNamespace: chain,
+        configId: id,
+        config: cfg,
+        blockNumber: snap.blockNumber,
+    };
+}
+//# sourceMappingURL=svm.js.map

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

@@ -0,0 +1,25 @@
+import { type Address } from 'viem';
+import type { AgenticGeneration } from '../deployments';
+import type { ChainReader } from '../contracts/reader';
+import type { WalletInfo, WalletSummary } from '../agentic.types';
+import { Snapshot } from './snapshot';
+export declare function walletCount(snap: Snapshot, gen: AgenticGeneration, owner: Address): Promise<bigint>;
+/** client.agentic.derive: default index is the owner's next unused slot. */
+export declare function deriveForOwner(reader: ChainReader, gen: AgenticGeneration, owner: Address, index?: number): Promise<{
+    address: Address;
+    index: number;
+    deployed: boolean;
+}>;
+export declare function rulesCount(snap: Snapshot, gen: AgenticGeneration, wallet: Address): Promise<number>;
+/**
+ * client.agentic.list: every deployed slot plus the next undeployed slot
+ * (deployed=false, rulesCount=0), as in the spec example.
+ */
+export declare function listForOwner(reader: ChainReader, gen: AgenticGeneration, owner: Address): Promise<WalletSummary[]>;
+/** w.owner(): the owner as the wallet stores it. */
+export declare function walletOwner(reader: ChainReader, gen: AgenticGeneration, wallet: Address): Promise<Address>;
+/**
+ * w.info(). A deployed wallet is read from chain. An undeployed address is
+ * only describable when it is `signerIdentity`'s next predicted slot.
+ */
+export declare function walletInfo(reader: ChainReader, gen: AgenticGeneration, wallet: Address, signerIdentity?: Address): Promise<WalletInfo>;