---
name: blockchain-web3-core
description: "Shared reference for the blockchain-web3 cluster: the adversarial on-chain threat model (immutable, anyone-can-call, MEV), checks-effects-interactions, oracle-manipulation resistance, token-decimals precision, and the non-advisory stance for trading/prediction-market work. USE WHEN writing, auditing, or reasoning about smart-contract / DeFi / on-chain code — the cross-cutting model every web3 spoke shares."
cluster: blockchain-web3
version: 1.0.0
origin: "affaan-m/ECC (MIT)"
---

# Blockchain / Web3 Core

Shared model for the `blockchain-web3` cluster. On-chain code is **immutable, public, and
adversarial** — once deployed, anyone can call it, read its state, and reorder/observe its
transactions. That single fact drives every rule below.

## 1. The adversarial model (decide everything from here)

- **Anyone can call any external function** in any order, any number of times. Never assume a
  caller, a sequence, or a single invocation.
- **Everything on-chain is public** — "private" variables are readable; no secrets in contract state.
- **Transactions are front-runnable / reorderable (MEV)** — the mempool is visible; assume an
  adversary can sandwich, front-run, or back-run any state-changing call.
- **Deployed code is immutable** (absent an upgrade proxy) — a bug is permanent and exploitable
  for the contract's full TVL. There is no "ship and patch."

## 2. Non-negotiable contract-safety rules

- **Checks-Effects-Interactions (CEI):** validate → update state → *then* make external calls. The
  canonical defense against **reentrancy** (+ a `nonReentrant` guard for value transfers). → `defi-amm-security`
- **Access control:** explicit, least-privilege roles; prefer two-step ownership transfer
  (`Ownable2Step`); never leave an unguarded `selfdestruct`/`delegatecall`.
- **Oracle manipulation:** never price off a spot AMM reserve an attacker can move in one block;
  use TWAP / multiple sources / circuit breakers. → `prediction-market-oracle-research`
- **Integer & decimals precision:** track token `decimals` explicitly; multiply before dividing;
  beware rounding that leaks value; validate the donation/inflation attack on share-based vaults. → `evm-token-decimals`
- **Validate all inputs** (the webview-is-untrusted rule, on-chain edition): the caller is hostile.

## 3. Routing within the cluster

| Concern | Spoke |
|---|---|
| AMM / vault / DeFi security review | `defi-amm-security` |
| Token decimals / precision bugs | `evm-token-decimals` |
| LLM/agent that touches a wallet or trades | `llm-trading-agent-security` |
| Hashing / keccak256 utility | `nodejs-keccak256` |
| Prediction-market oracle / risk research | `prediction-market-oracle-research`, `prediction-market-risk-review` |

## 4. Non-advisory stance (hard guardrail)

The prediction-market and trading spokes produce **research and risk analysis, not
financial advice**. Never present an output as a recommendation to buy/sell, never auto-execute a
trade or move funds, and always surface assumptions + downside/risk. An agent with wallet access
(`llm-trading-agent-security`) must gate every value-moving action behind explicit human confirmation.

## 5. Tooling / version matrix

| Need | Tool |
|---|---|
| Build / test (Solidity) | Foundry (`forge`) or Hardhat |
| Static analysis | Slither, Mythril; `forge` invariant/fuzz tests |
| Standards | OpenZeppelin (audited primitives) over hand-rolled |
| Hashing off-chain | `nodejs-keccak256` (match on-chain `keccak256` exactly) |

## 6. Shared guardrails

- Assume adversarial callers, public state, and MEV — always.
- Checks-Effects-Interactions + reentrancy guards on every external interaction.
- No spot-reserve price oracles; TWAP / multi-source.
- Track decimals explicitly; multiply-before-divide.
- Audited primitives (OpenZeppelin) over bespoke crypto.
- Trading/prediction outputs are non-advisory; never auto-move funds; gate on human confirmation.
- Treat deployed code as permanent — audit + test (fuzz/invariant) before mainnet.