dero-mcp-server 0.1.2 → 0.4.0

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

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

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

package/dist/composites/forge-demo-proof.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `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 { type DeroCitation } from '../citations.js';
+import { type DeroDaemonRpc } from './_shared.js';
+export declare const forgeDemoProofInputSchema: {
+    readonly tx_hash: z.ZodOptional<z.ZodString>;
+    readonly tx_hex: z.ZodOptional<z.ZodString>;
+    readonly ring_slot: z.ZodDefault<z.ZodNumber>;
+    readonly amount_dero: z.ZodDefault<z.ZodString>;
+};
+export type ForgeDemoProofInput = {
+    tx_hash?: string;
+    tx_hex?: string;
+    ring_slot?: number;
+    amount_dero?: string;
+};
+export type ForgeDemoProofResult = {
+    forged_proof_string: string;
+    target_amount: {
+        dero: string;
+        atoms_signed: string;
+        atoms_uint64: string;
+    };
+    ring_slot: number;
+    ring_size: number;
+    ring_receiver_address: string | null;
+    math: {
+        C_slot_hex: string;
+        amount_x_G_hex: string;
+        blinder_hex: string;
+    };
+    self_check: {
+        verified: boolean;
+        method: string;
+    };
+    explorer_display_amount: string;
+    context_note: string | null;
+    related_docs: DeroCitation[];
+    _diagnostics: {
+        step_latencies: Record<string, number>;
+        halted_at: string | null;
+        total_ms: number;
+        tx_source: 'tx_hash' | 'tx_hex';
+    };
+};
+/**
+ * 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 declare function forgeDemoProof(rpc: DeroDaemonRpc, input: ForgeDemoProofInput): Promise<ForgeDemoProofResult>;
+//# sourceMappingURL=forge-demo-proof.d.ts.map

package/dist/composites/forge-demo-proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forge-demo-proof.d.ts","sourceRoot":"","sources":["../../src/composites/forge-demo-proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAYvB,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAA;AAKrB,eAAO,MAAM,yBAAyB;;;;;CA+B5B,CAAA;AAEV,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAWD,MAAM,MAAM,oBAAoB,GAAG;IACjC,mBAAmB,EAAE,MAAM,CAAA;IAC3B,aAAa,EAAE;QACb,IAAI,EAAE,MAAM,CAAA;QACZ,YAAY,EAAE,MAAM,CAAA;QACpB,YAAY,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,IAAI,EAAE;QACJ,UAAU,EAAE,MAAM,CAAA;QAClB,cAAc,EAAE,MAAM,CAAA;QACtB,WAAW,EAAE,MAAM,CAAA;KACpB,CAAA;IACD,UAAU,EAAE;QACV,QAAQ,EAAE,OAAO,CAAA;QACjB,MAAM,EAAE,MAAM,CAAA;KACf,CAAA;IACD,uBAAuB,EAAE,MAAM,CAAA;IAC/B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,YAAY,EAAE,YAAY,EAAE,CAAA;IAC5B,YAAY,EAAE;QACZ,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACtC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;QACxB,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,SAAS,GAAG,QAAQ,CAAA;KAChC,CAAA;CACF,CAAA;AAuCD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAiI/B"}