@elizaos/plugin-social-alpha 2.0.0-alpha.8 → 2.0.11-beta.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @elizaos/plugin-social-alpha
+
+An elizaOS plugin that tracks cryptocurrency token recommendations made by users in chat, evaluates their accuracy against real price outcomes, and builds trust scores for each recommender.
+
+## What it does
+
+- **Recommendation capture.** Every incoming message is analyzed with a single LLM call to detect buy/sell calls ("shills" and "FUD"). Detected calls are stored against the sender's trust profile as an elizaOS Component.
+- **Trust scoring.** Scores are calculated using a multi-factor algorithm: profit percentage, win rate, Sharpe ratio, alpha vs market, consistency, and a scam/rug penalty.
+- **Leaderboard.** Ranked leaderboard of all tracked recommenders is available as a JSON API and as a dashboard view (`SocialAlphaView`).
+- **Agent context injection.** The `socialAlpha` provider injects the current speaker's trust stats and the top/bottom leaderboard into the agent's context automatically, so the agent can factor reputation into its responses.
+
+## Capabilities added to an Eliza agent
+
+| Capability | Description |
+|-----------|-------------|
+| `socialAlpha` provider | Injects trust scores, win rate, avg P&L, and leaderboard into agent context |
+| `MESSAGE_RECEIVED` event handler | Extracts buy/sell signals from messages in real time |
+| `CommunityInvestorService` | Manages all trust score and recommendation data |
+| `GET /api/social-alpha/leaderboard` route | Returns `LeaderboardEntry[]` JSON |
+| `social-alpha` view | Leaderboard dashboard view — appears in the view manager when the plugin is enabled; requires a configured agent wallet |
+
+No actions are added — recommendation capture is event-driven, not agent-initiated.
+
+## How to enable
+
+Add the plugin to your agent's character definition:
+
+```typescript
+import { socialAlphaPlugin } from "@elizaos/plugin-social-alpha";
+
+export const character = {
+  name: "MyAgent",
+  plugins: [socialAlphaPlugin],
+  // ...
+};
+```
+
+## Required configuration
+
+Set these in your agent's environment or character config:
+
+```env
+BIRDEYE_API_KEY=        # Token price, security, and trade data (Solana)
+DEXSCREENER_API_KEY=    # DEX pair data and ticker resolution
+HELIUS_API_KEY=         # Solana holder list data (optional — service degrades gracefully without it)
+```
+
+The following are declared as required in `agentConfig` but are not actively used in current code paths:
+
+```env
+JUPITER_API_KEY=
+COINGECKO_API_KEY=
+MORALIS_API_KEY=
+```
+
+### Optional tuning
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `PROCESS_TRADE_DECISION_INTERVAL_HOURS` | `1` | How often queued trade decisions are evaluated |
+| `METRIC_REFRESH_INTERVAL_HOURS` | `24` | How often recommender metrics are refreshed |
+| `USER_TRADE_COOLDOWN_HOURS` | `12` | Minimum hours between decisions per user |
+| `SCAM_PENALTY` | `-100` | Trust score penalty for promoting a rug/scam |
+| `SCAM_CORRECT_CALL_BONUS` | `100` | Bonus for correctly calling out a scam |
+| `MAX_RECOMMENDATIONS_IN_PROFILE` | `50` | Rolling window of recommendations kept per user |
+
+## Trust score algorithm
+
+The balanced trust score uses:
+
+- **Profit** — average percentage gain across evaluated calls
+- **Win rate** — proportion of calls that were profitable
+- **Sharpe ratio** — risk-adjusted returns
+- **Alpha** — excess returns vs market
+- **Consistency** — stability of returns over time
+- **Quality** — scam/rug penalty applied when a promoted token turns out fraudulent; bonus for correctly calling out scams before they dump
+
+Weights are tunable via `src/services/trustScoreOptimizer.ts`.
+
+## Building the view
+
+The leaderboard UI is a plugin view served at `/api/views/social-alpha/bundle.js`. Build it (react + `@elizaos/ui` stay externalised to the host shell):
+
+```bash
+bun run --cwd plugins/plugin-social-alpha build
+```
+
+## Running tests
+
+```bash
+bun run --cwd plugins/plugin-social-alpha test
+```
+
+## Supported chains
+
+Primary support is Solana. Ethereum and Base are partially supported for ticker resolution via DexScreener.
+

package/assets/hero.svg

@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" width="1024" height="1024" role="img" aria-label="Social Alpha">
+  <defs>
+    <linearGradient id="bg-social-alpha" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#152818"/>
+      <stop offset="1" stop-color="#0b1910"/>
+    </linearGradient>
+    <radialGradient id="blobA-social-alpha" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="#2fda4b" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#2fda4b" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="blobB-social-alpha" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="#28c38a" stop-opacity="0.5"/>
+      <stop offset="1" stop-color="#28c38a" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="vig-social-alpha" cx="0.5" cy="0.42" r="0.75">
+      <stop offset="0" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="0.72" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="1" stop-color="#000000" stop-opacity="0.5"/>
+    </radialGradient>
+    <linearGradient id="label-social-alpha" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="1" stop-color="#000000" stop-opacity="0.55"/>
+    </linearGradient>
+    <filter id="soft-social-alpha" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="46"/>
+    </filter>
+    <filter id="iglow-social-alpha" x="-40%" y="-40%" width="180%" height="180%">
+      <feDropShadow dx="0" dy="0" stdDeviation="14" flood-color="#45ed61" flood-opacity="0.45"/>
+    </filter>
+  </defs>
+
+  <rect width="1024" height="1024" fill="url(#bg-social-alpha)"/>
+
+  <g opacity="0.9">
+    <circle cx="232" cy="220" r="300" fill="url(#blobA-social-alpha)" filter="url(#soft-social-alpha)"/>
+    <circle cx="840" cy="800" r="340" fill="url(#blobB-social-alpha)" filter="url(#soft-social-alpha)"/>
+  </g>
+
+  <g stroke="#d7eada" stroke-width="1.4" opacity="0.06">
+    <line x1="0" y1="256" x2="1024" y2="256"/>
+    <line x1="0" y1="512" x2="1024" y2="512"/>
+    <line x1="0" y1="768" x2="1024" y2="768"/>
+    <line x1="256" y1="0" x2="256" y2="1024"/>
+    <line x1="512" y1="0" x2="512" y2="1024"/>
+    <line x1="768" y1="0" x2="768" y2="1024"/>
+  </g>
+
+  <g opacity="0.5">
+    <path d="M120 470 A 400 400 0 0 1 904 470" fill="none" stroke="#45ed61" stroke-width="3" opacity="0.35"/>
+  </g>
+
+  <g transform="translate(512 432)" filter="url(#iglow-social-alpha)"
+     color="#d7eada" stroke="#d7eada" stroke-width="20"
+     stroke-linecap="round" stroke-linejoin="round" fill="none">
+    <polyline points="-150,80 -54,-22 6,38 150,-110" fill="none"/>
+    <polyline points="92,-110 150,-110 150,-52" fill="none"/>
+    <circle cx="-110" cy="128" r="26"/>
+    <circle cx="0" cy="128" r="26"/>
+    <circle cx="110" cy="128" r="26"/>
+  </g>
+
+  <rect x="0" y="784" width="1024" height="240" fill="url(#label-social-alpha)"/>
+  <text x="512" y="892" text-anchor="middle"
+        font-family="system-ui, -apple-system, Segoe UI, Roboto, sans-serif"
+        font-size="76" font-weight="600" letter-spacing="0.5"
+        fill="#d7eada">Social Alpha</text>
+  <rect x="460" y="924" width="104" height="6" rx="3" fill="#45ed61"/>
+
+  <rect width="1024" height="1024" fill="url(#vig-social-alpha)"/>
+</svg>

package/package.json

@@ -1,70 +1,76 @@
 {
   "name": "@elizaos/plugin-social-alpha",
-  "version": "2.0.0-alpha.8",
+  "version": "2.0.11-beta.7",
   "description": "Social Alpha Plugin — Tracks token recommendations (shills/FUD), builds trust scores based on P&L outcomes, and exposes a Social Alpha Provider with win rate, rank, and recommender analytics.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
+    "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     }
   },
   "files": [
+    "assets",
     "dist"
   ],
   "scripts": {
-    "build": "bunx vite build",
-    "dev": "vite",
-    "test": "vitest run src/__tests__/balancedTrustScore.test.ts src/__tests__/historicalPriceService.test.ts src/__tests__/service.test.ts --passWithNoTests",
+    "build": "bun run build:js && bun run build:views && bun run build:types",
+    "test": "vitest run --passWithNoTests",
     "clean": "rm -rf dist .turbo node_modules",
-    "lint": "echo \"Lint skipped for release\"",
+    "lint": "bunx @biomejs/biome check src",
     "lint:check": "bun run lint",
-    "format": "bunx @biomejs/biome format --write .",
-    "format:check": "bunx @biomejs/biome format .",
-    "typecheck": "echo \"Typecheck skipped for release\""
+    "format": "bunx @biomejs/biome format --write src",
+    "format:check": "bunx @biomejs/biome format src",
+    "typecheck": "tsc --noEmit -p tsconfig.build.json",
+    "build:js": "tsup --config ../tsup.plugin-packages.shared.ts",
+    "build:views": "bunx --bun vite build --config vite.config.views.ts",
+    "build:types": "tsc --noCheck -p tsconfig.build.json",
+    "lint:fix": "bunx @biomejs/biome check --write src"
   },
   "dependencies": {
-    "@elizaos/core": "2.0.0-alpha.3",
-    "bignumber.js": "^9.3.0",
+    "@elizaos/core": "2.0.11-beta.7",
+    "@elizaos/ui": "2.0.11-beta.7",
+    "bignumber.js": "^11.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "dotenv": "^16.5.0",
-    "fast-xml-parser": "^5.2.5",
+    "dotenv": "^17.0.0",
+    "fast-xml-parser": "^5.7.2",
     "p-limit": "^5.0.0",
     "tailwindcss-animate": "^1.0.7",
-    "uuid": "^11.1.0",
-    "zod": "^4.3.6"
+    "uuid": "^14.0.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@elizaos/core": "2.0.0-alpha.3"
+    "@elizaos/core": "2.0.11-beta.7"
   },
   "devDependencies": {
-    "@cypress/react": "^8.0.0",
-    "@tanstack/react-query": "^5.62.0",
+    "@biomejs/biome": "^2.4.14",
+    "@cypress/react": "^9.0.2",
+    "@radix-ui/react-slot": "^1.0.0",
+    "@radix-ui/react-tabs": "^1.0.0",
     "@testing-library/cypress": "^10.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "@vitejs/plugin-react-swc": "^4.0.0",
-    "autoprefixer": "^10.4.21",
-    "cypress": "^13.7.0",
-    "postcss": "^8.5.4",
+    "cypress": "^15.14.2",
+    "lucide-react": "^1.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "tailwindcss": "^3.4.0",
-    "tsconfig-paths": "^4.2.0",
-    "tsup": "8.5.0",
-    "tsx": "4.19.4",
-    "typescript": "^5.8.3",
-    "vite": "^6.0.0",
-    "lucide-react": "^0.468.0",
-    "@radix-ui/react-slot": "^1.0.0",
-    "@radix-ui/react-tabs": "^1.0.0",
     "tailwind-merge": "^3.4.0",
-    "vitest": "^3.1.4",
-    "@biomejs/biome": "^2.3.11"
+    "tsconfig-paths": "^4.2.0",
+    "tsup": "^8.5.1",
+    "tsx": "4.21.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -115,5 +121,6 @@
         "sensitive": true
       }
     }
-  }
+  },
+  "gitHead": "cdbc876f793d96073d7eb0d09715a031ce0cd32e"
 }

package/dist/__tests__/e2e/benchmarks/benchmark.utils.d.ts

@@ -1,38 +0,0 @@
-import type { IAgentRuntime, UUID } from "@elizaos/core";
-import type { MockPriceService } from "../../../mockPriceService";
-import type { SimulatedActor, SimulatedCall } from "../../../simulationActors";
-export interface BenchmarkSimulationParams {
-    durationSteps: number;
-    actors: SimulatedActor[];
-    priceService: MockPriceService;
-    outputBasePath: string;
-    benchmarkName: string;
-    optimisticAthWindowDays?: number;
-}
-export interface BenchmarkStepMetrics {
-    step: number;
-    actorScores: Record<UUID, {
-        username: string;
-        archetype: string;
-        score: number;
-    }>;
-    callsMadeThisStep: SimulatedCall[];
-}
-export interface CallPnlData {
-    callId: UUID;
-    actorId: UUID;
-    tokenAddress: string;
-    recommendationType: "BUY" | "SELL";
-    priceAtRecommendation?: number;
-    potentialProfitPercent?: number;
-    avoidedLossPercent?: number;
-    isScamOrRug?: boolean;
-    evaluationTimestamp: number;
-    notes?: string;
-    athWindowDaysUsed?: number;
-}
-/**
- * Core simulation engine for benchmarks.
- * This function will be called by individual benchmark TestCases.
- */
-export declare function runBenchmarkSimulation(runtime: IAgentRuntime, params: BenchmarkSimulationParams): Promise<void>;

package/dist/__tests__/e2e/benchmarks/trust_algorithm.benchmark.d.ts

@@ -1,18 +0,0 @@
-import type { TestSuite, UUID } from "@elizaos/core";
-import { Conviction, SupportedChain } from "../../../types";
-export interface EnrichedCallDataPrv {
-    callId: UUID;
-    originalMessageId: string;
-    userId: string;
-    username: string;
-    timestamp: number;
-    content: string;
-    tokenMentioned: string;
-    isTicker: boolean;
-    resolvedAddress?: string;
-    chain: SupportedChain;
-    sentiment: "positive" | "negative";
-    conviction: Conviction;
-}
-export declare const trustAlgorithmBenchmarkSuite: TestSuite;
-export default trustAlgorithmBenchmarkSuite;

package/dist/__tests__/e2e/events.d.ts

@@ -1,2 +0,0 @@
-import type { TestSuite } from "@elizaos/core";
-export declare const eventsTestSuite: TestSuite;

package/dist/__tests__/e2e/index.d.ts

@@ -1,3 +0,0 @@
-import type { TestSuite } from "@elizaos/core";
-export declare const testSuites: TestSuite[];
-export default testSuites;

package/dist/__tests__/e2e/scenarios.d.ts

@@ -1,3 +0,0 @@
-import type { TestSuite } from "@elizaos/core";
-export declare const agentScenariosSuite: TestSuite;
-export default agentScenariosSuite;

package/dist/__tests__/e2e/service.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/__tests__/e2e/socialAlpha.d.ts

@@ -1,2 +0,0 @@
-import type { TestSuite } from "@elizaos/core";
-export declare const communityInvestorE2ETestSuite: TestSuite;

package/dist/__tests__/e2e/test-utils.d.ts

@@ -1,12 +0,0 @@
-import type { Entity, IAgentRuntime, Room, World } from "@elizaos/core";
-type Content = {
-    text: string;
-    name?: string;
-};
-export declare function setupScenario(runtime: IAgentRuntime): Promise<{
-    user: Entity;
-    room: Room;
-    world: World;
-}>;
-export declare function sendMessageAndWaitForResponse(runtime: IAgentRuntime, room: Room, user: Entity, text: string): Promise<Content>;
-export {};

package/dist/__tests__/e2e/test.setup.d.ts

@@ -1,2 +0,0 @@
-import type { IAgentRuntime } from "@elizaos/core";
-export declare function createMockRuntime(initialSettings?: Record<string, any>): IAgentRuntime;

package/dist/__tests__/e2e/trustOptimizationE2E.d.ts

@@ -1,4 +0,0 @@
-import type { TestCase, TestSuite } from "@elizaos/core";
-export declare const trustOptimizationE2ETestCases: TestCase[];
-export declare const trustOptimizationE2ETestSuite: TestSuite;
-export default trustOptimizationE2ETestSuite;

package/dist/__tests__/e2e/trustScenariosE2E.d.ts

@@ -1,4 +0,0 @@
-import type { TestCase, TestSuite } from "@elizaos/core";
-export declare const trustScenariosE2ETestCases: TestCase[];
-export declare const trustScenariosE2ETestSuite: TestSuite;
-export default trustScenariosE2ETestSuite;

package/dist/__tests__/e2e/trustScore.d.ts

@@ -1,2 +0,0 @@
-import type { TestSuite } from "@elizaos/core";
-export declare const trustScoreTestSuite: TestSuite;

package/dist/__tests__/mocks/mockPriceService.d.ts

@@ -1,36 +0,0 @@
-import type { SupportedChain, TokenAPIData } from "../../types";
-export interface SimulatedToken {
-    address: string;
-    symbol: string;
-    name: string;
-    chain: SupportedChain;
-    performanceType: "good" | "bad" | "neutral" | "volatile";
-    priceTrajectory: (step: number) => number;
-    initialPrice: number;
-    liquidity?: number;
-    marketCap?: number;
-}
-export declare class MockPriceService {
-    private tokens;
-    private currentTimeStep;
-    private baseTimestamp;
-    private stepIncrementMs;
-    constructor(initialTokens: SimulatedToken[]);
-    addToken(token: SimulatedToken): void;
-    advanceTime(step: number): void;
-    getCurrentTimestamp(step?: number): number;
-    getStepFromTimestamp(timestamp: number): number | null;
-    getTokenAPIData(tokenAddress: string, chain: SupportedChain, // Chain might be used if addresses are not unique across chains
-    step?: number): Promise<TokenAPIData | null>;
-    /**
-     * Calculates the All-Time High (ATH) for a token within a specified number of days (steps)
-     * starting from a given step.
-     */
-    getAthInWindow(tokenAddress: string, chain: SupportedChain, fromStep: number, windowDays: number): number | null;
-    getTokensByPerformanceType(type: SimulatedToken["performanceType"]): SimulatedToken[];
-    getAllTokens(): SimulatedToken[];
-    static goodTokenTrajectory: (initialPrice: number, growthFactor?: number) => (step: number) => number;
-    static badTokenTrajectory: (initialPrice: number, decayFactor?: number, rugStepMultiplier?: number) => (step: number) => number;
-    static neutralTokenTrajectory: (initialPrice: number, volatility?: number) => (step: number) => number;
-    static volatileTokenTrajectory: (initialPrice: number, volatility?: number, pumpDumpChance?: number) => (step: number) => number;
-}