ChainLead Agent

موتور قابل نصب برای کشف پروژه‌های Web3، تشخیص فرصت‌های همکاری و امتیازدهی لیدها بر پایه شواهد قابل حسابرسی — طراحی‌شده برای اینکه ایجنت‌های دیگر از طریق MCP، REST API یا Python SDK از آن استفاده کنند.

• هسته فقط با کتابخانه استاندارد پایتون (۳.۱۰+) اجرا می‌شود؛ هیچ وابستگی اجباری ندارد.

• کاملاً فقط‌خواندنی است: کلید خصوصی، Seed Phrase یا امضای تراکنش را نمی‌پذیرد و هیچ متد نوشتنی RPC ندارد.

• هر ادعا در گزارش فرصت، منبع (URL) و زمان مشاهده دارد.

• بودجه را موتور کنترل می‌کند، نه مدل زبانی.

شروع سریع (۳۰ ثانیه، بدون اینترنت)

pip install -e .
chainlead demo --out demo-briefs          # روی اکوسیستم «ساختگی» داخلی اجرا می‌شود

خروجی: جدول رتبه‌بندی + demo-briefs/report.json + یک Opportunity Brief (Markdown و JSON) برای هر لید واجد شرایط یا نیازمند بررسی.

داده نمایشی کاملاً ساختگی است (دامنه‌های .example). موارد سخت عمداً در آن گذاشته شده‌اند: پروژه تکراری، هویت مشکوک که قرارداد پروژه دیگری را ادعا می‌کند، پروژه دارای Prompt Injection و انتشار اسپم، رویداد Reorg‌شده، پروژه قدیمی، پروژه خارج از بازار هدف، و پروژه بدون راه تماس تأییدشده.

Related MCP server: GTM MCP Server

اجرای واقعی

cp .env.example .env     # کلیدهای خودت را وارد کن (BYOK)
export GITHUB_TOKEN=...                       # اختیاری؛ سقف GitHub را از 60 به 5000 درخواست در ساعت می‌برد
export CHAINLEAD_RPC_8453=https://<your-base-rpc>   # برای بررسی آن‌چین روی Base
export EXPLORER_API_KEY=...                   # اختیاری؛ تأیید سورس قرارداد (Etherscan V2)
chainlead run examples/campaign_base_bridge.json --out briefs --lang fa

نمونه کمپین (examples/campaign_base_bridge.json):

{
  "name": "base-bridge-q4",
  "offer": "bridge_dev",
  "target_sectors": ["defi", "infrastructure", "bridge"],
  "target_chains": [8453],
  "allowed_sources": ["github", "public_web", "rpc", "explorer"],
  "github_queries": ["topic:cross-chain solidity", "base bridge in:readme"],
  "max_candidates": 20, "max_leads": 10, "budget_usd": 0.50, "freshness_days": 90
}

پیشنهادهای آماده (chainlead offers): smart_contract_dev, bridge_dev, security_audit, onchain_analytics — یا یک پیشنهاد سفارشی با کلیدواژه‌ها و وزن ارتباط هر نوع سیگنال.

اتصال ایجنت‌ها

MCP (stdio)

{
  "mcpServers": {
    "chainlead": {
      "command": "chainlead",
      "args": ["mcp"],
      "env": { "CHAINLEAD_DB": "/path/chainlead.db", "GITHUB_TOKEN": "...", "CHAINLEAD_AGENT_MAX_BUDGET_USD": "1.0" }
    }
  }
}

ابزارها: chainlead_list_offers، chainlead_create_campaign، chainlead_run_campaign، chainlead_list_leads، chainlead_get_brief، chainlead_get_budget. عمداً ابزاری برای افزایش بودجه وجود ندارد و بودجه کمپین‌هایی که ایجنت می‌سازد به CHAINLEAD_AGENT_MAX_BUDGET_USD محدود است. تغییر بودجه فقط از CLI یا REST با کلید ممکن است.

REST API

CHAINLEAD_API_KEYS="acme:secret-key-1" chainlead serve --host 0.0.0.0 --port 8787

احراز هویت: Authorization: Bearer <key>. هر کلید یک tenant است و داده‌ها کاملاً جدا هستند. بدون کلید، سرور فقط روی 127.0.0.1 اجرا می‌شود.

Python SDK

from chainlead.sdk import ChainLeadClient, LocalChainLead

cl = ChainLeadClient("http://127.0.0.1:8787", api_key="secret-key-1")   # یا LocalChainLead("x.db")
c = cl.create_campaign(name="audit-leads", offer="security_audit", allowed_sources=["github", "public_web"],
                       github_queries=["topic:defi base"], target_chains=[8453], budget_usd=0.2)
report = cl.run_campaign(c["id"])
for lead in cl.leads(c["id"], "qualified"):
    print(cl.brief(lead["lead_id"], "markdown", "fa"))

خط لوله

1. پیشنهاد تجاری — بدون آن «لید خوب» معنا ندارد.

2. کشف — جست‌وجوی GitHub + پروژه‌های بذر کمپین؛ حذف Fork و Archive؛ ادغام تکراری‌ها بر اساس سازمان GitHub یا دامنه.

3. شواهد — GitHub (نسخه‌ها، فعالیت ۹۰ روزه، README، آدرس قراردادها)، وب‌سایت رسمی (با رعایت robots.txt: شبکه‌ها، استخدام، ممیزی، تأمین مالی، یکپارچه‌سازی، تیم، کانال‌های تماس).

4. هویت — فقط پیوندهای دوطرفه سایت↔GitHub و آدرس‌هایی که منابع رسمی منتشر کرده‌اند. کلید قرارداد chain_id + address است؛ اگر دو پروژه یک قرارداد را ادعا کنند، ضعیف‌تر جریمه می‌شود.

5. آن‌چین — بررسی بایت‌کد و رویدادهای Upgraded / AdminChanged / Initialized / OwnershipTransferred، از جدید به قدیم و با سقف درخواست. کلید رویداد chain_id + tx_hash + log_index، همراه شماره و هش بلاک؛ وضعیت pending → safe → finalized و علامت‌گذاری orphaned پس از Reorg.

6. سیگنال و امتیاز — جدا کردن مشاهده / استنباط / فرصت، سپس:

   • L = 0.30F + 0.25B + 0.20C + 0.15D + 0.10R

   • O = 0.35N + 0.25T + 0.20E + 0.20Q

7. تکمیل با بودجه — فراخوانی‌های پولی (تأیید قرارداد، تکمیل تماس) فقط برای بهترین گزینه‌ها و قبل از اجرا از بودجه رزرو می‌شوند.

8. رتبه‌بندی و گزارش — Opportunity Brief به فارسی یا انگلیسی.

قانون تصمیم

امتیاز بالا کافی نیست. لید فقط وقتی qualified است که علاوه بر حد امتیازها: هویت مطمئن باشد، محتوای مشکوک نداشته باشد، اطمینان داده کافی باشد، حداقل یک سیگنال رسمی یا تأییدشده و یک راه تماس رسمی داشته باشد. وگرنه review (بررسی انسانی) یا rejected.

امنیت

• رد خودکار هر ورودی شامل کلید خصوصی، Seed Phrase یا فیلدهایی با این نام‌ها (در CLI، REST، MCP و SDK).

• RPC فقط متدهای خواندنی را مجاز می‌داند؛ GraphQL فقط query.

• متن‌های وب، README و نسخه‌ها «داده» هستند: پاک‌سازی کاراکترهای پنهان، محدودیت طول، تشخیص Prompt Injection. پروژه پرچم‌خورده هرگز خودکار واجد شرایط نمی‌شود و هزینه پولی برایش خرج نمی‌شود.

• مقاومت در برابر دست‌کاری امتیاز: سقف ۳ سیگنال از هر نوع، تشخیص انتشار انبوه (signal flood)، کیفیت پایین برای ادعاهای تأییدنشده شخص ثالث.

• جداسازی کامل tenantها در همه جداول؛ مقایسه کلید API در زمان ثابت؛ سقف اندازه درخواست.

• محافظ SSRF برای وب‌سایت‌های نامطمئن: فقط IP عمومی، اتصال به همان IP بررسی‌شده (ضد DNS rebinding)، بررسی دوباره هر redirect، فقط پورت 80/443، سقف حجم و زمان.

• محدودیت نرخ REST برای هر tenant/IP و timeout سوکت؛ بودجه فقط عدد متناهی بین ۰ و ۱٬۰۰۰٬۰۰۰ دلار.

• جزئیات: SECURITY_REVIEW.md

هزینه

• هر فراخوانی در جدول provider_calls با هزینه، وضعیت و کش ثبت می‌شود؛ گزارش هر اجرا «هزینه هر لید واجد شرایط» را می‌دهد.

• درخواست‌های تکراری از کش سرو می‌شوند (اجرای مجدد کمپین هزینه پولی دوباره ندارد).

• منابع رایگان همیشه قبل از منابع پولی برای همان قابلیت انتخاب می‌شوند.

• خطای ارائه‌دهنده = بازگشت هزینه رزروشده.

تست

pip install -e ".[dev]"
pytest -q                        # ۲۱۴ تست: unit, integration, security, e2e, tool
CHAINLEAD_LIVE=1 pytest -m live  # تست دود روی GitHub واقعی (نیاز به اینترنت)

ارائه‌دهندگان واقعی (GitHub، وب‌سایت، JSON-RPC، Explorer، The Graph) در تست‌ها با سرورهای HTTP محلی که پاسخ‌های واقعی را شبیه‌سازی می‌کنند آزموده می‌شوند.

ابزار پولی برای ایجنت‌ها (OpenSea Tools / ERC-8257 / x402)

chainlead tool-serve یک endpoint پولی و هم‌زمان (synchronous) می‌سازد که ایجنت‌های دیگر با USDC روی Base برایش پول می‌دهند:

• ترتیب پرداخت: اعتبارسنجی ورودی (422) ← verify ← رزرو replay ← اجرا ← settle. نتیجه فقط بعد از settle موفق برگردانده می‌شود. اگر هیچ کاندیدی پیدا نشود هزینه‌ای گرفته نمی‌شود.

• سقف‌ها: حداکثر ۸ کاندید، ۵ لید، ۳ جستجوی GitHub، بودجه زمانی ۳۵ ثانیه، ۲ اجرای هم‌زمان (بیشتر = 503 قبل از پرداخت)، ۶۰ درخواست در دقیقه برای هر IP.

• فقط منابع رایگان (GitHub، وب‌سایت رسمی، RPC عمومی Base)؛ هزینه داده صفر. داده کمپین بعد از هر فراخوانی پاک می‌شود.

• قیمت پیشنهادی: 0.50 USDC برای هر فراخوانی (CHAINLEAD_PRICE_USDC). تغییر قیمت یا URL، hash مانیفست را عوض می‌کند.

متغیرها (همه عمومی‌اند؛ برای دریافت پول هیچ کلید خصوصی لازم نیست):

PUBLIC_BASE_URL=https://<service>.onrender.com   # الزامی برای مانیفست
X402_MODE=facilitator                           # PayAI؛ off = غیرفعال (503)
X402_PAY_TO=0x...                               # گیرنده USDC
TOOL_CREATOR_ADDRESS=0x...                      # امضاکننده ثبت
CHAINLEAD_PRICE_USDC=0.50
GITHUB_TOKEN=...                                            # توکن بدون scope؛ عملاً لازم (بدون آن ۶۰ درخواست در ساعت)

استقرار روی Render (رایگان): render.yaml و Dockerfile آماده‌اند. سرویس رایگان بعد از بیکاری می‌خوابد؛ قبل از tool-sdk verify یا ثبت، یک بار /health را صدا بزن تا بیدار شود.

Docker

docker build -t chainlead . && docker run -p 8000:8000 --env-file .env chainlead   # ابزار پولی x402
docker compose up --build        # REST API روی :8787 ، داده در volume

محدودیت‌های نسخه اول

• یک شبکه EVM هدف (پیش‌فرض Base) پیشنهاد می‌شود؛ شبکه‌های دیگر در registry هستند اما هر کدام RPC جداگانه می‌خواهند.

• اسکن رویدادها روی RPCهای عمومی با سقف درخواست محدود است؛ برای پوشش کامل بازه تازگی، RPC با سقف بالاتر یا log_range_override لازم است.

• تکمیل تماس پولی (مثل پایگاه‌های داده B2B) فقط به‌صورت رابط وجود دارد؛ در نسخه اول فقط کانال‌های عمومی و رسمی پروژه استخراج می‌شوند.

• The Graph به‌صورت اتصال‌دهنده عمومی است و به شناسه Subgraph مخصوص هر پروژه نیاز دارد (graph_queries در پروژه بذر).

• وزن‌ها نقطه شروع‌اند و باید با نتایج واقعی فروش تنظیم شوند.

نشانه‌ها فقط نیاز «احتمالی» را نشان می‌دهند؛ اثبات بودجه یا قصد خرید نیستند. پیش از تماس، منابع را بررسی کن و قوانین ضداسپم و حریم خصوصی را رعایت کن.

مجوز: MIT