dero-mcp-server 0.1.2 → 0.4.0

package/dist/composites/forge-demo-proof.js

@@ -0,0 +1,204 @@
+/**
+ * `dero_forge_demo_proof` — composite #7.
+ *
+ * Builds a `deroproof…` display object for a chosen transaction, ring slot,
+ * and amount. The string is constructed locally from public chain data — no
+ * wallet, no keys, no broadcast. On an unpatched explorer it shows
+ * **Verified ✓** for the chosen amount; on the chain, nothing changes.
+ *
+ * Purpose: defensive demonstration of the integrity-page Part 3 forge math
+ * (`docs/integrity/inflation-claim`, Part 3). When an AI agent is asked
+ * "does this deroproof string prove the chain minted coins?", the agent can
+ * forge an equivalent string here and show, on real chain inputs, that
+ * **Verified** is a display-layer fact about the pasted object — not a
+ * consensus statement about coins moving.
+ *
+ * Math (same equation `proof.Prove()` checks at `proof/proof.go:88-95`):
+ *
+ *   blinder = C[slot] − amount × G
+ *   forged_string = bech32("deroproof", version || blinder_compressed || CBOR({HH: 0…0, VU: amount}))
+ *
+ * Self-check: amount × G + blinder == C[slot]. If this fails, the encoded
+ * string would not verify and we never return it.
+ *
+ * Read-only invariant: this tool computes a string and returns it. It does
+ * NOT touch a wallet, broadcast a transaction, or mutate any chain state.
+ * Annotation `readOnlyHint: true` is preserved.
+ */
+import { z } from 'zod';
+import { G, add, deroCompressHex, negate, pointsEqual, scalarMult, uint64ToSignedScalar, } from '../bn254.js';
+import { enrichWithFlaggedArtifacts, relatedDocsFor, } from '../citations.js';
+import { encodeForgeProofString } from '../proof-decode.js';
+import { getRingCommitment, parseTransaction } from '../tx-parse.js';
+import { runChain, stepLatencies, stepValue, } from './_shared.js';
+const ATOMIC = 100000n;
+const UINT64_MOD = 1n << 64n;
+export const forgeDemoProofInputSchema = {
+    tx_hash: z
+        .string()
+        .regex(/^[0-9a-fA-F]{64}$/, 'tx_hash must be 64 hex characters')
+        .optional()
+        .describe('TX hash to forge against. Daemon fetches the TX hex + ring members. Mutually exclusive with tx_hex.'),
+    tx_hex: z
+        .string()
+        .min(2)
+        .optional()
+        .describe('Raw TX bytes as hex (skip the daemon round-trip). Mutually exclusive with tx_hash. When provided, ring_receiver_address is omitted from the response (the hex carries publickey pointers, not full addresses).'),
+    ring_slot: z
+        .number()
+        .int()
+        .nonnegative()
+        .default(0)
+        .describe('Which ring slot 0..ring_size-1 the forged proof should resolve to. Defaults to 0.'),
+    amount_dero: z
+        .string()
+        .regex(/^-?\d+(\.\d{1,5})?$/, 'amount_dero must be a signed decimal with at most 5 fractional digits (e.g. "-1", "1000000", "-2200000.00181")')
+        .default('-1')
+        .describe('Target display amount in signed DERO (5 fractional digits = atomic precision). Negative values demonstrate the uint64 wraparound. Default "-1".'),
+};
+/**
+ * Parse a signed-decimal DERO string (e.g. "-2200000.00181") into:
+ *   - signed atoms (bigint, may be negative)
+ *   - uint64 (atoms mod 2^64)
+ */
+function parseAmount(amountDero) {
+    const negative = amountDero.startsWith('-');
+    const unsigned = negative ? amountDero.slice(1) : amountDero;
+    const dot = unsigned.indexOf('.');
+    const wholeStr = dot === -1 ? unsigned : unsigned.slice(0, dot);
+    const fracStr = dot === -1 ? '' : unsigned.slice(dot + 1);
+    const fracPadded = (fracStr + '00000').slice(0, 5);
+    const whole = BigInt(wholeStr.length === 0 ? '0' : wholeStr);
+    const frac = BigInt(fracPadded);
+    const absAtoms = whole * ATOMIC + frac;
+    const signedAtoms = negative ? -absAtoms : absAtoms;
+    const uint64 = ((signedAtoms % UINT64_MOD) + UINT64_MOD) % UINT64_MOD;
+    // Normalize the input echo so callers see the canonical form (5 fractional digits).
+    const normalized = `${negative && absAtoms > 0n ? '-' : ''}${whole.toString()}.${fracPadded}`;
+    return { signedAtoms, uint64, signedDeroNormalized: normalized };
+}
+/** Format a uint64 as the unpatched-explorer display amount (whole.fractional with 5 digits). */
+function formatExplorerDisplay(uint64) {
+    const whole = uint64 / ATOMIC;
+    const frac = uint64 % ATOMIC;
+    // Group thousands in the whole-part for readability.
+    const wholeStr = whole.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+    return `${wholeStr}.${frac.toString().padStart(5, '0')} DERO`;
+}
+/**
+ * Execute the forge. Composes:
+ *   1. (optional) daemon fetch of TX hex + ring members
+ *   2. parse TX → extract C[ring_slot]
+ *   3. compute blinder = C[slot] − amount × G
+ *   4. self-check: amount × G + blinder == C[slot]
+ *   5. encode forged proof string + assemble narrative + citations
+ */
+export async function forgeDemoProof(rpc, input) {
+    if (input.tx_hash && input.tx_hex) {
+        throw new Error('INVALID_INPUT: provide exactly one of tx_hash or tx_hex (not both)');
+    }
+    if (!input.tx_hash && !input.tx_hex) {
+        throw new Error('INVALID_INPUT: provide either tx_hash or tx_hex');
+    }
+    const ringSlot = input.ring_slot ?? 0;
+    const amountDero = input.amount_dero ?? '-1';
+    // ─── 1. Fetch TX (optional daemon round-trip) ─────────────────────────────
+    let txHex;
+    let receiverAddress = null;
+    const txSource = input.tx_hash ? 'tx_hash' : 'tx_hex';
+    const steps = [];
+    if (input.tx_hash) {
+        const hash = input.tx_hash;
+        steps.push({
+            name: 'get_transaction',
+            required: true,
+            fn: () => rpc('DERO.GetTransaction', {
+                txs_hashes: [hash],
+                decode_as_json: 1,
+            }),
+        });
+    }
+    const chain = await runChain(steps);
+    if (input.tx_hash) {
+        const txResult = stepValue(chain, 'get_transaction');
+        if (!txResult || !txResult.txs_as_hex || txResult.txs_as_hex.length === 0) {
+            throw new Error(`daemon did not return TX hex for ${input.tx_hash} (chain halted at ${chain.haltedAt ?? '?'})`);
+        }
+        txHex = txResult.txs_as_hex[0];
+        const ring = txResult.txs?.[0]?.ring?.[0];
+        if (ring && ringSlot >= 0 && ringSlot < ring.length) {
+            receiverAddress = ring[ringSlot];
+        }
+    }
+    else {
+        txHex = input.tx_hex;
+    }
+    // ─── 2. Parse TX → extract C[ring_slot] ──────────────────────────────────
+    let tx;
+    try {
+        tx = parseTransaction(txHex);
+    }
+    catch (err) {
+        throw new Error(`tx-parse failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const stmt = tx.payloads[0].statement;
+    if (ringSlot >= stmt.ring_size) {
+        throw new Error(`INVALID_INPUT: ring_slot ${ringSlot} >= ring_size ${stmt.ring_size}`);
+    }
+    const Cslot = getRingCommitment(tx, ringSlot);
+    // ─── 3. Forge math ────────────────────────────────────────────────────────
+    const { signedAtoms, uint64, signedDeroNormalized } = parseAmount(amountDero);
+    const amountG = scalarMult(G, uint64ToSignedScalar(uint64));
+    const blinder = add(Cslot, negate(amountG));
+    // ─── 4. Self-check (mirror of proof.Prove() inner loop) ──────────────────
+    const reconstructed = add(amountG, blinder);
+    const verified = pointsEqual(reconstructed, Cslot);
+    if (!verified) {
+        // Should be impossible by construction — bail loud rather than emit a string
+        // that would fail an explorer check.
+        throw new Error('self-check FAILED: amount × G + blinder != C[slot] — bn254 math regression');
+    }
+    // ─── 5. Encode forged proof string ────────────────────────────────────────
+    const blinderHex = deroCompressHex(blinder);
+    const blinderBytes = new Uint8Array(33);
+    for (let i = 0; i < 33; i++)
+        blinderBytes[i] = parseInt(blinderHex.slice(i * 2, i * 2 + 2), 16);
+    const forgedString = encodeForgeProofString(blinderBytes, uint64);
+    // ─── 6. Citations + context_note enrichment ───────────────────────────────
+    const enrichment = enrichWithFlaggedArtifacts({
+        ...(input.tx_hash ? { tx_hash: input.tx_hash } : {}),
+    }, relatedDocsFor('dero_forge_demo_proof'));
+    const related_docs = enrichment?.related_docs ?? relatedDocsFor('dero_forge_demo_proof') ?? [];
+    const context_note = enrichment?.context_note ??
+        'This is a forged display object built locally from public chain data — no wallet, no keys, no broadcast. On unpatched explorers it shows Verified ✓ for the chosen amount; on the chain, nothing changed. See related_docs for the technical rebuttal.';
+    return {
+        forged_proof_string: forgedString,
+        target_amount: {
+            dero: signedDeroNormalized,
+            atoms_signed: signedAtoms.toString(),
+            atoms_uint64: uint64.toString(),
+        },
+        ring_slot: ringSlot,
+        ring_size: stmt.ring_size,
+        ring_receiver_address: receiverAddress,
+        math: {
+            C_slot_hex: stmt.C_hex[ringSlot],
+            amount_x_G_hex: deroCompressHex(amountG),
+            blinder_hex: blinderHex,
+        },
+        self_check: {
+            verified: true,
+            method: 'Reconstructed amount × G + blinder and confirmed equal to C[slot] — same equation proof.Prove() uses (proof/proof.go:88-95).',
+        },
+        explorer_display_amount: formatExplorerDisplay(uint64),
+        context_note,
+        related_docs,
+        _diagnostics: {
+            step_latencies: stepLatencies(chain),
+            halted_at: chain.haltedAt,
+            total_ms: chain.totalMs,
+            tx_source: txSource,
+        },
+    };
+}
+//# sourceMappingURL=forge-demo-proof.js.map

package/dist/composites/forge-demo-proof.js.map

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

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 § 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 § 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 § 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"}