From d0e79277d8b10211499cd97ab35da25bace91041 Mon Sep 17 00:00:00 2001 From: IKIGAI LABS XYZ <128307722+IkigaiLabsETH@users.noreply.github.com> Date: Fri, 20 Dec 2024 11:57:50 +0100 Subject: [PATCH] add more knowledge about the artist, news, onchain data --- packages/plugin-nft-collections/README.md | 249 ++++++++++++++---- .../src/evaluators/nft-knowledge.ts | 47 +++- packages/plugin-nft-collections/src/types.ts | 99 +++++++ .../src/utils/response-enhancer.ts | 25 ++ 4 files changed, 369 insertions(+), 51 deletions(-) diff --git a/packages/plugin-nft-collections/README.md b/packages/plugin-nft-collections/README.md index f4c0ba4a147..513f9b3534c 100644 --- 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` ```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` +#### `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` ```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>; + rarityScores: Record; +} ``` -Returns: `Promise` +#### `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` ```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; +} ``` -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` ```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` + +```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` + +```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` ```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 index 5adeb000bf6..0ec605bb9fa 100644 --- a/packages/plugin-nft-collections/src/evaluators/nft-knowledge.ts +++ b/packages/plugin-nft-collections/src/evaluators/nft-knowledge.ts @@ -4,7 +4,12 @@ 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(); @@ -12,7 +17,11 @@ export const nftKnowledgeEvaluator: Evaluator = { 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.", }, ], }; diff --git a/packages/plugin-nft-collections/src/types.ts b/packages/plugin-nft-collections/src/types.ts index 8ec85250b56..0cc3ecb1cba 100644 --- a/packages/plugin-nft-collections/src/types.ts +++ b/packages/plugin-nft-collections/src/types.ts @@ -6,6 +6,67 @@ declare module "@ai16z/eliza" { } } +export interface NFTArtist { + id: string; + name: string; + bio: string; + socialLinks: { + twitter?: string; + instagram?: string; + website?: string; + }; + previousCollections: string[]; + collaborations: string[]; +} + +export 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>; + rarityScores: Record; +} + +export 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; +} + +export interface CollectionNews { + id: string; + title: string; + source: string; + url: string; + timestamp: number; + sentiment: "positive" | "negative" | "neutral"; + relevanceScore: number; +} + export interface NFTCollection { id: string; name: string; @@ -14,6 +75,26 @@ export interface NFTCollection { 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[]; + }; } export interface NFTListing { @@ -49,6 +130,11 @@ export interface NFTKnowledge { mentionsTraders: boolean; mentionsSentiment: boolean; mentionsMarketCap: boolean; + mentionsArtist: boolean; + mentionsOnChainData: boolean; + mentionsNews: boolean; + mentionsSocial: boolean; + mentionsContract: boolean; } export interface NFTService { @@ -72,4 +158,17 @@ export interface NFTService { }>; }>; getMarketStats(): Promise; + getCollectionAnalytics(address: string): Promise; + getCollectionNews( + address: string, + options?: { limit?: number; minRelevance?: number } + ): Promise; + getArtistInfo(artistId: string): Promise; + getMarketActivity( + address: string, + options?: { + timeframe?: "24h" | "7d" | "30d"; + excludeWashTrading?: boolean; + } + ): Promise; } diff --git a/packages/plugin-nft-collections/src/utils/response-enhancer.ts b/packages/plugin-nft-collections/src/utils/response-enhancer.ts index aa50d76033f..2fe93ee2ca9 100644 --- a/packages/plugin-nft-collections/src/utils/response-enhancer.ts +++ b/packages/plugin-nft-collections/src/utils/response-enhancer.ts @@ -44,5 +44,30 @@ export function enhanceResponse(response: string, state: State): string { " I can show you market cap rankings and valuation metrics."; } + if (nftKnowledge?.mentionsArtist) { + response += + " I can provide detailed information about the artist, their background, and previous collections."; + } + + if (nftKnowledge?.mentionsOnChainData) { + response += + " I can show you detailed on-chain analytics including holder distribution and trading patterns."; + } + + if (nftKnowledge?.mentionsNews) { + response += + " I can share the latest news and announcements about this collection."; + } + + if (nftKnowledge?.mentionsSocial) { + response += + " I can provide social media metrics and community engagement data."; + } + + if (nftKnowledge?.mentionsContract) { + response += + " I can show you contract details including standards, royalties, and verification status."; + } + return response; }