| name | web3-security |
| description | Use when: security check, transaction simulation, is this safe, dry-run, pre-execution check, approve safety, token risk, scan transaction. 中文: 安全检查, 交易模拟, 安全扫描, 是否安全, 蜜罐检测, 授权检查. |
| license | MIT |
| metadata | {"author":"blocksecteam","version":"1.0.0"} |
Web3 Security — Simulation & Checks
Tag semantics (<NEVER> / <MUST> / <SHOULD>): see ~/.claude/skills/_shared/tags.md.
Supported chains are determined by the deployment configuration — run web3 chain list for the current set. Do not hardcode chain names in this skill.
Simulate a transaction and run risk checks before signing or broadcasting.
Step 0 — Re-route check
- Same-chain token swap (initiation) — HARD BLOCK: route to
web3-swap. The swap flow builds the intent before returning here for security check.
- Cross-chain bridge transfer (initiation) — HARD BLOCK: route to
web3-bridge. The bridge flow builds the intent before returning here for security check.
- Token transfer (initiation) — HARD BLOCK: route to
web3-chain. The transfer flow builds the intent before returning here for security check.
- Portfolio / balance / USD value — HARD BLOCK: route to
web3-portfolio.
- Token search / metadata / price — HARD BLOCK: route to
web3-token.
- Sign transaction / EIP-7702 delegation / account status — HARD BLOCK: route to
web3-ssm.
- Wallet create / delete / export → guide the user to the Wallets page.
- Signing policies management → guide the user to the Signing Policies page.
- SSM audit log review → guide the user to the SSM Audit page.
- Pre-execution security check or user override → stay in this skill.
Fail-safe Principle
Scan completed + risk detected → follow the verdict. Never override fail yourself.
Scan failed (network error, timeout, server error) → is NOT a pass. Stop and inform the user.
Running a Check
The CLI accepts only the intent id.
web3 security check --transaction-id txi_123
The response includes:
verdict — top-level aggregated outcome: pass / warn / fail (priority fail > warn > pass).
checks[] — per-rule findings. Each entry has rule (rule name), status (pass / warn / fail), detail (human-readable explanation), and optional observed evidence. The runtime list of rules and their semantics live in this array — do not maintain a separate rule enumeration in this doc. When you need to explain a specific rule's finding to the user, read its detail directly.
effect — per-owner spending / receiving / gas / net USD summary derived from the simulation.
The simulation.trace subtree is not in the default response. Run web3 security trace --transaction-id <transaction_id> when the user explicitly asks for the full trace or you need low-level call detail beyond checks[]/effect.
Verdict & Decision Fields
This skill documents what the agent sees. The end-to-end flow (check → decision → sign → broadcast, including override) lives in ~/.claude/skills/_shared/security-handling.md.
After web3 security check runs, you may receive a system message containing decision=<label>. The labels and required actions are:
decision= label | Required action |
|---|
passkey_required | The intent is cleared. Proceed to web3 ssm sign (Passkey still gates the actual signing). |
stop | Do not sign. Explain the failing reason to the user. |
wait_user_confirm | Do not sign. Ask the user to explicitly confirm; if they do, run web3 security override. |
The system message also includes:
static_verdict=<verdict> — same verdict field from the check output (pass / warn / fail)
verdict=<safe|unsafe> — the Security Agent's own review verdict
confidence=<high|medium|low> — the Security Agent's confidence
reason=<text> — free-form review reason (optional; present when the Security Agent provided one)
When explaining stop or wait_user_confirm to the user, prefer the reason= field if present; otherwise cite static_verdict and pull specifics from checks[] in the check output.
If a decision= label arrives, follow the table above. If a pass arrives with no decision= label, proceed to sign.
ERC-7821 Handling
ERC-7821 and normal transactions are semantically checked the same way. The only difference is calldata decoding:
- normal transaction → one operation
- ERC-7821
execute(bytes32,bytes) → decoded inner operations
Approvals and value movement are checked over the normalized operations.
Self-Transfer Recognition
tx_summary.wallet_address is the originating wallet. When it equals
tx_summary.to (transfer) or appears as an inner op to (ERC-7821), the
wallet is sending value to itself. Decoded ops show gross value;
effect.spending/receiving show net (zero by definition). Do not flag
this gross-vs-net divergence as a data contradiction.
- Always run security before signing or broadcasting transaction intents.
- A failed scan is NOT safe.
Error Codes
For any error.code returned by web3 security check / web3 security trace / web3 security override (simulation_failed, security_override_rejected, security_override_failed, the challenge_* family on override resume, invalid_state_transition, etc.) consult ~/.claude/skills/_shared/error-codes.md. transaction_intent_expired has its own file (~/.claude/skills/_shared/intent-expiry.md).