web3skill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 nanobot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# web3skill
+
+`web3skill` packages the Web3-focused `nanobot` skills into a single npm
+artifact.
+
+It is meant for runtimes, installers, registries, or internal tooling that
+need to:
+
+- ship raw skill folders
+- consume prebuilt `.skill` archives
+- inspect skill metadata from a generated manifest
+- resolve packaged file paths programmatically
+
+This package is a distribution bundle, not a chain client or wallet SDK.
+
+## What is included
+
+The published tarball contains:
+
+- `dist/skills/`: raw skill directories
+- `dist/archives/`: zipped `.skill` artifacts
+- `dist/manifest.json`: generated metadata for all bundled skills
+- `index.js`: small runtime helpers for listing and resolving assets
+
+## Bundled skills
+
+- `web3-audit-orchestrator`
+- `web3-audit-reporting`
+- `web3-fuzzing-and-invariants`
+- `web3-native-operator`
+- `web3-repo-heuristics`
+- `web3-research-and-market-intel`
+- `web3-risk-gate`
+- `web3-service-orchestrator`
+- `web3-static-analysis-runner`
+- `web3-trace-and-state-analysis`
+- `web3-transaction-simulator`
+- `web3-wallet-operator`
+
+## Install
+
+```bash
+npm install web3skill
+```
+
+## Usage
+
+```js
+import {
+  getManifest,
+  getSkillArchive,
+  getSkillDir,
+  listSkills
+} from "web3skill";
+
+console.log(listSkills());
+console.log(getManifest().skills[0]);
+console.log(getSkillDir("web3-native-operator"));
+console.log(getSkillArchive("web3-native-operator"));
+```
+
+## API
+
+### `listSkills()`
+
+Returns the bundled skill names.
+
+### `getManifest()`
+
+Returns the parsed `dist/manifest.json` object.
+
+### `getSkillDir(name)`
+
+Returns the absolute path to a packaged raw skill directory.
+
+### `getSkillArchive(name)`
+
+Returns the absolute path to a packaged `.skill` archive.
+
+## File layout
+
+```text
+web3skill/
+  dist/
+    archives/
+      web3-native-operator.skill
+      ...
+    skills/
+      web3-native-operator/
+        SKILL.md
+        references/
+        scripts/
+      ...
+    manifest.json
+  index.js
+```
+
+## Build from source
+
+Requirements:
+
+- `node >= 20`
+- `python3`
+
+Build the distributable contents:
+
+```bash
+npm run build
+```
+
+Preview the npm tarball:
+
+```bash
+npm run pack:check
+```
+
+## Publish
+
+From `/home/kaima/Future/nanobot/web3skill`:
+
+```bash
+npm login
+npm publish --access public
+```
+
+As checked on `2026-03-22`, `npm view web3skill` returned `404 Not Found`, so
+the unscoped package name appeared to be available at that time.

package/dist/manifest.json

@@ -0,0 +1,170 @@
+{
+  "packageName": "web3skill",
+  "generatedAt": "2026-03-22T08:08:25.760Z",
+  "sourceRoot": "../nanobot/skills",
+  "skills": [
+    {
+      "name": "web3-audit-orchestrator",
+      "description": "Audit orchestration layer for smart contract and protocol reviews. Use when the task is a contract audit, security review, contest-style finding hunt, or fix validation. It routes to upstream audit workflows and normalizes the review lifecycle.",
+      "always": false,
+      "fileCount": 5,
+      "resourceDirs": [
+        "references",
+        "scripts"
+      ],
+      "paths": {
+        "directory": "dist/skills/web3-audit-orchestrator",
+        "archive": "dist/archives/web3-audit-orchestrator.skill"
+      }
+    },
+    {
+      "name": "web3-audit-reporting",
+      "description": "Produce high-signal Web3 audit deliverables with scope, trust boundaries, evidence-backed findings, severity calibration, remediation, and retest conclusions. Use when the user wants a smart contract audit report, finding writeup, severity review, contest submission, fix validation, or consolidated security deliverable.",
+      "always": false,
+      "fileCount": 5,
+      "resourceDirs": [
+        "references"
+      ],
+      "paths": {
+        "directory": "dist/skills/web3-audit-reporting",
+        "archive": "dist/archives/web3-audit-reporting.skill"
+      }
+    },
+    {
+      "name": "web3-fuzzing-and-invariants",
+      "description": "Fuzzing and invariant orchestration layer for protocol reviews and smart contract testing. Use when deriving invariants, writing harnesses, evaluating property-based tests, or interpreting fuzz failures.",
+      "always": false,
+      "fileCount": 5,
+      "resourceDirs": [
+        "references",
+        "scripts"
+      ],
+      "paths": {
+        "directory": "dist/skills/web3-fuzzing-and-invariants",
+        "archive": "dist/archives/web3-fuzzing-and-invariants.skill"
+      }
+    },
+    {
+      "name": "web3-native-operator",
+      "description": "Web3 routing layer for safe execution, simulation, trace analysis, and repo-first smart contract work. Use for transfers, approvals, swaps, audits, onchain debugging, or Web3 research. It does not execute venue-specific flows directly; it routes to safety gates and profile adapters.",
+      "always": true,
+      "fileCount": 20,
+      "resourceDirs": [
+        "references",
+        "scripts"
+      ],
+      "paths": {
+        "directory": "dist/skills/web3-native-operator",
+        "archive": "dist/archives/web3-native-operator.skill"
+      }
+    },
+    {
+      "name": "web3-repo-heuristics",
+      "description": "Repository triage and execution heuristics for Solidity and Vyper codebases, with explicit support for Foundry, Hardhat, and mixed monorepos. Use when inspecting, modifying, testing, or auditing smart contract repositories and deployment scripts.",
+      "always": true,
+      "fileCount": 4,
+      "resourceDirs": [
+        "references"
+      ],
+      "paths": {
+        "directory": "dist/skills/web3-repo-heuristics",
+        "archive": "dist/archives/web3-repo-heuristics.skill"
+      }
+    },
+    {
+      "name": "web3-research-and-market-intel",
+      "description": "Web3 market and protocol research routing layer. Use for token research, protocol diligence, TVL and market data analysis, whale flow review, wallet portfolio review, and multi-source investment intelligence before trading or monitoring.",
+      "always": false,
+      "fileCount": 9,
+      "resourceDirs": [
+        "references",
+        "scripts"
+      ],
+      "paths": {
+        "directory": "dist/skills/web3-research-and-market-intel",
+        "archive": "dist/archives/web3-research-and-market-intel.skill"
+      }
+    },
+    {
+      "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.",
+      "always": false,
+      "fileCount": 4,
+      "resourceDirs": [
+        "references",
+        "scripts"
+      ],
+      "paths": {
+        "directory": "dist/skills/web3-risk-gate",
+        "archive": "dist/archives/web3-risk-gate.skill"
+      }
+    },
+    {
+      "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.",
+      "always": false,
+      "fileCount": 1,
+      "resourceDirs": [],
+      "paths": {
+        "directory": "dist/skills/web3-service-orchestrator",
+        "archive": "dist/archives/web3-service-orchestrator.skill"
+      }
+    },
+    {
+      "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.",
+      "always": false,
+      "fileCount": 5,
+      "resourceDirs": [
+        "references",
+        "scripts"
+      ],
+      "paths": {
+        "directory": "dist/skills/web3-static-analysis-runner",
+        "archive": "dist/archives/web3-static-analysis-runner.skill"
+      }
+    },
+    {
+      "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.",
+      "always": false,
+      "fileCount": 5,
+      "resourceDirs": [
+        "references",
+        "scripts"
+      ],
+      "paths": {
+        "directory": "dist/skills/web3-trace-and-state-analysis",
+        "archive": "dist/archives/web3-trace-and-state-analysis.skill"
+      }
+    },
+    {
+      "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.",
+      "always": false,
+      "fileCount": 4,
+      "resourceDirs": [
+        "references",
+        "scripts"
+      ],
+      "paths": {
+        "directory": "dist/skills/web3-transaction-simulator",
+        "archive": "dist/archives/web3-transaction-simulator.skill"
+      }
+    },
+    {
+      "name": "web3-wallet-operator",
+      "description": "Wallet-first routing layer for bot-driven Web3 wallet use. Use when the user wants to inspect a wallet, transfer tokens, approve or revoke allowances, prepare a swap, or run MetaMask delegation flows through the bot. It classifies wallet intent first, then routes to the operator, risk gate, simulator, portfolio adapters, or MetaMask wallet tooling.",
+      "always": true,
+      "fileCount": 4,
+      "resourceDirs": [
+        "references",
+        "scripts"
+      ],
+      "paths": {
+        "directory": "dist/skills/web3-wallet-operator",
+        "archive": "dist/archives/web3-wallet-operator.skill"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,79 @@
+---
+name: web3-audit-orchestrator
+description: Audit orchestration layer for smart contract and protocol reviews. Use when the task is a contract audit, security review, contest-style finding hunt, or fix validation. It routes to upstream audit workflows and normalizes the review lifecycle.
+---
+
+# Web3 Audit Orchestrator
+
+Use this skill as the top-level coordinator for contract audits and protocol security reviews.
+
+## Required Components
+
+- `web3-repo-heuristics`
+- `web3-audit-reporting`
+
+## Required Profile Adapters
+
+Prefer the bundled upstream skills:
+
+- `solidity-auditor`
+- `audit-context-building`
+- `secure-workflow-guide`
+- `security-auditor`
+
+Use [references/ADAPTER_CONSUMPTION_MAP.md](references/ADAPTER_CONSUMPTION_MAP.md)
+to keep audit adapter outputs stable across review states.
+Use [references/REVIEW_STATE_MACHINE.md](references/REVIEW_STATE_MACHINE.md)
+and [references/OUTPUT_TEMPLATE.md](references/OUTPUT_TEMPLATE.md) to keep
+review lifecycle and emitted state stable.
+Use [scripts/render_audit_review.py](scripts/render_audit_review.py) when a
+downstream skill or runtime needs a machine-consumable audit state block.
+
+## Workflow
+
+1. Lock review context:
+   - repo or code snapshot
+   - commit, branch, or file scope
+   - chain / deployment assumptions
+2. Use `web3-repo-heuristics` to identify the real build and test surface.
+3. Use `audit-context-building` to establish architecture, invariants, and trust boundaries.
+4. Choose the main audit engine:
+   - `solidity-auditor` for Solidity-first repo audits
+   - `security-auditor` for broader structured security review
+   - `secure-workflow-guide` when the user wants a stepwise ToB security workflow
+5. Route concrete findings to `web3-static-analysis-runner` and `web3-fuzzing-and-invariants` when needed.
+6. Finalize output with `web3-audit-reporting`.
+
+## Review State Machine
+
+```text
+Scope Locked
+-> Context Built
+-> Evidence Collected
+-> Candidate Findings Triaged
+-> Confirmed Findings Written
+-> Retest / Residual Risk
+```
+
+## Reusable Output Contract
+
+Always emit both:
+
+1. A short audit progress summary
+2. A normalized `audit_review` block
+
+The normalized block must preserve:
+
+- `review_state`
+- scope and repo reference
+- which audit engines actually ran
+- coverage across context, manual review, static analysis, fuzzing, and retest
+- candidate vs confirmed finding counts
+- next steps and exact evidence sources
+
+## Guardrails
+
+- Do not write findings before scope and threat model are explicit.
+- Keep candidate issues separate from confirmed findings.
+- Do not let static tool output bypass human triage.
+- If the review lacks buildability, deployment data, or testability, state the coverage gap explicitly.

package/dist/skills/web3-audit-orchestrator/references/ADAPTER_CONSUMPTION_MAP.md

@@ -0,0 +1,15 @@
+# Audit Adapter Consumption Map
+
+- `audit-context-building` -> architecture, trust boundaries, invariants
+- `solidity-auditor` -> candidate findings and manual review vectors
+- `secure-workflow-guide` -> ordered review workflow and coverage steps
+- `security-auditor` -> structured audit checklist and validation paths
+
+Normalize into review states:
+
+- scope locked
+- context built
+- evidence collected
+- candidate findings triaged
+- confirmed findings written
+- retest / residual risk

package/dist/skills/web3-audit-orchestrator/references/OUTPUT_TEMPLATE.md

@@ -0,0 +1,52 @@
+# Web3 Audit Review Output Template
+
+Always emit:
+
+1. A short human-readable audit status summary
+2. A normalized block
+
+```yaml
+audit_review:
+  version: 1
+  review_state: candidate-findings-triaged
+  scope:
+    repo: protocol-x
+    ref: 9f3c2b1
+    target: src/core
+  engines:
+    - audit-context-building
+    - solidity-auditor
+    - semgrep
+  coverage:
+    context: complete
+    manual: partial
+    static: complete
+    fuzz: not-run
+    retest: pending
+  findings:
+    candidate_count: 4
+    confirmed_count: 1
+  next_steps:
+    - validate privilege issue with focused manual review
+  evidence:
+    - adapter: audit-context-building
+      detail: architecture and privilege boundaries mapped
+    - adapter: solidity-auditor
+      detail: privilege escalation path identified for triage
+```
+
+## Required Fields
+
+- `review_state`
+- `scope`
+- `engines`
+- `coverage`
+- `findings`
+- `next_steps`
+- `evidence`
+
+## Notes
+
+- `candidate_count` and `confirmed_count` must remain separate.
+- `static` and `fuzz` can be `not-run`; do not fake completion.
+- If the audit is blocked before evidence collection, explain the blocker in `next_steps`.

package/dist/skills/web3-audit-orchestrator/references/REVIEW_STATE_MACHINE.md

@@ -0,0 +1,25 @@
+# Audit Review State Machine
+
+Use this state machine to normalize audit progress before findings are reported.
+
+## States
+
+- `scope-locked`
+  - repo, commit/ref, file scope, and deployment assumptions named
+- `context-built`
+  - architecture, invariants, trust boundaries, and roles summarized
+- `evidence-collected`
+  - manual review and supporting scanners/harnesses have produced usable evidence
+- `candidate-findings-triaged`
+  - raw issues deduped and separated into candidate vs false-positive buckets
+- `confirmed-findings-written`
+  - findings have root cause, exploit relevance, impact, and remediation
+- `retest-or-residual-risk`
+  - fixes checked or residual gaps explicitly documented
+
+## Transition Rules
+
+- Do not skip from `scope-locked` to confirmed findings.
+- If buildability or runtime assumptions block evidence collection, stay at `context-built`.
+- If tool output exists but manual validation is incomplete, stay at `candidate-findings-triaged`.
+- Move to `retest-or-residual-risk` only after findings are already written or explicitly ruled out.

package/dist/skills/web3-audit-orchestrator/scripts/render_audit_review.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Render a stable Web3 audit review block."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a Web3 audit review block.")
+    parser.add_argument("--repo", required=True)
+    parser.add_argument("--ref", default="")
+    parser.add_argument("--target", default="")
+    parser.add_argument(
+        "--review-state",
+        choices=(
+            "scope-locked",
+            "context-built",
+            "evidence-collected",
+            "candidate-findings-triaged",
+            "confirmed-findings-written",
+            "retest-or-residual-risk",
+        ),
+        required=True,
+    )
+    parser.add_argument("--engine", action="append", default=[])
+    parser.add_argument(
+        "--context-coverage", choices=("complete", "partial", "missing"), default="partial"
+    )
+    parser.add_argument(
+        "--manual-coverage", choices=("complete", "partial", "missing"), default="partial"
+    )
+    parser.add_argument(
+        "--static-coverage", choices=("complete", "partial", "not-run"), default="not-run"
+    )
+    parser.add_argument(
+        "--fuzz-coverage", choices=("complete", "partial", "not-run"), default="not-run"
+    )
+    parser.add_argument(
+        "--retest-status", choices=("pending", "complete", "not-needed"), default="pending"
+    )
+    parser.add_argument("--candidate-count", type=int, default=0)
+    parser.add_argument("--confirmed-count", type=int, default=0)
+    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 = {
+        "audit_review": {
+            "version": 1,
+            "review_state": args.review_state,
+            "scope": {
+                "repo": args.repo,
+                "ref": args.ref,
+                "target": args.target,
+            },
+            "engines": args.engine,
+            "coverage": {
+                "context": args.context_coverage,
+                "manual": args.manual_coverage,
+                "static": args.static_coverage,
+                "fuzz": args.fuzz_coverage,
+                "retest": args.retest_status,
+            },
+            "findings": {
+                "candidate_count": args.candidate_count,
+                "confirmed_count": args.confirmed_count,
+            },
+            "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())