agentex-creator-sdk 1.0.0

package/dist/packages/contracts/src/deployer-investigation.js

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { AddressSchema, contentHash } from './index.js';
+import { ACTIVITY_TOOL_REFS, ActivityEvidenceIdSchema, ActivityFindingSchema, AddressFundingBodySchema, ContractOriginBodySchema, DeployerLaunchesBodySchema } from './indexed-activity.js';
+import { Hex32Schema, IndexedAnalysisSchema, IndexedEvidenceSchema, indexedManifestIssues, indexedManifestSchema, IndexedAgentChainSchema, IndexedReportErrorSchema, indexedReportIssues, IndexedSnapshotSchema, IndexedUsageSchema, validateIndexedReceipt } from './indexed-agents.js';
+/**
+ * P02 Deployer Investigator contract. Input: an explicit chain and contract, an optional creation transaction (verified, never trusted) and
+ * bounds for the funding and related-deployment sections. Output: how the contract was created, the observed sender/factory roles, the
+ * sender's earliest indexed funding, its other top-level creations, a chronological timeline and an evidence-linked relationship graph.
+ * Roles never identify people; a funding link or a shared sender is an observed relationship, not proof of common ownership or intent.
+ */
+export const DEPLOYER_SCHEMA_ID = 'agentex.deployer-investigation.v1';
+export const DEPLOYER_TOOLS = Object.freeze([ACTIVITY_TOOL_REFS.origin, ACTIVITY_TOOL_REFS.funding, ACTIVITY_TOOL_REFS.launches]);
+/** Pin (2) + code + one anchor + receipt + recheck: the least budget that can confirm a creation. */
+export const DEPLOYER_MINIMUM_RPC_CALLS = 6;
+export const DeployerInvestigationInputSchema = z.strictObject({
+    chain: IndexedAgentChainSchema, contract: AddressSchema, creationTransaction: Hex32Schema.optional(),
+    maximumFundingTransfers: z.number().int().min(1).max(25).default(10),
+    maximumRelatedTransactions: z.number().int().min(1).max(50).default(25),
+    maximumRelatedReceipts: z.number().int().min(0).max(4).default(2),
+});
+const ManifestSchema = indexedManifestSchema(DEPLOYER_SCHEMA_ID);
+const TOOL = (id) => ({ id, version: '0.1.0', capability: 'evm.read', chains: ['ethereum', 'base'], addressScope: 'input-address', maximumCalls: 16 });
+export const DEPLOYER_INVESTIGATOR_MANIFEST = Object.freeze(ManifestSchema.parse({
+    schemaVersion: '1.0', id: 'deployer-investigator', version: '0.1.0', name: 'Deployer Investigator',
+    description: 'Find how a contract was created (a creation receipt, or archive code checks around its first indexed activity), the account that sent the creation transaction or the factory that announced it, that account\'s earliest indexed funding and its other top-level contract creations, all at one latest block (sequencer-confirmed) pinned for the run. Relationships are observed transactions: they never identify a person or prove ownership, control or intent.',
+    author: { id: 'agentex', name: 'AGENTEX', ownership: 'first-party' }, license: 'Proprietary', visibility: 'source-visible', chains: ['ethereum', 'base'],
+    inputSchema: { type: 'object', additionalProperties: false, required: ['chain', 'contract'], properties: {
+            chain: { type: 'string', description: 'Explicit analysis network', enum: ['ethereum', 'base'] }, contract: { type: 'string', description: 'Contract address to investigate' },
+            creationTransaction: { type: 'string', description: 'Optional creation transaction hash; it is verified before use' },
+            maximumFundingTransfers: { type: 'integer', description: 'Earliest inbound transfers to the creation sender (1-25)' },
+            maximumRelatedTransactions: { type: 'integer', description: 'Sender transactions examined for other contract creations (1-50)' },
+            maximumRelatedReceipts: { type: 'integer', description: 'Other creation receipts resolved to contract addresses (0-4)' }
+        } },
+    outputSchemaId: DEPLOYER_SCHEMA_ID, tools: [TOOL('evm.contract-origin'), TOOL('evm.address-funding'), TOOL('evm.deployer-launches')],
+    modelPolicy: { mode: 'deterministic', maximumModelTokens: 0 },
+    limits: { maximumRpcCalls: 16, maximumDurationMs: 60000, maximumOutputBytes: 262144, maximumGraphDepth: 5, maximumPages: 1, maximumExecutionAtomic: '0' },
+    workflow: [
+        { id: 'input', type: 'input', dependsOn: [] },
+        { id: 'origin', type: 'tool', tool: 'evm.contract-origin', dependsOn: ['input'], arguments: { contract: { source: 'input', path: 'contract' }, creationTransaction: { source: 'input', path: 'creationTransaction' } } },
+        { id: 'funding', type: 'tool', tool: 'evm.address-funding', dependsOn: ['origin'], arguments: { address: { source: 'node', nodeId: 'origin', path: 'initiator' }, maximumTransfers: { source: 'input', path: 'maximumFundingTransfers' } } },
+        { id: 'launches', type: 'tool', tool: 'evm.deployer-launches', dependsOn: ['origin', 'funding'], arguments: { deployer: { source: 'node', nodeId: 'origin', path: 'initiator' }, maximumTransactions: { source: 'input', path: 'maximumRelatedTransactions' }, maximumReceipts: { source: 'input', path: 'maximumRelatedReceipts' } } },
+        { id: 'report', type: 'output', dependsOn: ['launches'], from: 'launches' },
+    ],
+    testCases: ['direct-deployment', 'factory-deployment', 'creation-not-indexed', 'infrastructure-funded-sender', 'truncated-history', 'provider-failure', 'chain-mismatch'],
+}));
+export const SupportedDeployerInvestigatorManifestSchema = ManifestSchema.superRefine((manifest, ctx) => {
+    for (const item of indexedManifestIssues(manifest, DEPLOYER_INVESTIGATOR_MANIFEST, DEPLOYER_MINIMUM_RPC_CALLS))
+        ctx.addIssue({ code: 'custom', path: item.path, message: item.message });
+});
+const Section = (body) => z.strictObject({ status: z.enum(['observed', 'not-read', 'unavailable']), reason: z.string().max(600), subject: AddressSchema.nullable(), body: body.nullable() });
+const Node = z.strictObject({ id: z.string().max(80), kind: z.enum(['account', 'contract', 'transaction']), label: z.string().max(100).nullable(), isPerson: z.literal(false) });
+const Edge = z.strictObject({ from: z.string().max(80), to: z.string().max(80), relation: z.enum(['sent-creation-transaction', 'created-contract', 'called-in-creation-transaction', 'emitted-creation-event', 'funded', 'sent-other-creation']),
+    basis: z.enum(['direct-transaction-evidence', 'heuristic-association', 'provider-index-assertion']), evidenceIds: z.array(ActivityEvidenceIdSchema).min(1) });
+export const DeployerInvestigationReportSchema = z.strictObject({
+    schemaVersion: z.literal(DEPLOYER_SCHEMA_ID), agentVersion: z.string().regex(/^\d+\.\d+\.\d+$/), manifestHash: z.string().regex(/^[a-f0-9]{64}$/),
+    input: DeployerInvestigationInputSchema, status: z.enum(['complete', 'partial', 'failed']), generatedAt: z.iso.datetime(), chainId: z.number().int().positive().nullable(), snapshot: IndexedSnapshotSchema.nullable(),
+    origin: ContractOriginBodySchema.omit({ errors: true }).nullable(),
+    funding: Section(AddressFundingBodySchema.omit({ errors: true })), relatedDeployments: Section(DeployerLaunchesBodySchema.omit({ errors: true })),
+    timeline: z.array(z.strictObject({ blockNumber: z.string().regex(/^(0|[1-9][0-9]{0,77})$/), transactionHash: Hex32Schema.nullable(), kind: z.enum(['funding-transfer', 'contract-creation', 'related-creation']), summary: z.string().max(400), evidenceIds: z.array(ActivityEvidenceIdSchema).min(1) })).max(128),
+    graph: z.strictObject({ nodes: z.array(Node).max(96), edges: z.array(Edge).max(160) }),
+    findings: z.array(ActivityFindingSchema).max(64), alternativeExplanations: z.array(z.string().max(600)).max(12), unknowns: z.array(z.string().max(600)).max(24),
+    limitations: z.array(z.string().max(1000)).max(24), errors: z.array(IndexedReportErrorSchema).max(40), evidence: IndexedEvidenceSchema,
+    analysis: IndexedAnalysisSchema.optional(), usage: IndexedUsageSchema,
+}).superRefine((report, ctx) => {
+    indexedReportIssues(report, DEPLOYER_TOOLS, ctx);
+    const nodes = new Set(report.graph.nodes.map((node) => node.id));
+    for (const edge of report.graph.edges)
+        if (!nodes.has(edge.from) || !nodes.has(edge.to))
+            ctx.addIssue({ code: 'custom', path: ['graph'], message: 'Every relationship edge must connect declared nodes.' });
+    if (report.origin && report.origin.contract.toLowerCase() !== report.input.contract.toLowerCase())
+        ctx.addIssue({ code: 'custom', path: ['origin'], message: 'The origin section must describe the accepted contract.' });
+    if (report.status === 'complete' && (!report.origin || !['confirmed-by-receipt', 'block-located'].includes(report.origin.creation.status) || report.funding.status !== 'observed' || report.relatedDeployments.status !== 'observed' || report.errors.length))
+        ctx.addIssue({ code: 'custom', path: ['status'], message: 'A complete investigation locates the creation and reads both relationship sections without errors.' });
+});
+export const DEPLOYER_RESULT_CONTRACT = { id: 'deployer-investigation-observed-v1', description: 'Charge only for a complete investigation read at one pinned latest block (sequencer-confirmed) that is still canonical at completion: contract code observed, the creation block located with a captured receipt or archive code checks, and the funding and related-deployment sections read with their index coverage stated. A reorganization, an unlocated creation or any read error makes the report partial or failed and charges nothing. No identity, ownership, fraud or safety claim is made.' };
+export function deployerResultContractIssues(raw, manifest) {
+    const parsed = DeployerInvestigationReportSchema.safeParse(raw);
+    if (!parsed.success)
+        return [`The report does not match ${DEPLOYER_SCHEMA_ID}.`];
+    const report = parsed.data;
+    const issues = [];
+    const evidence = new Map(report.evidence.map((item) => [item.id, item]));
+    if (manifest && (report.agentVersion !== manifest.version || report.manifestHash !== contentHash(manifest)))
+        issues.push('The report is bound to another version.');
+    if (report.status !== 'complete')
+        issues.push(`The investigation is ${report.status}.`);
+    if (report.snapshot?.canonicality !== 'verified-at-completion')
+        issues.push('The pinned block was not rechecked as canonical.');
+    const creation = report.origin?.creation;
+    if (!creation || !['confirmed-by-receipt', 'block-located'].includes(creation.status) || creation.blockNumber.status !== 'observed')
+        issues.push('The creation block was not located.');
+    else if (creation.blockNumber.evidenceIds.some((id) => evidence.get(id)?.completeness !== 'complete-for-request'))
+        issues.push('The creation block is not backed by complete captured reads.');
+    if (!report.evidence.some((item) => item.source.method === 'eth_chainId' && item.completeness === 'complete-for-request'))
+        issues.push('Chain identity was not captured.');
+    if (report.funding.status !== 'observed' || report.relatedDeployments.status !== 'observed')
+        issues.push('A relationship section was not read.');
+    return issues;
+}
+export const satisfiesDeployerResultContract = (raw, manifest) => deployerResultContractIssues(raw, manifest).length === 0;
+export const validateDeployerReceipt = (evidence, input) => validateIndexedReceipt(evidence, input, DEPLOYER_TOOLS);