dero-mcp-server 0.1.2 → 0.2.2

package/dist/composites/diagnose-chain-health.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `diagnose_chain_health` — Phase C composite #1.
+ *
+ * Decorator-style composite that replaces four agent round-trips
+ * (`DERO.Ping` + `DERO.GetInfo` + `DERO.GetHeight` + `DERO.GetTxPool`) and
+ * the "what does this field mean?" docs lookup with a single narrative
+ * response carrying chain metadata, mempool snapshot, narrative summary,
+ * and curated docs citations.
+ *
+ * Design contract: `docs/composites.md` § 1 (lowest-risk composite, ships
+ * first to prove the composite plumbing — shared utils + flow test pattern
+ * + smoke assertions — end-to-end).
+ *
+ * Failure model:
+ *   - `DERO.Ping` is the only required step. Its failure halts the chain
+ *     and the handler throws so `withStructuredErrors` surfaces a
+ *     structured `RPC_UNREACHABLE` error.
+ *   - `DERO.GetInfo`, `DERO.GetHeight`, and `DERO.GetTxPool` are
+ *     non-required. Their failures degrade `status` to `partial` and
+ *     leave the corresponding response field null, but the composite
+ *     still returns a useful payload.
+ */
+import { z } from 'zod';
+import { type DeroDaemonRpc } from './_shared.js';
+export declare const diagnoseChainHealthInputSchema: {
+    readonly include_tx_pool: z.ZodOptional<z.ZodBoolean>;
+};
+type DiagnoseInput = {
+    include_tx_pool?: boolean;
+};
+type DiagnoseStatus = 'healthy' | 'lagging' | 'partial' | 'unreachable';
+type DiagnoseSignal = {
+    key: string;
+    value: string | number;
+    note?: string;
+};
+export declare function diagnoseChainHealth(rpc: DeroDaemonRpc, args: DiagnoseInput): Promise<{
+    status: DiagnoseStatus;
+    narrative: string;
+    signals: DiagnoseSignal[];
+    chain: {
+        topoheight: number;
+        stableheight: number | null;
+        height: number | null;
+        network: string | null;
+        version: string | null;
+        difficulty: string | number | null;
+        total_supply: string | number | null;
+    } | null;
+    mempool: {
+        pending: number;
+        sample: string[];
+    } | null;
+    _diagnostics: {
+        step_latency_ms: Record<string, number>;
+        total_ms: number;
+        halted_at: string | null;
+        include_tx_pool: boolean;
+    };
+} & {
+    related_docs?: import("../citations.js").DeroCitation[];
+}>;
+export {};
+//# sourceMappingURL=diagnose-chain-health.d.ts.map

package/dist/composites/diagnose-chain-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose-chain-health.d.ts","sourceRoot":"","sources":["../../src/composites/diagnose-chain-health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,cAAc,CAAA;AAErB,eAAO,MAAM,8BAA8B;;CAKjC,CAAA;AAEV,KAAK,aAAa,GAAG;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAyBlD,KAAK,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;AAEvE,KAAK,cAAc,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AA4E5E,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;GA+DhF"}

package/dist/composites/diagnose-chain-health.js

@@ -0,0 +1,144 @@
+/**
+ * `diagnose_chain_health` — Phase C composite #1.
+ *
+ * Decorator-style composite that replaces four agent round-trips
+ * (`DERO.Ping` + `DERO.GetInfo` + `DERO.GetHeight` + `DERO.GetTxPool`) and
+ * the "what does this field mean?" docs lookup with a single narrative
+ * response carrying chain metadata, mempool snapshot, narrative summary,
+ * and curated docs citations.
+ *
+ * Design contract: `docs/composites.md` § 1 (lowest-risk composite, ships
+ * first to prove the composite plumbing — shared utils + flow test pattern
+ * + smoke assertions — end-to-end).
+ *
+ * Failure model:
+ *   - `DERO.Ping` is the only required step. Its failure halts the chain
+ *     and the handler throws so `withStructuredErrors` surfaces a
+ *     structured `RPC_UNREACHABLE` error.
+ *   - `DERO.GetInfo`, `DERO.GetHeight`, and `DERO.GetTxPool` are
+ *     non-required. Their failures degrade `status` to `partial` and
+ *     leave the corresponding response field null, but the composite
+ *     still returns a useful payload.
+ */
+import { z } from 'zod';
+import { attachCitations, runChain, stepLatencies, stepValue, } from './_shared.js';
+export const diagnoseChainHealthInputSchema = {
+    include_tx_pool: z
+        .boolean()
+        .optional()
+        .describe('Include mempool snapshot in narrative and response. Default true.'),
+};
+const LAG_DEPTH_LAGGING_THRESHOLD = 50;
+/**
+ * Pure function: turn the three RPC payloads (any of which may be null
+ * if the corresponding step failed) into a status, narrative, and
+ * machine-readable signals block. Kept inside this file because it is
+ * tightly coupled to the response shape and is not reused elsewhere.
+ */
+function summarizeChainHealth(info, height, txPool, txPoolRequested) {
+    const signals = [];
+    if (!info || typeof info.topoheight !== 'number' || typeof info.stableheight !== 'number') {
+        return {
+            status: 'partial',
+            narrative: 'Daemon ping succeeded but chain info was unavailable; only liveness can be confirmed. Inspect daemon logs and retry.',
+            signals,
+        };
+    }
+    const lagDepth = info.topoheight - info.stableheight;
+    signals.push({ key: 'topoheight', value: info.topoheight });
+    signals.push({ key: 'stableheight', value: info.stableheight });
+    signals.push({
+        key: 'lag_depth',
+        value: lagDepth,
+        note: 'topoheight minus stableheight; values above 50 suggest the node is catching up',
+    });
+    if (info.network)
+        signals.push({ key: 'network', value: info.network });
+    if (info.version)
+        signals.push({ key: 'version', value: info.version });
+    if (height && typeof height.topoheight === 'number' && height.topoheight !== info.topoheight) {
+        signals.push({
+            key: 'topoheight_drift',
+            value: height.topoheight - info.topoheight,
+            note: 'GetHeight reported a different topoheight than GetInfo; values within +/-1 are normal between RPC calls',
+        });
+    }
+    let status = 'healthy';
+    const narrativeParts = [];
+    if (lagDepth > LAG_DEPTH_LAGGING_THRESHOLD) {
+        status = 'lagging';
+        narrativeParts.push(`Chain shows a lag depth of ${lagDepth} blocks between topoheight (${info.topoheight}) and stableheight (${info.stableheight}); typical depth is under ${LAG_DEPTH_LAGGING_THRESHOLD}, so the node may be catching up.`);
+    }
+    else {
+        narrativeParts.push(`Chain appears healthy on ${info.network ?? 'unknown network'} (version ${info.version ?? 'unknown'}): topoheight ${info.topoheight}, stableheight ${info.stableheight}, lag depth ${lagDepth}.`);
+    }
+    if (!txPoolRequested) {
+        narrativeParts.push('Mempool snapshot was skipped by request (include_tx_pool=false).');
+    }
+    else if (!txPool) {
+        if (status === 'healthy')
+            status = 'partial';
+        narrativeParts.push('Mempool snapshot failed; mempool state is unknown for this report.');
+    }
+    else {
+        const pending = Array.isArray(txPool.tx_hashes) ? txPool.tx_hashes.length : 0;
+        signals.push({ key: 'mempool_pending', value: pending });
+        narrativeParts.push(pending === 0
+            ? 'Mempool is empty.'
+            : `Mempool has ${pending} pending transaction${pending === 1 ? '' : 's'}.`);
+    }
+    return { status, narrative: narrativeParts.join(' '), signals };
+}
+export async function diagnoseChainHealth(rpc, args) {
+    const includeTxPool = args.include_tx_pool !== false;
+    const steps = [
+        { name: 'ping', required: true, fn: () => rpc('DERO.Ping') },
+        { name: 'info', required: false, fn: () => rpc('DERO.GetInfo') },
+        { name: 'height', required: false, fn: () => rpc('DERO.GetHeight') },
+        ...(includeTxPool
+            ? [{ name: 'tx_pool', required: false, fn: () => rpc('DERO.GetTxPool') }]
+            : []),
+    ];
+    const chain = await runChain(steps);
+    if (chain.haltedAt === 'ping') {
+        const pingResult = chain.results.find((r) => r.name === 'ping');
+        const detail = pingResult?.error?.message ?? 'unknown error';
+        // `withStructuredErrors` classifies this message into RPC_UNREACHABLE.
+        throw new Error(`fetch failed: ${detail}`);
+    }
+    const info = stepValue(chain, 'info');
+    const height = stepValue(chain, 'height');
+    const txPool = includeTxPool ? stepValue(chain, 'tx_pool') : null;
+    const { status, narrative, signals } = summarizeChainHealth(info, height, txPool, includeTxPool);
+    const chainData = info && typeof info.topoheight === 'number'
+        ? {
+            topoheight: info.topoheight,
+            stableheight: info.stableheight ?? null,
+            height: info.height ?? null,
+            network: info.network ?? null,
+            version: info.version ?? null,
+            difficulty: info.difficulty ?? null,
+            total_supply: info.total_supply ?? null,
+        }
+        : null;
+    const mempool = txPool
+        ? {
+            pending: Array.isArray(txPool.tx_hashes) ? txPool.tx_hashes.length : 0,
+            sample: (txPool.tx_hashes ?? []).slice(0, 5),
+        }
+        : null;
+    return attachCitations({
+        status,
+        narrative,
+        signals,
+        chain: chainData,
+        mempool,
+        _diagnostics: {
+            step_latency_ms: stepLatencies(chain),
+            total_ms: chain.totalMs,
+            halted_at: chain.haltedAt,
+            include_tx_pool: includeTxPool,
+        },
+    }, 'diagnose_chain_health');
+}
+//# sourceMappingURL=diagnose-chain-health.js.map

package/dist/composites/diagnose-chain-health.js.map

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

package/dist/composites/estimate-deploy-cost.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `estimate_deploy_cost` — Phase C composite #4.
+ *
+ * Wedge: `dero_get_gas_estimate` returns raw `gascompute` and
+ * `gasstorage` numbers. Agents have to know that the first is DVM
+ * execution cost and the second is on-chain byte cost — and have to
+ * separately call `dero_get_sc` to understand what they are about to
+ * deploy. This composite returns the estimate, the parsed contract
+ * surface (functions / stringkeys / uint64keys), a plain-text
+ * breakdown explaining what each number means, and the curated
+ * "Create, Deploy & Use a Smart Contract" docs page as a citation.
+ *
+ * Design contract: `docs/composites.md` § 4. Sequencing rule: SHIP
+ * FOURTH. Numeric semantics; relies on `extractScSurface` (composite
+ * #2) being stable. Must not ship before composite #2 because the
+ * surface enrichment proves out the reuse path planned in the design
+ * doc.
+ *
+ * Failure model:
+ *   - DVM compile failure (daemon returns `RPC error -32098`) → the
+ *     classifier branch in `withStructuredErrors` surfaces this as
+ *     `INVALID_INPUT` with an actionable hint. The daemon's exact
+ *     compile message stays in `_meta.error.raw`.
+ *   - Invalid signer address → daemon usually emits `RPC error
+ *     -32602` (RPC_INVALID_PARAMS); existing classifier branch
+ *     handles it.
+ *   - Daemon returns a non-"OK" status with 0/0 numbers → return
+ *     the estimate as-is and set `breakdown: null`. NEVER fabricate
+ *     a breakdown when the numbers are 0/0 with a non-success
+ *     status; the agent must see the daemon's exact status string.
+ */
+import { z } from 'zod';
+import { type DeroDaemonRpc } from './_shared.js';
+export declare const estimateDeployCostInputSchema: {
+    readonly sc: z.ZodString;
+    readonly signer: z.ZodOptional<z.ZodString>;
+    readonly include_breakdown: z.ZodOptional<z.ZodBoolean>;
+};
+type EstimateInput = {
+    sc: string;
+    signer?: string;
+    include_breakdown?: boolean;
+};
+type EstimateBreakdown = {
+    compute_note: string;
+    storage_note: string;
+    total_units: number;
+};
+/**
+ * Pure function: turn a (gascompute, gasstorage) pair into a
+ * plain-language breakdown. Returns `null` when either number is
+ * unavailable or non-numeric, OR when the daemon returned 0/0 with a
+ * non-"OK" status (in which case fabricating a breakdown would
+ * mislead the agent — the design contract is explicit on this).
+ *
+ * The DVM denominates gas in atomic units (the daemon docs call them
+ * "gas units"). Converting to DERO requires the fee-per-gas table,
+ * which is itself a separate query. We deliberately do NOT convert
+ * here and instead surface the raw unit total plus a note pointing
+ * the agent at the docs.
+ */
+export declare function buildBreakdown(gascompute: number | string | undefined, gasstorage: number | string | undefined, status: string | undefined): EstimateBreakdown | null;
+export declare function estimateDeployCost(rpc: DeroDaemonRpc, args: EstimateInput): Promise<{
+    estimate: {
+        gascompute: number | null;
+        gasstorage: number | null;
+        status: string | null;
+    };
+    breakdown: EstimateBreakdown | null;
+    signer_used: string | null;
+    include_breakdown: boolean;
+    sc_surface: {
+        functions: import("./_shared.js").DvmFunctionSignature[];
+        stringkeys: string[];
+        uint64keys: string[];
+        raw_code_length: number;
+        function_count: number;
+    };
+} & {
+    related_docs?: import("../citations.js").DeroCitation[];
+}>;
+export {};
+//# sourceMappingURL=estimate-deploy-cost.d.ts.map

package/dist/composites/estimate-deploy-cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimate-deploy-cost.d.ts","sourceRoot":"","sources":["../../src/composites/estimate-deploy-cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAA;AAIrB,eAAO,MAAM,6BAA6B;;;;CAgBhC,CAAA;AAEV,KAAK,aAAa,GAAG;IACnB,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AASD,KAAK,iBAAiB,GAAG;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EACvC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EACvC,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,iBAAiB,GAAG,IAAI,CAU1B;AAED,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa;;;;;;;;;;;;;;;;;;GAgD/E"}

package/dist/composites/estimate-deploy-cost.js

@@ -0,0 +1,116 @@
+/**
+ * `estimate_deploy_cost` — Phase C composite #4.
+ *
+ * Wedge: `dero_get_gas_estimate` returns raw `gascompute` and
+ * `gasstorage` numbers. Agents have to know that the first is DVM
+ * execution cost and the second is on-chain byte cost — and have to
+ * separately call `dero_get_sc` to understand what they are about to
+ * deploy. This composite returns the estimate, the parsed contract
+ * surface (functions / stringkeys / uint64keys), a plain-text
+ * breakdown explaining what each number means, and the curated
+ * "Create, Deploy & Use a Smart Contract" docs page as a citation.
+ *
+ * Design contract: `docs/composites.md` § 4. Sequencing rule: SHIP
+ * FOURTH. Numeric semantics; relies on `extractScSurface` (composite
+ * #2) being stable. Must not ship before composite #2 because the
+ * surface enrichment proves out the reuse path planned in the design
+ * doc.
+ *
+ * Failure model:
+ *   - DVM compile failure (daemon returns `RPC error -32098`) → the
+ *     classifier branch in `withStructuredErrors` surfaces this as
+ *     `INVALID_INPUT` with an actionable hint. The daemon's exact
+ *     compile message stays in `_meta.error.raw`.
+ *   - Invalid signer address → daemon usually emits `RPC error
+ *     -32602` (RPC_INVALID_PARAMS); existing classifier branch
+ *     handles it.
+ *   - Daemon returns a non-"OK" status with 0/0 numbers → return
+ *     the estimate as-is and set `breakdown: null`. NEVER fabricate
+ *     a breakdown when the numbers are 0/0 with a non-success
+ *     status; the agent must see the daemon's exact status string.
+ */
+import { z } from 'zod';
+import { attachCitations, extractScSurface, } from './_shared.js';
+const DERO_ADDRESS_REGEX = /^(dero1|deto1)[0-9a-z]+$/i;
+export const estimateDeployCostInputSchema = {
+    sc: z
+        .string()
+        .min(1)
+        .describe('DVM-BASIC contract source to deploy. MUST be the full contract (Function ... End Function blocks), not a function body alone.'),
+    signer: z
+        .string()
+        .regex(DERO_ADDRESS_REGEX, 'Expected DERO address starting with dero1 or deto1')
+        .optional()
+        .describe('Optional dero1.../deto1... signer for the eventual deploy tx.'),
+    include_breakdown: z
+        .boolean()
+        .optional()
+        .describe('Default true. Set false to return raw estimate numbers only.'),
+};
+/**
+ * Pure function: turn a (gascompute, gasstorage) pair into a
+ * plain-language breakdown. Returns `null` when either number is
+ * unavailable or non-numeric, OR when the daemon returned 0/0 with a
+ * non-"OK" status (in which case fabricating a breakdown would
+ * mislead the agent — the design contract is explicit on this).
+ *
+ * The DVM denominates gas in atomic units (the daemon docs call them
+ * "gas units"). Converting to DERO requires the fee-per-gas table,
+ * which is itself a separate query. We deliberately do NOT convert
+ * here and instead surface the raw unit total plus a note pointing
+ * the agent at the docs.
+ */
+export function buildBreakdown(gascompute, gasstorage, status) {
+    const compute = typeof gascompute === 'number' ? gascompute : Number(gascompute);
+    const storage = typeof gasstorage === 'number' ? gasstorage : Number(gasstorage);
+    if (!Number.isFinite(compute) || !Number.isFinite(storage))
+        return null;
+    if (compute === 0 && storage === 0 && status !== 'OK')
+        return null;
+    return {
+        compute_note: `gascompute=${compute} — DVM execution cost (units the daemon charges for running the contract's Initialize and any reachable functions during the deploy). Higher when the contract has more code paths.`,
+        storage_note: `gasstorage=${storage} — on-chain byte cost (units the daemon charges for storing the contract code blob and its initial state). Roughly proportional to source length.`,
+        total_units: compute + storage,
+    };
+}
+export async function estimateDeployCost(rpc, args) {
+    const params = { sc: args.sc };
+    if (args.signer)
+        params.signer = args.signer;
+    // Required call. DVM compile failures throw RPC error -32098 which
+    // the classifier branch in src/server.ts maps to INVALID_INPUT.
+    const raw = (await rpc('DERO.GetGasEstimate', params)) ?? {};
+    const gascompute = typeof raw.gascompute === 'number' || typeof raw.gascompute === 'string'
+        ? Number(raw.gascompute)
+        : null;
+    const gasstorage = typeof raw.gasstorage === 'number' || typeof raw.gasstorage === 'string'
+        ? Number(raw.gasstorage)
+        : null;
+    const status = typeof raw.status === 'string' ? raw.status : null;
+    const includeBreakdown = args.include_breakdown !== false;
+    const breakdown = includeBreakdown ? buildBreakdown(raw.gascompute, raw.gasstorage, raw.status ?? undefined) : null;
+    // Wedge enrichment: parse the SC source the user just submitted so
+    // the agent can show "you're about to deploy X functions" alongside
+    // the gas numbers. Reuses extractScSurface from composite #2, with
+    // the user-provided `sc` shaped as a DeroGetScResult so the same
+    // extractor can run unchanged.
+    const surface = extractScSurface({ code: args.sc });
+    return attachCitations({
+        estimate: {
+            gascompute,
+            gasstorage,
+            status,
+        },
+        breakdown,
+        signer_used: args.signer ?? null,
+        include_breakdown: includeBreakdown,
+        sc_surface: {
+            functions: surface.functions,
+            stringkeys: surface.stringkeys,
+            uint64keys: surface.uint64keys,
+            raw_code_length: surface.raw_code_length,
+            function_count: surface.functions.length,
+        },
+    }, 'estimate_deploy_cost');
+}
+//# sourceMappingURL=estimate-deploy-cost.js.map

package/dist/composites/estimate-deploy-cost.js.map

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

package/dist/composites/explain-smart-contract.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `explain_smart_contract` — Phase C composite #2.
+ *
+ * Wedge-defining composite. Today an agent calls `dero_get_sc`, gets a
+ * raw code blob with stringkeys/uint64keys/balances, and must know
+ * DVM-BASIC syntax to interpret it. This composite extracts the
+ * contract's function surface and stitches it to the right bundled DVM
+ * docs page — something no generic chain MCP can replicate because no
+ * other chain MCP ships the docs index in-process.
+ *
+ * Design contract: `docs/composites.md` § 2. Sequencing rule: SHIP
+ * SECOND — establishes the SC-introspection pattern (`extractScSurface`)
+ * that `trace_transaction_with_context` and `estimate_deploy_cost` reuse.
+ *
+ * Failure model:
+ *   - `DERO.GetSC` failing entirely → handler throws so
+ *     `withStructuredErrors` surfaces a structured error to the agent.
+ *   - `DERO.GetSC` succeeds but returns no `code` → response carries
+ *     `surface.has_code: false`, `functions: []`, narrative explains
+ *     the SCID is unknown or has no on-chain code, and `_meta.error`
+ *     style hint points at `dero_docs_search("smart contract")`.
+ *   - Code present but `extractScSurface` finds zero functions →
+ *     return surface with `functions: []` and a narrative noting
+ *     parse-uncertainty. NEVER swallow the raw code; surface
+ *     `raw_code_length` so the agent knows to fall back to `dero_get_sc`.
+ */
+import { z } from 'zod';
+import { type DeroDaemonRpc, type DeroScSurface } from './_shared.js';
+export declare const explainSmartContractInputSchema: {
+    readonly scid: z.ZodString;
+    readonly topoheight: z.ZodOptional<z.ZodNumber>;
+};
+type ExplainInput = {
+    scid: string;
+    topoheight?: number;
+};
+type ContractKind = 'token' | 'registry' | 'minimal' | 'generic';
+/**
+ * Classify a contract from its surface + raw code so we can pick the
+ * most relevant docs page as "primary". Pure function, deterministic,
+ * unit-testable. Returns the classification AND the slug to elevate.
+ */
+export declare function classifyContractAndPickDoc(surface: DeroScSurface, code: string): {
+    kind: ContractKind;
+    primarySlug: string;
+};
+export declare function explainSmartContract(rpc: DeroDaemonRpc, args: ExplainInput): Promise<{
+    scid: string;
+    topoheight: number | null;
+    kind: ContractKind;
+    surface: {
+        functions: import("./_shared.js").DvmFunctionSignature[];
+        stringkeys: string[];
+        uint64keys: string[];
+        balances: Record<string, string | number>;
+    };
+    narrative: string;
+    raw_code_length: number;
+    has_code: boolean;
+} & {
+    related_docs?: import("../citations.js").DeroCitation[];
+}>;
+export {};
+//# sourceMappingURL=explain-smart-contract.d.ts.map

package/dist/composites/explain-smart-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-smart-contract.d.ts","sourceRoot":"","sources":["../../src/composites/explain-smart-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAGL,KAAK,aAAa,EAElB,KAAK,aAAa,EACnB,MAAM,cAAc,CAAA;AAIrB,eAAO,MAAM,+BAA+B;;;CAUlC,CAAA;AAEV,KAAK,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAWzD,KAAK,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAA;AAEhE;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,GACX;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CA6B7C;AA2CD,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY;;;;;;;;;;;;;;;GAmDhF"}

package/dist/composites/explain-smart-contract.js

@@ -0,0 +1,149 @@
+/**
+ * `explain_smart_contract` — Phase C composite #2.
+ *
+ * Wedge-defining composite. Today an agent calls `dero_get_sc`, gets a
+ * raw code blob with stringkeys/uint64keys/balances, and must know
+ * DVM-BASIC syntax to interpret it. This composite extracts the
+ * contract's function surface and stitches it to the right bundled DVM
+ * docs page — something no generic chain MCP can replicate because no
+ * other chain MCP ships the docs index in-process.
+ *
+ * Design contract: `docs/composites.md` § 2. Sequencing rule: SHIP
+ * SECOND — establishes the SC-introspection pattern (`extractScSurface`)
+ * that `trace_transaction_with_context` and `estimate_deploy_cost` reuse.
+ *
+ * Failure model:
+ *   - `DERO.GetSC` failing entirely → handler throws so
+ *     `withStructuredErrors` surfaces a structured error to the agent.
+ *   - `DERO.GetSC` succeeds but returns no `code` → response carries
+ *     `surface.has_code: false`, `functions: []`, narrative explains
+ *     the SCID is unknown or has no on-chain code, and `_meta.error`
+ *     style hint points at `dero_docs_search("smart contract")`.
+ *   - Code present but `extractScSurface` finds zero functions →
+ *     return surface with `functions: []` and a narrative noting
+ *     parse-uncertainty. NEVER swallow the raw code; surface
+ *     `raw_code_length` so the agent knows to fall back to `dero_get_sc`.
+ */
+import { z } from 'zod';
+import { attachCitations, extractScSurface, } from './_shared.js';
+const SCID_HEX_REGEX = /^[0-9a-fA-F]{64}$/;
+export const explainSmartContractInputSchema = {
+    scid: z
+        .string()
+        .regex(SCID_HEX_REGEX, 'Expected 64-character hex Smart Contract ID')
+        .describe('64-char hex Smart Contract ID'),
+    topoheight: z
+        .number()
+        .int()
+        .optional()
+        .describe('Optional topo height; omit for latest tip'),
+};
+// ---------------- Heuristic docs routing ----------------
+//
+// The four bundled DVM docs slugs we can route to. Validated by the
+// citation CI guard via `RELATED_DOCS_BY_TOOL.explain_smart_contract`.
+const DVM_DOC_FUNDAMENTALS = 'dvm/smart-contract-fundamentals';
+const DVM_DOC_LANGUAGE = 'dvm/dvm-basic';
+const DVM_DOC_DEPLOY = 'dvm/create-deploy-use-smart-contract';
+const DVM_DOC_PLATFORM = 'dvm/dero-virtual-machine';
+/**
+ * Classify a contract from its surface + raw code so we can pick the
+ * most relevant docs page as "primary". Pure function, deterministic,
+ * unit-testable. Returns the classification AND the slug to elevate.
+ */
+export function classifyContractAndPickDoc(surface, code) {
+    const functionNames = new Set(surface.functions.map((f) => f.name.toLowerCase()));
+    const codeUpper = code.toUpperCase();
+    const looksLikeToken = codeUpper.includes('SEND_ASSET_TO_ADDRESS') ||
+        functionNames.has('mint') ||
+        functionNames.has('burn') ||
+        (functionNames.has('transfer') && functionNames.has('transferownership'));
+    if (looksLikeToken) {
+        return { kind: 'token', primarySlug: DVM_DOC_LANGUAGE };
+    }
+    const looksLikeRegistry = codeUpper.includes('EXISTS(') ||
+        functionNames.has('register') ||
+        functionNames.has('lookup') ||
+        functionNames.has('reserve');
+    if (looksLikeRegistry) {
+        return { kind: 'registry', primarySlug: DVM_DOC_FUNDAMENTALS };
+    }
+    if (surface.functions.length <= 1) {
+        return { kind: 'minimal', primarySlug: DVM_DOC_DEPLOY };
+    }
+    return { kind: 'generic', primarySlug: DVM_DOC_FUNDAMENTALS };
+}
+// ---------------- Narrative ----------------
+//
+// Lives next to the composite (not in `_shared.ts`) because the shape is
+// tightly coupled to composite #2's response. Pure function for testability.
+function buildNarrative(scid, topoheight, surface, kind) {
+    if (!surface.has_code) {
+        return `SCID ${scid} returned no on-chain code at topoheight ${topoheight ?? 'tip'}. Either the contract does not exist or it was deployed without code. Try dero_docs_search("smart contract") for installation context, or re-check the SCID.`;
+    }
+    const fnCount = surface.functions.length;
+    const stringCount = surface.stringkeys.length;
+    const uint64Count = surface.uint64keys.length;
+    const balanceCount = Object.keys(surface.balances).length;
+    if (fnCount === 0) {
+        return `Found ${surface.raw_code_length} bytes of code at SCID ${scid} (topoheight ${topoheight ?? 'tip'}) but no DVM-BASIC Function declarations were recognized by the parser. The raw code is still available via dero_get_sc; ${stringCount} stored string keys and ${uint64Count} uint64 keys are present, with ${balanceCount} asset balance(s).`;
+    }
+    const kindPhrase = {
+        token: 'has a token-style surface (transfer/asset operations)',
+        registry: 'has a registry-style surface (Register/Lookup/EXISTS pattern)',
+        minimal: 'is a minimal contract (Initialize-only or single function)',
+        generic: 'has a generic state-machine surface',
+    };
+    const fnList = surface.functions
+        .slice(0, 6)
+        .map((f) => (f.args.length > 0 ? `${f.name}(${f.args.length}-arg)` : `${f.name}()`))
+        .join(', ');
+    const more = fnCount > 6 ? ` (+${fnCount - 6} more)` : '';
+    return `SCID ${scid} at topoheight ${topoheight ?? 'tip'} ${kindPhrase[kind]}. Exposes ${fnCount} function${fnCount === 1 ? '' : 's'}: ${fnList}${more}. State carries ${stringCount} string key${stringCount === 1 ? '' : 's'} and ${uint64Count} uint64 key${uint64Count === 1 ? '' : 's'}, with ${balanceCount} asset balance entr${balanceCount === 1 ? 'y' : 'ies'}. See the cited docs page for the DVM concept that best matches this surface.`;
+}
+// ---------------- Handler ----------------
+export async function explainSmartContract(rpc, args) {
+    const params = {
+        scid: args.scid,
+        code: true,
+        variables: true,
+    };
+    if (args.topoheight !== undefined)
+        params.topoheight = args.topoheight;
+    // Required call. Failure propagates through withStructuredErrors.
+    const raw = (await rpc('DERO.GetSC', params)) ?? {};
+    const surface = extractScSurface(raw);
+    const code = typeof raw.code === 'string' ? raw.code : '';
+    const { kind, primarySlug } = classifyContractAndPickDoc(surface, code);
+    const responseTopoheight = typeof args.topoheight === 'number' && Number.isFinite(args.topoheight)
+        ? args.topoheight
+        : null;
+    const narrative = buildNarrative(args.scid, responseTopoheight, surface, kind);
+    // Compose the payload, then attach static citations and re-order so the
+    // heuristic's pick is first. Static citation order (in RELATED_DOCS_BY_TOOL)
+    // ends up as the fallback order when the heuristic returns a slug already
+    // at position 0.
+    const payload = attachCitations({
+        scid: args.scid,
+        topoheight: responseTopoheight,
+        kind,
+        surface: {
+            functions: surface.functions,
+            stringkeys: surface.stringkeys,
+            uint64keys: surface.uint64keys,
+            balances: surface.balances,
+        },
+        narrative,
+        raw_code_length: surface.raw_code_length,
+        has_code: surface.has_code,
+    }, 'explain_smart_contract');
+    if (payload.related_docs && payload.related_docs.length > 0) {
+        const idx = payload.related_docs.findIndex((d) => d.slug === primarySlug);
+        if (idx > 0) {
+            const [picked] = payload.related_docs.splice(idx, 1);
+            payload.related_docs.unshift(picked);
+        }
+    }
+    return payload;
+}
+//# sourceMappingURL=explain-smart-contract.js.map