dero-mcp-server 0.1.2 → 0.2.2

package/README.md

@@ -6,7 +6,7 @@
 [![CI](https://github.com/DHEBP/dero-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/DHEBP/dero-mcp-server/actions/workflows/ci.yml)
 [![dero-mcp-server MCP server](https://glama.ai/mcp/servers/DHEBP/dero-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/DHEBP/dero-mcp-server)
 
-**Registry listing:** `io.github.DHEBP/dero-mcp-server` · **Version:** `0.1.2` · **Transport:** `stdio` (npm package)
+**Registry listing:** `io.github.DHEBP/dero-mcp-server` · **Version:** `0.2.2` · **Transport:** `stdio` (npm package)
 
 ---
 
@@ -114,18 +114,18 @@ In **OpenCode MCP settings**, add a server with the same `command` / `args` / `e
 | `DERO_DAEMON_URL` | `http://82.65.143.182:10102` | Daemon **base** URL (no `/json_rpc` required). Set to `http://127.0.0.1:10102` for a local daemon. |
 | `DERO_DOCS_ROOT` | bundled index | Optional dev override: path to a local `dero-docs` clone to index live MDX instead of the shipped bundle. |
 
-## Maintainer: refresh bundled docs
+## Maintainer: bundled docs
 
-Before publishing a new npm version when `dero-docs` changed:
+Docs tools read from `data/docs-index.json`, committed in this repo and shipped with the npm package. Rebuild the index when [dero-docs](https://github.com/DHEBP/dero-docs) changes:
 
 ```bash
-DERO_DOCS_ROOT=/path/to/dero-docs npm run build:docs
-npm run build
-npm publish
-mcp-publisher publish
+npm run release:docs-check
+git add data/docs-index.json && git commit -m "Refresh bundled docs index."
 ```
 
-`prepack` runs `build:docs` automatically when `dero-docs` is available at `../dero-docs` or via `DERO_DOCS_ROOT`.
+Or run **Refresh docs bundle** under [Actions](https://github.com/DHEBP/dero-mcp-server/actions/workflows/refresh-docs-bundle.yml) to open a PR. Pushes to `dero-docs` `main` can trigger that workflow via `repository_dispatch` when `MCP_DOCS_SYNC_TOKEN` is configured on the docs repo.
+
+After merging a bundle update: bump the patch version in `package.json` and `server.json`, then `npm publish --otp=...` and `mcp-publisher publish`.
 
 ## Testing
 

package/data/docs-index.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generated_at": "2026-05-20T04:57:07.336Z",
+  "generated_at": "2026-05-24T01:55:47.792Z",
   "page_count": 145,
   "pages": [
     {
@@ -1580,30 +1580,38 @@
     {
       "product": "derod",
       "slug": "tools/mcp-server",
-      "title": "Mcp Server",
-      "description": null,
+      "title": "DERO MCP Server | AI Assistant Integration for the DERO Blockchain",
+      "description": "Run a read-only, agent-ready DERO MCP server locally. 20 daemon-read primitives, 5 composite tools that fuse live chain reads with the bundled DERO docs index, plus structured errors and curated citations — no middlemen, no API keys, no surveillance.",
       "canonicalUrl": "https://derod.org/tools/mcp-server",
       "sourcePath": "derod-main/pages/tools/mcp-server.mdx",
       "headings": [
         "MCP Server",
+        "What's New in 0.2.0",
         "Why This Matters",
         "Install",
         "Run Your Own Node",
-        "Start your local DERO daemon with RPC enabled",
         "Configure Your MCP Client",
         "Claude Desktop",
         "Cursor",
         "OpenCode",
-        "Continue / Cline / Zed / Others",
+        "Continue · Cline · Zed · others",
+        "Inspect interactively",
         "What You Can Ask",
-        "Available Tools",
-        "Security Model",
+        "Composite Tools",
+        "Primitive Tools",
+        "Daemon RPC",
+        "Bundled docs index",
+        "Resources and Prompts",
+        "Resources",
+        "Prompts",
+        "Structured Errors",
+        "Read-Only by Design",
         "Environment",
         "Verify, Don't Trust",
         "See Also"
       ],
-      "plainText": "MCP Server Query the DERO blockchain from AI assistants — no middlemen, no API keys, no surveillance. The DERO MCP server implements the Model Context Protocol, an open standard for connecting AI models to external tools. Run it locally, point it at your own node, and let your AI assistant interact with DERO directly. Why This Matters AI assistants are powerful research tools, but most blockchain integrations route through centralized APIs that log your queries. This server runs on **your machine**, talks to **your node** (or a public one you choose), and communicates with your AI over **local stdio**. No accounts. No tracking. Just code you can audit. Install Requires Node.js 18+. Source code: github.com/DHEBP/dero-mcp-server Run Your Own Node The server defaults to a third-party public RPC. For real privacy, run your own daemon: Then configure the MCP server to use it (see below). Configure Your MCP Client Claude Desktop Edit claude_desktop_config.json: | OS | Path | |----|------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\\Claude\\claude_desktop_config.json | | Linux | ~/.config/claude/claude_desktop_config.json | Omit env to use the default public RPC. Cursor **Settings → MCP → Add Server** - Command: dero-mcp-server - Environment: DERO_DAEMON_URL=http://127.0.0.1:10102 (optional) OpenCode Or with a local node: Continue / Cline / Zed / Others Any MCP-compatible client works. The server uses **stdio** transport: Consult your client's MCP documentation for the exact config format. What You Can Ask Once connected, talk to your AI naturally: - *\"What's the current DERO block height?\"* - *\"Show me the source code for contract [SCID]\"* - *\"What variables does this smart contract store?\"* - *\"Look up the transaction [TXID]\"* - *\"What's the network hashrate and difficulty?\"* - *\"Resolve the name dero to a wallet address\"* Available Tools | Tool | RPC Method | Description | |------|------------|-------------| | dero_daemon_ping | DERO.Ping | Check daemon connectivity | | dero_get_info | DERO.GetInfo | Network height, difficulty, version, hashrate | | dero_get_height | DERO.GetHeight | Current height, stable height, topoheight | | dero_get_block | DERO.GetBlock | Full block by hash or height | | dero_get_block_header_by_hash | DERO.GetBlockHeaderByHash | Block header by hash | | dero_get_block_header_by_topoheight | DERO.GetBlockHeaderByTopoHeight | Block header by topoheight | | dero_get_block_template | DERO.GetBlockTemplate | Mining block template | | dero_get_tx | DERO.GetTransaction | Transaction details by hash | | dero_get_sc | DERO.GetSC | Smart contract code and state variables | | dero_get_gas_estimate | DERO.GetGasEstimate | Estimate gas for a contract call | | dero_get_random_address | DERO.GetRandomAddress | Random registered wallet addresses | | dero_name_to_address | DERO.NameToAddress | Resolve registered name → address | | dero_get_encrypted_balance | DERO.GetEncryptedBalance | Encrypted balance for an address | Security Model **Read-only by design.** This server cannot: - Send transactions - Transfer funds - Invoke smart contracts - Submit blocks - Access your wallet Wallet RPC methods (transfer, scinvoke, etc.) are explicitly excluded. The server only queries public blockchain data through daemon RPC. If you need write capabilities in the future, they will be gated behind explicit flags and a separate wallet URL — never enabled by default. Environment | Variable | Default | Description | |----------|---------|-------------| | DERO_DAEMON_URL | http://82.65.143.182:10102 | Daemon base URL. Set to http://127.0.0.1:10102 for a local node. | Verify, Don't Trust - Source code on GitHub - Package on npm - MIT licensed — fork it, audit it, improve it See Also - DERO Daemon RPC API — full RPC reference - Running a DERO Node — set up your own daemon - XSWD — browser wallet integration",
-      "lastUpdated": null
+      "plainText": "MCP Server Query the DERO blockchain — and the canonical DERO documentation — from AI assistants. No middlemen, no API keys, no surveillance. The DERO MCP server implements the Model Context Protocol, the open standard for connecting AI models to external tools. Run it locally, point it at your own daemon, and let your AI assistant interact with DERO directly over local **stdio** transport. **AI discovery files:** llms.txt and /api/openapi.json are curated subsets for agents — not a full RPC catalog. Use the Daemon RPC API and Wallet RPC API for complete method reference. Examples assume a **local daemon** at http://127.0.0.1:10102 (there is no official public node.dero.io endpoint). What's New in 0.2.0 The 0.2.0 release expands the surface from 20 primitives to **25 tools** by adding 5 **composite tools** that fuse live daemon reads with the bundled DERO docs index. Every response includes curated related_docs citations, every tool carries read-only annotations (so MCP hosts can auto-approve safely), and four new structured _meta.error codes (NO_DOCS_MATCH, INVALID_INPUT, TX_NOT_FOUND, plus existing RPC_UNREACHABLE / RPC_INVALID_PARAMS) let agents react programmatically to failures. | Surface area | 0.1.x | 0.2.0 | |---|---:|---:| | Tools | 20 | **25** (+5 composites) | | Read-only annotations | none | **25/25** | | Curated docs citations | none | **16 across 7 tools** | | Structured error codes | none | **5** | | Resources | 3 | **4** (+composite catalog) | | Prompts | 3 | **5** (refreshed composite-first, +2 new) | All 20 primitives keep their identifiers, schemas, and behavior — clients pinned to 0.1.x will continue to work. Why This Matters AI assistants are powerful research and dev tools, but most blockchain integrations route through centralized APIs that log your queries. This server runs on **your machine**, talks to **your daemon** (or a public one you choose), and communicates with your AI over **local stdio**. No accounts, no analytics, no tracking — just code you can audit. The bundled DERO documentation index (145+ pages across derod, tela, hologram, and deropay) is shipped inside the package, so the AI can quote primary sources offline without a single network round-trip beyond the daemon you pointed it at. Install Requires Node.js 18+. Source code: github.com/DHEBP/dero-mcp-server · npm: dero-mcp-server Run Your Own Node The server defaults to a third-party public RPC. For real privacy, run your own daemon: Then point the MCP server at it via DERO_DAEMON_URL (see below). Configure Your MCP Client Claude Desktop Edit claude_desktop_config.json: | OS | Path | |----|------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\\Claude\\claude_desktop_config.json | | Linux | ~/.config/claude/claude_desktop_config.json | Omit env to use the default public RPC. Cursor **Settings → MCP → Add Server** - Command: dero-mcp-server - Environment: DERO_DAEMON_URL=http://127.0.0.1:10102 (optional) OpenCode Or with a local node: Continue · Cline · Zed · others Any MCP-compatible client works. The server uses **stdio** transport: Consult your client's MCP documentation for the exact config format. Inspect interactively To explore the full surface without committing to a client config, use the official MCP Inspector: It opens a local web UI that lists every tool with its schema and annotations, lets you invoke any tool with form-filled args, and shows the structured response including _meta.error blocks. What You Can Ask Once connected, talk to your AI naturally — it will pick the right composite or primitive based on your intent: - *\"Is the DERO daemon healthy and synced?\"* → diagnose_chain_health - *\"What does the contract at SCID […] do?\"* → explain_smart_contract - *\"Look up transaction [txid] and tell me what it is.\"* → trace_transaction_with_context - *\"Which DERO docs page should I read to deploy a TELA app?\"* → recommend_docs_path - *\"Estimate the gas cost to deploy this DVM contract.\"* → estimate_deploy_cost - *\"What's the current block height?\"* → dero_get_info / dero_get_height - *\"Show me the source code for contract [SCID].\"* → dero_get_sc - *\"Resolve the name dero to a wallet address.\"* → dero_name_to_address Composite Tools Each composite replaces a multi-step primitive chain with a single call, returns a plain-language narrative summary, and stitches the most relevant bundled docs pages as related_docs citations. | Composite | Replaces | When to call | |---|---|---| | diagnose_chain_health | Ping + GetInfo + GetHeight + GetTxPool | Any \"is the chain healthy / are we synced\" question | | explain_smart_contract | GetSC + manual DVM-BASIC parsing + docs lookup | \"What does this contract do\" — returns function surface + token/registry/minimal/generic classification + 1-4 curated DVM docs | | recommend_docs_path | 4× parallel dero_docs_search + manual ranking | Natural-language intent → ranked docs across all 4 DERO products; product_hint is a 1.5× score bias, not a filter | | estimate_deploy_cost | GetGasEstimate + manual surface extraction + manual gas interpretation | DVM deploy pre-flight — returns gas estimate + plain-text breakdown + parsed function surface | | trace_transaction_with_context | GetTransaction + (for SC installs) GetSC + manual classification | \"What is this tx\" — returns confirmation status, kind classification, ring stats, and parsed SC install surface inline | Each composite is fully documented in docs/composites.md (design contract, accepted/rejected designs, failure modes), and every composite ships with a green flow test in CI that runs against a live public daemon. **Why composites matter for agents.** A generic JSON-RPC client can chain primitives, but it cannot stitch the right docs context or classify failure modes for free. Composites are the wedge: they deliver agent-ready answers from the canonical DERO data sources in one call. Primitive Tools The 20 primitives map 1:1 onto daemon RPC methods plus the bundled docs index. Use them when a composite is unavailable or you need raw data. Daemon RPC | Tool | RPC Method | Purpose | |------|------------|---------| | dero_daemon_ping | DERO.Ping | Liveness check | | dero_daemon_echo | DERO.Echo | Roundtrip string echo | | dero_get_info | DERO.GetInfo | Network height, difficulty, version, hashrate, testnet flag | | dero_get_height | DERO.GetHeight | Height, stableheight, topoheight | | dero_get_block_count | DERO.GetBlockCount | Total block count | | dero_get_block | DERO.GetBlock | Full block by hash or height | | dero_get_block_header_by_hash | DERO.GetBlockHeaderByHash | Block header by hash | | dero_get_block_header_by_topo_height | DERO.GetBlockHeaderByTopoHeight | Block header by topoheight | | dero_get_last_block_header | DERO.GetLastBlockHeader | Tip block header | | dero_get_block_template | DERO.GetBlockTemplate | Mining block template | | dero_get_transaction | DERO.GetTransaction | Transaction record by hash | | dero_get_tx_pool | DERO.GetTxPool | Mempool transaction hashes | | dero_get_sc | DERO.GetSC | Smart contract code, variables, balances | | dero_get_gas_estimate | DERO.GetGasEstimate | Daemon-side gas estimate for a contract source or call | | dero_get_encrypted_balance | DERO.GetEncryptedBalance | Encrypted balance for an address | | dero_get_random_address | DERO.GetRandomAddress | Random registered wallet addresses | | dero_name_to_address | DERO.NameToAddress | Resolve a registered name to its address | Bundled docs index | Tool | Purpose | |------|---------| | dero_docs_list | Enumerate available doc pages across derod, tela, hologram, deropay | | dero_docs_search | Full-text search across the bundled docs index — in-process, no network round-trip | | dero_docs_get_page | Fetch a single doc page by slug with full plain-text content and headings | Resources and Prompts Beyond tools, the server exposes 4 **resources** and 5 **prompts** so MCP-aware clients can surface them in their UI: Resources | URI | Content | |-----|---------| | dero://mcp/server-info | Server metadata, tool list, resource list, prompt names, daemon endpoint | | dero://mcp/safety-boundary | Read-only posture and excluded method list (transfer, scinvoke, etc.) | | dero://mcp/example-flows | Composite-first agent flow recipes for common DERO investigations | | dero://mcp/composites | Structured catalog of all 5 composites — what each replaces, when to call it, what it returns, and which _meta.error codes it can emit | Prompts | Prompt | What it scripts | |--------|----------------| | network_health_check | Drives diagnose_chain_health with optional reference_topoheight | | inspect_smart_contract | Drives explain_smart_contract for any SCID | | trace_transaction | Drives trace_transaction_with_context for any tx hash | | find_dero_docs_for_intent | Drives recommend_docs_path with a natural-language intent + optional product_hint | | estimate_deploy_for_contract | Drives estimate_deploy_cost with DVM-BASIC source | Structured Errors Every tool wraps failures in a structured _meta.error block so agents can react programmatically instead of parsing error strings: | Code | Emitted by | Meaning | Retryable | |------|------------|---------|:---------:| | RPC_UNREACHABLE | All tools | Daemon not reachable on DERO_DAEMON_URL | yes | | RPC_INVALID_PARAMS | Most tools | Daemon rejected the request shape | no | | NO_DOCS_MATCH | recommend_docs_path | Intent matched zero pages across all 4 products | no — rephrase first | | INVALID_INPUT | estimate_deploy_cost | DVM compile error (wraps daemon -32098); raw message preserved in _meta.error.raw | no | | TX_NOT_FOUND | trace_transaction_with_context | Daemon returned an empty record for the hash | yes — verify hash + network first | Every error code carries a hint string with actionable next steps so the agent can recover or explain the failure cleanly to the user. Read-Only by Design Every one of the 25 tools carries the MCP read-only annotation block: This lets MCP hosts safely auto-approve any tool call from this server without prompting on every read. The server **cannot**: - Send transactions - Transfer funds - Invoke smart contracts (only **estimate** deploy cost via estimate_deploy_cost — nothing is submitted to chain) - Submit blocks - Hold wallet keys or talk to wallet RPC Wallet RPC methods (transfer, scinvoke, DERO.SendRawTransaction, DERO.SubmitBlock) are explicitly excluded. The full read-only posture, the six AND-gated conditions that would be required to expand the boundary, and the rationale for each are documented in docs/decision-boundary.md. If you need write capabilities in the future, they will be gated behind explicit flags **and** a separate wallet URL **and** a distinct annotation block (readOnlyHint: false) **and** documented escalation — never enabled by default. Environment | Variable | Default | Description | |----------|---------|-------------| | DERO_DAEMON_URL | http://82.65.143.182:10102 | Daemon base URL. Set to http://127.0.0.1:10102 for a local node. | | DERO_DOCS_ROOT | _(unset; uses bundled index)_ | Optional dev override pointing at a local docs source tree. Production deployments should leave this unset to use the bundled index. | Verify, Don't Trust - Source code on GitHub — composite design contract in docs/composites.md, read-only posture in docs/decision-boundary.md, agent-ready evidence in docs/mcp-agent-ready-evidence.md - Package on npm - Listed in the official MCP registry as io.github.DHEBP/dero-mcp-server - CI runs full smoke probes, composite flow tests, primitive flow tests, and description / citation drift guards on every push - MIT licensed — fork it, audit it, improve it See Also - DERO Daemon RPC API — full RPC reference for the methods the primitives wrap - Running a DERO Node — set up your own daemon - Smart Contract Fundamentals — DVM concepts the composites cite - XSWD — browser wallet integration (for write flows the MCP server intentionally excludes)",
+      "lastUpdated": "2026-05-23"
     },
     {
       "product": "derod",

package/dist/citations.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Citation helper for DERO MCP tool responses.
+ *
+ * The wedge for this server is the combination of live chain reads and the
+ * in-process bundled docs index (145+ pages across derod, tela, hologram,
+ * deropay). Citations let agents link their responses back to authoritative
+ * docs without a second tool call, and they give downstream composite tools
+ * a uniform shape to compose.
+ *
+ * Design contract:
+ *   - One shape, used by primitives and composites alike.
+ *   - URLs are produced by the same builder used by `dero_docs_*` so the
+ *     citation always points at the same canonical page the agent would
+ *     reach via dero_docs_get_page.
+ *   - The slug is duplicated as `page_id` to give composites a stable join
+ *     key across tools (mirrors the FoodNearMe COMPOSITES.md citation pattern).
+ *   - The map of related docs per tool is hand-maintained and validated by
+ *     `scripts/check-citations.ts` (added alongside this helper) so a docs
+ *     reorganization cannot silently produce 404 citations in production.
+ */
+import { type DeroDocProduct } from './docs-parse.js';
+export type DeroCitation = {
+    /** Always `'dero_docs'` for now; future sources (e.g. `'dero_chain'`) can extend this. */
+    source: 'dero_docs';
+    product: DeroDocProduct;
+    slug: string;
+    title: string;
+    canonical_url: string;
+    /** Alias of `slug` so composites can use a single join key across tools. */
+    page_id: string;
+};
+/**
+ * Build a DeroCitation pointing at one bundled docs page.
+ *
+ * The title is required (not derived from the bundled index) so this helper
+ * stays synchronous and zero-IO. It must match the docs page title; the
+ * citation guard validates this against the bundled index in CI.
+ */
+export declare function buildDeroCitation(product: DeroDocProduct, slug: string, title: string): DeroCitation;
+/**
+ * Map of MCP tool name → hand-curated related docs pages.
+ *
+ * Keep this list tight — only add entries when a tool's response is
+ * meaningfully improved by linking the agent at a specific page. The CI
+ * guard verifies every slug resolves against the bundled docs index, so any
+ * docs reorganization will fail the build before it ships.
+ *
+ * Adding a tool here:
+ *   1. Use `dero_docs_search` to find the right slug(s).
+ *   2. Add an entry with product + slug + exact page title.
+ *   3. Run `npm run check:citations` to confirm slugs resolve.
+ */
+type RelatedDocsEntry = {
+    product: DeroDocProduct;
+    slug: string;
+    title: string;
+};
+export declare const RELATED_DOCS_BY_TOOL: Record<string, readonly RelatedDocsEntry[]>;
+/**
+ * Resolve the hand-curated related docs list for a tool name and return it
+ * as fully-built `DeroCitation` objects. Returns `undefined` when the tool
+ * has no related docs configured.
+ *
+ * Use in tool handlers like:
+ *   const related_docs = relatedDocsFor('dero_get_sc')
+ *   return { ...rpcResult, ...(related_docs ? { related_docs } : {}) }
+ */
+export declare function relatedDocsFor(toolName: string): DeroCitation[] | undefined;
+export {};
+//# sourceMappingURL=citations.d.ts.map

package/dist/citations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.d.ts","sourceRoot":"","sources":["../src/citations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEpE,MAAM,MAAM,YAAY,GAAG;IACzB,0FAA0F;IAC1F,MAAM,EAAE,WAAW,CAAA;IACnB,OAAO,EAAE,cAAc,CAAA;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;IACrB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAQD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,YAAY,CASd;AAED;;;;;;;;;;;;GAYG;AACH,KAAK,gBAAgB,GAAG;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAqGnE,CAAA;AAEV;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,GAAG,SAAS,CAI3E"}

package/dist/citations.js

@@ -0,0 +1,162 @@
+/**
+ * Citation helper for DERO MCP tool responses.
+ *
+ * The wedge for this server is the combination of live chain reads and the
+ * in-process bundled docs index (145+ pages across derod, tela, hologram,
+ * deropay). Citations let agents link their responses back to authoritative
+ * docs without a second tool call, and they give downstream composite tools
+ * a uniform shape to compose.
+ *
+ * Design contract:
+ *   - One shape, used by primitives and composites alike.
+ *   - URLs are produced by the same builder used by `dero_docs_*` so the
+ *     citation always points at the same canonical page the agent would
+ *     reach via dero_docs_get_page.
+ *   - The slug is duplicated as `page_id` to give composites a stable join
+ *     key across tools (mirrors the FoodNearMe COMPOSITES.md citation pattern).
+ *   - The map of related docs per tool is hand-maintained and validated by
+ *     `scripts/check-citations.ts` (added alongside this helper) so a docs
+ *     reorganization cannot silently produce 404 citations in production.
+ */
+import { DOC_BASE_URLS } from './docs-parse.js';
+function buildCanonicalUrl(product, slug) {
+    const trimmed = slug.replace(/^\/+|\/+$/g, '');
+    if (!trimmed)
+        return `${DOC_BASE_URLS[product]}/`;
+    return `${DOC_BASE_URLS[product]}/${trimmed}`;
+}
+/**
+ * Build a DeroCitation pointing at one bundled docs page.
+ *
+ * The title is required (not derived from the bundled index) so this helper
+ * stays synchronous and zero-IO. It must match the docs page title; the
+ * citation guard validates this against the bundled index in CI.
+ */
+export function buildDeroCitation(product, slug, title) {
+    return {
+        source: 'dero_docs',
+        product,
+        slug,
+        title,
+        canonical_url: buildCanonicalUrl(product, slug),
+        page_id: slug,
+    };
+}
+export const RELATED_DOCS_BY_TOOL = {
+    dero_get_info: [
+        {
+            product: 'derod',
+            slug: 'rpc-api/daemon-rpc-api',
+            title: 'DERO Daemon RPC API: Complete Reference Guide | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'basics/daemon',
+            title: 'DERO Daemon: Backbone of the Privacy Blockchain | DERO Blockchain',
+        },
+    ],
+    dero_get_sc: [
+        {
+            product: 'derod',
+            slug: 'dvm/smart-contract-fundamentals',
+            title: 'Smart Contract Fundamentals: Understanding DERO Contracts | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/dero-virtual-machine',
+            title: 'DERO Virtual Machine (DVM): Private Smart Contract Platform | DERO Blockchain',
+        },
+    ],
+    dero_get_gas_estimate: [
+        {
+            product: 'derod',
+            slug: 'rpc-api/daemon-rpc-api',
+            title: 'DERO Daemon RPC API: Complete Reference Guide | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/create-deploy-use-smart-contract',
+            title: 'Create, Deploy & Use a Smart Contract on DERO | Step-by-Step Tutorial',
+        },
+    ],
+    diagnose_chain_health: [
+        {
+            product: 'derod',
+            slug: 'basics/daemon',
+            title: 'DERO Daemon: Backbone of the Privacy Blockchain | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'rpc-api/daemon-rpc-api',
+            title: 'DERO Daemon RPC API: Complete Reference Guide | DERO Blockchain',
+        },
+    ],
+    trace_transaction_with_context: [
+        {
+            product: 'derod',
+            slug: 'rpc-api/daemon-rpc-api',
+            title: 'DERO Daemon RPC API: Complete Reference Guide | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/smart-contract-fundamentals',
+            title: 'Smart Contract Fundamentals: Understanding DERO Contracts | DERO Blockchain',
+        },
+    ],
+    estimate_deploy_cost: [
+        {
+            product: 'derod',
+            slug: 'dvm/create-deploy-use-smart-contract',
+            title: 'Create, Deploy & Use a Smart Contract on DERO | Step-by-Step Tutorial',
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/dvm-basic',
+            title: "DVM-BASIC: DERO's Smart Contract Language Guide | DERO Blockchain",
+        },
+    ],
+    // Composite #2 (`explain_smart_contract`) curates all four DVM docs so its
+    // heuristic can elevate whichever page best matches the detected surface
+    // (token / registry / minimal / generic). The composite re-orders this
+    // array at runtime; the static ordering here is the fallback when the
+    // heuristic returns the same slug already at index 0 (the universal
+    // "fundamentals" default).
+    explain_smart_contract: [
+        {
+            product: 'derod',
+            slug: 'dvm/smart-contract-fundamentals',
+            title: 'Smart Contract Fundamentals: Understanding DERO Contracts | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/dvm-basic',
+            title: "DVM-BASIC: DERO's Smart Contract Language Guide | DERO Blockchain",
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/dero-virtual-machine',
+            title: 'DERO Virtual Machine (DVM): Private Smart Contract Platform | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/create-deploy-use-smart-contract',
+            title: 'Create, Deploy & Use a Smart Contract on DERO | Step-by-Step Tutorial',
+        },
+    ],
+};
+/**
+ * Resolve the hand-curated related docs list for a tool name and return it
+ * as fully-built `DeroCitation` objects. Returns `undefined` when the tool
+ * has no related docs configured.
+ *
+ * Use in tool handlers like:
+ *   const related_docs = relatedDocsFor('dero_get_sc')
+ *   return { ...rpcResult, ...(related_docs ? { related_docs } : {}) }
+ */
+export function relatedDocsFor(toolName) {
+    const entries = RELATED_DOCS_BY_TOOL[toolName];
+    if (!entries || entries.length === 0)
+        return undefined;
+    return entries.map((entry) => buildDeroCitation(entry.product, entry.slug, entry.title));
+}
+//# sourceMappingURL=citations.js.map

package/dist/citations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.js","sourceRoot":"","sources":["../src/citations.ts"],"names":[],"mappings":"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"}

package/dist/composites/_shared.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared utilities for DERO MCP composite tools.
+ *
+ * A composite tool stitches several primitives (daemon RPC reads + bundled
+ * docs lookups) into one intent-shaped response. These utilities exist so
+ * every composite handles failures, latency tracking, and citation
+ * attachment the same way.
+ *
+ * Anything reused by more than one composite belongs here. Composite-local
+ * helpers (e.g. narrative builders specific to one composite's response
+ * shape) should live next to that composite, not in this file.
+ *
+ * See `docs/composites.md` for the design contract that governs which
+ * utilities live here and the gate every composite must satisfy before it
+ * lands on main.
+ */
+import { type DeroCitation } from '../citations.js';
+/**
+ * One step in a composite's internal chain.
+ *
+ * `required: true` aborts the chain if the step throws (use for liveness
+ * gates like `DERO.Ping`). `required: false` lets the chain continue with
+ * a degraded payload (use for enrichments like a mempool snapshot).
+ */
+export type ChainStep<T = unknown> = {
+    name: string;
+    required?: boolean;
+    fn: () => Promise<T>;
+};
+export type ChainStepResult = {
+    name: string;
+    ok: boolean;
+    value?: unknown;
+    error?: {
+        message: string;
+    };
+    latencyMs: number;
+};
+export type ChainResult = {
+    results: ChainStepResult[];
+    haltedAt: string | null;
+    totalMs: number;
+};
+/**
+ * Run a chain of named primitive calls sequentially. Required-step
+ * failures halt the chain and record `haltedAt`; non-required failures
+ * are recorded and the chain continues. Step latencies are captured so
+ * composites can attach diagnostics to a degraded response.
+ */
+export declare function runChain(steps: readonly ChainStep[]): Promise<ChainResult>;
+/**
+ * Extract a single step's successful return value from a ChainResult.
+ * Returns null when the step was skipped (chain halted earlier), failed,
+ * or simply was not part of the chain.
+ */
+export declare function stepValue<T = unknown>(chain: ChainResult, name: string): T | null;
+/**
+ * Per-step latency map suitable for embedding in a composite's response
+ * under a `_diagnostics` field. Lets agents and operators see which step
+ * was slow without needing to instrument the host.
+ */
+export declare function stepLatencies(chain: ChainResult): Record<string, number>;
+/**
+ * Attach curated `related_docs` citations to a composite's payload.
+ * Mirrors how primitives attach citations so the response shape stays
+ * uniform across primitives and composites. Returns the payload
+ * unchanged when no curated docs are configured for the tool name.
+ */
+export declare function attachCitations<T extends Record<string, unknown>>(payload: T, toolName: string): T & {
+    related_docs?: DeroCitation[];
+};
+/**
+ * Shape used by the JSON-RPC `rpc` closure created in `src/server.ts`.
+ * Re-declared here so composites can take it as a dependency without
+ * importing from the server module (keeps the composite layer free of
+ * `McpServer` coupling).
+ */
+export type DeroDaemonRpc = <T = unknown>(method: string, params?: unknown) => Promise<T>;
+/**
+ * Loose representation of a `DERO.GetSC` response. Field names match the
+ * daemon's actual JSON keys observed on the public node. `uint64keys` is
+ * frequently absent (the daemon omits empty maps), so it is optional.
+ */
+export type DeroGetScResult = {
+    code?: string;
+    status?: string;
+    balance?: number;
+    balances?: Record<string, number>;
+    stringkeys?: Record<string, unknown>;
+    uint64keys?: Record<string, unknown>;
+    [k: string]: unknown;
+};
+export type DvmFunctionSignature = {
+    name: string;
+    args: string[];
+    returns: string;
+};
+export type DeroScSurface = {
+    functions: DvmFunctionSignature[];
+    stringkeys: string[];
+    uint64keys: string[];
+    balances: Record<string, number | string>;
+    raw_code_length: number;
+    has_code: boolean;
+};
+/**
+ * Convert a raw DERO.GetSC payload into a stable, agent-friendly surface.
+ *
+ * Behavior:
+ *  - Returns `functions: []` when `code` is missing or the regex finds
+ *    no Function declarations. Never throws on malformed code.
+ *  - Sorts `stringkeys` / `uint64keys` alphabetically for deterministic
+ *    output across invocations.
+ *  - `balances` is passed through unchanged so callers can render asset
+ *    balances; native DERO balance lives under `balance` on the raw
+ *    payload and is left for callers to decide whether to surface.
+ */
+export declare function extractScSurface(raw: DeroGetScResult | null | undefined): DeroScSurface;
+//# sourceMappingURL=_shared.d.ts.map

package/dist/composites/_shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../src/composites/_shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnE;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,OAAO,IAAI;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,OAAO,CAAA;IACX,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3B,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,eAAe,EAAE,CAAA;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAkChF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAIjF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIxE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,OAAO,EAAE,CAAC,EACV,QAAQ,EAAE,MAAM,GACf,CAAC,GAAG;IAAE,YAAY,CAAC,EAAE,YAAY,EAAE,CAAA;CAAE,CAIvC;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;AAUzF;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,EAAE,oBAAoB,EAAE,CAAA;IACjC,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;IACzC,eAAe,EAAE,MAAM,CAAA;IACvB,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AA+BD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,CAqBvF"}

package/dist/composites/_shared.js

@@ -0,0 +1,152 @@
+/**
+ * Shared utilities for DERO MCP composite tools.
+ *
+ * A composite tool stitches several primitives (daemon RPC reads + bundled
+ * docs lookups) into one intent-shaped response. These utilities exist so
+ * every composite handles failures, latency tracking, and citation
+ * attachment the same way.
+ *
+ * Anything reused by more than one composite belongs here. Composite-local
+ * helpers (e.g. narrative builders specific to one composite's response
+ * shape) should live next to that composite, not in this file.
+ *
+ * See `docs/composites.md` for the design contract that governs which
+ * utilities live here and the gate every composite must satisfy before it
+ * lands on main.
+ */
+import { relatedDocsFor } from '../citations.js';
+/**
+ * Run a chain of named primitive calls sequentially. Required-step
+ * failures halt the chain and record `haltedAt`; non-required failures
+ * are recorded and the chain continues. Step latencies are captured so
+ * composites can attach diagnostics to a degraded response.
+ */
+export async function runChain(steps) {
+    const results = [];
+    const startedAt = performance.now();
+    let haltedAt = null;
+    for (const step of steps) {
+        const stepStart = performance.now();
+        try {
+            const value = await step.fn();
+            results.push({
+                name: step.name,
+                ok: true,
+                value,
+                latencyMs: Math.round(performance.now() - stepStart),
+            });
+        }
+        catch (error) {
+            results.push({
+                name: step.name,
+                ok: false,
+                error: { message: error instanceof Error ? error.message : String(error) },
+                latencyMs: Math.round(performance.now() - stepStart),
+            });
+            if (step.required) {
+                haltedAt = step.name;
+                break;
+            }
+        }
+    }
+    return {
+        results,
+        haltedAt,
+        totalMs: Math.round(performance.now() - startedAt),
+    };
+}
+/**
+ * Extract a single step's successful return value from a ChainResult.
+ * Returns null when the step was skipped (chain halted earlier), failed,
+ * or simply was not part of the chain.
+ */
+export function stepValue(chain, name) {
+    const entry = chain.results.find((r) => r.name === name);
+    if (!entry || !entry.ok)
+        return null;
+    return entry.value;
+}
+/**
+ * Per-step latency map suitable for embedding in a composite's response
+ * under a `_diagnostics` field. Lets agents and operators see which step
+ * was slow without needing to instrument the host.
+ */
+export function stepLatencies(chain) {
+    const out = {};
+    for (const r of chain.results)
+        out[r.name] = r.latencyMs;
+    return out;
+}
+/**
+ * Attach curated `related_docs` citations to a composite's payload.
+ * Mirrors how primitives attach citations so the response shape stays
+ * uniform across primitives and composites. Returns the payload
+ * unchanged when no curated docs are configured for the tool name.
+ */
+export function attachCitations(payload, toolName) {
+    const related_docs = relatedDocsFor(toolName);
+    if (!related_docs || related_docs.length === 0)
+        return payload;
+    return { ...payload, related_docs };
+}
+// DVM-BASIC function declaration:
+//   Function Name(arg Type, ...) Uint64|String
+//
+// Anchored with `/m` so each line of source is examined independently.
+// Tolerant of leading whitespace and varied spacing inside the parens.
+const DVM_FUNCTION_REGEX = /^[ \t]*Function[ \t]+([A-Za-z_][A-Za-z0-9_]*)[ \t]*\(([^)]*)\)[ \t]*(Uint64|String)\b/gm;
+function parseDvmFunctions(code) {
+    const out = [];
+    const seen = new Set();
+    for (const match of code.matchAll(DVM_FUNCTION_REGEX)) {
+        const name = match[1];
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        const argsRaw = (match[2] ?? '').trim();
+        const returns = match[3] ?? '';
+        const args = argsRaw.length === 0
+            ? []
+            : argsRaw
+                .split(',')
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+        out.push({ name, args, returns });
+    }
+    return out;
+}
+/**
+ * Convert a raw DERO.GetSC payload into a stable, agent-friendly surface.
+ *
+ * Behavior:
+ *  - Returns `functions: []` when `code` is missing or the regex finds
+ *    no Function declarations. Never throws on malformed code.
+ *  - Sorts `stringkeys` / `uint64keys` alphabetically for deterministic
+ *    output across invocations.
+ *  - `balances` is passed through unchanged so callers can render asset
+ *    balances; native DERO balance lives under `balance` on the raw
+ *    payload and is left for callers to decide whether to surface.
+ */
+export function extractScSurface(raw) {
+    const code = typeof raw?.code === 'string' ? raw.code : '';
+    const functions = code.length > 0 ? parseDvmFunctions(code) : [];
+    const stringkeys = raw?.stringkeys ? Object.keys(raw.stringkeys).sort() : [];
+    const uint64keys = raw?.uint64keys ? Object.keys(raw.uint64keys).sort() : [];
+    const balances = {};
+    if (raw?.balances && typeof raw.balances === 'object') {
+        for (const [scid, amount] of Object.entries(raw.balances)) {
+            if (typeof amount === 'number' || typeof amount === 'string') {
+                balances[scid] = amount;
+            }
+        }
+    }
+    return {
+        functions,
+        stringkeys,
+        uint64keys,
+        balances,
+        raw_code_length: code.length,
+        has_code: code.length > 0,
+    };
+}
+//# sourceMappingURL=_shared.js.map

package/dist/composites/_shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.js","sourceRoot":"","sources":["../../src/composites/_shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,cAAc,EAAqB,MAAM,iBAAiB,CAAA;AA6BnE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAA2B;IACxD,MAAM,OAAO,GAAsB,EAAE,CAAA;IACrC,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAA;IACnC,IAAI,QAAQ,GAAkB,IAAI,CAAA;IAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAA;QACnC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,EAAE,EAAE,CAAA;YAC7B,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,EAAE,EAAE,IAAI;gBACR,KAAK;gBACL,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;aACrD,CAAC,CAAA;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;gBAC1E,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;aACrD,CAAC,CAAA;YACF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClB,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAA;gBACpB,MAAK;YACP,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO;QACP,QAAQ;QACR,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;KACnD,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAc,KAAkB,EAAE,IAAY;IACrE,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;IACxD,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,EAAE;QAAE,OAAO,IAAI,CAAA;IACpC,OAAO,KAAK,CAAC,KAAU,CAAA;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAkB;IAC9C,MAAM,GAAG,GAA2B,EAAE,CAAA;IACtC,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO;QAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,SAAS,CAAA;IACxD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAU,EACV,QAAgB;IAEhB,MAAM,YAAY,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAA;IAC7C,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAA;IAC9D,OAAO,EAAE,GAAG,OAAO,EAAE,YAAY,EAAE,CAAA;AACrC,CAAC;AAgDD,kCAAkC;AAClC,+CAA+C;AAC/C,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,MAAM,kBAAkB,GACtB,yFAAyF,CAAA;AAE3F,SAAS,iBAAiB,CAAC,IAAY;IACrC,MAAM,GAAG,GAA2B,EAAE,CAAA;IACtC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QACrB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAQ;QAC5B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACd,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;QACvC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAC9B,MAAM,IAAI,GACR,OAAO,CAAC,MAAM,KAAK,CAAC;YAClB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,OAAO;iBACJ,KAAK,CAAC,GAAG,CAAC;iBACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;iBACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QACpC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAA;IACnC,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAuC;IACtE,MAAM,IAAI,GAAG,OAAO,GAAG,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAChE,MAAM,UAAU,GAAG,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAC5E,MAAM,UAAU,GAAG,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAC5E,MAAM,QAAQ,GAAoC,EAAE,CAAA;IACpD,IAAI,GAAG,EAAE,QAAQ,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACtD,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1D,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC7D,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,CAAA;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO;QACL,SAAS;QACT,UAAU;QACV,UAAU;QACV,QAAQ;QACR,eAAe,EAAE,IAAI,CAAC,MAAM;QAC5B,QAAQ,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC;KAC1B,CAAA;AACH,CAAC"}