dero-mcp-server 0.1.1 → 0.2.2

package/dist/composites/recommend-docs-path.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `recommend_docs_path` — Phase C composite #3.
+ *
+ * Docs-only composite. Takes a natural-language intent, runs scoped
+ * searches across ALL four products in parallel, boosts
+ * hint-matching scores by 1.5× (when `product_hint` is provided),
+ * groups results by product, and returns a ranked path with
+ * per-result rationale and ready-to-cite citations.
+ *
+ * Wedge: agents currently have to guess which docs product to search
+ * (derod for daemon RPC, tela for on-chain apps, hologram for the
+ * simulator, deropay for the merchant flow). This composite removes
+ * that guess: one call, one ranked answer, with citations the agent
+ * can drop straight into a response.
+ *
+ * Design contract: `docs/composites.md` § 3. Sequencing rule: SHIP
+ * THIRD. Pure docs composition — no chain reads. Proves the
+ * "docs-only composite" pattern that future docs-heavy tools can
+ * reuse.
+ *
+ * Design clarification: the spec text "for each product (or just
+ * `product_hint` if provided)" reads like a filter, but the spec's
+ * scoring rule ("score by `score * productHintBoost` for hint
+ * matches") only makes sense if all four products are always
+ * searched and the hint is treated as a BIAS, not a FILTER. Treating
+ * the hint as a filter would make the boost a uniform no-op. This
+ * implementation searches all four products on every call so the
+ * hint scoring carries real weight and the agent still sees relevant
+ * cross-product docs (e.g. derod RPC pages that touch TELA).
+ *
+ * Failure model:
+ *   - Zero matches across every product → throw
+ *     `'No DERO docs matched intent: "..."'`. The `withStructuredErrors`
+ *     wrapper classifies this as `NO_DOCS_MATCH` and emits a hint
+ *     telling the agent to rephrase (or change the `product_hint`).
+ *   - The bundled docs index missing → propagates the existing
+ *     `DOCS_UNAVAILABLE` classification from `searchDeroDocs`.
+ */
+import { z } from 'zod';
+import { type DeroDocProduct } from '../docs.js';
+import { type DeroCitation } from '../citations.js';
+export declare const recommendDocsPathInputSchema: {
+    readonly intent: z.ZodString;
+    readonly product_hint: z.ZodOptional<z.ZodEnum<["derod", "tela", "hologram", "deropay"]>>;
+    readonly limit_per_product: z.ZodOptional<z.ZodNumber>;
+};
+type RecommendInput = {
+    intent: string;
+    product_hint?: DeroDocProduct;
+    limit_per_product?: number;
+};
+/**
+ * Per-result shape returned by `searchDeroDocs`. Re-declared here as the
+ * minimum surface the composite touches so this module stays decoupled
+ * from internal changes to the docs search response.
+ */
+type SearchHit = {
+    product: DeroDocProduct;
+    slug: string;
+    title: string;
+    description?: string;
+    canonical_url: string;
+    headings: string[];
+    excerpt: string;
+    score: number;
+};
+type Recommendation = {
+    product: DeroDocProduct;
+    slug: string;
+    title: string;
+    canonical_url: string;
+    score: number;
+    boosted_score: number;
+    rationale: string;
+};
+type ByProductSummary = Record<DeroDocProduct, {
+    count: number;
+    top_slug: string | null;
+    top_score: number | null;
+}>;
+/**
+ * Pure helper: turn raw per-product hits into a ranked, deduplicated
+ * list with boosted scores and rationale strings. Exported so flow
+ * tests / future unit tests can call it without spinning up an MCP
+ * client.
+ */
+export declare function rankRecommendations(intent: string, productHint: DeroDocProduct | undefined, hitsByProduct: ReadonlyMap<DeroDocProduct, readonly SearchHit[]>): Recommendation[];
+export declare function recommendDocsPath(args: RecommendInput): Promise<{
+    intent: string;
+    product_hint: "derod" | "tela" | "hologram" | "deropay" | null;
+    limit_per_product: number;
+    recommended: Recommendation[];
+    by_product: ByProductSummary;
+    related_docs: DeroCitation[];
+}>;
+export {};
+//# sourceMappingURL=recommend-docs-path.d.ts.map

package/dist/composites/recommend-docs-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommend-docs-path.d.ts","sourceRoot":"","sources":["../../src/composites/recommend-docs-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAItE,eAAO,MAAM,4BAA4B;;;;CAkB/B,CAAA;AAEV,KAAK,cAAc,GAAG;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,cAAc,CAAA;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED;;;;GAIG;AACH,KAAK,SAAS,GAAG;IACf,OAAO,EAAE,cAAc,CAAA;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,KAAK,cAAc,GAAG;IACpB,OAAO,EAAE,cAAc,CAAA;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,KAAK,gBAAgB,GAAG,MAAM,CAC5B,cAAc,EACd;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CACrE,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,cAAc,GAAG,SAAS,EACvC,aAAa,EAAE,WAAW,CAAC,cAAc,EAAE,SAAS,SAAS,EAAE,CAAC,GAC/D,cAAc,EAAE,CA2BlB;AA4CD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,cAAc;;;;;;;GAsC3D"}

package/dist/composites/recommend-docs-path.js

@@ -0,0 +1,149 @@
+/**
+ * `recommend_docs_path` — Phase C composite #3.
+ *
+ * Docs-only composite. Takes a natural-language intent, runs scoped
+ * searches across ALL four products in parallel, boosts
+ * hint-matching scores by 1.5× (when `product_hint` is provided),
+ * groups results by product, and returns a ranked path with
+ * per-result rationale and ready-to-cite citations.
+ *
+ * Wedge: agents currently have to guess which docs product to search
+ * (derod for daemon RPC, tela for on-chain apps, hologram for the
+ * simulator, deropay for the merchant flow). This composite removes
+ * that guess: one call, one ranked answer, with citations the agent
+ * can drop straight into a response.
+ *
+ * Design contract: `docs/composites.md` § 3. Sequencing rule: SHIP
+ * THIRD. Pure docs composition — no chain reads. Proves the
+ * "docs-only composite" pattern that future docs-heavy tools can
+ * reuse.
+ *
+ * Design clarification: the spec text "for each product (or just
+ * `product_hint` if provided)" reads like a filter, but the spec's
+ * scoring rule ("score by `score * productHintBoost` for hint
+ * matches") only makes sense if all four products are always
+ * searched and the hint is treated as a BIAS, not a FILTER. Treating
+ * the hint as a filter would make the boost a uniform no-op. This
+ * implementation searches all four products on every call so the
+ * hint scoring carries real weight and the agent still sees relevant
+ * cross-product docs (e.g. derod RPC pages that touch TELA).
+ *
+ * Failure model:
+ *   - Zero matches across every product → throw
+ *     `'No DERO docs matched intent: "..."'`. The `withStructuredErrors`
+ *     wrapper classifies this as `NO_DOCS_MATCH` and emits a hint
+ *     telling the agent to rephrase (or change the `product_hint`).
+ *   - The bundled docs index missing → propagates the existing
+ *     `DOCS_UNAVAILABLE` classification from `searchDeroDocs`.
+ */
+import { z } from 'zod';
+import { DERO_DOC_PRODUCTS, searchDeroDocs, } from '../docs.js';
+import { buildDeroCitation } from '../citations.js';
+const PRODUCT_HINT_BOOST = 1.5;
+export const recommendDocsPathInputSchema = {
+    intent: z
+        .string()
+        .min(8)
+        .describe('Natural-language description of what the user wants to do (e.g. "deploy a TELA app", "trace a transaction by hash", "verify a webhook signature").'),
+    product_hint: z
+        .enum(DERO_DOC_PRODUCTS)
+        .optional()
+        .describe('Optional bias toward one product (derod | tela | hologram | deropay) when known.'),
+    limit_per_product: z
+        .number()
+        .int()
+        .min(1)
+        .max(5)
+        .optional()
+        .describe('Cap per-product search results before merging. Default 2.'),
+};
+/**
+ * Pure helper: turn raw per-product hits into a ranked, deduplicated
+ * list with boosted scores and rationale strings. Exported so flow
+ * tests / future unit tests can call it without spinning up an MCP
+ * client.
+ */
+export function rankRecommendations(intent, productHint, hitsByProduct) {
+    const out = [];
+    const seen = new Set();
+    for (const [product, hits] of hitsByProduct) {
+        for (const hit of hits) {
+            const key = `${product}::${hit.slug}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const boost = product === productHint ? PRODUCT_HINT_BOOST : 1;
+            const boostedScore = Math.round(hit.score * boost * 100) / 100;
+            const topHeading = hit.headings[0];
+            const rationale = buildRationale(intent, product, hit.score, boost, topHeading);
+            out.push({
+                product,
+                slug: hit.slug,
+                title: hit.title,
+                canonical_url: hit.canonical_url,
+                score: hit.score,
+                boosted_score: boostedScore,
+                rationale,
+            });
+        }
+    }
+    out.sort((a, b) => b.boosted_score - a.boosted_score);
+    return out;
+}
+function buildRationale(intent, product, rawScore, boost, topHeading) {
+    const boostNote = boost > 1 ? ` (×${boost} product_hint boost applied)` : '';
+    const headingPart = topHeading ? ` Top heading: "${topHeading.slice(0, 80)}".` : '';
+    return `Match for "${intent.slice(0, 60)}" under product=${product} (raw score ${rawScore}${boostNote}).${headingPart}`;
+}
+function summarizeByProduct(recs) {
+    const out = Object.create(null);
+    for (const product of DERO_DOC_PRODUCTS) {
+        out[product] = { count: 0, top_slug: null, top_score: null };
+    }
+    for (const rec of recs) {
+        const bucket = out[rec.product];
+        bucket.count += 1;
+        if (bucket.top_score === null || rec.boosted_score > bucket.top_score) {
+            bucket.top_score = rec.boosted_score;
+            bucket.top_slug = rec.slug;
+        }
+    }
+    return out;
+}
+/**
+ * Build top-N citations from the ranked recommendations. Always
+ * deduplicated by `product::slug` (which `rankRecommendations` also
+ * enforces) so the citation list never lists the same page twice.
+ */
+function citationsFromRecommendations(recs, topN) {
+    return recs
+        .slice(0, topN)
+        .map((rec) => buildDeroCitation(rec.product, rec.slug, rec.title));
+}
+export async function recommendDocsPath(args) {
+    const intent = args.intent.trim();
+    const limitPerProduct = args.limit_per_product ?? 2;
+    const productHint = args.product_hint;
+    // Always fan out to all four products. `searchDeroDocs` shares an
+    // in-process page cache (15s TTL) so the second+ calls in the batch
+    // resolve from memory; the network/disk cost is paid once per cache
+    // window. See the module header for why we don't filter to
+    // product_hint.
+    const searches = await Promise.all(DERO_DOC_PRODUCTS.map((product) => searchDeroDocs({ query: intent, product, limit: limitPerProduct }).then((res) => [product, res.results])));
+    const hitsByProduct = new Map(searches);
+    const recommended = rankRecommendations(intent, productHint, hitsByProduct);
+    if (recommended.length === 0) {
+        throw new Error(`No DERO docs matched intent: "${intent}" across products: ${DERO_DOC_PRODUCTS.join(', ')}. Try rephrasing with product-specific nouns (e.g. "TELA INDEX-1 contract", "DeroPay webhook").`);
+    }
+    const by_product = summarizeByProduct(recommended);
+    const related_docs = citationsFromRecommendations(recommended, 2);
+    return {
+        intent,
+        product_hint: productHint ?? null,
+        limit_per_product: limitPerProduct,
+        recommended,
+        by_product,
+        related_docs,
+    };
+}
+//# sourceMappingURL=recommend-docs-path.js.map

package/dist/composites/recommend-docs-path.js.map

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

package/dist/composites/trace-transaction-with-context.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `trace_transaction_with_context` — Phase C composite #5 (final).
+ *
+ * Wedge: `dero_get_transaction` returns the raw tx record (block,
+ * ring, signer, code, balances) but leaves the agent to figure out
+ * confirmation state, classify the tx kind, and separately fetch
+ * any SC context. This composite combines all of that in one call
+ * and stitches the right docs page as a citation.
+ *
+ * Design contract: `docs/composites.md` § 5. Sequencing rule: SHIP
+ * LAST — highest fan-out + failure-mode count of all Phase C
+ * composites.
+ *
+ * Implementation notes (recorded honestly so the design doc and
+ * shipped surface stay in sync):
+ *
+ *   - SC INSTALL detection works directly off the tx record: when
+ *     `tx.code` is non-empty the tx_hash itself IS the resulting
+ *     SCID and the embedded code is the deployed source. We run
+ *     `extractScSurface` on `tx.code` directly — no second
+ *     `DERO.GetSC` call is needed for installs.
+ *   - SC INVOCATION arg/entrypoint decoding requires walking the
+ *     binary tx blob (`txs_as_hex`) with DERO's tx codec. That
+ *     codec is not yet bundled in this MCP, so the composite does
+ *     NOT fabricate decoded args. It surfaces `raw_tx_hex_length`
+ *     so the agent knows the binary is available via
+ *     `dero_get_transaction` if a downstream wallet wants to
+ *     decode it.
+ *   - TX_NOT_FOUND is signalled by the daemon as an EMPTY record
+ *     (`block_height: 0, in_pool: false, code: ''`) — it does
+ *     not throw. The composite detects this and throws a
+ *     classifier-friendly message so `withStructuredErrors`
+ *     surfaces `_meta.error.code = TX_NOT_FOUND`.
+ *
+ * Failure model:
+ *   - `DERO.GetTransaction` throws → propagates via
+ *     `withStructuredErrors` (RPC_UNREACHABLE / RPC_INVALID_PARAMS
+ *     classifier branches handle the daemon-side cases).
+ *   - Daemon returns empty record for the hash → composite throws
+ *     `'DERO transaction not found: ...'` → classifier returns
+ *     `TX_NOT_FOUND` with a retry hint.
+ *   - Tx found but SC surface extraction degraded for the install
+ *     case → record the surface as-is (`has_code: false`,
+ *     `functions: []`) and let the narrative explain. Never abort.
+ */
+import { z } from 'zod';
+import { type DeroDaemonRpc } from './_shared.js';
+export declare const traceTransactionWithContextInputSchema: {
+    readonly tx_hash: z.ZodString;
+    readonly decode: z.ZodOptional<z.ZodBoolean>;
+    readonly include_sc_context: z.ZodOptional<z.ZodBoolean>;
+};
+type TraceInput = {
+    tx_hash: string;
+    decode?: boolean;
+    include_sc_context?: boolean;
+};
+type ConfirmationStatus = 'confirmed' | 'mempool' | 'unknown';
+type TxKind = 'sc_install' | 'transfer_or_invocation' | 'coinbase' | 'unknown';
+export declare function traceTransactionWithContext(rpc: DeroDaemonRpc, args: TraceInput): Promise<{
+    tx_hash: string;
+    confirmation: {
+        status: ConfirmationStatus;
+        block_height: number | null;
+        valid_block: string | null;
+        invalid_blocks: string[];
+        in_pool: boolean;
+    };
+    kind: TxKind;
+    ring: {
+        groups: number | null;
+        first_group_size: number | null;
+    };
+    reward: number | null;
+    signer_visible: boolean;
+    native_balance: {
+        scid: string;
+        at_tx: number | null;
+        current: number | null;
+    };
+    sc_install: {
+        scid: string;
+        surface: {
+            functions: import("./_shared.js").DvmFunctionSignature[];
+            stringkeys: string[];
+            uint64keys: string[];
+            balances: Record<string, string | number>;
+        };
+        raw_code_length: number;
+        has_code: boolean;
+    } | null;
+    raw_tx_hex_length: number;
+    narrative: string;
+    _diagnostics: {
+        step_latency_ms: Record<string, number>;
+        total_ms: number;
+        halted_at: string | null;
+        decode_as_json: boolean;
+        include_sc_context: boolean;
+        sc_install_surface_attempted: boolean;
+        sc_install_surface_failed: boolean;
+    };
+} & {
+    related_docs?: import("../citations.js").DeroCitation[];
+}>;
+export {};
+//# sourceMappingURL=trace-transaction-with-context.d.ts.map

package/dist/composites/trace-transaction-with-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-transaction-with-context.d.ts","sourceRoot":"","sources":["../../src/composites/trace-transaction-with-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAOL,KAAK,aAAa,EAEnB,MAAM,cAAc,CAAA;AAKrB,eAAO,MAAM,sCAAsC;;;;CAezC,CAAA;AAEV,KAAK,UAAU,GAAG;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B,CAAA;AA6BD,KAAK,kBAAkB,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAA;AAC7D,KAAK,MAAM,GAAG,YAAY,GAAG,wBAAwB,GAAG,UAAU,GAAG,SAAS,CAAA;AAgF9E,wBAAsB,2BAA2B,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0GrF"}

package/dist/composites/trace-transaction-with-context.js

@@ -0,0 +1,217 @@
+/**
+ * `trace_transaction_with_context` — Phase C composite #5 (final).
+ *
+ * Wedge: `dero_get_transaction` returns the raw tx record (block,
+ * ring, signer, code, balances) but leaves the agent to figure out
+ * confirmation state, classify the tx kind, and separately fetch
+ * any SC context. This composite combines all of that in one call
+ * and stitches the right docs page as a citation.
+ *
+ * Design contract: `docs/composites.md` § 5. Sequencing rule: SHIP
+ * LAST — highest fan-out + failure-mode count of all Phase C
+ * composites.
+ *
+ * Implementation notes (recorded honestly so the design doc and
+ * shipped surface stay in sync):
+ *
+ *   - SC INSTALL detection works directly off the tx record: when
+ *     `tx.code` is non-empty the tx_hash itself IS the resulting
+ *     SCID and the embedded code is the deployed source. We run
+ *     `extractScSurface` on `tx.code` directly — no second
+ *     `DERO.GetSC` call is needed for installs.
+ *   - SC INVOCATION arg/entrypoint decoding requires walking the
+ *     binary tx blob (`txs_as_hex`) with DERO's tx codec. That
+ *     codec is not yet bundled in this MCP, so the composite does
+ *     NOT fabricate decoded args. It surfaces `raw_tx_hex_length`
+ *     so the agent knows the binary is available via
+ *     `dero_get_transaction` if a downstream wallet wants to
+ *     decode it.
+ *   - TX_NOT_FOUND is signalled by the daemon as an EMPTY record
+ *     (`block_height: 0, in_pool: false, code: ''`) — it does
+ *     not throw. The composite detects this and throws a
+ *     classifier-friendly message so `withStructuredErrors`
+ *     surfaces `_meta.error.code = TX_NOT_FOUND`.
+ *
+ * Failure model:
+ *   - `DERO.GetTransaction` throws → propagates via
+ *     `withStructuredErrors` (RPC_UNREACHABLE / RPC_INVALID_PARAMS
+ *     classifier branches handle the daemon-side cases).
+ *   - Daemon returns empty record for the hash → composite throws
+ *     `'DERO transaction not found: ...'` → classifier returns
+ *     `TX_NOT_FOUND` with a retry hint.
+ *   - Tx found but SC surface extraction degraded for the install
+ *     case → record the surface as-is (`has_code: false`,
+ *     `functions: []`) and let the narrative explain. Never abort.
+ */
+import { z } from 'zod';
+import { attachCitations, extractScSurface, runChain, stepLatencies, stepValue, } from './_shared.js';
+const HEX64_REGEX = /^[0-9a-fA-F]{64}$/;
+const NATIVE_DERO_SCID = '0000000000000000000000000000000000000000000000000000000000000000';
+export const traceTransactionWithContextInputSchema = {
+    tx_hash: z
+        .string()
+        .regex(HEX64_REGEX, 'Expected 64-character hex transaction hash')
+        .describe('64-char hex transaction hash'),
+    decode: z
+        .boolean()
+        .optional()
+        .describe('Pass decode_as_json=1 to the daemon. Default true. Decoded JSON view is informational; the raw hex always comes back.'),
+    include_sc_context: z
+        .boolean()
+        .optional()
+        .describe('When true (default), runs the SC-install surface extraction inline when the tx contains contract code. SC invocation arg decoding is NOT performed in either mode; see module docs.'),
+};
+function classifyConfirmation(tx) {
+    if (tx.in_pool === true)
+        return 'mempool';
+    if (typeof tx.block_height === 'number' && tx.block_height > 0)
+        return 'confirmed';
+    return 'unknown';
+}
+function classifyKind(tx) {
+    if (typeof tx.code === 'string' && tx.code.length > 0)
+        return 'sc_install';
+    if (typeof tx.reward === 'number' && tx.reward > 0 && (!tx.ring || tx.ring.length === 0)) {
+        return 'coinbase';
+    }
+    if (Array.isArray(tx.ring) && tx.ring.length > 0)
+        return 'transfer_or_invocation';
+    return 'unknown';
+}
+function ringStats(tx) {
+    if (!Array.isArray(tx.ring) || tx.ring.length === 0) {
+        return { groups: null, first_group_size: null };
+    }
+    const groups = tx.ring.length;
+    const first = tx.ring[0];
+    const firstSize = Array.isArray(first) ? first.length : null;
+    return { groups, first_group_size: firstSize };
+}
+function isEmptyTxRecord(tx) {
+    if (!tx)
+        return true;
+    const noBlock = !tx.block_height || tx.block_height === 0;
+    const noPool = tx.in_pool !== true;
+    const noCode = !tx.code || tx.code.length === 0;
+    const noRing = !Array.isArray(tx.ring) || tx.ring.length === 0;
+    return noBlock && noPool && noCode && noRing;
+}
+function buildNarrative(txHash, confirmation, kind, blockHeight, scInstallSurface, ringGroups, rawHexLen, scLookupFailed) {
+    const parts = [];
+    if (confirmation === 'mempool') {
+        parts.push(`Tx ${txHash} is in the mempool (not yet confirmed). It may still be reorganized or dropped; treat the result as provisional.`);
+    }
+    else if (confirmation === 'confirmed') {
+        parts.push(`Tx ${txHash} is confirmed at block height ${blockHeight ?? 'unknown'}.`);
+    }
+    else {
+        parts.push(`Tx ${txHash} confirmation status is unknown — the daemon returned a record but did not mark it confirmed or in mempool.`);
+    }
+    if (kind === 'sc_install') {
+        if (scInstallSurface && scInstallSurface.has_code) {
+            const fnCount = scInstallSurface.functions.length;
+            const sampleFns = scInstallSurface.functions
+                .slice(0, 4)
+                .map((f) => f.name)
+                .join(', ');
+            parts.push(`Tx is a smart-contract INSTALL: the tx_hash is the resulting SCID. The deployed source carries ${fnCount} function${fnCount === 1 ? '' : 's'}${sampleFns ? ` (${sampleFns}${fnCount > 4 ? ', …' : ''})` : ''}. The composite parsed the surface inline from the embedded code; no second dero_get_sc call was needed.`);
+        }
+        else if (scLookupFailed) {
+            parts.push('Tx is a smart-contract INSTALL but the surface extractor failed to parse the embedded code. Fall back to dero_get_sc with the tx_hash as SCID for the raw payload.');
+        }
+    }
+    else if (kind === 'coinbase') {
+        parts.push('Tx is a coinbase (mining reward) — no ring members, signer is the miner address.');
+    }
+    else if (kind === 'transfer_or_invocation') {
+        parts.push(`Tx is a transfer or SC invocation. ${ringGroups ? `${ringGroups} input ring group${ringGroups === 1 ? '' : 's'} present.` : ''} SC invocation arg decoding is not surfaced by the daemon's JSON response; the ${rawHexLen}-char raw hex blob is available via dero_get_transaction if a wallet-side decoder is needed.`);
+    }
+    return parts.join(' ');
+}
+export async function traceTransactionWithContext(rpc, args) {
+    const decode = args.decode !== false;
+    const includeScContext = args.include_sc_context !== false;
+    const params = {
+        txs_hashes: [args.tx_hash],
+        decode_as_json: decode ? 1 : 0,
+    };
+    const steps = [
+        {
+            name: 'get_transaction',
+            required: true,
+            fn: () => rpc('DERO.GetTransaction', params),
+        },
+    ];
+    const chain = await runChain(steps);
+    const txResult = stepValue(chain, 'get_transaction');
+    const tx = txResult?.txs?.[0];
+    const rawHexLen = (txResult?.txs_as_hex?.[0] ?? '').length;
+    if (!tx || isEmptyTxRecord(tx)) {
+        // Daemon does not error on unknown hashes — it returns an empty record.
+        // Throw a classifier-friendly message so withStructuredErrors emits
+        // TX_NOT_FOUND.
+        throw new Error(`DERO transaction not found: ${args.tx_hash}. The daemon returned an empty record (no block_height, no mempool entry, no code, no ring).`);
+    }
+    const confirmation = classifyConfirmation(tx);
+    const kind = classifyKind(tx);
+    const { groups: ringGroups, first_group_size: firstRingSize } = ringStats(tx);
+    let scInstallSurface = null;
+    let scLookupFailed = false;
+    if (includeScContext && kind === 'sc_install') {
+        try {
+            scInstallSurface = extractScSurface({ code: tx.code });
+        }
+        catch {
+            scLookupFailed = true;
+            scInstallSurface = null;
+        }
+    }
+    const narrative = buildNarrative(args.tx_hash, confirmation, kind, typeof tx.block_height === 'number' ? tx.block_height : null, scInstallSurface, ringGroups, rawHexLen, scLookupFailed);
+    return attachCitations({
+        tx_hash: args.tx_hash,
+        confirmation: {
+            status: confirmation,
+            block_height: typeof tx.block_height === 'number' ? tx.block_height : null,
+            valid_block: typeof tx.valid_block === 'string' && tx.valid_block.length > 0 ? tx.valid_block : null,
+            invalid_blocks: Array.isArray(tx.invalid_block) ? tx.invalid_block : [],
+            in_pool: tx.in_pool === true,
+        },
+        kind,
+        ring: {
+            groups: ringGroups,
+            first_group_size: firstRingSize,
+        },
+        reward: typeof tx.reward === 'number' ? tx.reward : null,
+        signer_visible: typeof tx.signer === 'string' && tx.signer.length > 0,
+        native_balance: {
+            scid: NATIVE_DERO_SCID,
+            at_tx: typeof tx.balance === 'number' ? tx.balance : null,
+            current: typeof tx.balancenow === 'number' ? tx.balancenow : null,
+        },
+        sc_install: scInstallSurface
+            ? {
+                scid: args.tx_hash,
+                surface: {
+                    functions: scInstallSurface.functions,
+                    stringkeys: scInstallSurface.stringkeys,
+                    uint64keys: scInstallSurface.uint64keys,
+                    balances: scInstallSurface.balances,
+                },
+                raw_code_length: scInstallSurface.raw_code_length,
+                has_code: scInstallSurface.has_code,
+            }
+            : null,
+        raw_tx_hex_length: rawHexLen,
+        narrative,
+        _diagnostics: {
+            step_latency_ms: stepLatencies(chain),
+            total_ms: chain.totalMs,
+            halted_at: chain.haltedAt,
+            decode_as_json: decode,
+            include_sc_context: includeScContext,
+            sc_install_surface_attempted: includeScContext && kind === 'sc_install',
+            sc_install_surface_failed: scLookupFailed,
+        },
+    }, 'trace_transaction_with_context');
+}
+//# sourceMappingURL=trace-transaction-with-context.js.map

package/dist/composites/trace-transaction-with-context.js.map

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

package/dist/docs-parse.d.ts

@@ -0,0 +1,30 @@
+export declare const DERO_DOC_PRODUCTS: readonly ["derod", "tela", "hologram", "deropay"];
+export type DeroDocProduct = (typeof DERO_DOC_PRODUCTS)[number];
+export declare const DOC_SITE_DIRS: Record<DeroDocProduct, string>;
+export declare const DOC_BASE_URLS: Record<DeroDocProduct, string>;
+export type DeroDocsPage = {
+    product: DeroDocProduct;
+    slug: string;
+    title: string;
+    description: string | null;
+    canonicalUrl: string;
+    sourcePath: string;
+    headings: string[];
+    plainText: string;
+    lastUpdated: string | null;
+};
+export type DocsIndexFile = {
+    version: 1;
+    generated_at: string;
+    page_count: number;
+    pages: DeroDocsPage[];
+};
+export declare function normalizeSlug(input: string): string;
+export declare function pathExists(targetPath: string): Promise<boolean>;
+export declare function parseFrontmatter(raw: string): Record<string, string>;
+export declare function stripFrontmatter(raw: string): string;
+export declare function extractHeadings(markdown: string): string[];
+export declare function mdxToPlainText(raw: string): string;
+export declare function indexDocsFromRoot(root: string): Promise<DeroDocsPage[]>;
+export declare function resolveDeroDocsRoot(customRoot?: string): Promise<string | null>;
+//# sourceMappingURL=docs-parse.d.ts.map

package/dist/docs-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-parse.d.ts","sourceRoot":"","sources":["../src/docs-parse.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,iBAAiB,mDAAoD,CAAA;AAClF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE/D,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAKxD,CAAA;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAKxD,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,cAAc,CAAA;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,CAAC,CAAA;IACV,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB,CAAA;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAYD,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOrE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWpE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWlD;AAyBD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAqC7E;AAED,wBAAsB,mBAAmB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkBrF"}