Skip to content

grkhmz23/Trailblazer

BranchesTags

Repository files navigation

Trailblazer — Solana Narrative Hunter

AI-powered fortnightly narrative detection for the Solana ecosystem. An autonomous agent that ingests developer, social, and market signals — runs deep investigations with explainable tool traces — clusters findings into emerging narratives — and generates actionable build ideas with downloadable Action Packs.

Live: trailblazeragent.fun

Data Sources

Source What It Monitors Access Method
GitHub Dev Activity Commits, stars, contributors, releases per repo GitHub API v3 (47 repos)
Twitter / X KOLs Posts from 90 Solana ecosystem KOLs across 6 tiers Nitter RSS proxies (opt-in)
News / RSS 4 feeds: Solana blog, The Block, CoinDesk, Blockworks Public RSS/Atom feeds

Twitter/X KOL Tracking (90 Accounts)

The tool monitors 90 Solana ecosystem Key Opinion Leaders across six tiers:

  • Core Team: Toly (Solana co-founder), Raj Gokal, Solana Labs, Solana Foundation
  • Protocol Founders: Mert, Meow (Jupiter), Cindy Leow (Drift), Lucas Bruder (Jito), Yutaro (Orca)
  • VC & Research: Multicoin Capital, a16z Crypto, Paradigm, Pantera, Dragonfly, Electric Capital, Messari
  • Dev Advocates: Superteam, Solana Devs, Lightspeed Podcast, Armani Ferrante
  • Mega Influencers: Elon Musk, CZ, Vitalik, Brian Armstrong, Balaji
  • CT Alpha: Ansem, Inversebrah, ZachXBT, Ash Crypto, SolBigBrain, CryptoCobain

Tweets are filtered for Solana relevance using 80+ keywords, classified by type (announcement, alpha, analysis, hype, pain_point), and merged with RSS signals. KOL mentions are weighted 3x higher than RSS mentions.

Note: Twitter/X ingestion uses Nitter RSS proxies which may be unreliable. If no working Nitter instance is available, the pipeline continues with RSS/blog sources only. For production use, consider integrating a paid Twitter API or SocialData.tools.

Tracked Protocols (47)

DeFi: Jupiter, Jupiter Perpetuals, Drift, Raydium, Orca, Phoenix, Marginfi, Kamino, Zeta Markets, Flash Trade, Meteora, Ondo Finance, DFlow LST: Marinade Finance, Jito, Sanctum, BlazeStake Infrastructure: Light Protocol, Squads, Clockwork, Switchboard, Backpack, Phantom, Solana Mobile Oracle: Pyth Network NFT: Tensor, Metaplex, Magic Eden Bridge: Wormhole DePIN: Helium, Render Network, Hivemapper Memecoin Infra: Bonk, Dogwifhat, Moonshot, Pump.fun AI: Robot AI Payments: Sphere Pay, PYUSD Social: Dialect, Access Protocol Gaming: Star Atlas, Genopets DAO: Realms, Meta DAO, Parcl

How Signals Are Detected and Ranked

1. Ingestion

Every fortnight, live data is fetched from all sources. For each of 47 tracked protocols, we collect:

  • Dev: commit velocity, star growth, new contributors, releases
  • Social: KOL tweet mentions (90 accounts), RSS article mentions (4 feeds), engagement scores
  • Market: TVL velocity and baseline comparisons where available

Ingestion also computes per-source reliability and presence quality scores. If configured thresholds fail, the run aborts early to avoid publishing low-quality reports. The gate supports both global thresholds and per-source overrides, plus controlled degraded-source tolerance.

2. Scoring (Momentum + Novelty - Quality Penalty)

Each metric is converted to a z-score: z = (current - baseline) / max(baseline, 0.001)

Momentum = weighted sum across all z-scores:

  • Dev signals: 50% weight (commits, stars, new_contributors, releases)
  • Social signals: 35% weight (mentions, unique_authors, engagement)
  • TVL / market signals: 15% weight (tvl_velocity)

Novelty bonus: 1.3x for brand new protocols, decaying linearly to 1.0x over 60 days.

Quality penalties:

  • Hype-only social (>80% hype snippets): 0.7x — filters noise

Total Score = momentum * novelty * quality

3. Clustering

Top 20 candidates are clustered using agglomerative clustering with cosine similarity on text embeddings. Average linkage, 0.4 threshold, max 10 clusters.

4. AI-Powered Labeling & Idea Generation

Kimi K2 (Moonshot AI) analyzes each cluster to generate:

  • Narrative title and one-paragraph summary
  • 3-5 concrete build ideas with pitch, target user, MVP scope, and rationale
  • Downloadable Action Packs (spec.md, tech.md, milestones.md, deps.json)

5. Saturation Check

Each idea is compared against 150+ existing Solana projects via cosine similarity to flag market saturation (low / medium / high).

Quick Start (Local)

Prerequisites

  • Node.js >= 20
  • pnpm >= 9
  • PostgreSQL database (e.g. Neon free tier)

Setup

git clone https://github.com/grkhmz23/Trailblazer.git
cd Trailblazer
pnpm install

# Copy env template and fill in your values
cp .env.example apps/web/.env

# Push schema to your database
pnpm --filter web prisma:push
pnpm --filter web prisma:generate

# Launch dashboard
pnpm dev
# -> Open http://localhost:3000

Run the Pipeline Locally

# Full pipeline run (requires MOONSHOT_API_KEY)
pnpm --filter web pipeline:run

# Dry run with demo data (no API keys needed)
pnpm --filter web pipeline:run:dry

# Custom date range
pnpm --filter web pipeline:run -- --start 2025-01-01 --end 2025-01-14

Run Daily Twitter Token Ideas (Alpha Discovery)

# Generates exactly 3 daily token ideas from Twitter-only narratives
# Requires: DATABASE_URL + SOCIALDATA_API_KEY (and an LLM key unless DEMO fallback)
pnpm --filter web daily:token-ideas

# Read latest result
curl http://localhost:3000/api/token-ideas/daily

Self-Hosting Guide

Want to run Trailblazer for your own ecosystem monitoring? Here's the full setup:

1. Provision Database

Use Neon (recommended) or any PostgreSQL provider.

2. Environment Variables

Variable Required Description
DATABASE_URL Yes PostgreSQL connection string
ADMIN_TOKEN Yes Secret for admin API (set a strong random value)
MOONSHOT_API_KEY Preferred for live mode Moonshot AI API key
MOONSHOT_MODEL No Default: kimi-k2-thinking-turbo
OPENAI_API_KEY No Optional LLM fallback provider (OpenAI-compatible)
OPENAI_MODEL No OpenAI fallback model (default gpt-4.1-mini)
OPENROUTER_API_KEY No Optional LLM fallback provider (OpenRouter)
OPENROUTER_MODEL No OpenRouter fallback model (default openai/gpt-4.1-mini)
LLM_PROVIDER_ORDER No Fallback order, comma-separated (default moonshot,openai,openrouter)
LLM_FAILOVER_PERSIST_STATE No Persist LLM provider failover state in DB (default true)
LLM_FAILOVER_STATE_SYNC_MS No Refresh interval for DB failover state sync (default 60000)
GITHUB_TOKEN No GitHub PAT for higher API rate limits
SOCIALDATA_API_KEY No SocialData.tools API key for Twitter/X ingestion
PIPELINE_LOCK_NAME No DB lock key used to prevent overlapping pipeline runs
PIPELINE_LOCK_TTL_MS No Lock lease duration in ms (default 5400000)
PIPELINE_ALERT_ENABLED No Enable pipeline failure webhook alerts (default false)
PIPELINE_ALERT_WEBHOOK_URLS No Comma-separated webhook URLs for failure notifications
PIPELINE_ALERT_FORMAT No Alert payload format: generic
PIPELINE_ALERT_TIMEOUT_MS No Webhook request timeout in ms (default 10000)
PIPELINE_ALERT_RETRY_ATTEMPTS No Retry attempts per webhook send (default 3)
INGEST_QUALITY_ENFORCE No Enforce ingestion quality gate before scoring (default true)
INGEST_QUALITY_MIN_SOURCE_SCORE No Minimum per-source quality score (default 0.45)
INGEST_QUALITY_MIN_HEALTHY_SOURCES No Minimum number of healthy enabled sources (default 2)
INGEST_QUALITY_MIN_AGGREGATE_SCORE No Minimum aggregate ingest quality score (default 0.55)
INGEST_QUALITY_MAX_DEGRADED_SOURCES No Max enabled sources allowed below threshold (default 1)
INGEST_QUALITY_SOURCE_MIN_SCORES No Optional per-source min score overrides (helius:0.5,github:0.5,...)
NEXT_PUBLIC_SITE_URL No Your deployment URL (for OG images)
DEMO_MODE No true to use fixture data instead of live APIs

3. Deploy to Vercel

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

# Push database schema
DATABASE_URL="your-neon-url" pnpm --filter web prisma:push

4. Trigger a Pipeline Run

# Via admin API
curl -X POST https://your-app.vercel.app/api/admin/run-fortnight \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

# Or use GitHub Actions (runs automatically via pipeline.yml)

5. Scheduled Reports

The GitHub Actions workflow (.github/workflows/pipeline.yml) can be triggered manually via workflow_dispatch with optional date range parameters. Set up a cron schedule by adding:

on:
  schedule:
    - cron: '0 6 1,15 * *'  # 1st and 15th of each month

6. Customizing Protocols

Edit apps/web/src/lib/pipeline/protocols.ts to add/remove tracked protocols. Each entry needs:

  • key: Unique identifier
  • label: Display name
  • kind: Category (defi, lst, infra, etc.)
  • programIds: Solana program addresses (for onchain data)
  • github: GitHub org/repo (for dev activity)

7. Customizing KOLs

Edit apps/web/src/lib/pipeline/ingestors/twitter.ts to add/remove tracked Twitter accounts. Each entry needs:

  • handle: Twitter username (without @)
  • label: Display name
  • category: One of: core_team, protocol_founder, vc_research, dev_advocate, mega_influencer, ct_alpha

Architecture

Trailblazer/
+-- apps/web/                    # Next.js 14 dashboard + API routes
|   +-- src/app/                 # Pages: /, /reports, /narratives/[id], /explore, /methodology
|   +-- src/components/          # Bento grid UI with glassmorphism
|   +-- src/lib/
|   |   +-- config.ts            # Typed config loader
|   |   +-- prisma.ts            # Prisma client singleton
|   |   +-- report-health.ts     # Runtime/failure telemetry parser for reports
|   |   +-- rate-limit.ts        # In-memory API rate limiter
|   |   +-- llm/
|   |   |   +-- moonshot.ts      # Moonshot Kimi K2 integration (OpenAI-compatible)
|   |   |   +-- provider-failover-store.ts # DB-backed provider failover persistence
|   |   |   +-- schemas.ts       # Zod schemas for LLM output
|   |   +-- pipeline/
|   |       +-- index.ts         # Pipeline orchestrator (idempotent, crash-safe)
|   |       +-- scoring.ts       # Z-score momentum + novelty + quality
|   |       +-- clustering.ts    # Agglomerative clustering + saturation
|   |       +-- ingest.ts        # Signal ingestion orchestrator
|   |       +-- alerts.ts        # Failure webhook notifier (generic/slack/discord)
|   |       +-- lock.ts          # DB runtime lock to prevent overlapping runs
|   |       +-- protocols.ts     # 47 tracked Solana protocols registry
|   |       +-- ingestors/
|   |           +-- helius.ts    # Solana onchain via Helius RPC
|   |           +-- github.ts    # Dev activity via GitHub API v3
|   |           +-- social.ts    # RSS/Atom news feeds
|   |           +-- twitter.ts   # Twitter/X KOLs via Nitter RSS (opt-in)
|   +-- prisma/                  # Schema (PostgreSQL)
+-- fixtures/                    # Demo signals, embeddings, project corpus
+-- archive/                     # Archived code (Python worker, old scripts)
+-- .github/workflows/
    +-- pipeline.yml             # Pipeline dispatch (manual + schedulable)
    +-- ci.yml                   # Quality gate: lint + typecheck + build

Security

  • Security headers: CSP, X-Frame-Options, HSTS, X-Content-Type-Options, Referrer-Policy, Permissions-Policy
  • Rate limiting: In-memory token bucket on all public API routes (429 on abuse)
  • Input validation: Query length limits, wildcard escaping on search
  • Error boundaries: Global error/loading/not-found pages (no white screen crashes)
  • Pipeline safety: Idempotent report upserts, crash-safe with automatic "failed" status marking
  • Data quality gate: Run is blocked if enabled ingest sources fail minimum reliability/presence thresholds
  • Run telemetry: Report config stores runtime timeline, per-step durations, counters, and structured failure reason
  • Failure alerts: Optional webhook notifications (generic/slack/discord) with category, step, period, and report link
  • CI gate: Lint + typecheck + build on every PR and push to main
  • Admin auth: Bearer token required for pipeline trigger endpoint

API Reference

Method Endpoint Auth Rate Limit Description
GET /api/reports/latest -- 60/min Latest report with narratives
GET /api/reports -- 60/min All reports
GET /api/narratives/:id -- -- Narrative detail + evidence + ideas
GET /api/ideas/:id/action-pack.zip -- -- Download Action Pack
GET /api/explore?q=... -- 30/min Search entities + narratives (max 80 chars)
POST /api/admin/run-fortnight Bearer -- Trigger pipeline

Report endpoints now include runtime telemetry (runtime) and a condensed failure message (failureReason) when available.

Tech Stack

  • Framework: Next.js 14.2 (App Router)
  • Database: PostgreSQL (Neon)
  • ORM: Prisma 5
  • LLM: Moonshot Kimi K2 Thinking Turbo
  • Onchain: Helius RPC
  • Styling: Tailwind CSS with glassmorphism + bento grid layout
  • Fonts: Outfit + JetBrains Mono
  • CI/CD: GitHub Actions + Vercel
  • Deployment: Vercel

License

MIT

About

Solana Narrative Hunter — an autonomous AI agent (“Trailblazer”) that detects emerging Solana narratives every fortnight using onchain + dev + social signals, runs recursive investigations with tool traces, and generates explainable narratives plus downloadable “Action Packs” (spec/tech/deps) for build ideas.

trailblazer-ruby.vercel.app

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages