web3skill 0.1.0

package/dist/skills/web3-static-analysis-runner/references/TRIAGE_BUCKETS.md

@@ -0,0 +1,16 @@
+# Static Analysis Triage Buckets
+
+Normalize static-analysis output into these buckets:
+
+- `confirmed-finding`
+  - root cause validated with exploit relevance or direct code proof
+- `review-needed`
+  - plausible issue that still needs human validation or environment support
+- `false-positive`
+  - tool hit does not survive code review or context check
+
+## Rules
+
+- Deduplicate by root cause, not by scanner line count.
+- A single root cause can have evidence from multiple scanners.
+- If scanners cannot run because the repo will not build or the environment is missing, put that in blockers instead of inventing triage.

package/dist/skills/web3-static-analysis-runner/scripts/render_static_analysis_summary.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Render a stable Web3 static-analysis summary block."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a Web3 static-analysis summary block.")
+    parser.add_argument("--scope", required=True)
+    parser.add_argument("--status", choices=("complete", "partial", "blocked"), default="partial")
+    parser.add_argument("--scanner", action="append", default=[])
+    parser.add_argument("--raw-hit-count", type=int, default=0)
+    parser.add_argument("--root-cause", action="append", default=[])
+    parser.add_argument("--confirmed-count", type=int, default=0)
+    parser.add_argument("--review-needed-count", type=int, default=0)
+    parser.add_argument("--false-positive-count", type=int, default=0)
+    parser.add_argument("--blocker", action="append", default=[])
+    parser.add_argument("--next-step", action="append", default=[])
+    parser.add_argument("--evidence", action="append", default=[])
+    return parser
+
+
+def parse_evidence(entries: list[str]) -> list[dict[str, str]]:
+    parsed = []
+    for entry in entries:
+        adapter, sep, detail = entry.partition(":")
+        if sep:
+            parsed.append({"adapter": adapter.strip(), "detail": detail.strip()})
+        else:
+            parsed.append({"adapter": "unknown", "detail": entry})
+    return parsed
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    payload = {
+        "static_analysis_summary": {
+            "version": 1,
+            "status": args.status,
+            "scope": args.scope,
+            "scanners_run": args.scanner,
+            "raw_hit_count": args.raw_hit_count,
+            "deduped_root_causes": args.root_cause,
+            "escalation_counts": {
+                "confirmed_finding": args.confirmed_count,
+                "review_needed": args.review_needed_count,
+                "false_positive": args.false_positive_count,
+            },
+            "blockers": args.blocker,
+            "next_steps": args.next_step,
+            "evidence": parse_evidence(args.evidence),
+        }
+    }
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/skills/web3-trace-and-state-analysis/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: web3-trace-and-state-analysis
+description: Trace and state analysis layer for transaction inspection, trace_call style reasoning, proxy/delegatecall analysis, and storage/state deltas. Use for tx hashes, suspicious calls, archive-node analysis, and call-path debugging.
+---
+
+# Web3 Trace And State Analysis
+
+Use this skill for transaction tracing, forward call inspection, proxy path analysis, and state-change attribution.
+
+## Required Components
+
+- Read `evm-mcp-playbook` for live chain access and backend setup.
+- Prefer these Web3 profile adapters when applicable:
+  - `behavioral-state-analysis`
+  - `entry-point-analyzer`
+  - `etherscan`
+
+Use [references/ADAPTER_CONSUMPTION_MAP.md](references/ADAPTER_CONSUMPTION_MAP.md)
+to normalize adapter evidence into a stable trace/state summary.
+Use [references/TRACE_BACKEND_PREFLIGHT.md](references/TRACE_BACKEND_PREFLIGHT.md)
+before claiming trace coverage or readiness.
+Use [references/OUTPUT_TEMPLATE.md](references/OUTPUT_TEMPLATE.md) and
+[scripts/render_trace_summary.py](scripts/render_trace_summary.py) when a downstream
+skill needs stable machine-consumable output.
+
+## Workflow
+
+1. Name chain, backend class, and block context.
+2. Determine whether this is:
+   - historical tx analysis
+   - forward-looking call analysis
+   - repo-assisted state analysis
+3. Use live reads or tracing backend to inspect call path, logs, code, and storage.
+4. If repo code is available, use `entry-point-analyzer` to map state-changing entry points.
+5. Use `behavioral-state-analysis` to explain risk, invariants, and exploit relevance.
+
+## Reusable Output Contract
+
+Always emit both:
+
+1. A short trace/state explanation for the user
+2. A normalized `trace_summary` block for downstream operator or audit flows
+
+The normalized block must preserve:
+
+- `status`
+- `subject`
+- chain, block, and backend readiness
+- call chain edges
+- state changes
+- risk notes and unknowns
+- exact evidence source per observation
+
+## Output Schema
+
+```text
+Context:
+- chain / block / backend
+Call Chain:
+- caller -> callee -> delegatecall / external call path
+State Changes:
+- key storage or balance changes
+Risk Notes:
+- privilege transition, token flow, upgrade path, invariant break
+Unknowns:
+- missing trace support, missing source, ambiguous state slot
+```
+
+## Guardrails
+
+- If the backend does not expose trace methods, say so clearly and fall back to code/storage/call-only analysis.
+- Distinguish historical traces from forward simulation.
+- Never claim a full state diff when only logs or receipts were inspected.
+- If backend readiness is partial or missing, reflect that in the normalized block instead of hiding the gap.

package/dist/skills/web3-trace-and-state-analysis/references/ADAPTER_CONSUMPTION_MAP.md

@@ -0,0 +1,27 @@
+# Trace Adapter Consumption Map
+
+- `behavioral-state-analysis` -> risk notes, invariant context, exploit relevance
+- `entry-point-analyzer` -> entrypoints, privilege boundaries, state-changing surface
+- `etherscan` -> ABI, verified source, proxy implementation, tx/account evidence
+
+Normalize into:
+
+```yaml
+trace_summary:
+  status: COMPLETE | PARTIAL | UNAVAILABLE
+  subject: historical-tx | forward-call | repo-assisted
+  backend:
+    class: archive-rpc | debug-trace-rpc | explorer-plus-abi | repo-assisted | mixed
+    readiness: ready | partial | missing
+  call_chain:
+    - caller -> callee
+  state_changes:
+    - concrete storage or balance delta
+  risk_notes:
+    - privilege / flow / invariant interpretation
+  unknowns:
+    - remaining ambiguity
+  evidence:
+    - adapter: name
+      detail: exact supporting hit
+```

package/dist/skills/web3-trace-and-state-analysis/references/OUTPUT_TEMPLATE.md

@@ -0,0 +1,63 @@
+# Web3 Trace Output Template
+
+Always emit:
+
+1. A short human-readable trace/state summary
+2. A normalized block
+
+```yaml
+trace_summary:
+  version: 1
+  status: PARTIAL
+  subject: historical-tx
+  chain: base
+  block: 28765432
+  backend:
+    class: mixed
+    readiness: partial
+    methods:
+      - eth_getTransactionReceipt
+      - getsourcecode
+  scope:
+    tx_hash: 0xabc
+    from: 0xcaller
+    to: 0xrouter
+    function: swapExactTokensForTokens
+  call_chain:
+    - 0xcaller -> 0xrouter
+    - 0xrouter -> 0xpair
+  state_changes:
+    - balance[tokenOut][receiver] increases
+    - allowance[tokenIn][router] decreases
+  risk_notes:
+    - proxy implementation resolved through explorer metadata only
+  unknowns:
+    - no internal trace for delegatecall branch
+  next_steps:
+    - rerun on a trace-capable archive backend
+  follow_up_skills:
+    - web3-native-operator
+  evidence:
+    - adapter: etherscan
+      detail: proxy implementation and verified ABI fetched
+    - adapter: entry-point-analyzer
+      detail: router path touches external callback surface
+```
+
+## Required Fields
+
+- `status`: `COMPLETE | PARTIAL | UNAVAILABLE`
+- `subject`: `historical-tx | forward-call | repo-assisted`
+- `chain`
+- `backend`
+- `call_chain`
+- `state_changes`
+- `risk_notes`
+- `unknowns`
+- `evidence`
+
+## Notes
+
+- Use empty lists instead of dropping list fields.
+- `status = UNAVAILABLE` still requires concrete `unknowns` and a next step.
+- Do not promote inferred state changes to confirmed ones without supporting evidence.

package/dist/skills/web3-trace-and-state-analysis/references/TRACE_BACKEND_PREFLIGHT.md

@@ -0,0 +1,47 @@
+# Trace Backend Preflight
+
+Use this checklist before claiming trace coverage.
+
+## Backend Classes
+
+- `archive-rpc`
+  - historical state reads and archive storage available
+- `debug-trace-rpc`
+  - `trace_call`, `debug_traceCall`, `debug_traceTransaction`, or equivalent available
+- `explorer-plus-abi`
+  - verified source, ABI, receipts, token transfers, and proxy metadata available
+- `repo-assisted`
+  - local source code available for entry-point and storage interpretation
+- `mixed`
+  - more than one backend class combined
+
+## Readiness
+
+- `ready`
+  - trace methods or equivalent archive capability confirmed
+  - enough data to attribute internal calls or state deltas with confidence
+- `partial`
+  - receipts, logs, explorer metadata, or repo analysis available
+  - but full internal call path or precise state diff is incomplete
+- `missing`
+  - no trace-capable backend and no credible fallback evidence
+
+## Minimum Preflight Questions
+
+1. Which chain and block context are in scope?
+2. Is this a historical tx, forward-looking call, or repo-assisted path analysis?
+3. Does the backend expose trace methods or only explorer/receipt data?
+4. Is verified source or local source available?
+5. Can balances, storage, or proxy implementation slots be cross-checked?
+
+## Status Mapping
+
+- `ready` -> `trace_summary.status = COMPLETE`
+- `partial` -> `trace_summary.status = PARTIAL`
+- `missing` -> `trace_summary.status = UNAVAILABLE`
+
+## Guardrails
+
+- Do not report `COMPLETE` if you only inspected receipts or logs.
+- If proxy resolution or storage attribution is inferred from source without live validation, keep readiness at `partial`.
+- If the action is safety-critical and readiness is not `ready`, tell the operator to keep the flow in investigate mode.

package/dist/skills/web3-trace-and-state-analysis/scripts/render_trace_summary.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Render a stable Web3 trace summary block from normalized backend evidence."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a Web3 trace summary block.")
+    parser.add_argument(
+        "--subject",
+        choices=("historical-tx", "forward-call", "repo-assisted"),
+        required=True,
+    )
+    parser.add_argument("--chain", required=True)
+    parser.add_argument("--block", default="latest")
+    parser.add_argument(
+        "--backend-class",
+        choices=("archive-rpc", "debug-trace-rpc", "explorer-plus-abi", "repo-assisted", "mixed"),
+        required=True,
+    )
+    parser.add_argument(
+        "--backend-readiness",
+        choices=("ready", "partial", "missing"),
+        required=True,
+    )
+    parser.add_argument("--method", action="append", default=[])
+    parser.add_argument("--tx-hash", default="")
+    parser.add_argument("--from-address", default="")
+    parser.add_argument("--to-address", default="")
+    parser.add_argument("--function", default="")
+    parser.add_argument("--call-edge", action="append", default=[])
+    parser.add_argument("--state-change", action="append", default=[])
+    parser.add_argument("--risk-note", action="append", default=[])
+    parser.add_argument("--unknown", action="append", default=[])
+    parser.add_argument("--next-step", action="append", default=[])
+    parser.add_argument("--follow-up-skill", action="append", default=[])
+    parser.add_argument("--evidence", action="append", default=[])
+    return parser
+
+
+def choose_status(readiness: str) -> str:
+    if readiness == "ready":
+        return "COMPLETE"
+    if readiness == "partial":
+        return "PARTIAL"
+    return "UNAVAILABLE"
+
+
+def parse_evidence(entries: list[str]) -> list[dict[str, str]]:
+    parsed = []
+    for entry in entries:
+        adapter, sep, detail = entry.partition(":")
+        if not sep:
+            parsed.append({"adapter": "unknown", "detail": entry})
+            continue
+        parsed.append({"adapter": adapter.strip(), "detail": detail.strip()})
+    return parsed
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    payload = {
+        "trace_summary": {
+            "version": 1,
+            "status": choose_status(args.backend_readiness),
+            "subject": args.subject,
+            "chain": args.chain,
+            "block": args.block,
+            "backend": {
+                "class": args.backend_class,
+                "readiness": args.backend_readiness,
+                "methods": args.method,
+            },
+            "scope": {
+                "tx_hash": args.tx_hash,
+                "from": args.from_address,
+                "to": args.to_address,
+                "function": args.function,
+            },
+            "call_chain": args.call_edge,
+            "state_changes": args.state_change,
+            "risk_notes": args.risk_note,
+            "unknowns": args.unknown,
+            "next_steps": args.next_step,
+            "follow_up_skills": args.follow_up_skill,
+            "evidence": parse_evidence(args.evidence),
+        }
+    }
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/skills/web3-transaction-simulator/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: web3-transaction-simulator
+description: Pre-execution simulation layer for swaps, approvals, transfers, and liquidity actions. Use after risk gating and before any chain write. It combines venue planners with live read checks and returns a normalized go/no-go summary.
+---
+
+# Web3 Transaction Simulator
+
+Use this skill after `web3-risk-gate` and before any chain write.
+
+## Required Adapters
+
+Load the adapter that matches the action:
+
+- `swap-planner`
+- `liquidity-planner`
+- `token-swap`
+- `hyperliquid`
+
+For live balances, allowance, code, or call checks, also read `evm-mcp-playbook`.
+For gas-sensitive routing or timing, use `gas-tracker`.
+When consuming adapter output, prefer each adapter's `references/SIMULATION_NORMALIZATION.md`
+or mode-specific template so route and failure labels remain stable.
+
+## Workflow
+
+1. Collect chain, input/output asset, amount, slippage, receiver, and deadline.
+2. Use the venue planner to get a route, quote, or execution plan.
+3. Use live reads to verify balance, allowance, target code, and basic preconditions.
+4. Normalize the result before any execution step.
+
+## Reusable Output Contract
+
+Always emit both:
+
+1. A short human-readable simulation summary
+2. A normalized block that downstream execution or routing skills can reuse
+
+Use [references/OUTPUT_TEMPLATE.md](references/OUTPUT_TEMPLATE.md) for the exact scaffold.
+Use [references/STATUS_AND_FAILURES.md](references/STATUS_AND_FAILURES.md) when classifying
+`PASS`, `WARN`, `FAIL`, or `NO_SIMULATION`.
+When deterministic merge behavior is needed, use
+[scripts/merge_simulation_blocks.py](scripts/merge_simulation_blocks.py)
+to combine multiple adapter-produced `simulation` blocks into one conservative result.
+
+The minimum fields are:
+
+```text
+Simulation: PASS | WARN | FAIL | NO_SIMULATION
+Action:
+- transfer | approve | swap | liquidity | perp-order
+Venue:
+- uniswap | hyperliquid | token-swap | unknown
+Preconditions:
+- balance / allowance / route assumptions
+Expected Result:
+- quoted output or expected state change
+Failure Modes:
+- revert reason, liquidity risk, unsupported path, missing backend
+Readiness:
+- ready | needs-confirmation | blocked
+Next Step:
+- proceed | adjust params | stop
+Evidence:
+- quote source or simulation backend
+```
+
+The normalized block must preserve:
+
+- simulation status
+- action type and venue
+- route assumptions
+- readiness and blockers
+- exact failure classification
+- next step and evidence source
+
+## Guardrails
+
+- Never execute from this skill. Stop at plan, quote, or simulation summary.
+- If the target token is not yet risk-gated, send the flow back to `web3-risk-gate`.
+- If no reliable quote or call simulation exists, return `NO_SIMULATION`.
+- Separate quote quality from token safety. A good quote does not imply a safe token.
+- Distinguish missing simulation infrastructure from an actual transaction failure.
+- If the route is available but preconditions are not met, return `WARN` or `FAIL`, not `NO_SIMULATION`.

package/dist/skills/web3-transaction-simulator/references/OUTPUT_TEMPLATE.md

@@ -0,0 +1,86 @@
+# Web3 Transaction Simulator Output Template
+
+Always emit two sections in this order.
+
+## 1. Human Summary
+
+```text
+Simulation: WARN
+Action:
+- swap
+Venue:
+- uniswap
+Preconditions:
+- Wallet balance is sufficient
+- Allowance is missing for router 0x...
+- Quote assumes 0.5% slippage and current pool reserves
+Expected Result:
+- Estimated output: 1,243.11 TOKEN
+- Expected state change: approve router, then swap exact input
+Failure Modes:
+- Approval missing
+- Quote may degrade if liquidity moves before execution
+Readiness:
+- needs-confirmation
+Next Step:
+- set allowance or use permit path
+- rerun simulation after allowance is available
+Evidence:
+- swap-planner quote at current route
+- evm-mcp-playbook allowance read
+```
+
+## 2. Normalized Block
+
+Use this exact field layout. Omit empty optional arrays, but do not rename fields.
+
+```yaml
+simulation:
+  version: 1
+  status: WARN
+  action: swap
+  venue: uniswap
+  chain: ethereum
+  readiness: needs-confirmation
+  route:
+    input_token: "0x..."
+    output_token: "0x..."
+    amount_in: "1.0 ETH"
+    slippage_bps: 50
+  preconditions:
+    - type: balance-ok
+      source: evm-mcp-playbook
+      detail: wallet balance covers amount and gas
+    - type: allowance-missing
+      source: evm-mcp-playbook
+      detail: router has no allowance
+  expected_result:
+    quoted_out: "1243.11 TOKEN"
+    state_change: approve then swap
+  failure_modes:
+    - type: missing-allowance
+      severity: medium
+      source: evm-mcp-playbook
+      detail: swap would revert without prior approval
+    - type: quote-drift
+      severity: low
+      source: swap-planner
+      detail: output depends on live liquidity at execution time
+  next_step:
+    - adjust params
+    - rerun simulation
+  evidence:
+    - adapter: swap-planner
+      signal: route quote
+      exact_hit: best path at current reserves
+    - adapter: evm-mcp-playbook
+      signal: allowance read
+      exact_hit: allowance is zero
+```
+
+## Notes
+
+- `status` is mandatory and must be one of `PASS`, `WARN`, `FAIL`, `NO_SIMULATION`.
+- `readiness` is mandatory and must be one of `ready`, `needs-confirmation`, `blocked`.
+- `NO_SIMULATION` is for missing or unreliable simulation capability, not for normal transaction reverts.
+- `failure_modes` should distinguish hard blockers from parameter issues.

package/dist/skills/web3-transaction-simulator/references/STATUS_AND_FAILURES.md

@@ -0,0 +1,49 @@
+# Web3 Transaction Simulator Status And Failure Rules
+
+Use these stable classifications.
+
+## Status
+
+- `PASS`
+  - A reliable quote or simulation exists.
+  - Preconditions are satisfied.
+  - No material blocker is detected.
+
+- `WARN`
+  - A route or simulation exists, but some precondition or parameter still needs user action.
+  - Example: missing allowance, slippage too loose, thin liquidity, permit path not confirmed.
+
+- `FAIL`
+  - A reliable simulation predicts revert, unacceptable loss, or clearly unsafe execution.
+  - Example: insufficient balance, guaranteed revert, route unavailable for requested size.
+
+- `NO_SIMULATION`
+  - The system cannot obtain a trustworthy simulation or quote.
+  - Example: unsupported venue backend, missing archive / tenderly backend, planner unavailable.
+
+## Readiness
+
+- `ready`
+  - User could proceed after confirmation.
+- `needs-confirmation`
+  - Parameters or preconditions still need fixing or confirming.
+- `blocked`
+  - Execution should not proceed.
+
+## Failure Type Labels
+
+- `missing-allowance`
+- `insufficient-balance`
+- `unsupported-route`
+- `quote-drift`
+- `liquidity-too-thin`
+- `gas-too-high`
+- `revert-predicted`
+- `backend-unavailable`
+- `venue-unreachable`
+
+## Mapping Rules
+
+- If backend access is the main problem, prefer `NO_SIMULATION` with a failure type like `backend-unavailable`.
+- If backend works and predicts revert, use `FAIL`, not `NO_SIMULATION`.
+- If the only issue is user-adjustable and execution may still succeed later, prefer `WARN`.