add more knowledge about the artist, news, onchain data

IkigaiLabsETH · Dec 20, 2024 · d0e7927 · d0e7927
1 parent 5e17b65
commit d0e7927
Show file tree

Hide file tree

Showing 4 changed files with 369 additions and 51 deletions.
diff --git a/packages/plugin-nft-collections/README.md b/packages/plugin-nft-collections/README.md
@@ -1,13 +1,39 @@
 # NFT Collections Plugin
 
-A powerful Eliza plugin that provides NFT collection data and interaction capabilities on Ethereum.
+A powerful Eliza plugin that provides deep insights into NFT collections, combining on-chain analytics, market data, artist information, and social metrics.
 
 ## Features
 
-- Get top NFT collections with floor prices and volume metrics
-- Fetch floor listings for specific collections
-- Execute NFT purchases with multi-step transaction paths
-- Smart NFT knowledge evaluation system
+### Collection Data
+
+- Comprehensive collection metadata and statistics
+- Artist profiles and background information
+- Real-time floor prices and volume metrics
+- Social media engagement tracking
+- Contract verification and standards
+
+### On-Chain Analytics
+
+- Holder distribution analysis
+- Whale tracking and monitoring
+- Trading volume and patterns
+- Liquidity depth analysis
+- Trait distribution and rarity scores
+
+### Market Intelligence
+
+- Price history and trends
+- Wash trading detection
+- Multi-marketplace activity tracking
+- Market sentiment analysis
+- Top gainers and losers tracking
+
+### News & Social
+
+- Curated collection news feed
+- Sentiment analysis on news
+- Community engagement metrics
+- Social media performance tracking
 
 ## Installation
 
@@ -28,66 +54,183 @@ const eliza = new Eliza({
 
 // Access NFT services
 const nftService = eliza.services.nft;
+
+// Get collection data with all analytics
+const collection = await nftService.getTopCollections({ limit: 1 });
+const analytics = await nftService.getCollectionAnalytics(
+    collection[0].address
+);
+const news = await nftService.getCollectionNews(collection[0].address, {
+    limit: 10,
+    minRelevance: 0.8,
+});
 ```
 
 ## API Reference
 
-### NFT Service Methods
+### Collection Methods
 
 #### `getTopCollections(options?: { limit?: number })`
 
-Fetches top NFT collections sorted by volume.
+Fetches top NFT collections with comprehensive data.
+
+Returns: `Promise<NFTCollection[]>`
 
 ```typescript
-const collections = await nftService.getTopCollections({ limit: 10 });
+interface NFTCollection {
+    id: string;
+    name: string;
+    address: string;
+    floorPrice: number;
+    volume24h: number;
+    imageUrl: string;
+    tokenCount: number;
+    artist: NFTArtist;
+    description: string;
+    launchDate: number;
+    category: string[];
+    onChainData: OnChainAnalytics;
+    marketActivity: MarketActivity;
+    news: CollectionNews[];
+    socialMetrics: {
+        twitterFollowers: number;
+        discordMembers: number;
+        telegramMembers: number;
+        sentiment24h: "positive" | "negative" | "neutral";
+    };
+    contractMetadata: {
+        standard: "ERC721" | "ERC1155";
+        hasSecondaryRoyalties: boolean;
+        royaltyBps: number;
+        verifiedContract: boolean;
+        implementedInterfaces: string[];
+    };
+}
 ```
 
-Returns: `Promise<NFTCollection[]>`
+#### `getCollectionAnalytics(address: string)`
 
-#### `getFloorListings(params: { collection: string, limit: number, sortBy?: "price" | "rarity" })`
+Fetches detailed on-chain analytics for a collection.
 
-Gets floor listings for a specific collection.
+Returns: `Promise<OnChainAnalytics>`
 
 ```typescript
-const listings = await nftService.getFloorListings({
-    collection: "0x...",
-    limit: 5,
-    sortBy: "price",
-});
+interface OnChainAnalytics {
+    holdersCount: number;
+    averageHoldingPeriod: number;
+    whaleHolders: Array<{
+        address: string;
+        tokenCount: number;
+        holdingSince: number;
+    }>;
+    transferVolume24h: number;
+    uniqueBuyers24h: number;
+    uniqueSellers24h: number;
+    liquidityDepth: Array<{
+        priceLevel: number;
+        tokenCount: number;
+    }>;
+    traitDistribution: Record<string, Record<string, number>>;
+    rarityScores: Record<string, number>;
+}
 ```
 
-Returns: `Promise<NFTListing[]>`
+#### `getMarketActivity(address: string, options?: { timeframe?: "24h" | "7d" | "30d", excludeWashTrading?: boolean })`
 
-#### `executeBuy(params: { listings: NFTListing[], taker: string, source?: string })`
+Fetches market activity with optional wash trading filtering.
 
-Executes NFT purchase transactions.
+Returns: `Promise<MarketActivity>`
 
 ```typescript
-const result = await nftService.executeBuy({
-  listings: [...],
-  taker: "0x..."
-});
+interface MarketActivity {
+    lastSales: Array<{
+        tokenId: string;
+        price: number;
+        timestamp: number;
+        buyer: string;
+        seller: string;
+        marketplace: string;
+    }>;
+    priceHistory: Array<{
+        timestamp: number;
+        floorPrice: number;
+        avgPrice: number;
+        maxPrice: number;
+    }>;
+    washTradingScore: number;
+    marketplaceDistribution: Record<string, number>;
+}
 ```
 
-Returns: `Promise<{ path: string, steps: Array<{ id: string, action: string, description: string, status: "complete" | "incomplete" }> }>`
+#### `getCollectionNews(address: string, options?: { limit?: number; minRelevance?: number })`
 
-## Types
+Fetches curated news for a collection with relevance filtering.
 
-### NFTCollection
+Returns: `Promise<CollectionNews[]>`
 
 ```typescript
-interface NFTCollection {
+interface CollectionNews {
+    id: string;
+    title: string;
+    source: string;
+    url: string;
+    timestamp: number;
+    sentiment: "positive" | "negative" | "neutral";
+    relevanceScore: number;
+}
+```
+
+#### `getArtistInfo(artistId: string)`
+
+Fetches detailed artist information.
+
+Returns: `Promise<NFTArtist>`
+
+```typescript
+interface NFTArtist {
     id: string;
     name: string;
-    address: string;
-    floorPrice: number;
-    volume24h: number;
-    imageUrl: string;
-    tokenCount: number;
+    bio: string;
+    socialLinks: {
+        twitter?: string;
+        instagram?: string;
+        website?: string;
+    };
+    previousCollections: string[];
+    collaborations: string[];
+}
+```
+
+### Market Methods
+
+#### `getMarketStats()`
+
+Fetches overall NFT market statistics.
+
+Returns: `Promise<NFTMarketStats>`
+
+```typescript
+interface NFTMarketStats {
+    totalVolume24h: number;
+    totalMarketCap: number;
+    activeTraders24h: number;
+    topGainers: Array<{
+        collection: string;
+        percentageChange: number;
+    }>;
+    topLosers: Array<{
+        collection: string;
+        percentageChange: number;
+    }>;
+    marketSentiment: "bullish" | "bearish" | "neutral";
 }
 ```
 
-### NFTListing
+#### `getFloorListings(params: { collection: string; limit: number; sortBy?: "price" | "rarity" })`
+
+Fetches floor listings with optional sorting.
+
+Returns: `Promise<NFTListing[]>`
 
 ```typescript
 interface NFTListing {
@@ -100,24 +243,40 @@ interface NFTListing {
 }
 ```
 
-### NFTKnowledge
+### Trading Methods
 
-```typescript
-interface NFTKnowledge {
-    mentionsCollection: boolean;
-    mentionsFloorPrice: boolean;
-    mentionsVolume: boolean;
-    mentionsRarity: boolean;
-}
-```
+#### `executeBuy(params: { listings: NFTListing[]; taker: string; source?: string })`
+
+Executes NFT purchase transactions.
+
+Returns: `Promise<{ path: string; steps: Array<{ id: string; action: string; description: string; status: "complete" | "incomplete" }> }>`
 
 ## Plugin Components
 
 The plugin consists of:
 
-- Actions: `getCollections` and `sweepFloor`
-- Providers: `nftCollectionProvider`
-- Evaluators: `nftKnowledgeEvaluator`
+- **Actions**: `getCollections` and `sweepFloor` for collection data and trading
+- **Providers**: `nftCollectionProvider` for data aggregation
+- **Evaluators**: `nftKnowledgeEvaluator` for context-aware responses
+
+## Best Practices
+
+1. **Data Freshness**
+
+    - Always check timestamps on market data
+    - Use real-time floor prices for trading
+    - Consider wash trading scores for volume analysis
+
+2. **Analytics Usage**
+
+    - Filter out wash trading for accurate market analysis
+    - Use relevance scores for news filtering
+    - Consider holding periods for whale analysis
+
+3. **Performance**
+    - Cache collection metadata when possible
+    - Stream large datasets for trait analysis
+    - Batch on-chain queries for efficiency
 
 ## License
 

diff --git a/packages/plugin-nft-collections/src/evaluators/nft-knowledge.ts b/packages/plugin-nft-collections/src/evaluators/nft-knowledge.ts
@@ -4,15 +4,24 @@ import { NFTKnowledge } from "../types";
 export const nftKnowledgeEvaluator: Evaluator = {
     name: "nft-collection-evaluator",
     description: "Evaluates NFT-related content in messages",
-    similes: ["nft-evaluator", "nft-knowledge", "market-analysis"],
+    similes: [
+        "nft-evaluator",
+        "nft-knowledge",
+        "market-analysis",
+        "artist-info",
+    ],
     alwaysRun: false,
     validate: async (runtime: IAgentRuntime, message: Memory) => {
         const content = message.content.text.toLowerCase();
         return (
             content.includes("nft") ||
             content.includes("collection") ||
             content.includes("market") ||
-            content.includes("trading")
+            content.includes("trading") ||
+            content.includes("artist") ||
+            content.includes("contract") ||
+            content.includes("news") ||
+            content.includes("onchain")
         );
     },
     handler: async (runtime: IAgentRuntime, message: Memory, state: State) => {
@@ -45,6 +54,30 @@ export const nftKnowledgeEvaluator: Evaluator = {
                 content.includes("market cap") ||
                 content.includes("marketcap") ||
                 content.includes("valuation"),
+            mentionsArtist:
+                content.includes("artist") ||
+                content.includes("creator") ||
+                content.includes("founder"),
+            mentionsOnChainData:
+                content.includes("onchain") ||
+                content.includes("blockchain") ||
+                content.includes("contract") ||
+                content.includes("holder") ||
+                content.includes("transfer"),
+            mentionsNews:
+                content.includes("news") ||
+                content.includes("announcement") ||
+                content.includes("update"),
+            mentionsSocial:
+                content.includes("twitter") ||
+                content.includes("discord") ||
+                content.includes("telegram") ||
+                content.includes("social"),
+            mentionsContract:
+                content.includes("contract") ||
+                content.includes("royalty") ||
+                content.includes("standard") ||
+                content.includes("erc"),
         };
 
         return {
@@ -54,21 +87,23 @@ export const nftKnowledgeEvaluator: Evaluator = {
     },
     examples: [
         {
-            context: "Evaluating NFT market trends",
+            context: "Evaluating comprehensive NFT collection data",
             messages: [
                 {
                     user: "{{user1}}",
-                    content: { text: "How's the NFT market sentiment today?" },
+                    content: {
+                        text: "Tell me about the artist and on-chain stats for this collection",
+                    },
                 },
                 {
                     user: "{{user2}}",
                     content: {
-                        text: "Let me check the market trends and whale activity.",
+                        text: "I'll analyze the creator's background and blockchain metrics.",
                     },
                 },
             ],
             outcome:
-                "The message contains market-related content and should be evaluated.",
+                "The message requests artist and on-chain information and should be evaluated.",
         },
     ],
 };