agentex-creator-sdk 1.0.0

package/dist/packages/contracts/src/watchtower.js

@@ -0,0 +1,196 @@
+import { z } from 'zod';
+import { AddressSchema, AgentManifestSchema, AtomicAmountSchema, ChainKeySchema, ResearchErrorSchema, contentHash, evmEvidenceItemSchema, matchesTemplateInput, publishManifest } from './index.js';
+/** Watchtower window contracts (P04 package interface). Kept outside index.ts so modules initialise without a circular import. */
+export const WATCH_SCHEMA_ID = 'agentex.watchtower-window.v1';
+export const WATCH_TOOL = 'evm.watch-logs@0.1.0';
+export const WATCH_MAX_WINDOW_BLOCKS = 2000;
+export const WATCH_MAX_LOGS = 100;
+export const WATCH_MAX_RULES = 8;
+export const WATCH_RPC_CEILING = 16;
+export const WATCH_RPC_METHODS = ['eth_chainId', 'eth_getBlockByNumber', 'eth_getLogs'];
+export const AUTHORITY_EVENTS = ['Upgraded', 'AdminChanged', 'BeaconUpgraded', 'OwnershipTransferred'];
+/** Watchtower 0.3.0: OpenZeppelin/Compound Governor, OpenZeppelin TimelockController and Compound Timelock events. */
+export const GOVERNANCE_EVENTS = ['ProposalCreated', 'ProposalQueued', 'ProposalExecuted', 'ProposalCanceled', 'CallScheduled', 'CallExecuted', 'Cancelled', 'MinDelayChange',
+    'QueueTransaction', 'ExecuteTransaction', 'CancelTransaction', 'NewDelay', 'NewAdmin', 'NewPendingAdmin'];
+/** Watchtower 0.3.0: OpenZeppelin AccessControl and Pausable events. */
+export const CONTROL_EVENTS = ['RoleGranted', 'RoleRevoked', 'RoleAdminChanged', 'Paused', 'Unpaused'];
+/** Watchtower 0.3.0: pool events of Uniswap V2-compatible, Uniswap V3-compatible and Aerodrome (Solidly) pools. */
+export const POOL_EVENTS = ['Swap', 'Mint', 'Burn'];
+export const POOL_DEXES = ['uniswap-v2', 'uniswap-v3', 'aerodrome'];
+/** Rule types added in Watchtower 0.3.0. Versions 0.1.0 and 0.2.0 refuse them, so a pinned monitor never gains a rule its version did not declare. */
+export const WATCH_RULES_V3 = ['wallet-token-flow', 'pool-activity', 'governance-change', 'control-change'];
+const WATCH_RULE_TYPES = ['erc20-transfer', 'erc20-approval', 'authority-change', ...WATCH_RULES_V3];
+const Hash = z.string().regex(/^[a-f0-9]{64}$/);
+const Hex32 = z.string().regex(/^0x[a-fA-F0-9]{64}$/);
+export const BlockNumberSchema = z.string().regex(/^(0|[1-9][0-9]{0,15})$/, 'Expected a decimal block number');
+export const WatchRuleIdSchema = z.string().regex(/^[a-z][a-z0-9-]{0,39}$/, 'Rule ids use lowercase letters, digits and hyphens (at most 40 characters)');
+/** Rule types that would need indexes the platform does not have. They fail validation instead of silently matching nothing. */
+export const UNSUPPORTED_WATCH_RULES = Object.freeze({
+    'liquidity-threshold': 'Liquidity threshold rules need a verified DEX pool index, which is not connected. This rule type is unsupported.',
+    'wallet-interaction': 'Wallet-interacted-with-contract rules need a transaction or trace index, which is not connected. This rule type is unsupported.',
+    'contract-interaction': 'Contract interaction rules need a transaction or trace index, which is not connected. This rule type is unsupported.',
+    'native-transfer': 'Native value transfers emit no logs and need a trace index, which is not connected. This rule type is unsupported.',
+});
+export const SupportedWatchRuleSchema = z.discriminatedUnion('type', [
+    z.strictObject({ id: WatchRuleIdSchema, type: z.literal('erc20-transfer'), token: AddressSchema, from: AddressSchema.optional(), to: AddressSchema.optional(), minimumAtomic: AtomicAmountSchema.optional() }),
+    z.strictObject({ id: WatchRuleIdSchema, type: z.literal('erc20-approval'), token: AddressSchema, owner: AddressSchema, spender: AddressSchema.optional() }),
+    z.strictObject({ id: WatchRuleIdSchema, type: z.literal('authority-change'), contract: AddressSchema, events: z.array(z.enum(AUTHORITY_EVENTS)).min(1).max(4).optional() }),
+    // 0.3.0: a wallet's ERC-20 movements in one direction across up to eight tokens, read with one address-list log filter.
+    z.strictObject({ id: WatchRuleIdSchema, type: z.literal('wallet-token-flow'), wallet: AddressSchema, tokens: z.array(AddressSchema).min(1).max(8), direction: z.enum(['in', 'out']) })
+        .refine((rule) => new Set(rule.tokens.map((token) => token.toLowerCase())).size === rule.tokens.length, 'Tokens must be distinct'),
+    // 0.3.0: swaps and liquidity added or removed on one supplied pool, optionally above exact per-token minimums.
+    z.strictObject({ id: WatchRuleIdSchema, type: z.literal('pool-activity'), pool: AddressSchema, dex: z.enum(POOL_DEXES), events: z.array(z.enum(POOL_EVENTS)).min(1).max(3).optional(),
+        minimumAmount0Atomic: AtomicAmountSchema.optional(), minimumAmount1Atomic: AtomicAmountSchema.optional() }),
+    z.strictObject({ id: WatchRuleIdSchema, type: z.literal('governance-change'), contract: AddressSchema, events: z.array(z.enum(GOVERNANCE_EVENTS)).min(1).max(GOVERNANCE_EVENTS.length).optional() }),
+    z.strictObject({ id: WatchRuleIdSchema, type: z.literal('control-change'), contract: AddressSchema, events: z.array(z.enum(CONTROL_EVENTS)).min(1).max(CONTROL_EVENTS.length).optional() }),
+]);
+export const WatchRuleSchema = z.preprocess((value, ctx) => {
+    const type = value !== null && typeof value === 'object' && !Array.isArray(value) ? value.type : undefined;
+    if (typeof type === 'string' && Object.hasOwn(UNSUPPORTED_WATCH_RULES, type))
+        ctx.addIssue({ code: 'custom', message: UNSUPPORTED_WATCH_RULES[type] });
+    return value;
+}, SupportedWatchRuleSchema);
+/** One bounded, inclusive block window at or below the latest head. Monitors create consecutive windows; a manual run can inspect one. */
+export const WatchtowerWindowInputSchema = z.strictObject({
+    chain: ChainKeySchema,
+    fromBlock: BlockNumberSchema,
+    toBlock: BlockNumberSchema,
+    rules: z.array(WatchRuleSchema).min(1).max(WATCH_MAX_RULES),
+    maximumLogs: z.number().int().min(1).max(WATCH_MAX_LOGS).default(50),
+}).superRefine((input, ctx) => {
+    const from = BigInt(input.fromBlock);
+    const to = BigInt(input.toBlock);
+    if (from > to)
+        ctx.addIssue({ code: 'custom', path: ['toBlock'], message: 'toBlock must not precede fromBlock' });
+    else if (to - from + 1n > BigInt(WATCH_MAX_WINDOW_BLOCKS))
+        ctx.addIssue({ code: 'custom', path: ['toBlock'], message: `A window covers at most ${WATCH_MAX_WINDOW_BLOCKS} blocks` });
+    if (new Set(input.rules.map((rule) => rule.id)).size !== input.rules.length)
+        ctx.addIssue({ code: 'custom', path: ['rules'], message: 'Rule ids must be unique' });
+});
+/** Worst-case RPC reads for one window: identity, latest head, from/to headers, one eth_getLogs per rule, a covered-through header and the final recheck. */
+export const watchWindowRpcEstimate = (rules) => 6 + rules;
+export const WATCHTOWER_MANIFEST = publishManifest({
+    schemaVersion: '1.0', id: 'watchtower', version: '0.1.0', name: 'Watchtower',
+    description: 'Scan one bounded finalized block window for declared ERC-20 Transfer/Approval events and proxy or ownership authority changes, with evidence and explicit coverage. Monitors schedule consecutive windows. Unsupported data sources are refused, never reported as quiet.',
+    author: { id: 'agentex', name: 'AGENTEX', ownership: 'first-party' }, license: 'Proprietary', visibility: 'source-visible', chains: ['ethereum', 'base'],
+    inputSchema: { type: 'object', additionalProperties: false, properties: { chain: { type: 'string', description: 'Explicit analysis network', enum: ['ethereum', 'base'] }, fromBlock: { type: 'string', description: 'First finalized block, inclusive' }, toBlock: { type: 'string', description: 'Last finalized block, inclusive; at most 2000 blocks per window' }, rules: { type: 'array', description: 'One to eight supported log rules' }, maximumLogs: { type: 'integer', description: 'Maximum logs examined in the window (1-100)' } }, required: ['chain', 'fromBlock', 'toBlock', 'rules'] },
+    outputSchemaId: WATCH_SCHEMA_ID, tools: [{ id: 'evm.watch-logs', version: '0.1.0', capability: 'evm.read', chains: ['ethereum', 'base'], addressScope: 'input-watch-scope', maximumCalls: 16 }],
+    modelPolicy: { mode: 'deterministic', maximumModelTokens: 0 }, limits: { maximumRpcCalls: 16, maximumDurationMs: 60000, maximumOutputBytes: 262144, maximumGraphDepth: 4, maximumPages: 0, maximumExecutionAtomic: '0' },
+    workflow: [{ id: 'input', type: 'input', dependsOn: [] }, { id: 'watch', type: 'tool', tool: 'evm.watch-logs', dependsOn: ['input'], arguments: { chain: { source: 'input', path: 'chain' }, fromBlock: { source: 'input', path: 'fromBlock' }, toBlock: { source: 'input', path: 'toBlock' }, rules: { source: 'input', path: 'rules' }, maximumLogs: { source: 'input', path: 'maximumLogs' } } }, { id: 'report', type: 'output', dependsOn: ['watch'], from: 'watch' }],
+    testCases: ['transfer-filters', 'approval-owner', 'authority-events', 'mismatched-topics', 'log-cap-truncation', 'provider-unavailable', 'reorged-window', 'unsupported-rules'],
+}).manifest;
+/** Watchtower 0.2.0: identical graph, tool, limits and output schema to 0.1.0 (kept byte-identical, hash f5ad5883…); instant-read wording for new drafts. */
+export const WATCHTOWER_MANIFEST_V2 = publishManifest({
+    ...structuredClone(WATCHTOWER_MANIFEST), version: '0.2.0',
+    description: 'Scan one bounded block window, read up to the latest block (sequencer-confirmed), for declared ERC-20 Transfer/Approval events and proxy or ownership authority changes, with evidence and explicit coverage. A reorged window fails its end-hash recheck and is retracted and rescanned. Monitors schedule consecutive windows. Unsupported data sources are refused, never reported as quiet.',
+    inputSchema: { ...structuredClone(WATCHTOWER_MANIFEST.inputSchema), properties: { ...structuredClone(WATCHTOWER_MANIFEST.inputSchema.properties),
+            fromBlock: { type: 'string', description: 'First block, inclusive' }, toBlock: { type: 'string', description: 'Last block, inclusive, at or before the latest block; at most 2000 blocks per window' } } },
+}).manifest;
+/**
+ * Watchtower 0.3.0: the same bounded window graph, tool and output schema, plus wallet token flows across a token list, pool swaps and
+ * liquidity changes, governance and timelock events and access-control or pause events, and Robinhood Chain. New drafts start from it.
+ */
+export const WATCHTOWER_MANIFEST_V3 = publishManifest({
+    ...structuredClone(WATCHTOWER_MANIFEST_V2), version: '0.3.0', chains: ['ethereum', 'base', 'robinhood'],
+    description: 'Scan one bounded block window, read up to the latest block (sequencer-confirmed), for declared on-chain events: ERC-20 transfers and approvals, a wallet\'s token movements across up to eight tokens, swaps and liquidity changes on a supplied Uniswap V2/V3 or Aerodrome pool, governor proposals and timelock operations, proxy, ownership, role and pause changes. Every event carries evidence and explicit coverage; a reorged window is retracted and rescanned. Monitors schedule consecutive windows. Unsupported data sources are refused, never reported as quiet.',
+    inputSchema: { ...structuredClone(WATCHTOWER_MANIFEST_V2.inputSchema), properties: { ...structuredClone(WATCHTOWER_MANIFEST_V2.inputSchema.properties),
+            chain: { type: 'string', description: 'Explicit analysis network', enum: ['ethereum', 'base', 'robinhood'] }, rules: { type: 'array', description: 'One to eight supported event rules' } } },
+    tools: [{ ...structuredClone(WATCHTOWER_MANIFEST_V2.tools[0]), chains: ['ethereum', 'base', 'robinhood'] }],
+    testCases: [...WATCHTOWER_MANIFEST_V2.testCases, 'wallet-token-flow', 'pool-activity', 'governance-events', 'control-events'],
+}).manifest;
+const versionAtLeast = (version, minimum) => { const a = version.split('.').map(Number); const b = minimum.split('.').map(Number); for (let index = 0; index < 3; index++) {
+    if (a[index] !== b[index])
+        return a[index] > b[index];
+} return true; };
+/** The rule types an exact Watchtower version declares. Returns the refusal for the first rule its version cannot run, or null. */
+export function watchRuleRefusal(version, rules) {
+    if (versionAtLeast(version, '0.3.0'))
+        return null;
+    const rule = rules.find((item) => WATCH_RULES_V3.includes(item.type));
+    return rule ? `Rule ${rule.id} (${rule.type}) needs Watchtower 0.3.0 or later; version ${version} watches ERC-20 transfers, approvals and authority changes only.` : null;
+}
+export const SupportedWatchtowerManifestSchema = AgentManifestSchema.superRefine((manifest, ctx) => {
+    if (manifest.outputSchemaId !== WATCH_SCHEMA_ID)
+        ctx.addIssue({ code: 'custom', path: ['outputSchemaId'], message: 'Only agentex.watchtower-window.v1 manifests are Watchtower packages.' });
+    if (contentHash(manifest.workflow) !== contentHash(WATCHTOWER_MANIFEST.workflow))
+        ctx.addIssue({ code: 'custom', path: ['workflow'], message: 'The executor supports only the bounded Watchtower window graph.' });
+    if (!matchesTemplateInput(manifest, [WATCHTOWER_MANIFEST, WATCHTOWER_MANIFEST_V2, WATCHTOWER_MANIFEST_V3]))
+        ctx.addIssue({ code: 'custom', path: ['inputSchema'], message: 'The input declaration must match the supported chain/window/rules/maximumLogs inputs.' });
+    if (manifest.chains.includes('robinhood') && !versionAtLeast(manifest.version, '0.3.0'))
+        ctx.addIssue({ code: 'custom', path: ['chains'], message: 'Robinhood Chain windows need Watchtower 0.3.0 or later.' });
+    const tool = manifest.tools[0];
+    if (manifest.tools.length !== 1 || tool?.id !== 'evm.watch-logs' || tool.version !== '0.1.0' || tool.capability !== 'evm.read' || tool.addressScope !== 'input-watch-scope')
+        ctx.addIssue({ code: 'custom', path: ['tools'], message: 'Only evm.watch-logs@0.1.0 with the read-only input-watch-scope grant is executable.' });
+    if (manifest.limits.maximumRpcCalls < watchWindowRpcEstimate(1))
+        ctx.addIssue({ code: 'custom', path: ['limits', 'maximumRpcCalls'], message: 'A Watchtower window needs at least seven RPC calls.' });
+});
+export const WatchEvidenceItemSchema = evmEvidenceItemSchema(WATCH_TOOL);
+export const WatchIgnoredReasonSchema = z.enum(['address-mismatch', 'topic-mismatch', 'data-mismatch', 'filter-mismatch', 'below-minimum', 'removed', 'outside-coverage']);
+export const WatchEventSchema = z.strictObject({
+    eventKey: Hash, ruleId: WatchRuleIdSchema, ruleType: z.enum(WATCH_RULE_TYPES), event: z.enum(['Transfer', 'Approval', ...AUTHORITY_EVENTS, ...POOL_EVENTS, ...GOVERNANCE_EVENTS, ...CONTROL_EVENTS]),
+    blockNumber: BlockNumberSchema, blockHash: Hex32, transactionHash: Hex32, logIndex: z.number().int().nonnegative(), address: AddressSchema,
+    fields: z.record(z.string().regex(/^[a-zA-Z][a-zA-Z0-9]{0,31}$/), z.string().max(200)), explanation: z.string().max(600), evidenceIds: z.array(z.string()).min(1),
+});
+export const WatchRuleCoverageSchema = z.strictObject({
+    id: WatchRuleIdSchema, type: z.enum(WATCH_RULE_TYPES), coverage: z.enum(['complete', 'truncated', 'unavailable', 'not-read']),
+    logsReturned: z.number().int().nonnegative(), logsMatched: z.number().int().nonnegative(), ignored: z.partialRecord(WatchIgnoredReasonSchema, z.number().int().positive()),
+    coveredThroughBlock: BlockNumberSchema.nullable(), reason: z.string().max(500), evidenceIds: z.array(z.string()),
+});
+export const WatchtowerWindowReportSchema = z.strictObject({
+    schemaVersion: z.literal(WATCH_SCHEMA_ID), agentVersion: z.string().regex(/^\d+\.\d+\.\d+$/), manifestHash: Hash,
+    input: WatchtowerWindowInputSchema, status: z.enum(['complete', 'partial', 'failed']), generatedAt: z.iso.datetime(), chainId: z.number().int().positive().nullable(),
+    window: z.strictObject({
+        fromBlock: BlockNumberSchema, toBlock: BlockNumberSchema, fromBlockHash: Hex32.nullable(), toBlockHash: Hex32.nullable(), toBlockTimestamp: AtomicAmountSchema.nullable(),
+        // New windows are read up to the latest head (`sequencer-confirmed`); a reorg is caught by the end-hash recheck and retracted. `finalized`,
+        // `finalizedBlock` and `finalityLagBlocks` only parse windows captured before the instant-read rule (new windows leave them null).
+        finality: z.enum(['finalized', 'sequencer-confirmed']), canonicality: z.enum(['verified-at-completion', 'unchecked', 'changed']), coverage: z.enum(['complete', 'partial', 'unavailable']),
+        coveredThroughBlock: BlockNumberSchema.nullable(), coveredThroughBlockHash: Hex32.nullable(), finalizedBlock: BlockNumberSchema.nullable(),
+        finalityLagBlocks: z.number().int().nonnegative().nullable(), dataLagSeconds: z.number().int().nonnegative().nullable(),
+        /** Informational: the latest head read when the window was scanned, and how many blocks the window end trailed it. */
+        headBlock: BlockNumberSchema.nullable().optional(), headLagBlocks: z.number().int().nonnegative().nullable().optional(),
+    }),
+    rules: z.array(WatchRuleCoverageSchema).min(1).max(WATCH_MAX_RULES), events: z.array(WatchEventSchema).max(WATCH_MAX_LOGS),
+    unknowns: z.array(z.string().max(500)).max(32), limitations: z.array(z.string()), errors: z.array(ResearchErrorSchema), evidence: z.array(WatchEvidenceItemSchema).max(WATCH_RPC_CEILING * 2),
+    usage: z.strictObject({ rpcCalls: z.number().int().nonnegative(), maximumRpcCalls: z.number().int().positive(), elapsedMs: z.number().int().nonnegative(), modelTokens: z.literal(0), providerCostAtomic: z.null(), providerCostStatus: z.literal('unpriced') }),
+}).superRefine((report, ctx) => {
+    const issue = (message) => ctx.addIssue({ code: 'custom', message });
+    const ids = new Set(report.evidence.map((item) => item.id));
+    if (ids.size !== report.evidence.length)
+        issue('Duplicate evidence id');
+    for (const item of report.evidence) {
+        if (contentHash(item.result) !== item.contentHash)
+            issue('Evidence content hash does not match its captured result');
+        if (!WATCH_RPC_METHODS.includes(item.source.method))
+            issue(`Unsupported Watchtower RPC method ${item.source.method}`);
+    }
+    for (const item of [...report.rules, ...report.events])
+        for (const id of item.evidenceIds)
+            if (!ids.has(id))
+                issue(`Unknown evidence reference ${id}`);
+    for (const error of report.errors)
+        if (error.evidenceId && !ids.has(error.evidenceId))
+            issue(`Unknown error evidence reference ${error.evidenceId}`);
+    const { window } = report;
+    if (window.fromBlock !== report.input.fromBlock || window.toBlock !== report.input.toBlock)
+        issue('The report window must equal the accepted input window.');
+    const ruleIds = new Set(report.input.rules.map((rule) => rule.id));
+    if (report.rules.length !== report.input.rules.length || report.rules.some((rule, index) => rule.id !== report.input.rules[index]?.id))
+        issue('Rule coverage must describe every accepted rule in order.');
+    if (window.coverage === 'complete' && (window.coveredThroughBlock !== window.toBlock || report.rules.some((rule) => rule.coverage !== 'complete') || window.canonicality !== 'verified-at-completion'))
+        issue('Complete coverage requires every rule read through the verified window end.');
+    if (window.coverage === 'unavailable' && (window.coveredThroughBlock !== null || report.events.length > 0))
+        issue('An unavailable window cannot claim coverage or events.');
+    if (report.status !== 'failed' && window.canonicality !== 'verified-at-completion')
+        issue('Only a canonical rechecked window can be accepted.');
+    const keys = new Set();
+    for (const event of report.events) {
+        if (!ruleIds.has(event.ruleId))
+            issue(`Event references unknown rule ${event.ruleId}`);
+        if (keys.has(event.eventKey))
+            issue('Duplicate event key');
+        keys.add(event.eventKey);
+        const block = BigInt(event.blockNumber);
+        if (block < BigInt(window.fromBlock) || window.coveredThroughBlock === null || block > BigInt(window.coveredThroughBlock))
+            issue('Events must lie inside the covered part of the window.');
+    }
+});