agentex-creator-sdk 1.0.0

package/dist/packages/contracts/src/wallet-analysis.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import { AddressSchema, contentHash } from './index.js';
+import { ACTIVITY_TOOL_REFS, ActivityFindingSchema, WalletActivityBodySchema } from './indexed-activity.js';
+import { BlockNumberInputSchema, IndexedAnalysisSchema, IndexedEvidenceSchema, indexedManifestIssues, indexedManifestSchema, IndexedAgentChainSchema, IndexedReportErrorSchema, indexedReportIssues, IndexedSnapshotSchema, IndexedUsageSchema, NotComputedSchema, validateIndexedReceipt } from './indexed-agents.js';
+/**
+ * P03 Wallet Analyst contract. Input: an explicit chain and wallet, an optional block window and a transfer bound. Output: the native balance
+ * at the pinned block, bounded inbound and outbound transfers by category with exact amounts, per-asset flows without double-counted
+ * self-transfers, current token balances, and a transaction ledger (CSV in the run export). Trades are not classified, fees are not computed
+ * and realised or unrealised results, cost basis and win rate are reported as not computed because no verified price or trade source exists.
+ */
+export const WALLET_SCHEMA_ID = 'agentex.wallet-analysis.v1';
+export const WALLET_TOOLS = Object.freeze([ACTIVITY_TOOL_REFS.wallet]);
+/** Pin (2) + balance + two transfer pages + recheck. */
+export const WALLET_MINIMUM_RPC_CALLS = 6;
+export const WalletAnalysisInputSchema = z.strictObject({
+    chain: IndexedAgentChainSchema, wallet: AddressSchema, fromBlock: BlockNumberInputSchema.optional(), toBlock: BlockNumberInputSchema.optional(),
+    maximumTransfers: z.number().int().min(1).max(50).default(25),
+    /** Requested valuation currency. Valuations are not computed until a verified historical price source exists; the report says so. */
+    pricingDenomination: z.enum(['usd']).optional(),
+}).superRefine((input, ctx) => { if (input.fromBlock !== undefined && input.toBlock !== undefined && BigInt(input.fromBlock) > BigInt(input.toBlock))
+    ctx.addIssue({ code: 'custom', path: ['toBlock'], message: 'toBlock must not precede fromBlock' }); });
+const ManifestSchema = indexedManifestSchema(WALLET_SCHEMA_ID);
+export const WALLET_ANALYST_MANIFEST = Object.freeze(ManifestSchema.parse({
+    schemaVersion: '1.0', id: 'wallet-analyst', version: '0.1.0', name: 'Wallet Analyst',
+    description: 'Read a wallet\'s native balance at one latest block (sequencer-confirmed) pinned for the run, its bounded inbound and outbound transfers (native, internal, ERC-20, ERC-721 and ERC-1155) with exact amounts, per-asset flows without double-counted self-transfers and its current token balances, with a downloadable transaction ledger. Trades are not labelled; fees, cost basis, realised and unrealised results and win rate are reported as not computed.',
+    author: { id: 'agentex', name: 'AGENTEX', ownership: 'first-party' }, license: 'Proprietary', visibility: 'source-visible', chains: ['ethereum', 'base'],
+    inputSchema: { type: 'object', additionalProperties: false, required: ['chain', 'wallet'], properties: {
+            chain: { type: 'string', description: 'Explicit analysis network', enum: ['ethereum', 'base'] }, wallet: { type: 'string', description: 'Wallet address to analyse' },
+            fromBlock: { type: 'string', description: 'Optional first block of the activity window' }, toBlock: { type: 'string', description: 'Optional last block, at or before the latest block' },
+            maximumTransfers: { type: 'integer', description: 'Most recent transfers read per direction (1-50)' }, pricingDenomination: { type: 'string', description: 'Requested valuation currency; valuations are not computed yet', enum: ['usd'] }
+        } },
+    outputSchemaId: WALLET_SCHEMA_ID, tools: [{ id: 'evm.wallet-activity', version: '0.1.0', capability: 'evm.read', chains: ['ethereum', 'base'], addressScope: 'input-address', maximumCalls: 16 }],
+    modelPolicy: { mode: 'deterministic', maximumModelTokens: 0 },
+    limits: { maximumRpcCalls: 16, maximumDurationMs: 60000, maximumOutputBytes: 262144, maximumGraphDepth: 3, maximumPages: 1, maximumExecutionAtomic: '0' },
+    workflow: [
+        { id: 'input', type: 'input', dependsOn: [] },
+        { id: 'activity', type: 'tool', tool: 'evm.wallet-activity', dependsOn: ['input'], arguments: { wallet: { source: 'input', path: 'wallet' }, fromBlock: { source: 'input', path: 'fromBlock' }, toBlock: { source: 'input', path: 'toBlock' }, maximumTransfers: { source: 'input', path: 'maximumTransfers' } } },
+        { id: 'report', type: 'output', dependsOn: ['activity'], from: 'activity' },
+    ],
+    testCases: ['transfers-and-balances', 'in-and-out-not-a-trade', 'self-transfer-counted-once', 'truncated-history', 'missing-token-metadata', 'provider-failure', 'chain-mismatch'],
+}));
+export const SupportedWalletAnalystManifestSchema = ManifestSchema.superRefine((manifest, ctx) => {
+    for (const item of indexedManifestIssues(manifest, WALLET_ANALYST_MANIFEST, WALLET_MINIMUM_RPC_CALLS))
+        ctx.addIssue({ code: 'custom', path: item.path, message: item.message });
+});
+/** Columns of the transaction ledger rows in the CSV run export (one row per transfer leg). */
+export const WALLET_LEDGER_COLUMNS = Object.freeze(['direction', 'category', 'blockNumber', 'blockTimestamp', 'transactionHash', 'from', 'to', 'contract', 'asset', 'tokenId', 'valueAtomic', 'decimals', 'valueFormatted', 'selfTransfer', 'classification', 'evidenceId']);
+export const WalletAnalysisReportSchema = z.strictObject({
+    schemaVersion: z.literal(WALLET_SCHEMA_ID), agentVersion: z.string().regex(/^\d+\.\d+\.\d+$/), manifestHash: z.string().regex(/^[a-f0-9]{64}$/),
+    input: WalletAnalysisInputSchema, status: z.enum(['complete', 'partial', 'failed']), generatedAt: z.iso.datetime(), chainId: z.number().int().positive().nullable(), snapshot: IndexedSnapshotSchema.nullable(),
+    activity: WalletActivityBodySchema.omit({ errors: true }).nullable(),
+    trades: z.strictObject({ status: z.literal('not-classified'), reason: z.string().max(600) }),
+    fees: NotComputedSchema,
+    results: z.strictObject({ realised: NotComputedSchema, unrealised: NotComputedSchema, costBasis: NotComputedSchema, winRate: NotComputedSchema, valuationDenomination: z.enum(['usd']).nullable() }),
+    ledger: z.strictObject({ format: z.literal('csv-in-run-export'), rows: z.number().int().nonnegative().max(200), columns: z.array(z.string().max(32)).max(24) }),
+    findings: z.array(ActivityFindingSchema).max(64), 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, WALLET_TOOLS, ctx);
+    if (report.activity && report.activity.wallet.toLowerCase() !== report.input.wallet.toLowerCase())
+        ctx.addIssue({ code: 'custom', path: ['activity'], message: 'The activity section must describe the accepted wallet.' });
+    if (report.ledger.rows !== (report.activity?.transfers.length ?? 0))
+        ctx.addIssue({ code: 'custom', path: ['ledger', 'rows'], message: 'The ledger row count must equal the returned transfer legs.' });
+    if (report.status === 'complete' && (!report.activity || report.errors.length || report.activity.nativeBalance.balanceAtomic.status !== 'observed' || [report.activity.coverage.inbound, report.activity.coverage.outbound].some((status) => status === 'unavailable' || status === 'not-read-call-bound')))
+        ctx.addIssue({ code: 'custom', path: ['status'], message: 'A complete analysis observes the native balance and reads both transfer directions without errors.' });
+});
+export const WALLET_RESULT_CONTRACT = { id: 'wallet-analysis-observed-v1', description: 'Charge only for a complete analysis read at one pinned latest block (sequencer-confirmed) that is still canonical at completion: the native balance observed, both inbound and outbound transfer pages read with exact amounts and their index coverage stated, and the transaction ledger included. Trades, fees, cost basis, realised and unrealised results and win rate are never claimed. A reorganization or any read error makes the report partial or failed and charges nothing.' };
+export function walletResultContractIssues(raw, manifest) {
+    const parsed = WalletAnalysisReportSchema.safeParse(raw);
+    if (!parsed.success)
+        return [`The report does not match ${WALLET_SCHEMA_ID}.`];
+    const report = parsed.data;
+    const issues = [];
+    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 analysis is ${report.status}.`);
+    if (report.snapshot?.canonicality !== 'verified-at-completion')
+        issues.push('The pinned block was not rechecked as canonical.');
+    if (!report.activity || report.activity.nativeBalance.balanceAtomic.status !== 'observed')
+        issues.push('The native balance was not observed.');
+    if (!report.evidence.some((item) => item.source.method === 'eth_chainId' && item.completeness === 'complete-for-request'))
+        issues.push('Chain identity was not captured.');
+    if (report.activity && !['in', 'out'].every((direction) => report.activity.pages.some((page) => page.direction === direction && (page.status === 'provider-exhausted' || page.status === 'truncated-with-cursor'))))
+        issues.push('Both transfer directions were not read.');
+    return issues;
+}
+export const satisfiesWalletResultContract = (raw, manifest) => walletResultContractIssues(raw, manifest).length === 0;
+export const validateWalletReceipt = (evidence, input) => validateIndexedReceipt(evidence, input, WALLET_TOOLS);