web3skill 0.1.0

package/dist/skills/web3-native-operator/scripts/render_posttrade_followup_bundle.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""Render the full posttrade follow-up bundle from execution receipt fields."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from render_operator_bundle import build_posttrade_bundle
+from render_posttrade_watch_status import build_posttrade_watch_payload
+from render_watch_cron_request import build_cron_request_payload
+from render_watch_heartbeat import build_heartbeat_task
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a Web3 posttrade follow-up bundle.")
+    parser.add_argument("--venue", required=True)
+    parser.add_argument(
+        "--receipt-status",
+        choices=("SUBMITTED", "PENDING", "CONFIRMED", "FILLED", "FAILED", "REVERTED"),
+        required=True,
+    )
+    parser.add_argument("--settlement", choices=("evm", "venue"), required=True)
+    parser.add_argument("--reference-id", default="")
+    parser.add_argument("--subject", default="")
+    parser.add_argument(
+        "--severity",
+        choices=("low", "medium", "high", "critical"),
+        default="",
+    )
+    parser.add_argument("--next-check-hint", default="")
+    parser.add_argument("--schedule-hint", default="")
+    parser.add_argument("--recommended-adapter", default="")
+    parser.add_argument("--reason", action="append", default=[])
+    parser.add_argument("--follow-up-skill", action="append", default=[])
+    parser.add_argument("--evidence", action="append", default=[])
+    parser.add_argument("--task-note", default="")
+    parser.add_argument("--every-seconds", type=int, default=0)
+    parser.add_argument("--cron-expr", default="")
+    parser.add_argument("--tz", default="")
+    parser.add_argument("--at", default="")
+    return parser
+
+
+def maybe_build_cron_request(
+    args: argparse.Namespace,
+    watch_args: argparse.Namespace,
+) -> dict[str, object] | None:
+    if not (
+        args.every_seconds > 0
+        or args.cron_expr
+        or args.at
+        or (watch_args.schedule_hint and watch_args.schedule_hint != "manual")
+    ):
+        return None
+    cron_expr = args.cron_expr or (
+        watch_args.schedule_hint if watch_args.schedule_hint and watch_args.schedule_hint != "manual" else ""
+    )
+    cron_args = argparse.Namespace(
+        subject=watch_args.subject,
+        watch_kind="posttrade",
+        status=watch_args.status,
+        severity=watch_args.severity,
+        recommended_adapter=watch_args.recommended_adapter,
+        next_check_hint=watch_args.next_check_hint,
+        message="",
+        every_seconds=args.every_seconds,
+        cron_expr=cron_expr,
+        tz=args.tz,
+        at=args.at,
+    )
+    return build_cron_request_payload(cron_args)["cron_request"]
+
+
+def build_receipt_summary(args: argparse.Namespace) -> dict[str, str]:
+    return {
+        "receipt_status": args.receipt_status,
+        "venue": args.venue,
+        "settlement": args.settlement,
+        "reference_id": args.reference_id,
+    }
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    operator_bundle = build_posttrade_bundle(args)
+    watch_payload = build_posttrade_watch_payload(args)["watch_status"]
+    watch_args = argparse.Namespace(
+        subject=str(watch_payload["subject"]),
+        watch_kind="posttrade",
+        watch_status=str(watch_payload["status"]),
+        status=str(watch_payload["status"]),
+        severity=str(watch_payload["severity"]),
+        recommended_adapter=str(watch_payload["recommended_adapter"]),
+        next_check_hint=str(watch_payload["next_check_hint"]),
+        schedule_hint=str(watch_payload["schedule_hint"]),
+        task_note=args.task_note,
+    )
+    heartbeat_task = build_heartbeat_task(watch_args)
+    cron_request = maybe_build_cron_request(args, watch_args)
+    payload = {
+        "posttrade_followup_bundle": {
+            "version": 1,
+            "execution_receipt": build_receipt_summary(args),
+            "operator_bundle": operator_bundle,
+            "watch_status": watch_payload,
+            "heartbeat_task": heartbeat_task,
+            "cron_request": cron_request,
+        }
+    }
+    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-native-operator/scripts/render_posttrade_watch_status.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Render a watch_status block from a normalized execution_receipt."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a posttrade watch status block.")
+    parser.add_argument(
+        "--receipt-status",
+        choices=("SUBMITTED", "PENDING", "CONFIRMED", "FILLED", "FAILED", "REVERTED"),
+        required=True,
+    )
+    parser.add_argument("--venue", required=True)
+    parser.add_argument("--settlement", choices=("evm", "venue"), required=True)
+    parser.add_argument("--reference-id", default="")
+    parser.add_argument("--subject", default="")
+    parser.add_argument(
+        "--severity",
+        choices=("low", "medium", "high", "critical"),
+        default="",
+    )
+    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 default_subject(args: argparse.Namespace) -> str:
+    if args.subject:
+        return args.subject
+    if args.reference_id and args.settlement == "evm":
+        return f"tx:{args.reference_id}"
+    if args.reference_id:
+        return f"{args.venue}:{args.reference_id}"
+    return f"{args.venue}:posttrade"
+
+
+def default_severity(receipt_status: str) -> str:
+    if receipt_status in ("FAILED", "REVERTED"):
+        return "high"
+    if receipt_status in ("CONFIRMED", "FILLED"):
+        return "medium"
+    return "medium"
+
+
+def default_schedule_hint(receipt_status: str) -> str:
+    if receipt_status in ("SUBMITTED", "PENDING"):
+        return "*/5 * * * *"
+    if receipt_status in ("CONFIRMED", "FILLED"):
+        return "manual"
+    return "manual"
+
+
+def default_next_check_hint(args: argparse.Namespace) -> str:
+    if args.receipt_status in ("SUBMITTED", "PENDING"):
+        if args.settlement == "evm":
+            return "check receipt confirmations and final token balances after 5 minutes"
+        return "refresh venue fill status and open positions after 5 minutes"
+    if args.receipt_status in ("CONFIRMED", "FILLED"):
+        if args.settlement == "evm":
+            return "verify final settlement state, logs, and output balances"
+        return "verify final position, fills, and venue balances"
+    return "inspect failure path, revert reason, and settlement evidence immediately"
+
+
+def default_adapter(args: argparse.Namespace) -> str:
+    if args.recommended_adapter:
+        return args.recommended_adapter
+    if args.settlement == "evm":
+        return "web3-trace-and-state-analysis"
+    return args.venue
+
+
+def map_watch_status(receipt_status: str) -> str:
+    if receipt_status in ("SUBMITTED", "PENDING"):
+        return "ACTIVE"
+    return "TRIGGERED"
+
+
+def parse_evidence(entries: list[str], venue: str, receipt_status: str) -> list[dict[str, str]]:
+    if not entries:
+        return [{"adapter": venue, "detail": f"execution receipt status is {receipt_status}"}]
+    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": venue, "detail": entry})
+    return parsed
+
+
+def build_posttrade_watch_payload(args: argparse.Namespace) -> dict[str, object]:
+    return {
+        "watch_status": {
+            "version": 1,
+            "status": map_watch_status(args.receipt_status),
+            "watch_kind": "posttrade",
+            "subject": default_subject(args),
+            "trigger_source": args.venue,
+            "severity": args.severity or default_severity(args.receipt_status),
+            "next_check_hint": args.next_check_hint or default_next_check_hint(args),
+            "schedule_hint": args.schedule_hint or default_schedule_hint(args.receipt_status),
+            "recommended_adapter": default_adapter(args),
+            "evidence": parse_evidence(args.evidence, args.venue, args.receipt_status),
+        }
+    }
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    payload = build_posttrade_watch_payload(args)
+    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-native-operator/scripts/render_pretrade_packet.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""Render all normalized pretrade artifacts in one bundle."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+from render_execution_bundle import resolve_risk_gate, resolve_simulation, validate_merged_context
+from render_operator_bundle import (
+    RESEARCH_CONCLUSIONS,
+    RESEARCH_FRESHNESS_VALUES,
+    build_pretrade_bundle,
+    resolve_research_brief,
+    wants_risk_context,
+    wants_simulation_context,
+)
+
+
+RISK_GATE_SCRIPTS_DIR = (
+    Path(__file__).resolve().parents[2] / "web3-risk-gate" / "scripts"
+)
+if str(RISK_GATE_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(RISK_GATE_SCRIPTS_DIR))
+
+from merge_risk_gate_blocks import default_next_steps as default_risk_next_steps
+
+SIMULATION_SCRIPTS_DIR = (
+    Path(__file__).resolve().parents[2] / "web3-transaction-simulator" / "scripts"
+)
+if str(SIMULATION_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SIMULATION_SCRIPTS_DIR))
+
+from merge_simulation_blocks import default_next_steps as default_simulation_next_steps
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a Web3 pretrade packet.")
+    parser.add_argument("--intent", required=True)
+    parser.add_argument("--chain", required=True)
+    parser.add_argument("--research-input-file")
+    parser.add_argument("--research-conclusion", choices=RESEARCH_CONCLUSIONS)
+    parser.add_argument("--research-freshness", choices=RESEARCH_FRESHNESS_VALUES)
+    parser.add_argument("--research-question", default="")
+    parser.add_argument("--research-source", action="append", default=[])
+    parser.add_argument("--research-evidence", action="append", default=[])
+    parser.add_argument("--research-cross-check", action="append", default=[])
+    parser.add_argument("--research-next-step", action="append", default=[])
+    parser.add_argument("--risk-decision", choices=("ALLOW", "WARN", "BLOCK"))
+    parser.add_argument("--risk-coverage", choices=("complete", "partial", "missing"))
+    parser.add_argument("--risk-input-file", action="append", default=[])
+    parser.add_argument(
+        "--simulation-status",
+        choices=("PASS", "WARN", "FAIL", "NO_SIMULATION"),
+    )
+    parser.add_argument(
+        "--simulation-readiness",
+        choices=("ready", "needs-confirmation", "blocked"),
+    )
+    parser.add_argument("--simulation-venue")
+    parser.add_argument("--simulation-input-file", action="append", default=[])
+    parser.add_argument("--reason", action="append", default=[])
+    parser.add_argument("--follow-up-skill", action="append", default=[])
+    return parser
+
+
+def build_minimal_risk_gate(
+    intent: str,
+    chain: str,
+    decision: str,
+    coverage: str,
+) -> dict[str, object]:
+    return {
+        "version": 1,
+        "decision": decision,
+        "action": intent,
+        "chain": chain,
+        "coverage": coverage,
+        "subject": {},
+        "next_steps": default_risk_next_steps(decision, intent, coverage),
+        "evidence": [],
+    }
+
+
+def build_minimal_simulation(
+    intent: str,
+    chain: str,
+    status: str,
+    readiness: str,
+    venue: str,
+) -> dict[str, object]:
+    return {
+        "version": 1,
+        "status": status,
+        "action": intent,
+        "venue": venue,
+        "chain": chain,
+        "readiness": readiness,
+        "route": {},
+        "next_step": default_simulation_next_steps(status, readiness),
+        "evidence": [],
+    }
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        research_conclusion, research_freshness, research_brief = resolve_research_brief(
+            intent=args.intent,
+            chain=args.chain,
+            research_input_file=args.research_input_file,
+            research_conclusion=args.research_conclusion,
+            research_freshness=args.research_freshness,
+            research_question=args.research_question,
+            research_source=args.research_source,
+            research_evidence=args.research_evidence,
+            research_cross_check=args.research_cross_check,
+            research_next_step=args.research_next_step,
+        )
+        risk_decision = None
+        risk_coverage = None
+        merged_gate = None
+        if research_conclusion == "ready-for-risk-gate" or wants_risk_context(args):
+            risk_decision, risk_coverage, merged_gate = resolve_risk_gate(
+                args.risk_decision,
+                args.risk_coverage,
+                args.risk_input_file,
+            )
+
+        simulation_status = None
+        simulation_readiness = None
+        simulation_venue = None
+        merged_simulation = None
+        if research_conclusion == "ready-for-risk-gate" or wants_simulation_context(args):
+            simulation_status, simulation_readiness, simulation_venue, merged_simulation = resolve_simulation(
+                args.simulation_status,
+                args.simulation_readiness,
+                args.simulation_venue,
+                args.simulation_input_file,
+            )
+
+        validate_merged_context(args.intent, args.chain, merged_gate, merged_simulation)
+    except ValueError as exc:
+        parser.error(str(exc))
+
+    operator_args = argparse.Namespace(
+        intent=args.intent,
+        chain=args.chain,
+        research_conclusion=research_conclusion,
+        research_freshness=research_freshness,
+        risk_decision=args.risk_decision,
+        risk_coverage=args.risk_coverage,
+        simulation_status=args.simulation_status,
+        simulation_readiness=args.simulation_readiness,
+        simulation_venue=args.simulation_venue,
+        follow_up_skill=args.follow_up_skill,
+        reason=args.reason,
+    )
+    operator_bundle = build_pretrade_bundle(
+        operator_args,
+        research_conclusion=research_conclusion,
+        research_freshness=research_freshness,
+        risk_decision=risk_decision,
+        risk_coverage=risk_coverage,
+        simulation_status=simulation_status,
+        simulation_readiness=simulation_readiness,
+        simulation_venue=simulation_venue,
+    )
+
+    packet: dict[str, object] = {
+        "version": 1,
+        "intent": args.intent,
+        "chain": args.chain,
+        "research_brief": research_brief,
+        "operator_bundle": operator_bundle,
+    }
+    if risk_decision is not None and risk_coverage is not None:
+        packet["risk_gate"] = (
+            merged_gate
+            if merged_gate is not None
+            else build_minimal_risk_gate(args.intent, args.chain, risk_decision, risk_coverage)
+        )
+    if simulation_status is not None and simulation_readiness is not None:
+        packet["simulation"] = (
+            merged_simulation
+            if merged_simulation is not None
+            else build_minimal_simulation(
+                args.intent,
+                args.chain,
+                simulation_status,
+                simulation_readiness,
+                simulation_venue or "",
+            )
+        )
+
+    json.dump({"pretrade_packet": packet}, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/skills/web3-native-operator/scripts/render_watch_cron_request.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Render a structured cron request from watch fields."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a watch-driven cron request.")
+    parser.add_argument("--subject", required=True)
+    parser.add_argument("--watch-kind", required=True)
+    parser.add_argument("--status", required=True)
+    parser.add_argument("--severity", required=True)
+    parser.add_argument("--recommended-adapter", required=True)
+    parser.add_argument("--next-check-hint", default="")
+    parser.add_argument("--message", default="")
+    parser.add_argument("--every-seconds", type=int, default=0)
+    parser.add_argument("--cron-expr", default="")
+    parser.add_argument("--tz", default="")
+    parser.add_argument("--at", default="")
+    return parser
+
+
+def build_message(args: argparse.Namespace) -> str:
+    if args.message:
+        return args.message
+    next_check = args.next_check_hint or "refresh according to the configured schedule"
+    return (
+        f"Re-run {args.recommended_adapter} for {args.subject} ({args.watch_kind}) and summarize any new evidence. "
+        f"Current status is {args.status} with severity {args.severity}. "
+        f"Next check hint: {next_check}. "
+        "Escalate immediately if severity becomes high or critical."
+    )
+
+
+def schedule_key_count(args: argparse.Namespace) -> int:
+    return sum(
+        1
+        for active in (
+            args.every_seconds > 0,
+            bool(args.cron_expr),
+            bool(args.at),
+        )
+        if active
+    )
+
+
+def validate_schedule_args(args: argparse.Namespace) -> None:
+    if schedule_key_count(args) != 1:
+        raise SystemExit("exactly one of --every-seconds, --cron-expr, or --at is required")
+    if args.tz and not args.cron_expr:
+        raise SystemExit("--tz can only be used with --cron-expr")
+
+
+def build_cron_request_payload(args: argparse.Namespace) -> dict[str, object]:
+    validate_schedule_args(args)
+    payload: dict[str, object] = {
+        "cron_request": {
+            "action": "add",
+            "message": build_message(args),
+        }
+    }
+    request = payload["cron_request"]
+    assert isinstance(request, dict)
+    if args.every_seconds > 0:
+        request["every_seconds"] = args.every_seconds
+    elif args.cron_expr:
+        request["cron_expr"] = args.cron_expr
+        if args.tz:
+            request["tz"] = args.tz
+    else:
+        request["at"] = args.at
+    return payload
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    payload = build_cron_request_payload(args)
+    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-native-operator/scripts/render_watch_followup_bundle.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""Render all downstream watch artifacts in one bundle."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from render_operator_bundle import build_watch_bundle
+from render_watch_cron_request import build_cron_request_payload
+from render_watch_heartbeat import build_heartbeat_task
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a Web3 watch follow-up bundle.")
+    parser.add_argument(
+        "--watch-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("--reason", action="append", default=[])
+    parser.add_argument("--follow-up-skill", action="append", default=[])
+    parser.add_argument("--task-note", default="")
+    parser.add_argument("--every-seconds", type=int, default=0)
+    parser.add_argument("--cron-expr", default="")
+    parser.add_argument("--tz", default="")
+    parser.add_argument("--at", default="")
+    return parser
+
+
+def maybe_build_cron_request(args: argparse.Namespace) -> dict[str, object] | None:
+    explicit_args = argparse.Namespace(
+        subject=args.subject,
+        watch_kind=args.watch_kind,
+        status=args.watch_status,
+        severity=args.severity,
+        recommended_adapter=args.recommended_adapter,
+        next_check_hint=args.next_check_hint,
+        message="",
+        every_seconds=args.every_seconds,
+        cron_expr=args.cron_expr,
+        tz=args.tz,
+        at=args.at,
+    )
+    if args.every_seconds > 0 or args.cron_expr or args.at:
+        return build_cron_request_payload(explicit_args)["cron_request"]
+    if args.schedule_hint and args.schedule_hint != "manual":
+        cron_args = argparse.Namespace(
+            subject=args.subject,
+            watch_kind=args.watch_kind,
+            status=args.watch_status,
+            severity=args.severity,
+            recommended_adapter=args.recommended_adapter,
+            next_check_hint=args.next_check_hint,
+            message="",
+            every_seconds=0,
+            cron_expr=args.schedule_hint,
+            tz=args.tz,
+            at="",
+        )
+        return build_cron_request_payload(cron_args)["cron_request"]
+    return None
+
+
+def build_watch_status(args: argparse.Namespace) -> dict[str, object]:
+    return {
+        "version": 1,
+        "status": args.watch_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,
+    }
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    operator_bundle = build_watch_bundle(args)
+    effective_adapter = args.recommended_adapter or str(operator_bundle["next_adapter"])
+    normalized_args = argparse.Namespace(**vars(args))
+    normalized_args.recommended_adapter = effective_adapter
+    heartbeat_task = build_heartbeat_task(normalized_args)
+    cron_request = maybe_build_cron_request(normalized_args)
+    payload = {
+        "watch_followup_bundle": {
+            "version": 1,
+            "watch_status": build_watch_status(normalized_args),
+            "operator_bundle": operator_bundle,
+            "heartbeat_task": heartbeat_task,
+            "cron_request": cron_request,
+        }
+    }
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())