dero-mcp-server 0.1.2 → 0.4.0

package/dist/bn254.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Thin wrapper around `@noble/curves` bn254 G1 for the FORGE feature.
+ *
+ * Two responsibilities:
+ *   1. Expose DERO's custom Pedersen base point `G` (not the standard bn254
+ *      generator). See [src/dero-curve.ts](./dero-curve.ts) for the source.
+ *   2. Compress/decompress points in **DERO format** (big-endian X + 1 sign
+ *      byte), not the SEC1 format noble uses natively.
+ *
+ * Compression format mirrors `derohe/cryptography/bn256/changes.go:19-35`:
+ *   bytes[0..32] = X big-endian
+ *   bytes[32]    = 0x01 if Y is the larger of the two square roots of x^3 + 3
+ *                  mod P (i.e. Y > P - Y), else 0x00.
+ *
+ * Scalar handling mirrors `proof.go:89` — DERO casts `uint64 → int64` before
+ * passing to `big.Int.SetInt64`, so the uint64 wraparound `18446744073709451616`
+ * becomes scalar `-100000`. `scalarMult` accepts arbitrary signed bigints and
+ * reduces mod the curve order before multiplication.
+ */
+declare const Point: import("@noble/curves/abstract/weierstrass.js").WeierstrassPointCons<bigint>;
+export type DeroPoint = InstanceType<typeof Point>;
+/**
+ * Decompress a 33-byte DERO point. Throws on malformed input or x not on curve.
+ *
+ * Logic mirrors `Decompress` in `cryptography/bn256/changes.go:215-241`:
+ * compute both square roots of x^3 + 3 mod P, then pick smaller/larger based
+ * on the sign byte.
+ */
+export declare function deroDecompress(bytes: Uint8Array): DeroPoint;
+/**
+ * Compress a point to DERO 33-byte format.
+ *
+ * Mirrors `Compress` in `cryptography/bn256/changes.go:19-35`:
+ *   sign = 0 if Y < P - Y, else 1.
+ */
+export declare function deroCompress(point: DeroPoint): Uint8Array;
+/** Convenience: hex string round-trip. */
+export declare function deroDecompressHex(hex: string): DeroPoint;
+/** Convenience: returns lowercase hex of the 33-byte compressed form. */
+export declare function deroCompressHex(point: DeroPoint): string;
+/** DERO's Pedersen base point G (custom — not the standard bn254 generator). */
+export declare const G: DeroPoint;
+/**
+ * Scalar multiplication mirroring `proof.go:89`.
+ *
+ * DERO casts `uint64 → int64 → big.Int` before multiplying, so the uint64
+ * wraparound `2^64 - n` for small `n` becomes the negative scalar `-n`. We
+ * accept arbitrary signed bigints here and reduce mod the curve order before
+ * delegating to noble.
+ */
+export declare function scalarMult(point: DeroPoint, scalar: bigint): DeroPoint;
+/**
+ * Treat `value` as a Go `uint64`, mimic `big.Int.SetInt64(int64(value))`, and
+ * return the resulting signed scalar reduced mod the curve order.
+ *
+ * For the cited 2022 proof's V = 18446743853709551435, this returns the
+ * curve-order reduction of -220000000181 — the same scalar `proof.Prove()` uses.
+ */
+export declare function uint64ToSignedScalar(uintValue: bigint): bigint;
+export declare function add(a: DeroPoint, b: DeroPoint): DeroPoint;
+export declare function subtract(a: DeroPoint, b: DeroPoint): DeroPoint;
+export declare function negate(point: DeroPoint): DeroPoint;
+export declare function pointsEqual(a: DeroPoint, b: DeroPoint): boolean;
+/**
+ * Re-derive each fixture from scalar operations and compare against the
+ * compressed bytes printed by the Go scratch program. Throws on any mismatch.
+ *
+ * This is the cross-implementation correctness gate — if the wiring is wrong
+ * (custom G missing, SEC1 vs DERO compression confused, sqrt root inversion),
+ * one of the six fixtures will fail and forging anything else is unsafe.
+ */
+export declare function verifyDeroBn254(): void;
+export {};
+//# sourceMappingURL=bn254.d.ts.map

package/dist/bn254.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bn254.d.ts","sourceRoot":"","sources":["../src/bn254.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH,QAAA,MAAM,KAAK,8EAAiB,CAAA;AAG5B,MAAM,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,KAAK,CAAC,CAAA;AA8ClD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CA4B3D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAOzD;AAED,0CAA0C;AAC1C,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAExD;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAExD;AAMD,gFAAgF;AAChF,eAAO,MAAM,CAAC,EAAE,SAAoD,CAAA;AAEpE;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAMtE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAK9D;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CAEzD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CAE9D;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAElD;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,OAAO,CAE/D;AAMD;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,IAAI,CA0BtC"}

package/dist/bn254.js

@@ -0,0 +1,205 @@
+/**
+ * Thin wrapper around `@noble/curves` bn254 G1 for the FORGE feature.
+ *
+ * Two responsibilities:
+ *   1. Expose DERO's custom Pedersen base point `G` (not the standard bn254
+ *      generator). See [src/dero-curve.ts](./dero-curve.ts) for the source.
+ *   2. Compress/decompress points in **DERO format** (big-endian X + 1 sign
+ *      byte), not the SEC1 format noble uses natively.
+ *
+ * Compression format mirrors `derohe/cryptography/bn256/changes.go:19-35`:
+ *   bytes[0..32] = X big-endian
+ *   bytes[32]    = 0x01 if Y is the larger of the two square roots of x^3 + 3
+ *                  mod P (i.e. Y > P - Y), else 0x00.
+ *
+ * Scalar handling mirrors `proof.go:89` — DERO casts `uint64 → int64` before
+ * passing to `big.Int.SetInt64`, so the uint64 wraparound `18446744073709451616`
+ * becomes scalar `-100000`. `scalarMult` accepts arbitrary signed bigints and
+ * reduces mod the curve order before multiplication.
+ */
+import { bn254 } from '@noble/curves/bn254.js';
+import { BN254_B, BN254_P, BN254_R, CURVE_FIXTURES, DERO_G_COMPRESSED_HEX, } from './dero-curve.js';
+const Point = bn254.G1.Point;
+const Fp = bn254.G1.Point.Fp;
+// ─────────────────────────────────────────────────────────────────────────────
+// Hex / bytes helpers (private — proof-decode.ts has its own copies).
+// ─────────────────────────────────────────────────────────────────────────────
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0)
+        throw new Error(`hex: odd length ${hex.length}`);
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        const b = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(b))
+            throw new Error(`hex: invalid byte "${hex.slice(i * 2, i * 2 + 2)}"`);
+        out[i] = b;
+    }
+    return out;
+}
+function bytesToHex(bytes) {
+    let hex = '';
+    for (const b of bytes)
+        hex += b.toString(16).padStart(2, '0');
+    return hex;
+}
+function bigIntToBE32(value) {
+    if (value < 0n || value >= 1n << 256n) {
+        throw new Error(`bigIntToBE32: out of range ${value}`);
+    }
+    const out = new Uint8Array(32);
+    let v = value;
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return out;
+}
+function be32ToBigInt(bytes, offset = 0) {
+    let v = 0n;
+    for (let i = 0; i < 32; i++)
+        v = (v << 8n) | BigInt(bytes[offset + i]);
+    return v;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// DERO-format compress / decompress
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Decompress a 33-byte DERO point. Throws on malformed input or x not on curve.
+ *
+ * Logic mirrors `Decompress` in `cryptography/bn256/changes.go:215-241`:
+ * compute both square roots of x^3 + 3 mod P, then pick smaller/larger based
+ * on the sign byte.
+ */
+export function deroDecompress(bytes) {
+    if (bytes.length !== 33) {
+        throw new Error(`deroDecompress: expected 33 bytes, got ${bytes.length}`);
+    }
+    const sign = bytes[32];
+    if (sign !== 0 && sign !== 1) {
+        throw new Error(`deroDecompress: invalid sign byte 0x${sign.toString(16).padStart(2, '0')}`);
+    }
+    const x = be32ToBigInt(bytes, 0);
+    if (x >= BN254_P)
+        throw new Error(`deroDecompress: x >= P`);
+    // rhs = x^3 + B mod P, computed in the field.
+    const xF = Fp.create(x);
+    const x3 = Fp.mul(Fp.mul(xF, xF), xF);
+    const rhs = Fp.add(x3, Fp.create(BN254_B));
+    const y1 = Fp.sqrt(rhs);
+    if (y1 === undefined)
+        throw new Error('deroDecompress: x not on curve (no sqrt)');
+    const y2 = Fp.neg(y1);
+    // Confirm we actually got a square root (defensive — Fp.sqrt may return any root).
+    if (Fp.mul(y1, y1) !== rhs)
+        throw new Error('deroDecompress: sqrt verification failed');
+    const smaller = y1 < y2 ? y1 : y2;
+    const larger = y1 < y2 ? y2 : y1;
+    const y = sign === 0 ? smaller : larger;
+    return Point.fromAffine({ x: xF, y });
+}
+/**
+ * Compress a point to DERO 33-byte format.
+ *
+ * Mirrors `Compress` in `cryptography/bn256/changes.go:19-35`:
+ *   sign = 0 if Y < P - Y, else 1.
+ */
+export function deroCompress(point) {
+    const { x, y } = point.toAffine();
+    const out = new Uint8Array(33);
+    out.set(bigIntToBE32(x), 0);
+    const negY = (BN254_P - y) % BN254_P;
+    out[32] = y < negY ? 0 : 1;
+    return out;
+}
+/** Convenience: hex string round-trip. */
+export function deroDecompressHex(hex) {
+    return deroDecompress(hexToBytes(hex));
+}
+/** Convenience: returns lowercase hex of the 33-byte compressed form. */
+export function deroCompressHex(point) {
+    return bytesToHex(deroCompress(point));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Point operations
+// ─────────────────────────────────────────────────────────────────────────────
+/** DERO's Pedersen base point G (custom — not the standard bn254 generator). */
+export const G = deroDecompressHex(DERO_G_COMPRESSED_HEX);
+/**
+ * Scalar multiplication mirroring `proof.go:89`.
+ *
+ * DERO casts `uint64 → int64 → big.Int` before multiplying, so the uint64
+ * wraparound `2^64 - n` for small `n` becomes the negative scalar `-n`. We
+ * accept arbitrary signed bigints here and reduce mod the curve order before
+ * delegating to noble.
+ */
+export function scalarMult(point, scalar) {
+    const r = BN254_R;
+    let s = scalar % r;
+    if (s < 0n)
+        s += r;
+    if (s === 0n)
+        return Point.ZERO;
+    return point.multiply(s);
+}
+/**
+ * Treat `value` as a Go `uint64`, mimic `big.Int.SetInt64(int64(value))`, and
+ * return the resulting signed scalar reduced mod the curve order.
+ *
+ * For the cited 2022 proof's V = 18446743853709551435, this returns the
+ * curve-order reduction of -220000000181 — the same scalar `proof.Prove()` uses.
+ */
+export function uint64ToSignedScalar(uintValue) {
+    if (uintValue < 0n || uintValue >= 1n << 64n) {
+        throw new Error(`uint64ToSignedScalar: out of uint64 range ${uintValue}`);
+    }
+    return uintValue >= 1n << 63n ? uintValue - (1n << 64n) : uintValue;
+}
+export function add(a, b) {
+    return a.add(b);
+}
+export function subtract(a, b) {
+    return a.subtract(b);
+}
+export function negate(point) {
+    return point.negate();
+}
+export function pointsEqual(a, b) {
+    return a.equals(b);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Self-test against the Go-extracted fixtures.
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Re-derive each fixture from scalar operations and compare against the
+ * compressed bytes printed by the Go scratch program. Throws on any mismatch.
+ *
+ * This is the cross-implementation correctness gate — if the wiring is wrong
+ * (custom G missing, SEC1 vs DERO compression confused, sqrt root inversion),
+ * one of the six fixtures will fail and forging anything else is unsafe.
+ */
+export function verifyDeroBn254() {
+    const checks = [
+        ['G', CURVE_FIXTURES.G, G],
+        ['2G', CURVE_FIXTURES.twoG, G.double()],
+        ['3G', CURVE_FIXTURES.threeG, G.double().add(G)],
+        ['-G', CURVE_FIXTURES.negG, G.negate()],
+        ['G*100000', CURVE_FIXTURES.gMul1Dero, scalarMult(G, 100000n)],
+        [
+            'G*int64(uint_wrap)',
+            CURVE_FIXTURES.gMulNeg1DeroAtoms,
+            scalarMult(G, uint64ToSignedScalar(18446744073709451616n)),
+        ],
+        [
+            'G*int64(cited2022V)',
+            CURVE_FIXTURES.gMulCited2022V,
+            scalarMult(G, uint64ToSignedScalar(18446743853709551435n)),
+        ],
+    ];
+    for (const [label, expectedHex, point] of checks) {
+        const actualHex = deroCompressHex(point);
+        if (actualHex !== expectedHex) {
+            throw new Error(`verifyDeroBn254: ${label} mismatch\n  expected: ${expectedHex}\n  actual:   ${actualHex}`);
+        }
+    }
+}
+//# sourceMappingURL=bn254.js.map

package/dist/bn254.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bn254.js","sourceRoot":"","sources":["../src/bn254.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAE9C,OAAO,EACL,OAAO,EACP,OAAO,EACP,OAAO,EACP,cAAc,EACd,qBAAqB,GACtB,MAAM,iBAAiB,CAAA;AAExB,MAAM,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC,KAAK,CAAA;AAC5B,MAAM,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAA;AAI5B,gFAAgF;AAChF,sEAAsE;AACtE,gFAAgF;AAEhF,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAA;IAC1E,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QACnD,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAA;QAC1F,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACZ,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,UAAU,CAAC,KAAiB;IACnC,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IAC7D,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,YAAY,CAAC,KAAa;IACjC,IAAI,KAAK,GAAG,EAAE,IAAI,KAAK,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,EAAE,CAAC,CAAA;IACxD,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAA;IAC9B,IAAI,CAAC,GAAG,KAAK,CAAA;IACb,KAAK,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,CAAA;QAC1B,CAAC,KAAK,EAAE,CAAA;IACV,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,YAAY,CAAC,KAAiB,EAAE,MAAM,GAAG,CAAC;IACjD,IAAI,CAAC,GAAG,EAAE,CAAA;IACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE;QAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAA;IACtE,OAAO,CAAC,CAAA;AACV,CAAC;AAED,gFAAgF;AAChF,oCAAoC;AACpC,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAiB;IAC9C,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,0CAA0C,KAAK,CAAC,MAAM,EAAE,CAAC,CAAA;IAC3E,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,CAAA;IACtB,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,uCAAuC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;IAC9F,CAAC;IACD,MAAM,CAAC,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IAChC,IAAI,CAAC,IAAI,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAA;IAE3D,8CAA8C;IAC9C,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IACvB,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;IACrC,MAAM,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;IAE1C,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACvB,IAAI,EAAE,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAA;IACjF,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAErB,mFAAmF;IACnF,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAA;IAEvF,MAAM,OAAO,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IACjC,MAAM,MAAM,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAChC,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAA;IAEvC,OAAO,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAA;AACvC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAgB;IAC3C,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAA;IACjC,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAA;IAC9B,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAC3B,MAAM,IAAI,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,GAAG,OAAO,CAAA;IACpC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1B,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,OAAO,cAAc,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;AACxC,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,eAAe,CAAC,KAAgB;IAC9C,OAAO,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAA;AACxC,CAAC;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF,gFAAgF;AAChF,MAAM,CAAC,MAAM,CAAC,GAAc,iBAAiB,CAAC,qBAAqB,CAAC,CAAA;AAEpE;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,KAAgB,EAAE,MAAc;IACzD,MAAM,CAAC,GAAG,OAAO,CAAA;IACjB,IAAI,CAAC,GAAG,MAAM,GAAG,CAAC,CAAA;IAClB,IAAI,CAAC,GAAG,EAAE;QAAE,CAAC,IAAI,CAAC,CAAA;IAClB,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC,IAAI,CAAA;IAC/B,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,IAAI,SAAS,GAAG,EAAE,IAAI,SAAS,IAAI,EAAE,IAAI,GAAG,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,6CAA6C,SAAS,EAAE,CAAC,CAAA;IAC3E,CAAC;IACD,OAAO,SAAS,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AACrE,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,CAAY,EAAE,CAAY;IAC5C,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,CAAY,EAAE,CAAY;IACjD,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;AACtB,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,KAAgB;IACrC,OAAO,KAAK,CAAC,MAAM,EAAE,CAAA;AACvB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAY,EAAE,CAAY;IACpD,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;AACpB,CAAC;AAED,gFAAgF;AAChF,+CAA+C;AAC/C,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,MAAM,GAAuC;QACjD,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC,IAAI,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;QACvC,CAAC,IAAI,EAAE,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChD,CAAC,IAAI,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;QACvC,CAAC,UAAU,EAAE,cAAc,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,EAAE,OAAQ,CAAC,CAAC;QAC/D;YACE,oBAAoB;YACpB,cAAc,CAAC,iBAAiB;YAChC,UAAU,CAAC,CAAC,EAAE,oBAAoB,CAAC,qBAAqB,CAAC,CAAC;SAC3D;QACD;YACE,qBAAqB;YACrB,cAAc,CAAC,cAAc;YAC7B,UAAU,CAAC,CAAC,EAAE,oBAAoB,CAAC,qBAAqB,CAAC,CAAC;SAC3D;KACF,CAAA;IACD,KAAK,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACjD,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,CAAA;QACxC,IAAI,SAAS,KAAK,WAAW,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACb,oBAAoB,KAAK,0BAA0B,WAAW,iBAAiB,SAAS,EAAE,CAC3F,CAAA;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/citations.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Citation helper for DERO MCP tool responses.
+ *
+ * The wedge for this server is the combination of live chain reads and the
+ * in-process bundled docs index (145+ pages across derod, tela, hologram,
+ * deropay). Citations let agents link their responses back to authoritative
+ * docs without a second tool call, and they give downstream composite tools
+ * a uniform shape to compose.
+ *
+ * Design contract:
+ *   - One shape, used by primitives and composites alike.
+ *   - URLs are produced by the same builder used by `dero_docs_*` so the
+ *     citation always points at the same canonical page the agent would
+ *     reach via dero_docs_get_page.
+ *   - The slug is duplicated as `page_id` to give composites a stable join
+ *     key across tools (mirrors the FoodNearMe COMPOSITES.md citation pattern).
+ *   - The map of related docs per tool is hand-maintained and validated by
+ *     `scripts/check-citations.ts` (added alongside this helper) so a docs
+ *     reorganization cannot silently produce 404 citations in production.
+ */
+import { type DeroDocProduct } from './docs-parse.js';
+export type DeroCitation = {
+    /** Always `'dero_docs'` for now; future sources (e.g. `'dero_chain'`) can extend this. */
+    source: 'dero_docs';
+    product: DeroDocProduct;
+    slug: string;
+    title: string;
+    canonical_url: string;
+    /** Alias of `slug` so composites can use a single join key across tools. */
+    page_id: string;
+};
+/**
+ * Build a DeroCitation pointing at one bundled docs page.
+ *
+ * The title is required (not derived from the bundled index) so this helper
+ * stays synchronous and zero-IO. It must match the docs page title; the
+ * citation guard validates this against the bundled index in CI.
+ */
+export declare function buildDeroCitation(product: DeroDocProduct, slug: string, title: string): DeroCitation;
+/**
+ * Map of MCP tool name → hand-curated related docs pages.
+ *
+ * Keep this list tight — only add entries when a tool's response is
+ * meaningfully improved by linking the agent at a specific page. The CI
+ * guard verifies every slug resolves against the bundled docs index, so any
+ * docs reorganization will fail the build before it ships.
+ *
+ * Adding a tool here:
+ *   1. Use `dero_docs_search` to find the right slug(s).
+ *   2. Add an entry with product + slug + exact page title.
+ *   3. Run `npm run check:citations` to confirm slugs resolve.
+ */
+type RelatedDocsEntry = {
+    product: DeroDocProduct;
+    slug: string;
+    title: string;
+};
+export declare const RELATED_DOCS_BY_TOOL: Record<string, readonly RelatedDocsEntry[]>;
+/**
+ * Resolve the hand-curated related docs list for a tool name and return it
+ * as fully-built `DeroCitation` objects. Returns `undefined` when the tool
+ * has no related docs configured.
+ *
+ * Use in tool handlers like:
+ *   const related_docs = relatedDocsFor('dero_get_sc')
+ *   return { ...rpcResult, ...(related_docs ? { related_docs } : {}) }
+ */
+export declare function relatedDocsFor(toolName: string): DeroCitation[] | undefined;
+export type FlaggedArtifactMatcher = {
+    kind: 'topoheight';
+    value: number;
+} | {
+    kind: 'block_hash';
+    value: string;
+} | {
+    kind: 'tx_hash';
+    value: string;
+} | {
+    kind: 'proof_string';
+    value: string;
+};
+export type FlaggedArtifact = {
+    /** Stable human-readable id for logs and downstream tooling. */
+    id: string;
+    matchers: readonly FlaggedArtifactMatcher[];
+    /** Short factual statement appended to responses that match this artifact. */
+    context_note: string;
+    related_docs: readonly RelatedDocsEntry[];
+    /**
+     * The most rebuttal-relevant signed-DERO amount for `dero_forge_demo_proof`
+     * to use when `audit_chain_artifact_claim` is called with
+     * `include_forge_demo: true` and this artifact matches. For the 2022 claim
+     * this is the report's headline amount — forging the same display number
+     * for a non-receiver ring slot is the most direct demonstration that the
+     * pasted string is a display object, not a consensus statement.
+     */
+    demo_amount_dero?: string;
+};
+export declare const FLAGGED_CHAIN_ARTIFACTS: readonly FlaggedArtifact[];
+/**
+ * Input shape passed by tool handlers. Optional fields let each tool pass
+ * only the inputs it actually has (e.g. dero_get_block_header_by_topo_height
+ * only knows about topoheight; dero_get_transaction only knows about
+ * tx_hashes). String comparisons are case-insensitive on hex values.
+ */
+export type FlaggedArtifactQuery = {
+    topoheight?: number;
+    block_hash?: string;
+    tx_hash?: string;
+    tx_hashes?: readonly string[];
+    proof_string?: string;
+};
+/**
+ * Return all flagged artifacts whose matchers fire against the given inputs.
+ *
+ * Multiple matches return multiple artifacts (rare today; would happen if the
+ * same TX got cited in multiple false claims). Tool handlers should merge all
+ * matches into a single response.
+ */
+export declare function flaggedArtifactsForInput(query: FlaggedArtifactQuery): FlaggedArtifact[];
+/**
+ * Build the response-side enrichment for matched artifacts: a context note
+ * (joined if multiple match) plus prepended citations for each match.
+ *
+ * `baseRelatedDocs` is the tool's existing relatedDocsFor() output (or undefined).
+ * Returns `undefined` when no artifacts match — caller should noop in that case.
+ *
+ * Usage in a tool handler:
+ *   const enrichment = enrichWithFlaggedArtifacts(
+ *     { topoheight: args.topoheight },
+ *     relatedDocsFor('dero_get_block_header_by_topo_height'),
+ *   )
+ *   return { ...result, ...(enrichment ?? {}) }
+ */
+export declare function enrichWithFlaggedArtifacts(query: FlaggedArtifactQuery, baseRelatedDocs: DeroCitation[] | undefined): {
+    context_note: string;
+    related_docs: DeroCitation[];
+} | undefined;
+export {};
+//# sourceMappingURL=citations.d.ts.map

package/dist/citations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.d.ts","sourceRoot":"","sources":["../src/citations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEpE,MAAM,MAAM,YAAY,GAAG;IACzB,0FAA0F;IAC1F,MAAM,EAAE,WAAW,CAAA;IACnB,OAAO,EAAE,cAAc,CAAA;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;IACrB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAWD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,YAAY,CASd;AAED;;;;;;;;;;;;GAYG;AACH,KAAK,gBAAgB,GAAG;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CA8InE,CAAA;AAEV;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,GAAG,SAAS,CAI3E;AAsBD,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3C,MAAM,MAAM,eAAe,GAAG;IAC5B,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAA;IAC3C,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAA;IACzC;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,uBAAuB,EAAE,SAAS,eAAe,EAqCpD,CAAA;AAEV;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAOD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,oBAAoB,GAC1B,eAAe,EAAE,CAyBnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,oBAAoB,EAC3B,eAAe,EAAE,YAAY,EAAE,GAAG,SAAS,GAC1C;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,YAAY,EAAE,CAAA;CAAE,GAAG,SAAS,CA2BpE"}