@clawnch/clawncher-sdk 0.3.1 → 0.3.3

package/dist/herd.d.ts

@@ -0,0 +1,223 @@
+/**
+ * HerdIntelligence — On-chain intelligence via Herd MCP
+ *
+ * Composes Herd's block explorer data with Clawncher's domain-specific
+ * on-chain reading to produce rich, actionable intelligence that neither
+ * system can provide alone.
+ *
+ * Architecture:
+ *   - Uses the MCP SDK's HTTP client to call Herd's MCP server
+ *   - Combines Herd responses with ClawnchReader / ClawnchPrice data
+ *   - Caches responses with configurable TTLs
+ *   - Degrades gracefully when Herd is unavailable
+ *
+ * @example
+ * ```typescript
+ * const herd = new HerdIntelligence({
+ *   accessToken: 'your-herd-token',
+ *   publicClient,
+ *   network: 'mainnet',
+ * });
+ *
+ * // Investigate any contract — enriched with Clawncher data if applicable
+ * const profile = await herd.investigateContract('0x...');
+ *
+ * // Audit a token for safety before interacting
+ * const audit = await herd.auditTokenSafety('0x...');
+ *
+ * // Validate a swap route against historical on-chain data
+ * const validation = await herd.validateSwapRoute('0xTokenIn', '0xTokenOut', '1.0');
+ * ```
+ */
+import type { PublicClient } from 'viem';
+import { type NetworkName } from './addresses.js';
+import type { HerdBlockchain, HerdCacheTtl, ContractProfile, TokenAuditReport, TransactionProfile, WalletProfile, ContractRelationship, TokenFlowReport, VersionDiff, SwapValidation, FeeClaimValidation, CounterpartyProfile, Bookmark, BookmarkType } from './herd-types.js';
+export type { ContractProfile, TokenAuditReport, TransactionProfile, WalletProfile, ContractRelationship, TokenFlowReport, VersionDiff, SwapValidation, FeeClaimValidation, CounterpartyProfile, Bookmark, BookmarkType, SecurityFlag, SecuritySeverity, } from './herd-types.js';
+export interface HerdIntelligenceConfig {
+    /** Public client for on-chain reads (composing Herd data with ours) */
+    publicClient?: PublicClient;
+    /** Network for Clawncher address lookups */
+    network?: NetworkName;
+    /** Herd access token (or set HERD_ACCESS_TOKEN env var) */
+    accessToken?: string;
+    /** Herd MCP server URL */
+    mcpUrl?: string;
+    /** Default blockchain for Herd queries */
+    blockchain?: HerdBlockchain;
+    /** Cache TTL overrides in seconds */
+    cacheTtl?: Partial<HerdCacheTtl>;
+    /** Timeout for MCP calls in ms (default: 30000) */
+    timeout?: number;
+}
+export declare class HerdIntelligence {
+    private mcp;
+    private reader;
+    private price;
+    private publicClient;
+    private network;
+    private blockchain;
+    private addresses;
+    private knownAddresses;
+    private cache;
+    private cacheTtl;
+    constructor(config?: HerdIntelligenceConfig);
+    /**
+     * Check if the Herd MCP server is reachable and authenticated.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Investigate any contract on Base/Ethereum.
+     *
+     * Returns a rich profile combining Herd's metadata (ABI, proxy info,
+     * token data, protocol labels) with Clawncher-specific data when the
+     * contract is one of ours (vault status, MEV config, fees, etc.).
+     *
+     * Also runs security pattern analysis on the source code.
+     */
+    investigateContract(address: string, options?: {
+        blockchain?: HerdBlockchain;
+        skipCodeAnalysis?: boolean;
+    }): Promise<ContractProfile>;
+    /**
+     * Investigate any transaction.
+     *
+     * Decodes traces, logs, and balance changes via Herd, then annotates
+     * with Clawncher-specific context (e.g. "this was a fee claim",
+     * "this was a V4 swap with 0.35 ETH output").
+     */
+    investigateTransaction(txHash: string, options?: {
+        blockchain?: HerdBlockchain;
+    }): Promise<TransactionProfile>;
+    /**
+     * Investigate any wallet.
+     *
+     * Detects wallet type (EOA, 4337, 7702, multisig), shows holdings,
+     * and overlays Clawncher token positions and fee data if the wallet
+     * holds any of our tokens.
+     */
+    investigateWallet(address: string, options?: {
+        blockchain?: HerdBlockchain;
+        includeActivity?: boolean;
+    }): Promise<WalletProfile>;
+    /**
+     * Map relationships for a contract — who calls it, what it calls,
+     * what it deployed. Highlights Clawncher contracts in the graph.
+     */
+    getContractRelationships(address: string, options?: {
+        blockchain?: HerdBlockchain;
+    }): Promise<ContractRelationship>;
+    /**
+     * Track token transfer history for a holder.
+     * Annotates transfers with known contract labels.
+     */
+    trackTokenFlow(holder: string, token: string, options?: {
+        blockchain?: HerdBlockchain;
+        page?: number;
+    }): Promise<TokenFlowReport>;
+    /**
+     * Compare implementation versions of an upgradeable contract.
+     */
+    compareVersions(address: string, options?: {
+        blockchain?: HerdBlockchain;
+        allVersions?: boolean;
+    }): Promise<VersionDiff>;
+    /**
+     * Search contract source code using natural language or regex.
+     */
+    searchCode(addresses: string[], query: string, options?: {
+        includeProxies?: boolean;
+        returnAllCode?: boolean;
+    }): Promise<string>;
+    /**
+     * Comprehensive security audit of any ERC-20 token.
+     *
+     * Combines contract metadata, code analysis for dangerous patterns,
+     * proxy/upgrade detection, and owner privilege scanning into a single
+     * risk report with a 0-100 score.
+     */
+    auditTokenSafety(tokenAddress: string, options?: {
+        blockchain?: HerdBlockchain;
+    }): Promise<TokenAuditReport>;
+    /**
+     * Validate a swap route by comparing our on-chain quote against
+     * historical execution data from Herd.
+     *
+     * Answers: "Is our quote reasonable? What did recent swaps actually get?"
+     */
+    validateSwapRoute(tokenIn: string, tokenOut: string, amountIn: string, options?: {
+        blockchain?: HerdBlockchain;
+    }): Promise<SwapValidation>;
+    /**
+     * Validate fee claim expectations against historical on-chain data.
+     *
+     * Looks up recent claimFees txs on our FeeLocker, decodes actual gas
+     * costs and outcomes, and compares with our ClawnchReader estimate.
+     */
+    validateFeeClaim(tokenAddress: string, options?: {
+        blockchain?: HerdBlockchain;
+    }): Promise<FeeClaimValidation>;
+    /**
+     * Profile a counterparty wallet before interacting.
+     *
+     * Combines wallet overview, transaction history, deployed contracts,
+     * and derives a trust assessment.
+     */
+    profileCounterparty(address: string, options?: {
+        blockchain?: HerdBlockchain;
+    }): Promise<CounterpartyProfile>;
+    /**
+     * Validate a factory contract before deploying through it.
+     * Checks metadata, recent successful deploys, and source code.
+     */
+    validateDeployTarget(factoryAddress?: string, options?: {
+        blockchain?: HerdBlockchain;
+    }): Promise<{
+        factory: ContractProfile;
+        recentDeploys: number;
+        warnings: string[];
+        safe: boolean;
+    }>;
+    /**
+     * Get all bookmarks for the authenticated user.
+     */
+    getBookmarks(): Promise<Bookmark[]>;
+    /**
+     * Add or update a bookmark.
+     */
+    bookmark(objectType: BookmarkType, objectId: string, label?: string, blockchain?: HerdBlockchain): Promise<void>;
+    /**
+     * Remove a bookmark.
+     */
+    removeBookmark(objectType: BookmarkType, objectId: string, blockchain?: HerdBlockchain): Promise<void>;
+    /**
+     * Clear the in-memory cache.
+     */
+    clearCache(): void;
+    /**
+     * Call a Herd tool with retry and graceful error handling.
+     * Returns null instead of throwing on non-critical failures.
+     * Logs warnings on transient failures so callers can distinguish
+     * "no data" from "Herd unreachable".
+     */
+    private callToolSafe;
+    private buildContractProfile;
+    private buildTransactionProfile;
+    private buildWalletProfile;
+    private buildRelationships;
+    private buildTokenFlowReport;
+    private buildVersionDiff;
+    private getClawncherOverlay;
+    private getClawncherWalletOverlay;
+    private analyzeContractSecurity;
+    private parseTraces;
+    private annotateTransaction;
+    private extractHistoricalSwaps;
+    private analyzeSwapValidation;
+    private extractHistoricalClaims;
+    private analyzeFeeClaimValidation;
+    private extractDeployedContracts;
+    private assessCounterpartyRisk;
+    private calculateAge;
+    private parseBookmarks;
+}
+//# sourceMappingURL=herd.d.ts.map

package/dist/herd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"herd.d.ts","sourceRoot":"","sources":["../src/herd.ts"],"names":[],"mappings":"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"}