AI Reference

Use the button above to copy the full reference. The raw text is also shown below for inspection.

# SpotBlock AI Reference

Purpose: single machine-oriented reference assembled from existing SpotBlock docs so another AI can answer questions about SpotBlock without browsing the full doc set.

Usage guidance:
- Treat this file as a high-level product and operations reference, not as executable source code.
- Prefer facts in this file over generic assumptions.
- If a point is marked planned/not public yet, do not describe it as live.
- Network scope is primarily Ethereum mainnet unless a section explicitly says Sepolia.

Source set used:
- `website/src/app/docs/getting-started/page.tsx`
- `website/src/app/docs/detection-scoring-system/page.tsx`
- `website/src/app/docs/real-time-monitoring/page.tsx`
- `website/src/app/docs/company-quick-start/page.tsx`
- `website/src/app/explorer/capabilities/page.tsx`
- `website/SECURITY_AUDIT.md`

## 1. Product identity

SpotBlock is an Ethereum-focused security and threat-intelligence platform combining:
- fast scam detection and listing intelligence
- deeper AI-assisted contract analysis
- conservative high-confidence publication
- real-time monitoring for wallets and contracts
- a public lightweight threat lookup API

Primary user roles:
- End user: searches addresses in Explorer, checks threat status, can trigger Deep AI scan when address not found.
- Company/integrator: uses the Threat Check API and monitoring/scoring concepts inside product flows.
Hiring: security analysts apply via Contact / Discord; there is no public contribution programme.

## 2. Platform model

SpotBlock uses a three-layer model:

Layer 1: Scam Scanner
- Purpose: fast automated detection and listing intelligence.
- Inputs: bytecode patterns, token heuristics, ownership/liquidity/distribution signals.
- Output: `confidenceScore` 0-100 plus reasons/tags/metadata.

Layer 2: Advanced Scans
- Includes:
  - Deep AI scanner / Super-Analyst
  - vulnerability scanner
- Purpose: richer context and structured contract-level reasoning before promotion/review decisions.
- Deep AI requests are queued from Explorer.

Layer 3: Publication
- Purpose: publish only high-confidence scanner auto-promotes (default score >= 80).
- Medium-confidence detections (about 40-79) stay unpublished in staging and are not flagged as scam or malicious.
- Public community review, validator API, contribution form, leaderboard, and rewards are discontinued.

Platform operations currently described as active:
- threat check API
- real-time monitoring registration, list, status, stop flows

## 3. Explorer behavior

Explorer is the main user entry point.

Key user actions:
- search an Ethereum address
- inspect known malicious records
- start real-time monitoring
- run Deep AI / Super-Analyst scan if address is not found

Deep AI / Super-Analyst user flow:
1. Search address in Explorer.
2. If not found, connect wallet.
3. Sign scan request.
4. Request enters queue.
5. Worker processes retriever plus analyzer.
6. If result is promoted, user is redirected to explorer data for the address.
7. Re-run for same depth/version is blocked until analyzer version changes.

Typical Deep AI timing:
- around 15 seconds, but may be longer under load or for heavier contracts.

## 4. Scam scanner and scoring

Scam scanner characteristics:
- first detection layer
- fast, signal-driven
- optimized for continuous intake
- produces `confidenceScore` from 0 to 100
- only contracts with score >= 10 enter staging

High-level routing:
- `< 10`: not staged / ignored
- `40-79`: unpublished (`not_published`); not flagged as scam/malicious
- `>= 80`: auto-promoted / auto-approved path
- low-confidence staging remains unpublished

Score and label mapping for non-phishing cases:
- `>= 80`: severity critical; label `scam` if malicious evidence is present, otherwise `suspicious`
- `>= 60`: same critical/evidence rule
- `>= 40`: label `suspicious`
- `>= 20`: label `dangerous`
- `>= 10`: label `dangerous`
- otherwise `unknown`

Special phishing handling:
- token name/symbol phishing can force score `99`
- severity becomes critical
- label becomes `phishing scam`
- can trigger auto-approval behavior

Governance / provenance principles:
- outputs are designed to be explainable, auditable, and risk-aware
- staging records store `detectionReasons`, tags, and metadata
- promotion is gated and conservative
- only strong outcomes are published publicly

## 5. Deep AI / Super-Analyst and vulnerability scanning

Purpose:
- add richer contract context
- standardize contract reasoning
- support promotion and review decisions

Retrieval layer described in docs:
- verified retriever: verified source and ABI inputs, plus lightweight on-chain and provenance enrichment when useful
- unverified retriever: bytecode-first retrieval with contract-structure, proxy, and activity context when source is unavailable
- both retrievers use bounded, best-effort enrichment so deeper scans gain context without disclosing the full internal retrieval or scoring logic

Analysis layer described in docs:
- Super-Analyst AI mode: structured contract risk reasoning from retrieved evidence
- vulnerability scanner mode: pattern-based security findings for common exploit classes and dangerous logic
- analysis depth modes: simple and advanced
- request deduplication exists to avoid repeating expensive analyses for same input/version

Promotion semantics:
- Deep AI returns structured JSON with `rating` in:
  - `safe`
  - `suspicious`
  - `threat`
  - `unknown`
- only `suspicious` or `threat` are promoted into public malicious explorer entries
- `safe` and `unknown` remain as historical/internal analysis state for traceability

## 6. Publication policy

Public contribution and community validator review are discontinued.

Scanner publication:
- high confidence (default >= 80): auto-promote to production `contracts` (Explorer / Threat Check)
- medium confidence (about 40-79): stay in staging as `not_published`; not flagged as scam or malicious
- low confidence: stay unpublished

Super-Analyst on-demand scans still promote only `suspicious` / `threat` ratings into public listings.

Historical `metadata.humanReview` comments on already published contracts may still display. There is no new public intake.

The former Discord review channels, register-bot, claim-reward-bot, validator API (`/api/validator/*`), contribution form, leaderboard, and rewards APIs are gone (HTTP 410).

## 10. Threat Check API


Purpose:
- lightweight lookup for wallets, dapps, and backends
- returns whether an address is currently listed by SpotBlock
- no API key documented

Endpoints:
- `GET /api/threat-check?address=0x...`
- `POST /api/threat-check` with JSON body `{ "address": "0x..." }`

Input:
- Ethereum address
- invalid input returns HTTP `400`

Response shape:
```json
{
  "address": "0x0000000000000000000000000000000000000000",
  "outcome": "safe",
  "source": "spotblock_db"
}
```

Response semantics:
- `outcome = threat`: address exists in the same dataset used by public Explorer
- `outcome = safe`: address is not in SpotBlock's published threat listings at query time; this is not a guarantee of benign behavior
- `source` is always `spotblock_db`

Integration notes:
- deterministic output contract: `address`, `outcome`, `source`
- near-real-time; GET may include short private caching
- current scope is Ethereum addresses

Business docs explicitly say:
- Threat Check API was the first business-ready automation endpoint
- the public automation surface now also includes security-check, tx-harm, the monitoring list/watch/stop/status endpoints, and MCP/OpenAPI/llms.txt (see Integration endpoints below)
- scoring API is not publicly available yet
- no public enterprise SLA is published yet

Simple integration flow:
1. user enters/selects address
2. backend calls `/api/threat-check`
3. app blocks, warns, or allows based on `outcome`

## 11. Real-time monitoring

Scope:
- Ethereum mainnet
- post-confirmation detection (not mempool)
- wallet and contract monitoring supported

How it works:
- once address is placed under monitoring, backend tracks each confirmed transaction involving that address
- transactions are analyzed against proprietary behavioral and heuristic models
- for contracts, interacting addresses are profiled (wallet age, contract vs EOA, known labels) and their funding origin is traced back toward known bad actors such as mixers or exploit wallets
- related actions across multiple blocks are correlated into multi-step attack sequences
- multiple signals for an interaction are combined into a single 0-100 risk score with a recommended action (continue / monitor / pause / emergency); exact signals, weights, and score boundaries are not published
- risk alerts surface in Explorer

Explorer monitoring UX:
- start RT monitoring from Explorer
- if address has bytecode, it becomes a contract watch
- if not, it becomes a wallet watch
- no wallet signature required for basic monitoring

Views:
- `Risk alerts`: threat-tier or notable alerts
- `All activity`: chronological feed

Contract monitoring v1:
- ingests transactions whose top-level `to` is the watched contract
- uses Ethereum mainnet receipt-level logic
- no trace RPC
- token movements routed only via routers/multicall without directly calling the contract may not appear

Detection categories disclosed at a high level:
- asset movement anomalies
- permission abuse signals
- behavioral velocity
- on-chain deployment events
- attacker origin and funding provenance (fresh wallets, mixer-funded or exploit-linked actors)
- multi-step attack sequences across blocks
- treasury drain intelligence (share of treasury moved, first-time recipients, destination type, rapid drains)
- per-contract anomaly baselines

Risk score:
- contract alerts carry a 0-100 risk score and a recommended action (continue / monitor / pause / emergency)
- severity is derived from the risk score, so higher score maps to more urgent severity

Alert severities:
- Critical: immediate threat, strong correlation with known exploit/drain patterns
- High: significant suspicious activity
- Medium: notable event worth reviewing

Current limitations / roadmap:
- no mempool detection
- multi-chain support planned
- email and Discord alert notifications planned
- custom thresholds planned
- wallet signature verification for premium monitoring features planned

## 12. Compliance and data usage posture

Docs emphasize:
- conservative publication
- evidence-backed entries
- traceable lifecycle
- conservative unpublished mid-score band

Public publishing rule:
- only `suspicious` / `threat` outcomes reach the public malicious explorer

Evidence/provenance:
- promoted entries carry scanner `detectionReasons`
- Super-Analyst outputs and structured evidence are persisted
- scan requests and promotions retain timestamps and queue state

## 13. Security posture for web app contribution/admin/API surfaces

Security audit highlights from `website/SECURITY_AUDIT.md`:
- fixed input validation issues
- added Ethereum hex validation
- email and wallet validation
- max length limits on descriptions, tags, evidence URLs, rejection reasons
- status/network/severity whitelist validation
- added sanitization functions to reduce XSS risk
- query params validated to reduce Mongo/NoSQL injection risk
- DoS risk reduced through size limits

Remaining recommendations:
- rate limiting
- CSRF protection
- stronger session/cookie handling for admin key flows
- frontend maxLength UX
- stricter production error handling
- consider GDPR/data retention policy for IP logging

Security best practices described as implemented:
- input validation and sanitization
- output encoding via React auto-escaping
- parameterized MongoDB queries
- authz/authn for admin API key flows
- URL validation and address format validation

## 14. Live vs planned features

Live or described as active:
- Explorer search
- public malicious listings
- scam scanner
- Super-Analyst / Deep AI on-demand scans
- vulnerability scan requests
- Threat Check API
- wallet and contract real-time monitoring

Not publicly available yet / planned:
- public RT monitoring API
- public scoring API
- enterprise SLA
- multi-chain support
- some notification channels and custom alert profile features

## 15. Safe answering rules for another AI

When answering questions about SpotBlock:
- The public automation surface is not limited to Threat Check API; the Integration endpoints section below lists security-check, tx-harm, MCP, OpenAPI, and llms.txt as live.
- Distinguish between:
  - scam scanner output
  - Deep AI / Super-Analyst output
- Do not describe `safe` from Threat Check API as a guarantee of benign behavior.
- Do not describe public contribution, validator review, leaderboard, or rewards as live.
- Treat capability snapshot uptime/latency numbers as informational, not contractual.

## 16. Short copy-paste briefing

SpotBlock is an Ethereum-focused security platform with 3 layers: (1) scam scanner for fast threat detection and staging, (2) Super-Analyst/Deep AI plus vulnerability scanning for richer contract analysis, and (3) publication of high-confidence auto-promotes only. Medium-confidence scanner findings stay unpublished. Public automation surfaces include `GET/POST /api/threat-check` (returns `{ address, outcome: safe|threat, source: spotblock_db }`) plus `/api/security-check`, `/api/tx-harm`, and `/api/mcp` — see the Integration endpoints section. Explorer is the main UI for search, Deep AI scans, and real-time monitoring. Community contribution, validator review, leaderboard, and rewards are discontinued. Do not describe SpotBlock as a public token product.

## Integration endpoints

SpotBlock exposes its security capabilities to scripts, Custom GPT actions, and MCP clients (no API key; base URL https://spotblock.org):
- `GET /api/security-check?selector=…` — umbrella check on any selector (EOA address, ENS name ending in `.eth`, or transaction hash): threat-DB lookup, contract report, live contract state, wallet profile, and monitoring status in one response, with a top-level verdict (`harmful`/`suspicious`/`clean`/`unknown`).
- `POST /api/tx-harm` with JSON body `{"txHash":"0x…"}` or `{"rawTx":"0x…"}` and optional `"network":"ethereum"|"sepolia"` — reports whether a transaction touched harmful (threat-listed) addresses, including token transfers parsed from receipt logs; call-trace depth capped at 10 when a trace-capable RPC is configured.
- `POST /api/mcp` — stateless MCP Streamable-HTTP JSON-RPC 2.0 endpoint (`initialize`, `tools/list`, `tools/call`); tools include `spotblock_threat_check`, `spotblock_security_check`, `spotblock_tx_harm`, `spotblock_scan_status`, `spotblock_monitor_list`, `spotblock_monitor_status`, `spotblock_stats`, and `spotblock_scan_instructions`.
- `GET /api/openapi.json` — OpenAPI 3.0.3 spec for Custom GPT actions and code generators.
- `GET /llms.txt` — machine-oriented discovery file describing all integration surfaces.

AI deep scan (super-analyst) daily caps: 3 scans per wallet per day, 5 per IP per day, 25 global per day. Nonce and scan flows require a wallet signature; scans are deliberately not exposed as MCP tools since MCP clients cannot sign wallets.