web3skill 0.1.0

package/dist/skills/web3-transaction-simulator/scripts/merge_simulation_blocks.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""Merge multiple normalized simulation blocks into one conservative result."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+READINESS_ORDER = {
+    "ready": 0,
+    "needs-confirmation": 1,
+    "blocked": 2,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Merge multiple simulation payloads into one block.")
+    parser.add_argument(
+        "--input-file",
+        action="append",
+        required=True,
+        help="Path to a JSON file containing a simulation 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_simulation(payload: dict[str, object]) -> dict[str, object]:
+    simulation = payload.get("simulation")
+    if isinstance(simulation, dict):
+        return simulation
+    if {"status", "action", "venue", "readiness"}.issubset(payload):
+        return payload
+    raise ValueError("input payload does not contain simulation")
+
+
+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_mapping(current: dict[str, object], new_value: dict[str, object], field_name: str) -> dict[str, object]:
+    merged = dict(current)
+    for key, value in new_value.items():
+        if key in merged and merged[key] != value:
+            raise ValueError(f"conflicting {field_name}.{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 choose_status(statuses: list[str]) -> str:
+    if any(status == "FAIL" for status in statuses):
+        return "FAIL"
+    if any(status == "WARN" for status in statuses):
+        return "WARN"
+    if any(status == "NO_SIMULATION" for status in statuses):
+        return "WARN" if any(status == "PASS" for status in statuses) else "NO_SIMULATION"
+    return "PASS"
+
+
+def choose_readiness(readiness_values: list[str]) -> str:
+    if not readiness_values:
+        return "needs-confirmation"
+    return max(readiness_values, key=lambda item: READINESS_ORDER[item])
+
+
+def default_next_steps(status: str, readiness: str) -> list[str]:
+    if status == "FAIL" or readiness == "blocked":
+        return ["stop", "adjust params or route before retrying"]
+    if status == "NO_SIMULATION":
+        return ["gather missing simulation backend", "investigate route before execution"]
+    if status == "WARN" or readiness == "needs-confirmation":
+        return ["adjust params", "rerun simulation"]
+    return ["proceed after confirmation"]
+
+
+def merge_payloads(payloads: list[dict[str, object]]) -> dict[str, object]:
+    action = ""
+    venue = ""
+    chain = ""
+    route: dict[str, object] = {}
+    expected_result: dict[str, object] = {}
+    preconditions: list[dict[str, object]] = []
+    failure_modes: list[dict[str, object]] = []
+    evidence: list[dict[str, object]] = []
+    next_steps: list[str] = []
+    statuses: list[str] = []
+    readiness_values: list[str] = []
+
+    for payload in payloads:
+        simulation = extract_simulation(payload)
+        action = merge_scalar(action, str(simulation.get("action", "")), "action")
+        venue = merge_scalar(venue, str(simulation.get("venue", "")), "venue")
+        chain = merge_scalar(chain, str(simulation.get("chain", "")), "chain")
+
+        status = str(simulation.get("status", "NO_SIMULATION"))
+        readiness = str(simulation.get("readiness", "needs-confirmation"))
+        if readiness not in READINESS_ORDER:
+            raise ValueError(f"unsupported readiness value: {readiness}")
+        statuses.append(status)
+        readiness_values.append(readiness)
+
+        route_value = simulation.get("route", {})
+        if isinstance(route_value, dict):
+            route = merge_mapping(route, route_value, "route")
+        expected_result_value = simulation.get("expected_result", {})
+        if isinstance(expected_result_value, dict):
+            expected_result = merge_mapping(expected_result, expected_result_value, "expected_result")
+
+        preconditions_value = simulation.get("preconditions", [])
+        if isinstance(preconditions_value, list):
+            preconditions.extend(item for item in preconditions_value if isinstance(item, dict))
+        failure_modes_value = simulation.get("failure_modes", [])
+        if isinstance(failure_modes_value, list):
+            failure_modes.extend(item for item in failure_modes_value if isinstance(item, dict))
+        evidence_value = simulation.get("evidence", [])
+        if isinstance(evidence_value, list):
+            evidence.extend(item for item in evidence_value if isinstance(item, dict))
+        next_step_value = simulation.get("next_step", [])
+        if isinstance(next_step_value, list):
+            next_steps.extend(str(item) for item in next_step_value if isinstance(item, str))
+
+    status = choose_status(statuses)
+    readiness = choose_readiness(readiness_values)
+    preconditions = dedupe_items(preconditions)
+    failure_modes = dedupe_items(failure_modes)
+    evidence = dedupe_items(evidence)
+    next_steps = dedupe_strings(next_steps) or default_next_steps(status, readiness)
+
+    payload: dict[str, object] = {
+        "simulation": {
+            "version": 1,
+            "status": status,
+            "action": action,
+            "venue": venue,
+            "chain": chain,
+            "readiness": readiness,
+            "route": route,
+            "next_step": next_steps,
+            "evidence": evidence,
+        }
+    }
+    if preconditions:
+        payload["simulation"]["preconditions"] = preconditions
+    if expected_result:
+        payload["simulation"]["expected_result"] = expected_result
+    if failure_modes:
+        payload["simulation"]["failure_modes"] = failure_modes
+    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-wallet-operator/SKILL.md

@@ -0,0 +1,52 @@
+---
+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
+---
+
+# Web3 Wallet Operator
+
+Use this skill when the user's frame is "use my wallet" rather than "analyze this protocol".
+
+## Wallet-First Contract
+
+- Never ask for seed phrases, mnemonics, raw private keys, exported keystores, or screenshots of wallet secrets.
+- Prefer existing wallet connections, exchange credentials, or wallet-native signing flows.
+- Any chain write still needs explicit user confirmation.
+- Treat MetaMask as one optional wallet entrance, not the default control plane.
+
+## Intent Classes
+
+- `portfolio`: inspect balances, positions, exposure, counterparties, or wallet activity
+- `transfer`: send native token or ERC-20 token to a receiver
+- `approve`: grant allowance or permission to a spender/router
+- `revoke`: clear or reduce an existing allowance or delegation
+- `swap`: buy, sell, or route a token through a DEX
+- `delegation`: MetaMask wallet-side EIP-7702 or ERC-7710 flow
+
+## Routing Contract
+
+1. Classify wallet intent before reading downstream skills.
+2. Read [references/ACTION_RECIPES.md](references/ACTION_RECIPES.md) for the route map.
+3. If the runtime needs a stable machine-consumable handoff, emit `wallet_operation_plan` with [scripts/render_wallet_operation_plan.py](scripts/render_wallet_operation_plan.py) and follow [references/OUTPUT_TEMPLATE.md](references/OUTPUT_TEMPLATE.md).
+4. Route by intent:
+   - `portfolio` -> `web3-research-and-market-intel`, then `debank` or `query-address-info`
+   - `transfer`, `approve`, `revoke`, `swap` -> `web3-native-operator`
+   - `delegation` -> `metamask-gator-cli`
+5. Do not prefer `metamask-smart-accounts-kit` unless the task changes into app-side wallet integration or SDK development.
+
+## Minimum Inputs
+
+- active wallet or account scope
+- chain
+- asset/token
+- amount and units
+- receiver, spender, router, or delegation target
+- whether the user wants read-only planning or confirmed execution
+
+## Guardrails
+
+- For `transfer`, `approve`, `revoke`, and `swap`, the downstream flow still must pass `web3-risk-gate` and `web3-transaction-simulator` before execution.
+- If wallet context is missing, stop and ask for the minimum safe parameters instead of guessing.
+- If the operation is MetaMask-specific and wallet-side, keep the flow in `metamask-gator-cli`.
+- If the request is really portfolio intelligence instead of execution, prefer wallet state adapters over venue execution tools.

package/dist/skills/web3-wallet-operator/references/ACTION_RECIPES.md

@@ -0,0 +1,56 @@
+# Web3 Wallet Operator Recipes
+
+Use these recipes when the user starts from a wallet intent.
+
+## Portfolio Review
+
+1. Normalize the request as `portfolio`.
+2. Route to `web3-research-and-market-intel`.
+3. Prefer:
+   - `debank` for wallet-level portfolio and protocol positions
+   - `query-address-info` for chain-scoped address holdings
+4. Emit a stable `portfolio_status` block before monitoring or follow-up.
+
+## Transfer
+
+1. Normalize the request as `transfer`.
+2. Route to `web3-native-operator`.
+3. Downstream checks must include:
+   - `web3-risk-gate`
+   - `web3-transaction-simulator`
+4. Treat receiver screening, blacklist risk, gas sufficiency, and token transfer behavior as mandatory checks before execution.
+
+## Approve Or Revoke
+
+1. Normalize the request as `approve` or `revoke`.
+2. Route to `web3-native-operator`.
+3. Downstream checks must include:
+   - `web3-risk-gate`
+   - `web3-transaction-simulator`
+4. Highlight spender identity, allowance scope, expiry, and whether a safer exact-amount approval exists.
+
+## Swap
+
+1. Normalize the request as `swap`.
+2. Route to `web3-native-operator`.
+3. Downstream flow should use:
+   - `web3-risk-gate`
+   - `web3-transaction-simulator`
+   - `swap-planner`, `token-swap`, or other venue adapters only after the gate and simulation are acceptable
+4. If token safety is unclear, keep the flow in pretrade investigation instead of implying execution readiness.
+
+## MetaMask Delegation
+
+1. Normalize the request as `delegation`.
+2. Route to `metamask-gator-cli`.
+3. Require wallet-side context:
+   - target profile
+   - chain / RPC
+   - delegation scope or redeem action
+4. Do not route to `metamask-smart-accounts-kit` unless the task turns into app-side integration work.
+
+## Global Guardrails
+
+- Never request seed phrases or private keys.
+- Never skip confirmation on chain writes.
+- Never imply wallet safety if risk gating or simulation is unavailable.

package/dist/skills/web3-wallet-operator/references/OUTPUT_TEMPLATE.md

@@ -0,0 +1,43 @@
+# Wallet Operation Plan Template
+
+Use this stable payload when the runtime needs a deterministic wallet-intent handoff.
+
+```json
+{
+  "wallet_operation_plan": {
+    "version": 1,
+    "intent": "transfer",
+    "wallet_entry": "generic",
+    "account_scope": "active-wallet",
+    "execution_class": "write",
+    "mode": "confirm_then_execute",
+    "chain": "base",
+    "asset": "USDC",
+    "amount": "50",
+    "target": "0xreceiver",
+    "next_skill": "web3-native-operator",
+    "downstream_checks": [
+      "web3-risk-gate",
+      "web3-transaction-simulator"
+    ],
+    "recommended_adapters": [
+      "gas-tracker"
+    ],
+    "requires_user_confirmation": true,
+    "notes": [
+      "screen receiver before write",
+      "verify wallet balance covers value and gas"
+    ]
+  }
+}
+```
+
+## Field Notes
+
+- `intent`: `portfolio | transfer | approve | revoke | swap | delegation`
+- `wallet_entry`: `generic | metamask-gator-cli | venue`
+- `execution_class`: `read | write`
+- `mode`: `read-only | confirm_then_execute`
+- `next_skill`: immediate next routing target
+- `downstream_checks`: builtin control skills that still must run
+- `recommended_adapters`: profile adapters or wallet tools likely to be used next

package/dist/skills/web3-wallet-operator/scripts/render_wallet_operation_plan.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Render a stable wallet-operation routing payload."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+INTENTS = ("portfolio", "transfer", "approve", "revoke", "swap", "delegation")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a wallet_operation_plan payload.")
+    parser.add_argument("--intent", choices=INTENTS, required=True)
+    parser.add_argument("--wallet-entry", choices=("generic", "metamask-gator-cli", "venue"), default="generic")
+    parser.add_argument("--account-scope", default="active-wallet")
+    parser.add_argument("--chain", default="")
+    parser.add_argument("--asset", default="")
+    parser.add_argument("--amount", default="")
+    parser.add_argument("--target", default="")
+    parser.add_argument("--mode", choices=("read-only", "confirm_then_execute"), default="read-only")
+    return parser
+
+
+def route_for_intent(intent: str) -> tuple[str, str, list[str], list[str], list[str], bool]:
+    if intent == "portfolio":
+        return (
+            "read",
+            "web3-research-and-market-intel",
+            [],
+            ["debank", "query-address-info"],
+            ["normalize wallet state before monitoring"],
+            False,
+        )
+    if intent == "delegation":
+        return (
+            "write",
+            "metamask-gator-cli",
+            [],
+            ["metamask-gator-cli"],
+            ["use MetaMask wallet-side tooling instead of app-side SDK guidance"],
+            True,
+        )
+
+    notes = [
+        "route through the Web3 control plane before any wallet write",
+        "risk and simulation must pass before execution",
+    ]
+    adapters = ["gas-tracker"]
+    if intent == "swap":
+        adapters.extend(["swap-planner", "token-swap"])
+        notes.append("prefer swap-specific adapters only after safety checks are acceptable")
+    if intent in {"approve", "revoke"}:
+        notes.append("review spender scope and allowance delta explicitly")
+    if intent == "transfer":
+        notes.append("screen receiver and confirm wallet balance plus gas coverage")
+
+    return (
+        "write",
+        "web3-native-operator",
+        ["web3-risk-gate", "web3-transaction-simulator"],
+        adapters,
+        notes,
+        True,
+    )
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    execution_class, next_skill, downstream_checks, adapters, notes, requires_confirmation = route_for_intent(
+        args.intent
+    )
+
+    payload = {
+        "wallet_operation_plan": {
+            "version": 1,
+            "intent": args.intent,
+            "wallet_entry": args.wallet_entry,
+            "account_scope": args.account_scope,
+            "execution_class": execution_class,
+            "mode": args.mode,
+            "chain": args.chain,
+            "asset": args.asset,
+            "amount": args.amount,
+            "target": args.target,
+            "next_skill": next_skill,
+            "downstream_checks": downstream_checks,
+            "recommended_adapters": adapters,
+            "requires_user_confirmation": requires_confirmation,
+            "notes": notes,
+        }
+    }
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/index.js

@@ -0,0 +1,50 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = dirname(fileURLToPath(import.meta.url));
+const manifestPath = join(packageRoot, "dist", "manifest.json");
+
+let manifestCache;
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function loadManifest() {
+  if (!manifestCache) {
+    manifestCache = JSON.parse(readFileSync(manifestPath, "utf8"));
+  }
+  return manifestCache;
+}
+
+function getSkill(skillName) {
+  const skill = loadManifest().skills.find((entry) => entry.name === skillName);
+  if (!skill) {
+    throw new Error(`Unknown skill: ${skillName}`);
+  }
+  return skill;
+}
+
+export function getManifest() {
+  return clone(loadManifest());
+}
+
+export function listSkills() {
+  return loadManifest().skills.map((skill) => skill.name);
+}
+
+export function getSkillDir(skillName) {
+  return join(packageRoot, getSkill(skillName).paths.directory);
+}
+
+export function getSkillArchive(skillName) {
+  return join(packageRoot, getSkill(skillName).paths.archive);
+}
+
+export default {
+  getManifest,
+  listSkills,
+  getSkillDir,
+  getSkillArchive
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "web3skill",
+  "version": "0.1.0",
+  "description": "Bundled Web3 nanobot skills with raw folders, metadata manifest, and packaged .skill archives.",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./manifest.json": "./dist/manifest.json"
+  },
+  "files": [
+    "dist",
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node ./scripts/build.mjs",
+    "prepack": "npm run build",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "agent",
+    "ai",
+    "nanobot",
+    "skill",
+    "web3"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}