@pioneer-platform/pioneer-discovery-service 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @pioneer-platform/pioneer-discovery-service
 
+## 0.2.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @pioneer-platform/default-mongo-v2@1.7.1
+
 ## 0.2.1
 
 ### Patch Changes

package/DAPP-INVESTIGATION.md

@@ -0,0 +1,459 @@
+# DApp Investigation Worker
+
+## Overview
+
+The DApp Investigator is a deep analysis worker that runs as part of the Pioneer Discovery Service to comprehensively investigate dApps before whitelisting them.
+
+## Investigation Areas
+
+### 1. Contract Verification
+
+**What we check:**
+- Are smart contracts verified on block explorers?
+- Etherscan, BSCScan, Polygonscan verification status
+- Source code availability
+- Security audit status (CertiK, Trail of Bits, OpenZeppelin)
+- Audit recency and findings
+
+**Data Sources:**
+- Etherscan API
+- BSCScan API
+- Polygonscan API
+- CertiK Security Oracle
+- DeFi Safety scores
+
+### 2. Social Media Presence
+
+**What we check:**
+- Twitter: Handle, followers, verification, activity
+- Discord: Server size, activity level
+- GitHub: Repository stats, stars, contributors, commit frequency
+- Telegram: Group size, admin activity
+- Medium/Blog: Technical documentation quality
+
+**Red Flags:**
+- No social presence
+- Inactive accounts
+- Recently created accounts
+- Bought followers
+- No community engagement
+
+### 3. Metrics & Usage
+
+**What we check:**
+- Total Value Locked (TVL) from DeFiLlama
+- Daily Active Users (DAU)
+- Transaction volume
+- Fee generation
+- User retention
+- Growth trends
+
+**Data Sources:**
+- DeFiLlama
+- Dune Analytics
+- The Graph
+- On-chain data
+
+### 4. Security History
+
+**What we check:**
+- Past security incidents
+- Exploit history
+- Bug bounty program
+- Response to vulnerabilities
+- Recovery procedures
+
+**Data Sources:**
+- Rekt News
+- Immunefi
+- CertiK incidents
+- SlowMist Hacked database
+- BlockSec alerts
+
+### 5. Team Transparency
+
+**What we check:**
+- Public team members
+- LinkedIn profiles
+- Previous project experience
+- KYC verification (CertiK, Assure)
+- Team size and roles
+- Developer activity
+
+**Scoring:**
+- Anonymous team: +20 risk
+- Public team: -10 risk
+- KYC verified: -10 risk
+- Experienced team: -15 risk
+
+## Risk Score Calculation
+
+Risk scores range from 0 (safe) to 100 (high risk):
+
+### Starting Point
+- Base score: 50 (neutral)
+
+### Adjustments
+
+**Reduce Risk (-):**
+- Contract verified: -20
+- Strong social presence: -10
+- High TVL (>$1M): -15
+- Bug bounty program: -5
+- Public team: -10
+- KYC verified: -10
+
+**Increase Risk (+):**
+- No contract verification: +10
+- No social presence: +15
+- Security incident: +25 per incident
+- Anonymous team: +20
+- Recent creation (<30 days): +15
+
+### Examples
+
+**Safe DApp (Risk: 15)**
+```
+Base: 50
+- Contract verified: -20
+- Strong social: -10
+- High TVL: -15
+- Public team: -10
+= 50 - 55 = 0 (clamped to minimum)
+```
+
+**Risky DApp (Risk: 85)**
+```
+Base: 50
++ Not verified: +10
++ No social: +15
++ 1 incident: +25
+= 50 + 50 = 100
+```
+
+## Whitelist Criteria
+
+A dApp is recommended for whitelisting if:
+
+1. **Risk score < 30**
+2. **Either:**
+   - Contract verified, OR
+   - TVL > $1M
+3. **Has social presence** (Twitter, Discord, or GitHub)
+4. **No major security incidents**
+
+## Investigation Flow
+
+### Phase 1: Contract Verification (30s)
+
+```typescript
+// Check Etherscan
+const etherscan = await axios.get(
+  `https://api.etherscan.io/api?module=contract&action=getsourcecode&address=${address}`
+);
+
+if (etherscan.data.result[0].SourceCode) {
+  findings.contractVerification = {
+    verified: true,
+    auditor: etherscan.data.result[0].AuditorName,
+    auditDate: etherscan.data.result[0].AuditDate,
+  };
+}
+```
+
+### Phase 2: Social Analysis (45s)
+
+```typescript
+// Check GitHub
+const github = await axios.get(
+  `https://api.github.com/repos/${org}/${repo}`
+);
+
+findings.socialPresence.github = {
+  repos: 1,
+  stars: github.data.stargazers_count,
+  lastCommit: github.data.pushed_at,
+};
+
+// Check Twitter (via scraping or paid API)
+// Check Discord (via bot or public stats)
+```
+
+### Phase 3: Metrics Fetch (30s)
+
+```typescript
+// Query DeFiLlama
+const protocols = await axios.get(
+  'https://api.llama.fi/protocols'
+);
+
+const match = protocols.data.find(p => 
+  p.name.toLowerCase() === dapp.name.toLowerCase()
+);
+
+if (match) {
+  findings.metrics = {
+    tvl: match.tvl,
+    source: 'DeFiLlama',
+  };
+}
+```
+
+### Phase 4: Security Check (60s)
+
+```typescript
+// Check Rekt News database
+// Check Immunefi for bounties
+// Check CertiK for incidents
+// Check SlowMist Hacked list
+
+findings.security = {
+  incidents: [],
+  bugBounty: false,
+};
+```
+
+### Phase 5: Team Check (45s)
+
+```typescript
+// Scrape team page
+// Check LinkedIn
+// Verify KYC badges
+
+findings.team = {
+  public: false,
+  kyc: false,
+  experience: 'unknown',
+};
+```
+
+**Total Time: ~3-4 minutes per dApp**
+
+## Batch Processing
+
+To avoid overwhelming the system:
+
+- **Process 10 dApps per run** (configurable)
+- **1 second delay** between dApps
+- **Only investigate stale dApps** (not checked in 7 days)
+- **Non-blocking** (doesn't slow down other discovery phases)
+
+```typescript
+// Get stale dApps
+const allDapps = await discoveryDB.getDappsNeedingCheck(24 * 7); // 7 days
+
+// Limit batch size
+const dappsToInvestigate = allDapps.slice(0, 10);
+
+// Process with delays
+for (const dapp of dappsToInvestigate) {
+  await investigateDApp(dapp);
+  await sleep(1000); // 1 second delay
+}
+```
+
+## Investigation Results
+
+### High Quality DApp Example
+
+```json
+{
+  "dappId": "uniswap-v3",
+  "dappName": "Uniswap V3",
+  "investigationComplete": true,
+  "findings": {
+    "contractVerification": {
+      "verified": true,
+      "auditor": "Trail of Bits",
+      "auditDate": "2021-03-15",
+      "auditUrl": "https://github.com/Uniswap/v3-core/blob/main/audits/"
+    },
+    "socialPresence": {
+      "twitter": {
+        "handle": "@Uniswap",
+        "followers": 1200000,
+        "verified": true,
+        "lastPost": "2024-01-15T10:30:00Z"
+      },
+      "discord": {
+        "serverSize": 50000,
+        "active": true
+      },
+      "github": {
+        "repos": 15,
+        "stars": 8500,
+        "lastCommit": "2024-01-14",
+        "contributors": 45
+      }
+    },
+    "metrics": {
+      "tvl": 3500000000,
+      "dailyActiveUsers": 25000,
+      "transactionVolume": 1000000000,
+      "source": "DeFiLlama"
+    },
+    "security": {
+      "incidents": [],
+      "bugBounty": true,
+      "bugBountyUrl": "https://immunefi.com/bounty/uniswap/"
+    },
+    "team": {
+      "public": true,
+      "kyc": true,
+      "experience": "Hayden Adams - experienced DeFi builder"
+    }
+  },
+  "riskScore": 5,
+  "recommendWhitelist": true,
+  "investigatedAt": 1705338000000
+}
+```
+
+### Suspicious DApp Example
+
+```json
+{
+  "dappId": "anon-swap-123",
+  "dappName": "AnonSwap",
+  "investigationComplete": true,
+  "findings": {
+    "contractVerification": {
+      "verified": false
+    },
+    "socialPresence": {},
+    "metrics": {},
+    "security": {
+      "incidents": [
+        {
+          "date": "2024-01-10",
+          "type": "rug-pull",
+          "severity": "critical",
+          "description": "Liquidity removed by deployer"
+        }
+      ],
+      "bugBounty": false
+    },
+    "team": {
+      "public": false,
+      "kyc": false
+    }
+  },
+  "riskScore": 95,
+  "recommendWhitelist": false,
+  "investigatedAt": 1705338000000
+}
+```
+
+## Integration with Discovery Service
+
+### Automatic Updates
+
+Investigation results automatically update the discovery database:
+
+```typescript
+// Update dapp record
+await discoveryDB.updateDapp(result.dappId, {
+  scamScore: result.riskScore / 100, // Convert to 0-1
+  whitelist: result.recommendWhitelist,
+  lastChecked: result.investigatedAt,
+});
+
+// Log to report
+if (result.recommendWhitelist) {
+  discoveryReporter.addLog('INFO', `✅ Whitelisted: ${result.dappName}`);
+}
+
+if (result.riskScore > 70) {
+  discoveryReporter.addLog('WARN', `⚠️ High risk: ${result.dappName}`);
+}
+```
+
+### Pioneer Server Integration
+
+The pioneer-server dapps controller can query investigation results:
+
+```typescript
+// In pioneer-server/src/controllers/dapps.controller.ts
+const dapp = await discoveryDB.getDapp(dappId);
+
+return {
+  id: dapp.id,
+  name: dapp.name,
+  url: dapp.url,
+  whitelist: dapp.whitelist,
+  riskScore: dapp.scamScore * 100,
+  investigation: dapp.metadata, // Full findings
+};
+```
+
+## Free Data Sources
+
+### Currently Used
+
+1. **DeFiLlama** - TVL and protocol data (free, no API key)
+2. **GitHub API** - Repository stats (free tier: 60 req/hour)
+3. **Etherscan/BSCScan** - Contract verification (free tier: 5 req/sec)
+
+### Planned
+
+4. **CoinGecko API** - Market data and social links
+5. **The Graph** - On-chain queries
+6. **Dune Analytics** - Usage metrics
+7. **Immunefi API** - Bug bounty info
+8. **CertiK API** - Audit data
+9. **Rekt News** - Incident history
+
+## Future Enhancements
+
+- [ ] ML model for scam detection
+- [ ] Automated contract analysis (Slither, Mythril)
+- [ ] User reputation integration
+- [ ] Community voting on dApps
+- [ ] Real-time incident alerts
+- [ ] Automated whitelist/blacklist updates
+- [ ] Integration with Web3 security tools
+- [ ] NFT project investigation
+- [ ] DAO governance analysis
+- [ ] Bridge security assessment
+
+## Monitoring
+
+Check discovery service logs for investigator status:
+
+```bash
+# View investigation logs
+tail -f /var/log/pioneer/discovery-service.log | grep dapp-investigator
+
+# Expected output
+[dapp-investigator] 🔍 Starting deep investigation of 10 dApps...
+[dapp-investigator] Investigating: Uniswap V3
+[dapp-investigator] ✅ WHITELIST RECOMMENDED: Uniswap V3
+[dapp-investigator] Investigating: SuspiciousDex
+[dapp-investigator] ⚠️ HIGH RISK: SuspiciousDex (score: 85)
+[dapp-investigator] Investigation complete: 10 dApps analyzed
+```
+
+## Performance
+
+- **Investigation time**: ~3-4 minutes per dApp
+- **Batch size**: 10 dApps per run
+- **Total run time**: ~30-40 minutes per discovery cycle
+- **Memory usage**: Minimal (<100MB)
+- **Network**: Moderate (multiple API calls per dApp)
+
+## Error Handling
+
+The investigator is designed to be fault-tolerant:
+
+- **API failures**: Continue with available data
+- **Timeouts**: Skip to next dApp after 30s
+- **Rate limits**: Respect and backoff
+- **Missing data**: Use defaults, don't fail
+- **Network issues**: Retry with exponential backoff
+
+## See Also
+
+- [Price Discovery](./PRICE-DISCOVERY.md)
+- [Discovery Service README](./README.md)
+- [Discord Integration](../../pioneer-server/DISCORD-INTEGRATION.md)
+