web3skill 0.1.0

package/dist/skills/web3-research-and-market-intel/scripts/render_research_brief.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Render a stable Web3 research brief block."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a Web3 research brief block.")
+    parser.add_argument("--question", required=True)
+    parser.add_argument("--freshness", choices=("fresh", "mixed", "stale"), default="mixed")
+    parser.add_argument("--source", action="append", default=[])
+    parser.add_argument("--evidence", action="append", default=[])
+    parser.add_argument("--cross-check", action="append", default=[])
+    parser.add_argument(
+        "--conclusion",
+        choices=("watch", "investigate-more", "ready-for-risk-gate", "avoid-for-now"),
+        required=True,
+    )
+    parser.add_argument("--next-step", 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 = {
+        "research_brief": {
+            "version": 1,
+            "question": args.question,
+            "freshness": args.freshness,
+            "sources_used": args.source,
+            "evidence": parse_evidence(args.evidence),
+            "cross_checks": args.cross_check,
+            "conclusion": args.conclusion,
+            "next_steps": args.next_step,
+        }
+    }
+    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-research-and-market-intel/scripts/render_watch_status.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Render a stable Web3 watch status block."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a Web3 watch status block.")
+    parser.add_argument(
+        "--status",
+        choices=("ACTIVE", "TRIGGERED", "CLEARED", "UNAVAILABLE"),
+        required=True,
+    )
+    parser.add_argument(
+        "--watch-kind",
+        choices=("research", "portfolio", "posttrade", "trace", "venue", "execution"),
+        required=True,
+    )
+    parser.add_argument("--subject", required=True)
+    parser.add_argument("--trigger-source", default="")
+    parser.add_argument(
+        "--severity",
+        choices=("low", "medium", "high", "critical"),
+        default="medium",
+    )
+    parser.add_argument("--next-check-hint", default="")
+    parser.add_argument("--schedule-hint", default="")
+    parser.add_argument("--recommended-adapter", default="")
+    parser.add_argument("--evidence", action="append", default=[])
+    return parser
+
+
+def parse_evidence(entries: list[str]) -> list[dict[str, str]]:
+    parsed: list[dict[str, str]] = []
+    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 = {
+        "watch_status": {
+            "version": 1,
+            "status": args.status,
+            "watch_kind": args.watch_kind,
+            "subject": args.subject,
+            "trigger_source": args.trigger_source,
+            "severity": args.severity,
+            "next_check_hint": args.next_check_hint,
+            "schedule_hint": args.schedule_hint,
+            "recommended_adapter": args.recommended_adapter,
+            "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-risk-gate/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: web3-risk-gate
+description: Pre-execution Web3 risk gate for transfers, approvals, swaps, and protocol interactions. Use before any value-moving or approval-changing action. It normalizes adapter output into ALLOW, WARN, or BLOCK.
+---
+
+# Web3 Risk Gate
+
+Use this skill before any transfer, approval, swap, liquidity action, or contract interaction that can move funds or grant permissions.
+
+## Required Adapters
+
+Load the matching Web3 profile adapters instead of improvising:
+
+- `security-check`
+- `binance-token-audit`
+- `query-token-audit`
+- `query-address-info`
+- `token-integration-analyzer`
+- `proxy-upgrade-safety`
+
+When consuming adapter output, prefer each adapter's `references/RISK_GATE_NORMALIZATION.md`
+to keep signal names and evidence fields stable.
+
+## Workflow
+
+1. Identify the action type: transfer, approve, swap, LP, or protocol interaction.
+2. Identify the subject: token, spender, receiver, router, proxy, or external protocol.
+3. Run the relevant adapter checks.
+4. Normalize the result into one gate decision.
+
+## Reusable Output Contract
+
+Always emit both:
+
+1. A short human-readable gate summary
+2. A normalized block that other Web3 skills can reuse
+
+Use [references/OUTPUT_TEMPLATE.md](references/OUTPUT_TEMPLATE.md) for the exact scaffold.
+If you need to map adapter findings into stable blocker/warning labels, use
+[references/SIGNAL_TAXONOMY.md](references/SIGNAL_TAXONOMY.md).
+When deterministic merge behavior is needed, use
+[scripts/merge_risk_gate_blocks.py](scripts/merge_risk_gate_blocks.py)
+to combine multiple adapter-produced `risk_gate` blocks into one conservative result.
+
+The minimum decision fields are:
+
+```text
+Decision: ALLOW | WARN | BLOCK
+Action:
+- transfer | approve | swap | liquidity | protocol-interaction
+Coverage:
+- complete | partial | missing
+Reasons:
+- concrete signal
+Warnings:
+- optional risk signal
+Must-Do Next:
+- required follow-up
+Evidence:
+- adapter name + exact hit
+```
+
+The normalized block must preserve:
+
+- decision
+- action type
+- chain and subject
+- coverage quality
+- blockers and warnings as separate lists
+- next steps
+- exact evidence source per signal
+
+## Hard Block Conditions
+
+Block by default if any checked source confirms one of:
+
+- honeypot / unsellable token
+- risk level `5` from Binance token audit
+- selfdestruct risk on live token or target contract
+- hidden owner combined with mint / reclaim ownership path
+- storage collision or uninitialized implementation in an upgrade path
+- clear proxy takeover or arbitrary upgrade control
+
+## Warning Conditions
+
+Warn and require explicit confirmation if any checked source shows:
+
+- buy or sell tax above 10%
+- proxy / upgradeable token or contract
+- mintable supply or concentrated owner control
+- missing verification / opaque code
+- abnormal holder concentration or thin distribution
+
+## Guardrails
+
+- Do not average away critical signals just because another adapter returned a lower risk score.
+- If the action is a swap, require `web3-transaction-simulator` after this gate.
+- If adapter coverage is missing for the target chain or token, say `coverage incomplete` instead of implying safety.
+- If evidence is weak or adapter coverage is partial, downgrade certainty, not the signal itself.
+- If the output will be consumed by another skill, keep the normalized block stable and do not rename fields ad hoc.

package/dist/skills/web3-risk-gate/references/OUTPUT_TEMPLATE.md

@@ -0,0 +1,72 @@
+# Web3 Risk Gate Output Template
+
+Always emit two sections in this order.
+
+## 1. Human Summary
+
+```text
+Decision: BLOCK
+Action:
+- swap
+Coverage:
+- partial
+Reasons:
+- Honeypot risk confirmed by query-token-audit
+- Proxy upgrade path is externally controlled
+Warnings:
+- Holder concentration is elevated
+Must-Do Next:
+- Do not execute this swap
+- If still investigating, fetch verified source and owner privileges
+Evidence:
+- query-token-audit: honeypot / unsellable token flag
+- proxy-upgrade-safety: arbitrary upgrade control
+```
+
+## 2. Normalized Block
+
+Use this exact field layout. Omit empty optional arrays, but do not rename fields.
+
+```yaml
+risk_gate:
+  version: 1
+  decision: BLOCK
+  action: swap
+  chain: bsc
+  coverage: partial
+  subject:
+    token: "0x..."
+    router: "0x..."
+    spender: "0x..."
+  blockers:
+    - type: honeypot
+      severity: critical
+      source: query-token-audit
+      detail: unsellable token
+    - type: unsafe-upgrade-control
+      severity: critical
+      source: proxy-upgrade-safety
+      detail: privileged arbitrary implementation change
+  warnings:
+    - type: holder-concentration
+      severity: medium
+      source: binance-token-audit
+      detail: top holders dominate supply
+  next_steps:
+    - stop
+    - gather verified source and owner privilege evidence
+  evidence:
+    - adapter: query-token-audit
+      signal: honeypot
+      exact_hit: unsellable token flag
+    - adapter: proxy-upgrade-safety
+      signal: arbitrary upgrade control
+      exact_hit: implementation can be changed by privileged actor
+```
+
+## Notes
+
+- `decision` is mandatory and must be one of `ALLOW`, `WARN`, `BLOCK`.
+- `coverage` is mandatory and must be one of `complete`, `partial`, `missing`.
+- `blockers` and `warnings` are separate. Do not merge them.
+- `evidence` should retain adapter-level provenance so later skills can cite it.

package/dist/skills/web3-risk-gate/references/SIGNAL_TAXONOMY.md

@@ -0,0 +1,34 @@
+# Web3 Risk Gate Signal Taxonomy
+
+Use these stable labels when normalizing adapter output.
+
+## Blocker Types
+
+- `honeypot`
+- `unsellable-token`
+- `malicious-upgrade-path`
+- `unsafe-upgrade-control`
+- `hidden-owner-with-mint`
+- `storage-collision-risk`
+- `uninitialized-implementation`
+- `selfdestruct-risk`
+- `known-blacklist-hit`
+- `unsafe-token-callback`
+
+## Warning Types
+
+- `high-tax`
+- `mintable-supply`
+- `upgradeable-contract`
+- `opaque-code`
+- `holder-concentration`
+- `unverified-contract`
+- `allowance-exposure`
+- `admin-centralization`
+
+## Mapping Rules
+
+- If any blocker type is confirmed, the decision is `BLOCK`.
+- If only warning types are present, the decision is `WARN` unless the action is strictly read-only.
+- If coverage is missing for the primary subject, keep the decision conservative and mark `coverage: missing` or `partial`.
+- Do not invent new labels when an existing label is close enough. Stable labels are more useful than expressive prose.

package/dist/skills/web3-risk-gate/scripts/merge_risk_gate_blocks.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""Merge multiple normalized risk_gate blocks into one conservative decision."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+COVERAGE_ORDER = {
+    "complete": 0,
+    "partial": 1,
+    "missing": 2,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Merge multiple risk_gate payloads into one block.")
+    parser.add_argument(
+        "--input-file",
+        action="append",
+        required=True,
+        help="Path to a JSON file containing a risk_gate payload or '-' for stdin",
+    )
+    return parser
+
+
+def load_payload(path: str) -> dict[str, object]:
+    if path == "-":
+        return json.load(sys.stdin)
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def extract_gate(payload: dict[str, object]) -> dict[str, object]:
+    gate = payload.get("risk_gate")
+    if isinstance(gate, dict):
+        return gate
+    if {"decision", "action", "chain", "coverage"}.issubset(payload):
+        return payload
+    raise ValueError("input payload does not contain risk_gate")
+
+
+def merge_scalar(current: str, new_value: str, field_name: str) -> str:
+    if not new_value:
+        return current
+    if not current:
+        return new_value
+    if current != new_value:
+        raise ValueError(f"conflicting {field_name}: {current} vs {new_value}")
+    return current
+
+
+def merge_subject(subject: dict[str, object], new_subject: dict[str, object]) -> dict[str, object]:
+    merged = dict(subject)
+    for key, value in new_subject.items():
+        if key in merged and merged[key] != value:
+            raise ValueError(f"conflicting subject field {key}: {merged[key]} vs {value}")
+        merged[key] = value
+    return merged
+
+
+def dedupe_items(items: list[dict[str, object]]) -> list[dict[str, object]]:
+    seen: set[str] = set()
+    deduped: list[dict[str, object]] = []
+    for item in items:
+        key = json.dumps(item, sort_keys=True, ensure_ascii=False)
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(item)
+    return deduped
+
+
+def dedupe_strings(items: list[str]) -> list[str]:
+    seen: set[str] = set()
+    deduped: list[str] = []
+    for item in items:
+        if item in seen:
+            continue
+        seen.add(item)
+        deduped.append(item)
+    return deduped
+
+
+def default_next_steps(decision: str, action: str, coverage: str) -> list[str]:
+    if decision == "BLOCK":
+        return ["stop", "collect additional evidence before retrying"]
+
+    steps: list[str] = []
+    if coverage != "complete":
+        steps.append("gather missing adapter coverage")
+    if decision == "WARN":
+        steps.append("require explicit confirmation")
+    if action in {"transfer", "approve", "swap", "liquidity", "protocol-interaction"}:
+        steps.append("run web3-transaction-simulator")
+    if not steps:
+        steps.append("continue with standard confirmation")
+    return steps
+
+
+def merge_payloads(payloads: list[dict[str, object]]) -> dict[str, object]:
+    action = ""
+    chain = ""
+    subject: dict[str, object] = {}
+    coverages: list[str] = []
+    blockers: list[dict[str, object]] = []
+    warnings: list[dict[str, object]] = []
+    evidence: list[dict[str, object]] = []
+    next_steps: list[str] = []
+    seen_warn = False
+    seen_block = False
+
+    for payload in payloads:
+        gate = extract_gate(payload)
+        gate_action = str(gate.get("action", ""))
+        gate_chain = str(gate.get("chain", ""))
+        gate_coverage = str(gate.get("coverage", "partial"))
+        if gate_coverage not in COVERAGE_ORDER:
+            raise ValueError(f"unsupported coverage value: {gate_coverage}")
+
+        action = merge_scalar(action, gate_action, "action")
+        chain = merge_scalar(chain, gate_chain, "chain")
+        coverages.append(gate_coverage)
+        seen_warn = seen_warn or str(gate.get("decision", "")) == "WARN"
+        seen_block = seen_block or str(gate.get("decision", "")) == "BLOCK"
+
+        gate_subject = gate.get("subject", {})
+        if isinstance(gate_subject, dict):
+            subject = merge_subject(subject, gate_subject)
+
+        gate_blockers = gate.get("blockers", [])
+        if isinstance(gate_blockers, list):
+            blockers.extend(item for item in gate_blockers if isinstance(item, dict))
+        gate_warnings = gate.get("warnings", [])
+        if isinstance(gate_warnings, list):
+            warnings.extend(item for item in gate_warnings if isinstance(item, dict))
+        gate_evidence = gate.get("evidence", [])
+        if isinstance(gate_evidence, list):
+            evidence.extend(item for item in gate_evidence if isinstance(item, dict))
+        gate_next_steps = gate.get("next_steps", [])
+        if isinstance(gate_next_steps, list):
+            next_steps.extend(str(item) for item in gate_next_steps if isinstance(item, str))
+
+    coverage = max(coverages, key=lambda item: COVERAGE_ORDER[item]) if coverages else "missing"
+    blockers = dedupe_items(blockers)
+    warnings = dedupe_items(warnings)
+    evidence = dedupe_items(evidence)
+
+    if blockers or seen_block:
+        decision = "BLOCK"
+    elif warnings or seen_warn or coverage != "complete":
+        decision = "WARN"
+    else:
+        decision = "ALLOW"
+
+    next_steps = dedupe_strings(next_steps) or default_next_steps(decision, action, coverage)
+
+    payload: dict[str, object] = {
+        "risk_gate": {
+            "version": 1,
+            "decision": decision,
+            "action": action,
+            "chain": chain,
+            "coverage": coverage,
+            "subject": subject,
+            "next_steps": next_steps,
+            "evidence": evidence,
+        }
+    }
+    if blockers:
+        payload["risk_gate"]["blockers"] = blockers
+    if warnings:
+        payload["risk_gate"]["warnings"] = warnings
+    return payload
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    payloads = [load_payload(path) for path in args.input_file]
+    merged = merge_payloads(payloads)
+    json.dump(merged, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/skills/web3-service-orchestrator/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: web3-service-orchestrator
+description: Service-level orchestrator for complex Web3 tasks decomposed into a local DAG. Use when a service plan is already present in prompt context and the task should be completed by combining multiple base Web3 skills step by step instead of improvising a monolithic answer.
+---
+
+# Web3 Service Orchestrator
+
+Use this skill only when the runtime has injected an active Web3 service DAG.
+
+## Operating Contract
+
+- Treat the injected `Active Web3 Service DAG` section as the local source of truth.
+- Work only on the current frontier nodes.
+- Do not skip ahead to downstream nodes whose dependencies are not yet satisfied.
+- Prefer base Web3 skills and stable output blocks over free-form reasoning.
+
+## Node Execution Rules
+
+1. Read the current frontier node goals and candidate skills.
+2. Use the smallest set of skills needed for that node.
+3. Try to produce the node's declared output schema.
+4. If a node is blocked by `risk_gate = BLOCK` or `simulation.readiness = blocked`, stop and explain the blocker.
+5. If the DAG is awaiting confirmation, ask for confirmation instead of executing.
+
+## Output Discipline
+
+- Prefer normalized artifacts like `wallet_operation_plan`, `research_brief`, `risk_gate`, `simulation`, `execution_receipt`, `portfolio_status`, and `watch_status`.
+- If multiple artifacts are available, summarize progress in plain language but keep the normalized blocks available in the turn for runtime consumption.
+
+## Scope Boundaries
+
+- This skill orchestrates.
+- Downstream wallet, research, risk, simulation, and execution skills do the actual work.
+- Do not treat MetaMask SDK documentation as an execution path unless the task explicitly becomes app-side development.

package/dist/skills/web3-static-analysis-runner/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: web3-static-analysis-runner
+description: Static analysis routing layer for smart contract and adjacent codebases. Use when running or coordinating Semgrep, CodeQL, SARIF parsing, or vulnerability pattern scans, especially during audits and pre-deployment reviews.
+---
+
+# Web3 Static Analysis Runner
+
+Use this skill to coordinate static analysis instead of improvising one-off scan commands.
+
+## Required Components
+
+- `web3-repo-heuristics`
+- `web3-audit-reporting`
+
+## Required Profile Adapters
+
+- `codeql`
+- `semgrep`
+- `sarif-parsing`
+- `scv-scan`
+
+Use [references/ADAPTER_CONSUMPTION_MAP.md](references/ADAPTER_CONSUMPTION_MAP.md)
+to normalize scanner output into stable triage buckets.
+Use [references/TRIAGE_BUCKETS.md](references/TRIAGE_BUCKETS.md) and
+[references/OUTPUT_TEMPLATE.md](references/OUTPUT_TEMPLATE.md) to keep scanner
+triage and escalation semantics stable.
+Use [scripts/render_static_analysis_summary.py](scripts/render_static_analysis_summary.py)
+when downstream skills need a normalized static-analysis block.
+
+## Workflow
+
+1. Detect the repo shape with `web3-repo-heuristics`.
+2. Decide which scanners apply:
+   - `semgrep` for fast broad pattern coverage
+   - `codeql` for deeper interprocedural analysis when language/tooling fits
+   - `sarif-parsing` when results already exist or need normalization
+   - `scv-scan` for smart contract vulnerability pattern review and checklist support
+3. Run the chosen scanners through their own upstream workflows.
+4. Deduplicate by root cause before surfacing anything as a finding.
+5. Pass only evidence-backed issues to `web3-audit-reporting`.
+
+## Output Contract
+
+```text
+Scanners Run:
+- name + scope
+Results:
+- raw hits
+Triage:
+- deduped root causes
+Escalate:
+- confirmed finding | review needed | false positive
+```
+
+## Reusable Output Contract
+
+Always emit both:
+
+1. A short scanner/triage summary
+2. A normalized `static_analysis_summary` block
+
+The normalized block must preserve:
+
+- scanners actually run
+- raw hit count
+- deduped root causes
+- escalation counts
+- blockers and next steps
+- exact evidence source per normalized issue
+
+## Guardrails
+
+- Zero findings is not proof of safety.
+- Do not mix scanner hits with confirmed findings.
+- If a tool cannot run because of environment or build constraints, say that explicitly.
+- Prefer existing SARIF over rerunning scans if the user asked for interpretation rather than execution.

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

@@ -0,0 +1,13 @@
+# Static Analysis Adapter Consumption Map
+
+- `codeql` -> deep query results
+- `semgrep` -> fast pattern hits
+- `sarif-parsing` -> normalized imported results
+- `scv-scan` -> checklist-aligned smart contract patterns
+
+Normalize into:
+
+- scanners run
+- raw hits
+- deduped root causes
+- escalate: confirmed finding | review needed | false positive

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

@@ -0,0 +1,45 @@
+# Web3 Static Analysis Output Template
+
+Always emit:
+
+1. A short human-readable scanner triage summary
+2. A normalized block
+
+```yaml
+static_analysis_summary:
+  version: 1
+  status: partial
+  scope: src/core
+  scanners_run:
+    - semgrep
+    - codeql
+  raw_hit_count: 17
+  deduped_root_causes:
+    - unchecked low-level call in withdraw path
+    - missing access control on emergency setter
+  escalation_counts:
+    confirmed_finding: 1
+    review_needed: 2
+    false_positive: 4
+  blockers:
+    - smart-contract-specific CodeQL pack unavailable
+  next_steps:
+    - manually validate emergency setter authorization
+  evidence:
+    - adapter: semgrep
+      detail: unsafe low-level call pattern in Vault.sol
+    - adapter: codeql
+      detail: path-sensitive result on setter authorization path
+```
+
+## Required Fields
+
+- `status`: `complete | partial | blocked`
+- `scope`
+- `scanners_run`
+- `raw_hit_count`
+- `deduped_root_causes`
+- `escalation_counts`
+- `blockers`
+- `next_steps`
+- `evidence`