web3skill 0.1.0

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

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Render a stable HEARTBEAT.md task block from watch status fields."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a Web3 watch heartbeat block.")
+    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("--schedule-hint", default="")
+    parser.add_argument("--next-check-hint", default="")
+    parser.add_argument("--task-note", default="")
+    return parser
+
+
+def build_heartbeat_task(args: argparse.Namespace) -> str:
+    status = getattr(args, "status", getattr(args, "watch_status", ""))
+    task = (
+        args.task_note
+        or (
+            f"Re-run {args.recommended_adapter} for {args.subject} on heartbeat and summarize any new evidence. "
+            "Escalate immediately if severity becomes high or critical."
+        )
+    )
+    lines = [
+        f"- [ ] Watch {args.subject}",
+        f"  Task: {task}",
+        f"  Watch Kind: {args.watch_kind}",
+        f"  Status: {status}",
+        f"  Severity: {args.severity}",
+        f"  Adapter: {args.recommended_adapter}",
+        f"  Schedule Hint: {args.schedule_hint or 'manual'}",
+        f"  Next Check Hint: {args.next_check_hint or 'refresh on next heartbeat'}",
+    ]
+    return "\n".join(lines)
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    sys.stdout.write(build_heartbeat_task(args) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/skills/web3-repo-heuristics/SKILL.md

@@ -0,0 +1,37 @@
+---
+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
+---
+
+# Web3 Repo Heuristics
+
+Use this skill to fingerprint the repository before editing or testing.
+
+## Detection Order
+
+1. Look for `foundry.toml`, `remappings.txt`, `lib/`, `src/`, `script/`, `test/`.
+2. Look for `hardhat.config.*`, `package.json`, `contracts/`, `ignition/`, `deploy/`, `tasks/`, `test/`.
+3. Look for Vyper signals such as `.vy` files, `pyproject.toml`, `requirements*.txt`, `ape-config.yaml`, or `brownie-config.yaml`.
+4. If multiple stacks exist, map which stack is authoritative for build, test, deploy, and verification instead of assuming one toolchain owns everything.
+
+## Read Order
+
+- manifest and build config first
+- dependency and remapping files second
+- contracts and libraries third
+- scripts and deployment paths fourth
+- tests and invariants fifth
+- artifacts or broadcasts last, as outputs rather than source of truth
+
+## Command Selection
+
+- For Foundry, read `references/FOUNDRY.md`.
+- For Hardhat, read `references/HARDHAT.md`.
+- For Vyper-oriented repos, read `references/VYPER.md`.
+
+## Guardrails
+
+- Do not edit generated artifacts unless the user explicitly asks for it.
+- Prefer running the framework-native formatter and test commands before inventing custom shell glue.
+- If compile targets or Solidity versions differ across packages, record that explicitly before patching.

package/dist/skills/web3-repo-heuristics/references/FOUNDRY.md

@@ -0,0 +1,49 @@
+# Foundry Heuristics
+
+## Primary Files
+
+- `foundry.toml`
+- `remappings.txt`
+- `src/`
+- `script/`
+- `test/`
+- `lib/`
+- `broadcast/`
+- `out/`
+
+## Default Commands
+
+- format:
+  - `forge fmt`
+- build:
+  - `forge build`
+- test:
+  - `forge test`
+- focused test:
+  - `forge test --match-test <name>`
+  - `forge test --match-contract <name>`
+- gas and verbosity:
+  - `forge test -vvv`
+- inspect:
+  - `forge inspect <Contract> methods`
+  - `forge inspect <Contract> storage-layout`
+- local chain:
+  - `anvil`
+- ad hoc RPC or ABI work:
+  - `cast call`
+  - `cast sig`
+  - `cast 4byte`
+
+## Review Patterns
+
+- Read `script/` to understand deployment assumptions and broadcast behavior.
+- Read `test/` for expected invariants and edge cases before modifying contracts.
+- Treat `broadcast/` and `out/` as derived outputs.
+- Check for invariant tests, fuzz tests, and cheatcode usage in `forge-std/Test.sol`.
+
+## Common Risks
+
+- stale remappings
+- hidden dependency logic in `lib/`
+- deployment parameters embedded in scripts
+- tests that rely on forked state or env vars not obvious from the contract files

package/dist/skills/web3-repo-heuristics/references/HARDHAT.md

@@ -0,0 +1,47 @@
+# Hardhat Heuristics
+
+## Primary Files
+
+- `package.json`
+- `hardhat.config.js|ts|cjs|mjs`
+- `contracts/`
+- `test/`
+- `scripts/`
+- `tasks/`
+- `ignition/`
+- `deploy/`
+- `artifacts/`
+- `cache/`
+
+## Default Commands
+
+- install:
+  - `pnpm install`
+  - `npm install`
+  - `yarn install`
+- compile:
+  - `npx hardhat compile`
+- test:
+  - `npx hardhat test`
+- run a script:
+  - `npx hardhat run scripts/<name>.ts --network <network>`
+- local node:
+  - `npx hardhat node`
+- console:
+  - `npx hardhat console --network <network>`
+
+Choose the package manager already used by the repo.
+
+## Review Patterns
+
+- Start from `package.json` to see plugins, scripts, and package manager.
+- Read `hardhat.config.*` before running anything; it often hides compiler versions, forking, networks, named accounts, and verify settings.
+- Prefer repo scripts if they wrap standard Hardhat commands with required env vars.
+- Treat `artifacts/` and `cache/` as generated outputs.
+
+## Common Risks
+
+- tests relying on implicit `.env` values
+- mixed TypeScript and JavaScript task runners
+- deployment logic split between `deploy/`, `scripts/`, and `ignition/`
+- multiple Solidity compiler versions or optimizer settings

package/dist/skills/web3-repo-heuristics/references/VYPER.md

@@ -0,0 +1,26 @@
+# Vyper Heuristics
+
+## Detection Signals
+
+- `.vy` contracts
+- `pyproject.toml`
+- `requirements.txt`
+- `requirements-dev.txt`
+- `ape-config.yaml`
+- `brownie-config.yaml`
+
+## Default Commands
+
+- compile:
+  - `vyper <file>.vy`
+  - project-specific wrapper commands from `pyproject.toml`
+- tests:
+  - `pytest`
+  - `ape test`
+  - `brownie test`
+
+## Review Patterns
+
+- Read the Python project manifest before assuming test or build entrypoints.
+- Check whether the repo uses Ape, Brownie, or direct Vyper plus pytest.
+- Treat Python fixtures and helper modules as part of the protocol surface, not just test plumbing.

package/dist/skills/web3-research-and-market-intel/SKILL.md

@@ -0,0 +1,138 @@
+---
+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.
+---
+
+# Web3 Research And Market Intel
+
+Use this skill when the task is research, project diligence, token comparison, or pre-trade intelligence gathering.
+
+## Required Profile Adapters
+
+- `defillama`
+- `coingecko`
+- `dune`
+- `whale-watcher`
+- `trading-signal`
+- `binance-token-info`
+- `binance-market-rank`
+- `binance-meme-rush`
+- `four-meme`
+- `debank`
+
+Use [references/ADAPTER_CONSUMPTION_MAP.md](references/ADAPTER_CONSUMPTION_MAP.md)
+to keep research adapter outputs stable and comparable.
+Use [references/EVIDENCE_QUALITY.md](references/EVIDENCE_QUALITY.md) and
+[references/OUTPUT_TEMPLATE.md](references/OUTPUT_TEMPLATE.md) to keep source
+freshness and conclusion routing stable.
+Use [scripts/render_research_brief.py](scripts/render_research_brief.py) when a
+downstream skill or runtime needs a normalized research block.
+Use [references/PORTFOLIO_STATUS_TEMPLATE.md](references/PORTFOLIO_STATUS_TEMPLATE.md)
+and [scripts/render_portfolio_status.py](scripts/render_portfolio_status.py)
+when wallet, address, or venue position state must be emitted as a stable
+`portfolio_status` block.
+Use [references/WATCH_STATUS_TEMPLATE.md](references/WATCH_STATUS_TEMPLATE.md)
+and [scripts/render_watch_status.py](scripts/render_watch_status.py) when a
+monitoring or alerting workflow must be emitted as a stable `watch_status`
+block for operator consumption.
+
+## Workflow
+
+1. Decide the research question:
+   - token
+   - protocol
+   - chain ecosystem
+   - whale flow
+   - smart-money signal
+   - wallet / address / venue portfolio state
+   - recurring watch / alert condition
+2. Pull only the sources that answer that question.
+3. Keep raw source outputs separate from synthesized judgment.
+4. Summarize the result as evidence, not as blind trade advice.
+
+## Suggested Source Split
+
+- `defillama` for TVL, chain comparison, yield, and protocol-level metrics
+- `coingecko` for price, market cap, trending, and historical market context
+- `dune` for query-driven custom analytics
+- `whale-watcher` for large address flow
+- `trading-signal` for Binance smart-money style signals
+- `binance-token-info` for metadata, dynamic data, and kline access
+- `binance-market-rank` for ranked discovery and social/smart-money leaderboards
+- `binance-meme-rush` for launchpad and narrative discovery
+- `four-meme` for BSC launchpad-specific discovery
+- `debank` for wallet portfolio, protocol position, and address-level diligence
+- `query-address-info` for chain-scoped wallet holdings and concentration hints
+- `hyperliquid` for venue-native position and order state when the portfolio question is venue-specific
+
+## Output Contract
+
+```text
+Question:
+- what was investigated
+Evidence:
+- source + key observation
+Cross-Checks:
+- where sources agree or disagree
+Conclusion:
+- watch | investigate more | suitable for next-step simulation | avoid for now
+```
+
+## Reusable Output Contract
+
+Always emit both:
+
+1. A short research summary
+2. A normalized `research_brief` block
+
+The normalized block must preserve:
+
+- question and source freshness
+- sources actually used
+- evidence observations
+- cross-checks or disagreements
+- conclusion bucket
+- next steps and route-back conditions
+
+## Watch Status Contract
+
+Always emit a normalized `watch_status` block when the user asks to:
+
+- watch a token, protocol, address, or venue state over time
+- keep monitoring post-trade settlement or venue positions
+- produce an alert-ready monitoring bundle for the operator or scheduler
+
+The normalized block must preserve:
+
+- status and watch kind
+- the monitored subject
+- trigger source and severity
+- next check or schedule hints
+- the recommended adapter for the next monitoring step
+- evidence provenance per source
+
+## Portfolio Status Contract
+
+Always emit a normalized `portfolio_status` block when the user asks:
+
+- "这个地址里有什么"
+- "我在 Hyperliquid 上现在有哪些仓位"
+- "帮我看这个钱包/仓位状态"
+
+The normalized block must preserve:
+
+- status and coverage
+- source class: `wallet | address | venue`
+- venue or provider identity
+- address or user reference
+- chain / network scope
+- asset and position summary
+- evidence provenance per source
+
+## Guardrails
+
+- Do not present a single data provider as ground truth.
+- Separate descriptive analysis from trading recommendation.
+- If the data is stale, chain-limited, or sparse, say that explicitly.
+- If the user wants to trade after research, send the flow to `web3-risk-gate` and `web3-transaction-simulator`.
+- If the outcome is "keep watching", emit `watch_status` instead of implying trade readiness.

package/dist/skills/web3-research-and-market-intel/references/ADAPTER_CONSUMPTION_MAP.md

@@ -0,0 +1,66 @@
+# Research Adapter Consumption Map
+
+- `defillama` -> TVL, protocol metrics, chain comparison
+- `coingecko` -> price, market cap, historical context
+- `dune` -> custom query evidence
+- `whale-watcher` -> large flow evidence
+- `trading-signal` -> smart-money style signals
+- `binance-token-info` -> metadata and dynamic token fields
+- `binance-market-rank` -> ranked discovery
+- `binance-meme-rush` -> meme/token launch discovery
+- `four-meme` -> BSC launchpad discovery
+- `debank` -> address portfolio and position evidence
+- `query-address-info` -> chain-scoped holdings and asset concentration evidence
+- `hyperliquid` -> venue-native position / order / balance status
+
+Normalize into:
+
+- question
+- evidence
+- cross-checks
+- conclusion
+
+For wallet, address, or venue state questions, also normalize into:
+
+```yaml
+portfolio_status:
+  status: COMPLETE | PARTIAL | UNAVAILABLE
+  coverage: complete | partial | missing
+  source_class: wallet | address | venue
+  provider: debank | query-address-info | hyperliquid
+  venue: hyperliquid | none
+  subject:
+    address: "0x..."
+    user: "0x..."
+  scope:
+    chain: base
+    network: mainnet
+  assets:
+    - symbol: USDC
+      usd_value: "1200"
+  positions:
+    - protocol: Aave
+      type: lending
+      usd_value: "800"
+  evidence:
+    - adapter: debank
+      detail: total balance and token list fetched
+```
+
+For monitoring or alerting tasks, also normalize into:
+
+```yaml
+watch_status:
+  version: 1
+  status: ACTIVE | TRIGGERED | CLEARED | UNAVAILABLE
+  watch_kind: research | portfolio | posttrade | trace | venue | execution
+  subject: token:PEPE
+  trigger_source: whale-watcher
+  severity: medium
+  next_check_hint: refresh whale flow after 15 minutes
+  schedule_hint: "*/15 * * * *"
+  recommended_adapter: whale-watcher
+  evidence:
+    - adapter: whale-watcher
+      detail: large inflow exceeds prior 24h baseline
+```

package/dist/skills/web3-research-and-market-intel/references/EVIDENCE_QUALITY.md

@@ -0,0 +1,27 @@
+# Research Evidence Quality
+
+Normalize data freshness into:
+
+- `fresh`
+  - recent enough for the research question and cross-checked with at least one other source when possible
+- `mixed`
+  - some evidence is current, some is stale or chain-limited
+- `stale`
+  - core evidence is outdated, sparse, or unavailable
+
+## Conclusion Buckets
+
+- `watch`
+  - evidence is interesting but not ready for execution
+- `investigate-more`
+  - evidence conflicts or coverage is too thin
+- `ready-for-risk-gate`
+  - research is good enough to proceed into safety checks and simulation
+- `avoid-for-now`
+  - evidence is materially negative or too weak for action
+
+## Rules
+
+- Always separate factual evidence from final judgment.
+- If a source is chain-limited or provider-limited, mention that in cross-checks.
+- If the user wants execution after research, route to `web3-risk-gate` and `web3-transaction-simulator`.

package/dist/skills/web3-research-and-market-intel/references/OUTPUT_TEMPLATE.md

@@ -0,0 +1,37 @@
+# Web3 Research Output Template
+
+Always emit:
+
+1. A short human-readable research summary
+2. A normalized block
+
+```yaml
+research_brief:
+  version: 1
+  question: Should this token move into trade-prep?
+  freshness: mixed
+  sources_used:
+    - defillama
+    - coingecko
+    - dune
+  evidence:
+    - adapter: defillama
+      detail: TVL has been flat for 30 days
+    - adapter: coingecko
+      detail: market cap up 18% this week
+  cross_checks:
+    - price momentum improved but TVL confirmation is weak
+  conclusion: investigate-more
+  next_steps:
+    - pull whale flow and address concentration before risk gate
+```
+
+## Required Fields
+
+- `question`
+- `freshness`: `fresh | mixed | stale`
+- `sources_used`
+- `evidence`
+- `cross_checks`
+- `conclusion`: `watch | investigate-more | ready-for-risk-gate | avoid-for-now`
+- `next_steps`

package/dist/skills/web3-research-and-market-intel/references/PORTFOLIO_STATUS_TEMPLATE.md

@@ -0,0 +1,51 @@
+# Web3 Portfolio Status Template
+
+Always emit:
+
+1. A short human-readable portfolio / position summary
+2. A normalized block
+
+```yaml
+portfolio_status:
+  version: 1
+  status: COMPLETE
+  coverage: complete
+  source_class: wallet
+  provider: debank
+  venue: none
+  subject:
+    address: 0xabc
+    user: ""
+  scope:
+    chain: multi
+    network: mainnet
+  assets:
+    - symbol: ETH
+      amount: "1.2"
+      usd_value: "2400"
+  positions:
+    - protocol: Aave
+      type: lending
+      usd_value: "1800"
+  evidence:
+    - adapter: debank
+      detail: total balance and protocol positions fetched
+```
+
+## Required Fields
+
+- `status`: `COMPLETE | PARTIAL | UNAVAILABLE`
+- `coverage`: `complete | partial | missing`
+- `source_class`: `wallet | address | venue`
+- `provider`
+- `subject`
+- `scope`
+- `assets`
+- `positions`
+- `evidence`
+
+## Notes
+
+- Use empty lists instead of dropping `assets` or `positions`.
+- `venue` should be `none` for non-venue sources.
+- `UNAVAILABLE` still requires concrete evidence or unknowns in the human summary.

package/dist/skills/web3-research-and-market-intel/references/WATCH_STATUS_TEMPLATE.md

@@ -0,0 +1,39 @@
+# Web3 Watch Status Template
+
+Always emit:
+
+1. A short human-readable monitoring or alert summary
+2. A normalized block
+
+```yaml
+watch_status:
+  version: 1
+  status: TRIGGERED
+  watch_kind: research
+  subject: token:PEPE
+  trigger_source: whale-watcher
+  severity: high
+  next_check_hint: refresh large-holder flow after 5 minutes
+  schedule_hint: "*/5 * * * *"
+  recommended_adapter: whale-watcher
+  evidence:
+    - adapter: whale-watcher
+      detail: net inflow exceeded 1m USDT in 10 minutes
+```
+
+## Required Fields
+
+- `status`: `ACTIVE | TRIGGERED | CLEARED | UNAVAILABLE`
+- `watch_kind`: `research | portfolio | posttrade | trace | venue | execution`
+- `subject`
+- `trigger_source`
+- `severity`: `low | medium | high | critical`
+- `next_check_hint`
+- `recommended_adapter`
+- `evidence`
+
+## Notes
+
+- `schedule_hint` is optional and should stay advisory until a runtime actually schedules it.
+- Use `recommended_adapter = none` only when the watch is cleared or intentionally terminated.
+- `UNAVAILABLE` still requires concrete evidence about missing data, backend failure, or unsupported scope.

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

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Render a stable Web3 portfolio status block."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a Web3 portfolio status block.")
+    parser.add_argument("--status", choices=("COMPLETE", "PARTIAL", "UNAVAILABLE"), required=True)
+    parser.add_argument("--coverage", choices=("complete", "partial", "missing"), default="partial")
+    parser.add_argument("--source-class", choices=("wallet", "address", "venue"), required=True)
+    parser.add_argument("--provider", required=True)
+    parser.add_argument("--venue", default="none")
+    parser.add_argument("--address", default="")
+    parser.add_argument("--user", default="")
+    parser.add_argument("--chain", default="")
+    parser.add_argument("--network", default="mainnet")
+    parser.add_argument("--asset", action="append", default=[])
+    parser.add_argument("--position", action="append", default=[])
+    parser.add_argument("--evidence", action="append", default=[])
+    return parser
+
+
+def parse_pairs(entries: list[str], kind: str) -> list[dict[str, str]]:
+    parsed: list[dict[str, str]] = []
+    for entry in entries:
+        parts = [part.strip() for part in entry.split("|")]
+        if kind == "asset":
+            symbol = parts[0] if len(parts) > 0 else ""
+            amount = parts[1] if len(parts) > 1 else ""
+            usd_value = parts[2] if len(parts) > 2 else ""
+            parsed.append({"symbol": symbol, "amount": amount, "usd_value": usd_value})
+        else:
+            protocol = parts[0] if len(parts) > 0 else ""
+            position_type = parts[1] if len(parts) > 1 else ""
+            usd_value = parts[2] if len(parts) > 2 else ""
+            parsed.append({"protocol": protocol, "type": position_type, "usd_value": usd_value})
+    return parsed
+
+
+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 = {
+        "portfolio_status": {
+            "version": 1,
+            "status": args.status,
+            "coverage": args.coverage,
+            "source_class": args.source_class,
+            "provider": args.provider,
+            "venue": args.venue,
+            "subject": {
+                "address": args.address,
+                "user": args.user,
+            },
+            "scope": {
+                "chain": args.chain,
+                "network": args.network,
+            },
+            "assets": parse_pairs(args.asset, "asset"),
+            "positions": parse_pairs(args.position, "position"),
+            "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())