← Back to docs
AI Reference
Single all-in-one SpotBlock reference intended for copy/paste into a chatbot, agent, or LLM context window.
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/contributor-manual/page.tsx`
- `website/src/app/docs/company-quick-start/page.tsx`
- `website/src/app/docs/threat-check-api/page.tsx`
- `website/src/app/docs/token-fundamentals/page.tsx`
- `website/src/app/explorer/capabilities/page.tsx`
- `website/src/app/deployed-contracts/page.tsx`
- `website/SECURITY_AUDIT.md`
- `contracts/TOKEN_GUIDE.md`
- `contracts/SPOT_SALE_CONTRACT.md`
- `contracts/DEPLOY.md`
- `contracts/TESTING_GUIDE.md`
- `contracts/SECURITY_AUDIT_STAKING.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
- human review / validator workflows
- real-time monitoring for wallets and contracts
- a public lightweight threat lookup API
- a project token called `SPOT`
Primary user roles:
- End user: searches addresses in Explorer, checks threat status, can trigger Deep AI scan when address not found.
- Contributor: submits structured reports via form, validates scanner tickets in Discord, or uses the validator API.
- Company/integrator: uses the Threat Check API and monitoring/scoring concepts inside product flows.
- Investor/supporter: buys or stakes SPOT and follows token ecosystem growth.
## 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: Human Review
- Purpose: validate medium-confidence or uncertain cases.
- Workflow exists in Discord and via signed validator API submissions.
- First resolver of a review ticket earns the reward for that ticket.
Platform operations currently described as active:
- threat check API
- reward bot / reward-claim related flow
- contributor leaderboard / contribution stats
- 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
- submit contributions
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`: routed to human review
- `>= 80`: auto-promoted / auto-approved path
- low-confidence staging remains in workflow until handled
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. Human review model
Human review purpose:
- reduce false positives
- finalize production labels
- provide auditable verdicts
Review queue:
- medium-confidence scam-scanner findings move into staging
- staging includes fields like:
- `confidenceScore`
- `label`
- `detectionReasons`
Possible verdicts:
- `safe`: reject as false positive, do not promote to malicious explorer
- `threat`: approve and promote to malicious explorer
Auditability:
- analyst comments and verdicts are stored
- docs reference `metadata.humanReview.latest` as the place where latest human review metadata is kept
- reviewer identity and timestamps are persisted
Human review channels:
- Discord validation
- validator API
- requested/routine queues can exist depending on configuration
## 7. Contributor system
Three contribution paths:
- Discord validation
- contribution form
- validator API
Discord validation:
- validators review scam-scanner items needing human judgment
- social / group workflow
- low setup
Contribution form:
- structured report submission
- useful for richer evidence and multi-address cases
- asynchronous, no chat required
Validator API:
- same review action as Discord, exposed to code
- intended for automation and agent-assisted review
- comment is required so reasoning remains auditable
- optional `toolName` can be supplied for tool attribution
Docs explicitly encourage:
- agents
- batch tooling
- automation on validator API
- machine-assisted review combined with accountable signed submissions
## 8. Validator API summary
Authentication model:
- wallet-linked contributor identity
- short-lived wallet signatures
- server-issued nonce
Flow:
1. `GET /api/validator/nonce`
2. sign message containing wallet + nonce + issued timestamp
3. use signature to fetch pending tickets or submit review
Main endpoints:
- `GET /api/validator/nonce`
- `GET /api/validator/pending`
- `POST /api/validator/review`
`GET /api/validator/pending`:
- authenticated
- returns items from `contracts_staging`
- statuses included: `pending` and `needs_review`
- supports `limit` with default 50 and max 200
`POST /api/validator/review`:
- authenticated
- required:
- `address`
- `chainId`
- `verdict` (`safe` or `threat`)
- `comment`
- wallet auth payload
- optional:
- `toolName`
Operational semantics:
- target address can be a staging ticket from `/api/validator/pending`
- if verdict is `threat`, submission auto-promotes into malicious explorer database
- validator comment is stored as reviewer context; it does not overwrite scanner or Super-Analyst data
Security guidance from docs:
- do not use a high-value wallet private key for validator automation
- prefer a dedicated hot wallet with minimal assets
## 9. Reward and claim model
General principles:
- quality bar applies across Discord, form, and API
- base reward differs by channel
- sustained high-signal work can increase multiplier
Scam-scanner validation rewards:
- first resolver earns the ticket reward
- reward is measured in contributor points sized from a published USD reference for the SPOT leg
- docs cite about US$0.70 per routine ticket at a $0.10 / SPOT program reference (subject to live config)
- requested queue can have higher per-ticket reference
Form contribution rewards:
- variable
- depend on address count and evidence quality
Multipliers:
- profile-based
- manually tuned by SpotBlock
- can go up to 5x
Claim processing:
- reviewed by admins before transfer
- minimum claim threshold applies
- payout has two legs:
- SPOT
- USD-stable top-up / stable leg where program operates it
- SPOT and USD-stable transfers are separate operational steps
Token compensation reference:
- token docs say stable leg is currently 2% of SPOT reward value at reference price
- contributor manual frames it as a separate USD-stable pool/top-up model
- safest phrasing: contributor rewards are mixed SPOT plus USD-stable support, subject to current program settings
## 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 is the only live business-ready automation endpoint today
- RT monitoring API is not publicly available yet
- 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
- 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
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
- human accountability
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. SPOT token overview
SPOT basics:
- project token of SpotBlock
- current role: participation and long-term ecosystem alignment
- planned role: utility key for advanced platform capabilities including deeper Super-Analyst-related features
Token properties from token docs:
- name: `SPOT`
- symbol: `SPOT`
- decimals: `18`
- total supply: `50,000,000`
- no minting function
- no owner / no special privileges on token contract
- burnable: users can burn their own tokens
Distribution model described in docs:
- about 99% treasury / locked treasury
- remaining portion for distribution wallet, staking allocations, and reward operations
- docs present a conservative release model
- project reference price used in docs: `$0.10`
Wallet display caveat:
- MetaMask/Rabby may show balances but no fiat value if third-party pricing/indexing services do not index SPOT
- on-chain balance and SpotBlock platform metrics remain source of truth
Roadmap direction:
- more practical utility via APIs, AML/institution-facing capabilities, faster transaction risk checks, deeper premium analysis flows
## 15. Contracts overview
Main contract set:
- `SpotBlockToken` / SPOT token
- `SpotSaleContract`
- `SpotStaking`
Deployed addresses listed in website docs:
Mainnet:
- SPOT token: `0xaA2F9D3d9E3A5F085FC03B75CA620ca2d05EAE73`
- SpotSaleContract: `0x1B2190465528FEABA1bcceD0d62bEe6EC943a095`
- SpotStaking: `0x99222f88b4Cff9165A9622d3D94A364d14e651FC`
Sepolia:
- SPOT token: `0xD085Df14A21255b2FEC69B4e2717633F7F4e6FAB`
- SpotSaleContract: `0xB0043fA9dc62fe6919b779e875fAa41145E97D8B`
- SpotStaking: `0x7626bdBf130B0BBDC47ce5E70B6F0DC6c6a3C7Ef`
## 16. SPOT token contract details
Token contract characteristics from `TOKEN_GUIDE.md`:
- standard ERC20
- burnable
- fixed supply
- no mint function
- no `owner()` / no `transferOwnership()`
Initial distribution in token guide:
- treasury: `49,500,000 SPOT`
- distribution wallet: `500,000 SPOT`
Functions available:
- standard ERC20:
- `transfer`
- `approve`
- `transferFrom`
- `balanceOf`
- `allowance`
- `totalSupply`
- additional:
- `burn`
- `burnFrom`
- `totalSupplyCap`
Important notes:
- all supply minted at deployment
- no owner privileges
- total supply decreases if holders burn
## 17. SpotSaleContract details
Purpose:
- sell SPOT in exchange for whitelisted ERC20s and ETH
Core features:
- whitelist system for payment tokens
- updatable prices
- owner can add/remove tokens from whitelist
- supports ETH and ERC20 payments
- buy-only, no selling
- reentrancy protection
Pricing model documented:
- `10 SPOT = 2 USD`
- `1 USD = 5 SPOT`
- `1 SPOT = 0.2 USD`
- price can be updated via `updateSpotPrice()`
User functions:
- `buyWithToken(address paymentToken, uint256 amount)`
- `buyWithETH()`
- `calculateSpotAmount(address paymentToken, uint256 amount)`
Owner/admin functions:
- `whitelistToken(address token, uint256 priceUSD)`
- `removeTokenFromWhitelist(address token)`
- `updateTokenPrice(address token, uint256 newPriceUSD)`
- `updateSpotPrice(uint256 newSpotPerUSD)`
- `updateETHPrice(uint256 newPriceUSD)`
- `depositSPOT(uint256 amount)`
- `withdrawTokens(address token, uint256 amount)`
- `withdrawETH()`
Default documented payment assets:
- WETH
- USDC
- USDT
Sale contract deployment guide says deployment script:
- deploys SpotSaleContract
- whitelists USDT, USDC, WETH
- sets ETH price to `$2000`
## 18. Staking contract status
Staking audit doc presents `SpotStaking` as:
- protected against reentrancy
- protected against integer over/underflow by Solidity 0.8.30
- protected with `Ownable` on admin functions
- using `SafeERC20`
- mathematically correct according to audit document
- production-ready according to audit document
Key staking points from audit:
- minimum stake requirement: `2 SPOT`
- core functions:
- `stake()`
- `unstake()`
- `claimRewards()`
- admin functions:
- `updateRewardRate()`
- `emergencyWithdraw()`
- reward formula uses:
- `stakedAmount`
- `rewardRateBps`
- `timeElapsed`
- `BASIS_POINTS`
- `SECONDS_PER_YEAR`
Audit summary status from doc:
- contract marked secure / approved for deployment
- 38/38 tests passing per audit document
## 19. Testing and deployment notes
Contracts repo uses Foundry.
Common tooling:
- `forge`
- `cast`
- `anvil`
Documented commands:
- build: `forge build`
- test: `forge test`
- local chain: `anvil`
Token testing:
- run all tests with `forge test`
- deploy locally with `forge script ...DeploySpotBlockToken`
Sale contract testing:
- recommended to test locally with Anvil using a Sepolia fork
- testing guide includes impersonation and cast-based purchase testing
Deployment emphasis:
- save deployed address
- fund sale contract with SPOT after deployment
- verify whitelisting and balances
## 20. 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
- validator API
- Discord validation
- Threat Check API
- wallet and contract real-time monitoring
- reward claim/admin flow components
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
## 21. Safe answering rules for another AI
When answering questions about SpotBlock:
- Do not say all APIs are public; only Threat Check API is explicitly public/live in docs.
- Distinguish between:
- scam scanner output
- Deep AI / Super-Analyst output
- human review verdict
- Do not describe `safe` from Threat Check API as a guarantee of benign behavior.
- Treat validator API as authenticated and wallet-signature based.
- Treat contributor rewards as configurable/operational, not legally fixed.
- Treat capability snapshot uptime/latency numbers as informational, not contractual.
- Treat staking audit statements as claims from the internal audit doc, not independent third-party assurance.
## 22. 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) human review through Discord and a wallet-signed validator API. The main public automation surface is `GET/POST /api/threat-check`, which returns `{ address, outcome: safe|threat, source: spotblock_db }`. Explorer is the main UI for search, Deep AI scans, and real-time monitoring. Medium-confidence scanner findings go to human review; suspicious/threat AI outcomes can be promoted into the public malicious explorer. SpotBlock also has an ERC20 token named SPOT with fixed 50M supply, a sale contract, and a staking contract. Contributors can work via Discord, form submission, or validator API and are rewarded through a SPOT-plus-USD-stable operational model.