agentex-creator-sdk 1.0.0

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

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+import { AddressSchema, AgentManifestSchema, AtomicAmountSchema, ChainKeySchema, ObservationSchema, ResearchErrorSchema, contentHash, evmEvidenceItemSchema, matchesTemplateInput, publishManifest } from './index.js';
+/** Transaction Inspector contracts. Kept outside index.ts so both modules initialise without a circular import. */
+export const INSPECTION_MAX_DATA_BYTES = 16384;
+export const INSPECTION_RPC_CEILING = 24;
+export const INSPECTION_TOOL = 'evm.inspect-transaction@0.1.0';
+const Hash = z.string().regex(/^[a-f0-9]{64}$/);
+const Hex32 = z.string().regex(/^0x[a-f0-9]{64}$/);
+export const CalldataSchema = z.string().max(2 + INSPECTION_MAX_DATA_BYTES * 2, `Calldata exceeds ${INSPECTION_MAX_DATA_BYTES} bytes`).regex(/^0x(?:[0-9a-fA-F]{2})*$/, 'Expected even-length 0x-prefixed hex data');
+/** A proposed, unsigned payload. There is deliberately no signature, nonce, key or broadcast field. */
+export const TransactionInspectionInputSchema = z.strictObject({
+    chain: ChainKeySchema,
+    from: AddressSchema,
+    to: AddressSchema.nullable().default(null),
+    data: CalldataSchema,
+    value: AtomicAmountSchema.default('0'),
+    snapshotBlock: AtomicAmountSchema.optional(),
+}).superRefine((input, ctx) => {
+    if (input.to === null && input.data === '0x')
+        ctx.addIssue({ code: 'custom', path: ['data'], message: 'Contract creation (to = null) requires init code' });
+});
+export const TRANSACTION_INSPECTOR_MANIFEST = publishManifest({
+    schemaVersion: '1.0', id: 'transaction-inspector', version: '0.1.0', name: 'Transaction Inspector',
+    description: 'Decode a proposed EVM payload, read target and grantee context at one finalized snapshot, and run eth_call plus eth_estimateGas from the sender. It never signs or broadcasts, does not trace asset flows and gives no safety verdict.',
+    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'] }, from: { type: 'string', description: 'Sender address used as simulation context' }, to: { type: 'string', description: 'Target address; omit or null for contract creation' }, data: { type: 'string', description: 'Hex calldata or init code, at most 16 KiB' }, value: { type: 'string', description: 'Native value in atomic units' }, snapshotBlock: { type: 'string', description: 'Optional finalized block number' } }, required: ['chain', 'from', 'data'] },
+    outputSchemaId: 'agentex.transaction-inspection.v1', tools: [{ id: 'evm.inspect-transaction', version: '0.1.0', capability: 'evm.read', chains: ['ethereum', 'base'], addressScope: 'input-transaction', maximumCalls: 24 }],
+    modelPolicy: { mode: 'deterministic', maximumModelTokens: 0 }, limits: { maximumRpcCalls: 24, maximumDurationMs: 60000, maximumOutputBytes: 262144, maximumGraphDepth: 4, maximumPages: 0, maximumExecutionAtomic: '0' },
+    workflow: [{ id: 'input', type: 'input', dependsOn: [] }, { id: 'inspect', type: 'tool', tool: 'evm.inspect-transaction', dependsOn: ['input'], arguments: { chain: { source: 'input', path: 'chain' }, from: { source: 'input', path: 'from' }, to: { source: 'input', path: 'to' }, data: { source: 'input', path: 'data' }, value: { source: 'input', path: 'value' }, snapshotBlock: { source: 'input', path: 'snapshotBlock' } } }, { id: 'report', type: 'output', dependsOn: ['inspect'], from: 'inspect' }],
+    testCases: ['erc20-decoders', 'nested-multicall-bound', 'unknown-selector', 'revert-reason', 'contract-creation', 'no-code-target', 'unlimited-approval', 'provider-failure', 'budget-stop'],
+}).manifest;
+/** Transaction Inspector 0.2.0: identical graph, tool, limits and output schema to 0.1.0 (kept byte-identical, hash 4dab080b…); instant-read wording for new drafts. */
+export const TRANSACTION_INSPECTOR_MANIFEST_V2 = publishManifest({
+    ...structuredClone(TRANSACTION_INSPECTOR_MANIFEST), version: '0.2.0',
+    description: 'Decode a proposed EVM payload, read target and grantee context at the latest block (sequencer-confirmed), pinned for the run and rechecked at completion, and run eth_call plus eth_estimateGas from the sender. It never signs or broadcasts, does not trace asset flows and gives no safety verdict.',
+    inputSchema: { ...structuredClone(TRANSACTION_INSPECTOR_MANIFEST.inputSchema), properties: { ...structuredClone(TRANSACTION_INSPECTOR_MANIFEST.inputSchema.properties), snapshotBlock: { type: 'string', description: 'Optional block number (defaults to the latest block)' } } },
+}).manifest;
+/** Executable manifest subset for the transaction inspector: fixed graph and tool, selectable chains and lower limits only. */
+export const SupportedTransactionInspectorManifestSchema = AgentManifestSchema.superRefine((manifest, ctx) => {
+    if (manifest.outputSchemaId !== 'agentex.transaction-inspection.v1')
+        ctx.addIssue({ code: 'custom', path: ['outputSchemaId'], message: 'Only agentex.transaction-inspection.v1 manifests are Transaction Inspector packages.' });
+    if (contentHash(manifest.workflow) !== contentHash(TRANSACTION_INSPECTOR_MANIFEST.workflow))
+        ctx.addIssue({ code: 'custom', path: ['workflow'], message: 'The executor supports only the bounded Transaction Inspector graph.' });
+    if (!matchesTemplateInput(manifest, [TRANSACTION_INSPECTOR_MANIFEST, TRANSACTION_INSPECTOR_MANIFEST_V2]))
+        ctx.addIssue({ code: 'custom', path: ['inputSchema'], message: 'The input declaration must match the supported chain/from/to/data/value/snapshot inputs.' });
+    const tool = manifest.tools[0];
+    if (manifest.tools.length !== 1 || tool?.id !== 'evm.inspect-transaction' || tool.version !== '0.1.0' || tool.capability !== 'evm.read' || tool.addressScope !== 'input-transaction')
+        ctx.addIssue({ code: 'custom', path: ['tools'], message: 'Only evm.inspect-transaction@0.1.0 with the read-only input-transaction grant is executable.' });
+    if (manifest.researchPolicy !== undefined)
+        ctx.addIssue({ code: 'custom', path: ['researchPolicy'], message: 'The inspector has no selectable research policy.' });
+});
+export const InspectionEvidenceItemSchema = evmEvidenceItemSchema(INSPECTION_TOOL);
+export const INSPECTION_RPC_METHODS = ['eth_chainId', 'eth_getBlockByNumber', 'eth_getCode', 'eth_getStorageAt', 'eth_call', 'eth_estimateGas'];
+export const DecodedActionKindSchema = z.enum(['native-transfer', 'contract-creation', 'erc20.transfer', 'erc20.approve', 'erc20-or-erc721.transferFrom', 'erc20.increaseAllowance', 'erc20.decreaseAllowance',
+    'eip2612.permit', 'erc721-or-erc1155.setApprovalForAll', 'erc721.safeTransferFrom', 'erc1155.safeTransferFrom', 'weth.deposit', 'weth.withdraw', 'multicall', 'unknown']);
+export const DecodedActionSchema = z.strictObject({
+    path: z.string().regex(/^\d{1,3}(?:\.\d{1,3}){0,7}$/), depth: z.number().int().min(0).max(8), target: AddressSchema.nullable(),
+    status: z.enum(['decoded', 'unknown', 'invalid', 'bound-reached']), kind: DecodedActionKindSchema,
+    selector: z.string().regex(/^0x[a-f0-9]{8}$/).nullable(), signature: z.string().max(200).nullable(),
+    arguments: z.record(z.string().regex(/^[a-zA-Z][a-zA-Z0-9]{0,31}$/), z.union([z.string().max(1024), z.boolean()])),
+    notes: z.array(z.string().max(500)).max(8),
+});
+export const InspectionFindingCodeSchema = z.enum(['unlimited-approval', 'approval-grantee-without-code', 'operator-approval-granted', 'operator-grantee-without-code', 'native-value-sent',
+    'upgradeable-proxy-target', 'target-without-code', 'simulation-reverted', 'contract-creation', 'unknown-action', 'invalid-calldata', 'decoding-bound-reached']);
+/** New inspections record the pinned latest block (`sequencer-confirmed`); `finalized` parses inspections captured before the instant-read rule. */
+const SnapshotSchema = z.strictObject({ blockNumber: AtomicAmountSchema, blockHash: z.string(), timestamp: AtomicAmountSchema, finality: z.enum(['finalized', 'sequencer-confirmed']), canonicality: z.enum(['verified-at-completion', 'unchecked', 'changed']) });
+export const TransactionInspectionReportSchema = z.strictObject({
+    schemaVersion: z.literal('agentex.transaction-inspection.v1'), agentVersion: z.string().regex(/^\d+\.\d+\.\d+$/), manifestHash: Hash,
+    input: TransactionInspectionInputSchema, status: z.enum(['complete', 'partial', 'failed']), generatedAt: z.iso.datetime(),
+    chainId: z.number().int().positive().nullable(), snapshot: SnapshotSchema.nullable(),
+    transaction: z.strictObject({ kind: z.enum(['call', 'native-transfer', 'contract-creation']), selector: z.string().regex(/^0x[a-f0-9]{8}$/).nullable(), dataBytes: z.number().int().min(0).max(INSPECTION_MAX_DATA_BYTES), dataHash: Hex32, valueAtomic: AtomicAmountSchema, valueFormatted: z.string(), valueUnit: z.literal('native-18-decimals') }),
+    actions: z.array(DecodedActionSchema).max(64),
+    target: z.strictObject({ address: AddressSchema.nullable(), codePresent: ObservationSchema, codeHash: ObservationSchema, implementation: ObservationSchema, admin: ObservationSchema, beacon: ObservationSchema, tokenName: ObservationSchema, tokenSymbol: ObservationSchema, tokenDecimals: ObservationSchema }),
+    grantees: z.array(z.strictObject({ address: AddressSchema, owner: AddressSchema, role: z.enum(['spender', 'operator']), actionPaths: z.array(z.string()).min(1).max(64), codePresent: ObservationSchema, currentAllowance: ObservationSchema })).max(8),
+    simulation: z.strictObject({
+        semantics: z.literal('eth_call-at-snapshot-not-asset-flow'),
+        call: z.strictObject({ status: z.enum(['success', 'reverted', 'execution-error', 'error', 'not-run']), reason: z.string().max(1000), returnData: z.string().regex(/^0x(?:[a-f0-9]{2})*$/).max(514).nullable(), returnDataBytes: z.number().int().nonnegative().nullable(), returnDataHash: Hex32.nullable(), revertData: z.string().regex(/^0x(?:[a-f0-9]{2})*$/).max(2 + INSPECTION_MAX_DATA_BYTES * 2).nullable(), revertReason: z.string().max(1024).nullable(), evidenceIds: z.array(z.string()) }),
+        gasEstimate: ObservationSchema, balanceChanges: ObservationSchema,
+    }),
+    findings: z.array(z.strictObject({ code: InspectionFindingCodeSchema, message: z.string().max(1000), actionPaths: z.array(z.string()).max(64), evidenceIds: z.array(z.string()) })).max(64),
+    limitations: z.array(z.string()), errors: z.array(ResearchErrorSchema), evidence: z.array(InspectionEvidenceItemSchema).max(INSPECTION_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 ids = new Set(report.evidence.map((item) => item.id));
+    if (ids.size !== report.evidence.length)
+        ctx.addIssue({ code: 'custom', message: 'Duplicate evidence id' });
+    if (report.simulation.balanceChanges.status === 'observed')
+        ctx.addIssue({ code: 'custom', path: ['simulation', 'balanceChanges'], message: 'eth_call does not observe balance changes; they must remain unobserved.' });
+    if ((report.input.to === null) !== (report.target.address === null) || (report.input.to !== null && report.target.address?.toLowerCase() !== report.input.to.toLowerCase()))
+        ctx.addIssue({ code: 'custom', path: ['target'], message: 'Target context must describe the input target.' });
+    const paths = new Set(report.actions.map((action) => action.path));
+    const references = [...Object.values(report.target).filter((value) => typeof value === 'object' && value !== null), ...report.grantees.flatMap((grantee) => [grantee.codePresent, grantee.currentAllowance]),
+        report.simulation.call, report.simulation.gasEstimate, report.simulation.balanceChanges, ...report.findings];
+    for (const item of references)
+        for (const id of item.evidenceIds)
+            if (!ids.has(id))
+                ctx.addIssue({ code: 'custom', message: `Unknown evidence reference ${id}` });
+    for (const item of [...report.findings, ...report.grantees])
+        for (const path of item.actionPaths)
+            if (!paths.has(path))
+                ctx.addIssue({ code: 'custom', message: `Unknown action reference ${path}` });
+    for (const error of report.errors)
+        if (error.evidenceId && !ids.has(error.evidenceId))
+            ctx.addIssue({ code: 'custom', message: `Unknown error evidence reference ${error.evidenceId}` });
+    for (const item of report.evidence) {
+        if (contentHash(item.result) !== item.contentHash)
+            ctx.addIssue({ code: 'custom', message: 'Evidence content hash does not match its captured result' });
+        // An allowlist of read methods: signing and broadcast methods can never appear in a valid report.
+        if (!INSPECTION_RPC_METHODS.includes(item.source.method))
+            ctx.addIssue({ code: 'custom', message: `Unsupported inspector RPC method ${item.source.method}` });
+    }
+    if (['success', 'reverted', 'execution-error'].includes(report.simulation.call.status) && report.simulation.call.evidenceIds.length === 0)
+        ctx.addIssue({ code: 'custom', path: ['simulation', 'call'], message: 'A simulation outcome needs its captured eth_call receipt.' });
+});