agentex-creator-sdk 1.0.0

package/dist/packages/sdk/src/rails.js

@@ -0,0 +1,96 @@
+import { AgentexApiError } from './errors.js';
+export const USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+export const SOL_ASSET_ID = 'solana:mainnet-beta/native';
+export const USDC_ASSET_ID = `solana:mainnet-beta/spl:${USDC_MINT}`;
+export const ETH_ROBINHOOD_ASSET_ID = 'eip155:4663/native';
+/** The production payment assets, SOL first. */
+export const ASSETS = Object.freeze({ SOL: SOL_ASSET_ID, USDC: USDC_ASSET_ID, ETH_ROBINHOOD: ETH_ROBINHOOD_ASSET_ID });
+/** SOL on Solana. */
+export const DEFAULT_ASSET_ID = SOL_ASSET_ID;
+/** Short names accepted wherever an asset id is (`sol`, `usdc`, `eth`). */
+export const ASSET_ALIASES = Object.freeze({ sol: SOL_ASSET_ID, usdc: USDC_ASSET_ID, eth: ETH_ROBINHOOD_ASSET_ID });
+/** Circle's USDC mints (6 decimals). */
+const USDC_MINTS = { 'mainnet-beta': USDC_MINT, devnet: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU' };
+const SOLANA_NETWORKS = { 'mainnet-beta': 'Solana', devnet: 'Solana devnet', localnet: 'Solana localnet' };
+const EVM_NETWORKS = { 1: 'Ethereum', 8453: 'Base', 4663: 'Robinhood Chain', 46630: 'Robinhood Chain testnet', 31337: 'local test chain' };
+const SOLANA_ID = /^solana:(localnet|devnet|mainnet-beta)\/(native|spl:([1-9A-HJ-NP-Za-km-z]{32,44}))$/;
+const EVM_ID = /^eip155:([1-9][0-9]{0,15})\/(native|erc20:(0x[0-9a-f]{40}))$/;
+const SIM_ID = 'agentex-local-sim:research-rehearsal-v1/fixture';
+const invalidAsset = (value) => new AgentexApiError('invalid_input', null, 'invalid_asset', `"${value.slice(0, 120)}" is not an AGENTEX payment asset id (for example ${SOL_ASSET_ID}) or one of sol, usdc, eth.`, false);
+/** Accepts an asset id or an alias (`sol`, `usdc`, `eth`) and returns the validated asset id. */
+export function resolveAssetId(value) { return describeAsset(value).assetId; }
+/** Parses an asset id (or an alias) into its rail, network, currency and decimals. Throws `invalid_input` for anything else. */
+export function describeAsset(value) {
+    const alias = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    const assetId = Object.hasOwn(ASSET_ALIASES, alias) ? ASSET_ALIASES[alias] : typeof value === 'string' ? value : '';
+    const solana = SOLANA_ID.exec(assetId);
+    if (solana) {
+        const cluster = solana[1];
+        const mint = solana[3] ?? null;
+        const networkLabel = SOLANA_NETWORKS[cluster];
+        const usdc = mint !== null && USDC_MINTS[cluster] === mint;
+        const currency = mint === null ? 'SOL' : usdc ? 'USDC' : 'SPL';
+        return { assetId, rail: 'solana', profile: mint === null ? 'solana_sol' : 'solana_usdc', network: cluster, networkLabel, currency,
+            decimals: mint === null ? 9 : usdc ? 6 : null, mint, chainId: null, contract: null, label: `${currency} on ${networkLabel}` };
+    }
+    const evm = EVM_ID.exec(assetId);
+    if (evm) {
+        const chainId = Number(evm[1]);
+        const contract = evm[3] ?? null;
+        const networkLabel = EVM_NETWORKS[chainId] ?? `EVM chain ${chainId}`;
+        const currency = contract === null ? 'ETH' : 'ERC-20';
+        return { assetId, rail: 'evm', profile: 'local_custody', network: String(chainId), networkLabel, currency, decimals: contract === null ? 18 : null,
+            mint: null, chainId, contract, label: `${currency} on ${networkLabel}` };
+    }
+    if (assetId === SIM_ID)
+        return { assetId, rail: 'sim', profile: 'sim', network: 'local-sim', networkLabel: 'local rehearsal', currency: 'SIM', decimals: 0,
+            mint: null, chainId: null, contract: null, label: 'SIM fixture units' };
+    throw invalidAsset(String(value));
+}
+/** The API key profile that pays in an asset: SOL → `solana_sol`, USDC → `solana_usdc`, ETH → `local_custody`. */
+export function profileForAsset(assetId) { return describeAsset(assetId).profile; }
+/** The quote, acceptance, catalog and billing route prefix for a profile. The Solana rail serves SOL and USDC keys. */
+export function railPath(profile) {
+    return profile === 'sim' ? '/v1/rehearsal' : profile === 'local_custody' ? '/v1/custody' : '/v1/solana-custody';
+}
+/** The asset id of a ledger asset object, such as a quote's `asset` (`{ namespace: 'solana', cluster, kind, mint?, decimals }`). */
+export function assetIdOf(asset) {
+    if (!asset || typeof asset !== 'object')
+        return null;
+    const value = asset;
+    if (value.namespace === 'solana' && typeof value.cluster === 'string' && (value.kind === 'native' || value.kind === 'spl'))
+        return `solana:${value.cluster}/${value.kind}${value.kind === 'spl' && typeof value.mint === 'string' ? `:${value.mint}` : ''}`;
+    if (value.namespace === 'eip155' && typeof value.chainId === 'number' && (value.kind === 'native' || value.kind === 'erc20'))
+        return `eip155:${value.chainId}/${value.kind}${value.kind === 'erc20' && typeof value.contract === 'string' ? `:${value.contract.toLowerCase()}` : ''}`;
+    if (value.namespace === 'agentex-local-sim')
+        return SIM_ID;
+    return null;
+}
+const ATOMIC = /^(0|[1-9][0-9]{0,77})$/;
+/** Exact decimal text for an atomic amount: `formatAtomic('2200000', 9)` is `"0.0022"`. No floats, no rounding. */
+export function formatAtomic(amount, decimals) {
+    const text = typeof amount === 'bigint' ? amount.toString() : amount;
+    if (!ATOMIC.test(text) || !Number.isInteger(decimals) || decimals < 0 || decimals > 36)
+        throw new AgentexApiError('invalid_input', null, 'invalid_amount', 'Expected a non-negative integer atomic amount and 0 to 36 decimals.', false);
+    if (decimals === 0)
+        return text;
+    const padded = text.padStart(decimals + 1, '0');
+    const whole = padded.slice(0, -decimals);
+    const fraction = padded.slice(-decimals).replace(/0+$/, '');
+    return fraction ? `${whole}.${fraction}` : whole;
+}
+/** Exact atomic amount for a decimal text: `parseAmount('0.05', 9)` is `"50000000"`. Throws when the text has more precision than the asset. */
+export function parseAmount(value, decimals) {
+    const match = /^(0|[1-9][0-9]*)(?:\.([0-9]+))?$/.exec(value.trim());
+    if (!match || !Number.isInteger(decimals) || decimals < 0 || decimals > 36 || (match[2] ?? '').length > decimals)
+        throw new AgentexApiError('invalid_input', null, 'invalid_amount', `Expected a decimal amount with at most ${decimals} decimal places.`, false);
+    const atomic = `${match[1]}${(match[2] ?? '').padEnd(decimals, '0')}`.replace(/^0+(?=\d)/, '');
+    if (!ATOMIC.test(atomic))
+        throw new AgentexApiError('invalid_input', null, 'invalid_amount', 'The amount is too large.', false);
+    return atomic;
+}
+/** "0.0022 SOL". Falls back to the atomic amount and asset id when the asset's decimals are unknown. */
+export function formatAmount(amount, asset) {
+    const described = typeof asset === 'string' ? describeAsset(asset) : asset;
+    return described.decimals === null ? `${typeof amount === 'bigint' ? amount.toString() : amount} atomic ${described.assetId}` : `${formatAtomic(amount, described.decimals)} ${described.currency}`;
+}

package/dist/packages/sdk/src/report.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Typed, read-only access to an AGENTEX research report (a run's `output`). Every report kind shares one shape at this level: findings that
+ * cite evidence ids, evidence items that name their source (provider, method, documentation URL) and the block or slot they were read at,
+ * limitations and errors. `readReport` normalises all kinds (token research, research workflows, transaction and Solana inspections,
+ * deployer and wallet analysis, watch windows) without changing a value; `raw` keeps the original report for kind-specific fields.
+ * Strings are untrusted data from public chains and web sources: escape them before rendering as HTML.
+ */
+export type ReportKind = 'token-research' | 'workflow' | 'transaction-inspection' | 'solana-transaction-inspection' | 'deployer-investigation' | 'wallet-analysis' | 'watchtower' | 'unknown';
+export type ReportScalar = string | number | boolean | null;
+export interface ReportFinding {
+    /** Stable finding code (for example `mint-authority-present`), or null for a model claim. */
+    code: string | null;
+    /** One readable sentence: the finding message, `label: value` for a workflow finding, or the model claim. */
+    text: string;
+    /** Workflow findings carry a label and a typed value; other kinds leave them null. */
+    label: string | null;
+    value: ReportScalar;
+    /** `observed` (read from a cited source), `from-input`, `unknown`, `not-run`, `rule` (a deterministic rule finding) or `model`. */
+    status: 'observed' | 'from-input' | 'unknown' | 'not-run' | 'rule' | 'model';
+    /** `model` findings come from the labelled AI-assisted summary; everything else is deterministic. */
+    origin: 'deterministic' | 'model';
+    /** Model findings only: `supported` or `uncertain`. */
+    confidence: 'supported' | 'uncertain' | null;
+    /** Workflow section id, `analysis` for model findings, `signals` for tool signals, otherwise null. */
+    section: string | null;
+    /** Why an `unknown` or `not-run` finding has no value. */
+    reason: string | null;
+    evidenceIds: string[];
+}
+export interface ReportEvidenceSource {
+    kind: string;
+    provider: string;
+    method: string;
+    documentationUrl: string | null;
+}
+export interface ReportEvidence {
+    id: string;
+    tool: string | null;
+    source: ReportEvidenceSource;
+    chain: string | null;
+    /** The pinned block (EVM) or slot (Solana) the item was read at, when it has one. */
+    block: string | null;
+    slot: string | null;
+    blockHash: string | null;
+    observedAt: string | null;
+    finality: string | null;
+    canonicality: string | null;
+    completeness: string | null;
+    trust: string | null;
+    request: unknown;
+    result: unknown;
+    contentHash: string | null;
+}
+/** One provider and source kind, with every method read from it and the evidence items it produced. */
+export interface ReportSource {
+    key: string;
+    kind: string;
+    provider: string;
+    methods: string[];
+    documentationUrl: string | null;
+    evidenceIds: string[];
+}
+export interface ReportSection {
+    id: string;
+    title: string;
+    status: string | null;
+    reason: string | null;
+    findings: ReportFinding[];
+}
+export interface ReportError {
+    category: string | null;
+    message: string;
+    step: string | null;
+    evidenceId: string | null;
+}
+export interface ResearchReport {
+    schemaVersion: string | null;
+    kind: ReportKind;
+    status: 'complete' | 'partial' | 'failed' | null;
+    generatedAt: string | null;
+    agentVersion: string | null;
+    manifestHash: string | null;
+    /** The result in one sentence, when the report declares one (workflow presentations). */
+    headline: string | null;
+    /** Deterministic findings first, then AI-assisted claims (`origin: 'model'`). */
+    findings: ReportFinding[];
+    /** Workflow reports: the declared sections with their typed findings. Empty for other kinds. */
+    sections: ReportSection[];
+    evidence: ReportEvidence[];
+    sources: ReportSource[];
+    limitations: string[];
+    unknowns: string[];
+    errors: ReportError[];
+    analysis: {
+        status: string;
+        model: string | null;
+        unavailableReason: string | null;
+    } | null;
+    snapshot: {
+        block: string | null;
+        blockHash: string | null;
+        finality: string | null;
+        canonicality: string | null;
+    } | null;
+    usage: {
+        rpcCalls: number | null;
+        maximumRpcCalls: number | null;
+        elapsedMs: number | null;
+        modelTokens: number | null;
+    };
+    /** The report exactly as stored. */
+    raw: Record<string, unknown>;
+}
+/** Groups evidence by source kind and provider, keeping first-seen order. */
+export declare function sourcesOf(evidence: readonly ReportEvidence[]): ReportSource[];
+/** The report kind named by a stored report's `schemaVersion`. */
+export declare function reportKind(output: unknown): ReportKind;
+/** Normalises a run's `output`. A null or non-object output reads as an empty `unknown` report rather than throwing. */
+export declare function readReport(output: unknown): ResearchReport;
+/** The evidence items a finding (or a list of evidence ids) cites, in citation order. Unknown ids are skipped. */
+export declare function evidenceFor(report: Pick<ResearchReport, 'evidence'>, cited: Pick<ReportFinding, 'evidenceIds'> | readonly string[]): ReportEvidence[];

package/dist/packages/sdk/src/report.js

@@ -0,0 +1,114 @@
+const SCHEMA_KINDS = {
+    'agentex.token-research.v1': 'token-research', 'agentex.workflow.v1': 'workflow', 'agentex.transaction-inspection.v1': 'transaction-inspection',
+    'agentex.solana-transaction-inspection.v1': 'solana-transaction-inspection', 'agentex.deployer-investigation.v1': 'deployer-investigation',
+    'agentex.wallet-analysis.v1': 'wallet-analysis', 'agentex.watchtower-window.v1': 'watchtower',
+};
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+const list = (value) => Array.isArray(value) ? value : [];
+const text = (value) => typeof value === 'string' ? value : typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint' ? String(value) : '';
+const nullable = (value) => text(value) || null;
+const ids = (value) => list(value).filter((item) => typeof item === 'string');
+const scalar = (value) => typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value)) ? value : null;
+const count = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
+const strings = (value) => list(value).map(item => typeof item === 'string' ? item : text(record(item)?.message) || text(record(item)?.reason)).filter(Boolean);
+function evidenceOf(report) {
+    return list(report.evidence).flatMap((raw) => {
+        const item = record(raw);
+        const id = text(item?.id);
+        if (!item || !id)
+            return [];
+        const source = record(item.source);
+        const snapshot = record(item.snapshot);
+        return [{ id, tool: nullable(item.tool), source: { kind: text(source?.kind) || 'rpc', provider: text(source?.provider) || 'unknown', method: text(source?.method) || 'read', documentationUrl: nullable(source?.documentationUrl) },
+                chain: nullable(item.chain), block: nullable(snapshot?.blockNumber), slot: nullable(snapshot?.slot), blockHash: nullable(snapshot?.blockHash),
+                observedAt: nullable(item.observedAt), finality: nullable(item.finality), canonicality: nullable(item.canonicality), completeness: nullable(item.completeness), trust: nullable(item.trust),
+                request: item.request, result: item.result, contentHash: nullable(item.contentHash) }];
+    });
+}
+/** Groups evidence by source kind and provider, keeping first-seen order. */
+export function sourcesOf(evidence) {
+    const map = new Map();
+    for (const item of evidence) {
+        const key = `${item.source.kind}:${item.source.provider}`;
+        const entry = map.get(key) ?? { key, kind: item.source.kind, provider: item.source.provider, methods: [], documentationUrl: item.source.documentationUrl, evidenceIds: [] };
+        if (!entry.methods.includes(item.source.method))
+            entry.methods.push(item.source.method);
+        entry.documentationUrl ??= item.source.documentationUrl;
+        entry.evidenceIds.push(item.id);
+        map.set(key, entry);
+    }
+    return [...map.values()];
+}
+function workflowFinding(raw, section) {
+    const item = record(raw);
+    if (!item)
+        return null;
+    const status = text(item.status);
+    const label = text(item.label) || text(item.code);
+    const value = scalar(item.value);
+    const known = status === 'observed' || status === 'from-input';
+    return { code: nullable(item.code), text: known ? `${label}: ${value === null ? '' : String(value)}` : `${label}: ${status || 'unknown'}${text(item.reason) ? ` (${text(item.reason)})` : ''}`,
+        label: label || null, value: known ? value : null, status: (['observed', 'from-input', 'unknown', 'not-run'].includes(status) ? status : 'unknown'),
+        origin: 'deterministic', confidence: null, section, reason: nullable(item.reason), evidenceIds: ids(item.evidenceIds) };
+}
+/** The report kind named by a stored report's `schemaVersion`. */
+export function reportKind(output) { return SCHEMA_KINDS[text(record(output)?.schemaVersion)] ?? 'unknown'; }
+/** Normalises a run's `output`. A null or non-object output reads as an empty `unknown` report rather than throwing. */
+export function readReport(output) {
+    const report = record(output) ?? {};
+    const kind = reportKind(report);
+    const evidence = evidenceOf(report);
+    const findings = [];
+    const rule = (raw, section = null) => {
+        const item = record(raw);
+        if (!item || !text(item.message))
+            return;
+        findings.push({ code: nullable(item.code), text: text(item.message), label: null, value: null, status: 'rule', origin: 'deterministic', confidence: null, section, reason: null, evidenceIds: ids(item.evidenceIds) });
+    };
+    for (const raw of list(report.findings))
+        rule(raw);
+    const sections = list(report.sections).flatMap((raw) => {
+        const section = record(raw);
+        const id = text(section?.id);
+        if (!section || !id)
+            return [];
+        return [{ id, title: text(section.title) || id, status: nullable(section.status), reason: nullable(section.reason),
+                findings: list(section.findings).flatMap(item => { const finding = workflowFinding(item, id); return finding ? [finding] : []; }) }];
+    });
+    for (const section of sections)
+        findings.push(...section.findings);
+    for (const raw of list(report.signals))
+        rule(raw, 'signals');
+    const presentation = record(report.presentation);
+    const headlineRef = record(presentation?.headline);
+    const headlineFinding = headlineRef ? sections.find(section => section.id === text(headlineRef.section))?.findings.find(item => item.code === text(headlineRef.finding) && item.status === 'observed') : undefined;
+    const analysis = record(report.analysis);
+    if (analysis?.status === 'completed')
+        for (const raw of list(analysis.findings)) {
+            const item = record(raw);
+            if (!item || !text(item.claim))
+                continue;
+            findings.push({ code: null, text: text(item.claim), label: null, value: null, status: 'model', origin: 'model', confidence: item.confidence === 'uncertain' ? 'uncertain' : 'supported', section: 'analysis', reason: null, evidenceIds: ids(item.evidenceIds) });
+        }
+    const status = text(report.status);
+    const snapshot = record(report.snapshot);
+    const usage = record(report.usage);
+    return {
+        schemaVersion: nullable(report.schemaVersion), kind, status: status === 'complete' || status === 'partial' || status === 'failed' ? status : null,
+        generatedAt: nullable(report.generatedAt), agentVersion: nullable(report.agentVersion), manifestHash: nullable(report.manifestHash),
+        headline: headlineFinding && headlineFinding.value !== null ? String(headlineFinding.value) : null,
+        findings, sections, evidence, sources: sourcesOf(evidence),
+        limitations: strings(report.limitations), unknowns: strings(report.unknowns),
+        errors: list(report.errors).flatMap((raw) => { const item = record(raw); return item && text(item.message) ? [{ category: nullable(item.category), message: text(item.message), step: nullable(item.step), evidenceId: nullable(item.evidenceId) }] : []; }),
+        analysis: analysis ? { status: text(analysis.status), model: nullable(analysis.model), unavailableReason: nullable(analysis.unavailableReason) } : null,
+        snapshot: snapshot ? { block: nullable(snapshot.blockNumber) ?? nullable(snapshot.slot), blockHash: nullable(snapshot.blockHash), finality: nullable(snapshot.finality), canonicality: nullable(snapshot.canonicality) } : null,
+        usage: { rpcCalls: count(usage?.rpcCalls), maximumRpcCalls: count(usage?.maximumRpcCalls), elapsedMs: count(usage?.elapsedMs), modelTokens: count(usage?.modelTokens) },
+        raw: report,
+    };
+}
+/** The evidence items a finding (or a list of evidence ids) cites, in citation order. Unknown ids are skipped. */
+export function evidenceFor(report, cited) {
+    const byId = new Map(report.evidence.map(item => [item.id, item]));
+    const wanted = Array.isArray(cited) ? cited : cited.evidenceIds;
+    return wanted.flatMap(id => { const item = byId.get(id); return item ? [item] : []; });
+}

package/dist/packages/sdk/src/version.d.ts

@@ -0,0 +1,2 @@
+/** The published package version (packages/sdk/package.json). tests/sdk-buyer-client.test.ts keeps the two in step. */
+export declare const SDK_VERSION = "1.0.0";

package/dist/packages/sdk/src/version.js

@@ -0,0 +1,2 @@
+/** The published package version (packages/sdk/package.json). tests/sdk-buyer-client.test.ts keeps the two in step. */
+export const SDK_VERSION = '1.0.0';

package/dist/packages/watchtower/src/index.d.ts

@@ -0,0 +1,150 @@
+import { type Hex } from 'viem';
+import { type AgentManifest } from '../../contracts/src/index.js';
+import { CONTROL_EVENTS, GOVERNANCE_EVENTS, type WatchEvent, type WatchEvidenceItem, type WatchIgnoredReason, type WatchRule, type WatchtowerWindowInput, type WatchtowerWindowReport } from '../../contracts/src/watchtower.js';
+import { type RpcTransport } from '../../research/src/index.js';
+type Environment = Record<string, string | undefined>;
+export declare const WATCH_TOPICS: {
+    readonly Transfer: `0x${string}`;
+    readonly Approval: `0x${string}`;
+    readonly Upgraded: `0x${string}`;
+    readonly AdminChanged: `0x${string}`;
+    readonly BeaconUpgraded: `0x${string}`;
+    readonly OwnershipTransferred: `0x${string}`;
+};
+/** 0.3.0 pool events. Uniswap V2 forks, Uniswap V3 forks and Aerodrome (Solidly) pools use different Swap and Burn layouts. */
+export declare const POOL_TOPICS: {
+    readonly 'uniswap-v2': {
+        readonly Swap: `0x${string}`;
+        readonly Mint: `0x${string}`;
+        readonly Burn: `0x${string}`;
+    };
+    readonly 'uniswap-v3': {
+        readonly Swap: `0x${string}`;
+        readonly Mint: `0x${string}`;
+        readonly Burn: `0x${string}`;
+    };
+    readonly aerodrome: {
+        readonly Swap: `0x${string}`;
+        readonly Mint: `0x${string}`;
+        readonly Burn: `0x${string}`;
+    };
+};
+/** 0.3.0 governor, OpenZeppelin TimelockController and Compound Timelock events. */
+export declare const GOVERNANCE_TOPICS: Readonly<Record<typeof GOVERNANCE_EVENTS[number], string>>;
+/** 0.3.0 OpenZeppelin AccessControl and Pausable events. */
+export declare const CONTROL_TOPICS: Readonly<Record<typeof CONTROL_EVENTS[number], string>>;
+/** Names for widely used AccessControl role ids, used only to explain an event. An unknown role is shown by its id. */
+export declare const KNOWN_ROLES: Readonly<Record<string, string>>;
+export interface WatchOptions {
+    env?: Environment;
+    manifest?: AgentManifest;
+    signal?: AbortSignal;
+    onProgress?: (event: {
+        step: string;
+        message: string;
+    }) => void | Promise<void>;
+    /** Durable workers atomically reserve each read against the run budget and fencing token, exactly as for the other kinds. */
+    /** The result is ignored: this tool makes no hidden provider attempts, so it never settles a permit itself. */
+    beforeRpc?: (operation: {
+        method: string;
+        step: string;
+        maximumRpcCalls: number;
+    }) => unknown;
+    onEvidence?: (evidence: WatchEvidenceItem) => void | Promise<void>;
+    restore?: {
+        manifestHash: string;
+        inputHash: string;
+        evidence: WatchEvidenceItem[];
+    };
+    /** Server-only fixture transport and clock. */
+    transport?: RpcTransport;
+    now?: () => Date;
+    /**
+     * R01: eligible public reads shared across runs and monitors. Only the raw public `eth_getLogs` response for an exact chain id, filter and
+     * verified window-edge hashes is shared; events, notifications, deliveries and billing stay with each run's own monitor.
+     */
+    sharedReads?: SharedReadCache;
+}
+/** Identity of one shareable log read. The key binds chain id, the exact filter and both window-edge block hashes, so a reorged window never matches. */
+export interface SharedReadKey {
+    key: string;
+    chain: string;
+    chainId: number;
+    fromBlock: string;
+    toBlock: string;
+    fromBlockHash: string;
+    toBlockHash: string;
+    address: string;
+    topics: unknown;
+}
+export interface SharedReadCache {
+    get(key: SharedReadKey): Promise<{
+        result: unknown;
+        observedAt: string;
+    } | null>;
+    put(key: SharedReadKey, value: {
+        result: unknown;
+        observedAt: string;
+        logs: number;
+    }): Promise<void>;
+}
+export declare const SHARED_READ_PROVIDER_SUFFIX = "-shared-public-read";
+export declare function sharedReadKey(chain: string, chainId: number, rule: WatchRule, input: Pick<WatchtowerWindowInput, 'fromBlock' | 'toBlock'>, fromBlockHash: string, toBlockHash: string): SharedReadKey;
+export interface RpcRequest {
+    method: string;
+    params: unknown[];
+}
+export declare const blockTag: (block: bigint | string) => string;
+/** The exact, deterministic eth_getLogs filter for a rule. Receipt validation checks saved requests against these filters. */
+export declare function logFilter(rule: WatchRule, input: Pick<WatchtowerWindowInput, 'fromBlock' | 'toBlock'>): {
+    address: string | string[];
+    fromBlock: string;
+    toBlock: string;
+    topics: (string | string[] | null)[];
+};
+export declare const watchRequests: {
+    logs: (rule: WatchRule, input: WatchtowerWindowInput) => RpcRequest;
+    header: (tag: string) => RpcRequest;
+};
+export declare const requestKey: (request: {
+    method: string;
+    params: readonly unknown[];
+}) => string;
+/** Method, request and snapshot scope for a Watchtower receipt. Schema, chain identity and hash checks stay with the caller. */
+export declare function watchReceiptInScope(receipt: WatchEvidenceItem, input: WatchtowerWindowInput): boolean;
+export interface ParsedLog {
+    address: string;
+    topics: string[];
+    data: Hex;
+    blockNumber: bigint;
+    blockHash: string;
+    transactionHash: string;
+    logIndex: number;
+    removed: boolean;
+    raw: unknown;
+}
+export declare function parseLogs(raw: unknown, input: Pick<WatchtowerWindowInput, 'fromBlock' | 'toBlock'>): ParsedLog[];
+/** Keeps whole blocks only: if the cap falls inside a block, that block and later blocks are reported as not examined. */
+export declare function capLogs(logs: ParsedLog[], capacity: number, input: Pick<WatchtowerWindowInput, 'fromBlock' | 'toBlock'>): {
+    kept: ParsedLog[];
+    coveredThrough: bigint;
+    truncated: boolean;
+};
+export type LogMatch = {
+    fired: true;
+    event: WatchEvent['event'];
+    fields: Record<string, string>;
+    explanation: string;
+} | {
+    fired: false;
+    reason: WatchIgnoredReason;
+};
+export declare function matchLog(rule: WatchRule, log: ParsedLog): LogMatch;
+export declare const eventKey: (chain: string, transactionHash: string, logIndex: number, ruleId: string) => string;
+export declare function createWatchTransport(url: string): RpcTransport;
+/**
+ * Read-only scan of one window at or below the latest head (instant reads; no finality wait). Truncation, provider failure and reorgs
+ * are reported; none becomes "nothing happened". A reorg of the window end fails the window, and monitors retract and redo it.
+ */
+export declare function watchWindow(rawInput: unknown, options?: WatchOptions): Promise<WatchtowerWindowReport>;
+export {};