@helm-protocol/ttt-mcp 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# @helm-protocol/ttt-mcp
+
+**MCP Server for OpenTTT — Proof of Time tools for AI agents**
+
+> AI Agent A and Agent B both trigger a payment at the same time.
+> Who was first?
+>
+> OpenTTT answers this with cryptographic Proof of Time — synthesized from
+> multiple independent time sources, verified through GRG integrity shards,
+> and signed with Ed25519 for non-repudiation.
+
+## Quick Start
+
+```bash
+npm install @helm-protocol/ttt-mcp
+```
+
+```json
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "ttt": {
+      "command": "npx",
+      "args": ["@helm-protocol/ttt-mcp"]
+    }
+  }
+}
+```
+
+That's it. Your AI agent now has access to 5 Proof of Time tools.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `pot_generate` | Generate a Proof of Time for a transaction |
+| `pot_verify` | Verify a Proof of Time using its hash and GRG shards |
+| `pot_query` | Query PoT history from local log and on-chain subgraph |
+| `pot_stats` | Get turbo/full mode statistics for a time period |
+| `pot_health` | Check system health: time sources, subgraph sync, uptime |
+
+## Example: Generate and Verify a PoT
+
+```typescript
+// In your AI agent's tool call:
+const pot = await pot_generate({
+  txHash: "0xabc123...",
+  chainId: 84532,
+  poolAddress: "0xdef456..."
+});
+
+// pot.potHash — unique Proof of Time hash
+// pot.grgShards — GRG integrity shards for verification
+// pot.timestamp — synthesized nanosecond timestamp
+// pot.mode — "turbo" (honest) or "full" (requires full verification)
+
+const verification = await pot_verify({
+  potHash: pot.potHash,
+  grgShards: pot.grgShards
+});
+// verification.valid — true if integrity shards reconstruct correctly
+```
+
+## How It Works
+
+1. **Time Synthesis** — Queries multiple independent time sources (NIST, Google, Cloudflare) via HTTPS/NTP and synthesizes a median timestamp with uncertainty bounds
+2. **GRG Pipeline** — Encodes transaction data through a Golomb-Rice + Reed-Solomon + Golay(24,12) integrity pipeline, producing verifiable shards
+3. **Ed25519 Signing** — Signs the PoT hash for non-repudiation
+4. **Adaptive Mode** — Honest builders get `turbo` mode (fast, profitable); tampered sequences get `full` mode (slow, costly) — natural economic selection
+
+## Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ttt": {
+      "command": "npx",
+      "args": ["@helm-protocol/ttt-mcp"]
+    }
+  }
+}
+```
+
+Config file locations:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+## Requirements
+
+- Node.js >= 18
+- Network access for time synthesis (HTTPS to time.nist.gov, time.google.com, time.cloudflare.com)
+
+## Learn More
+
+- [OpenTTT SDK](https://www.npmjs.com/package/openttt) — The underlying SDK
+- [IETF Draft: draft-helmprotocol-tttps-00](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) — TTTPS Protocol Specification
+- [Helm Protocol](https://github.com/Helm-Protocol) — GitHub
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+"use strict";
+// @helm-protocol/ttt-mcp — MCP Server for OpenTTT Proof of Time
+// Provides 5 tools for AI agents: pot_generate, pot_verify, pot_query, pot_stats, pot_health
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const tools_1 = require("./tools");
+const server = new mcp_js_1.McpServer({
+    name: "ttt-mcp",
+    version: "0.1.0",
+});
+// ---------- Tool 1: pot_generate ----------
+server.tool("pot_generate", "Generate a Proof of Time for a transaction. Returns potHash, timestamp, stratum, and GRG integrity shards.", {
+    txHash: zod_1.z.string().describe("Transaction hash (hex with 0x prefix)"),
+    chainId: zod_1.z.number().describe("Chain ID (e.g. 8453 for Base, 84532 for Base Sepolia)"),
+    poolAddress: zod_1.z.string().describe("DEX pool contract address"),
+}, async (args) => {
+    try {
+        const result = await (0, tools_1.potGenerate)(args);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ---------- Tool 2: pot_verify ----------
+server.tool("pot_verify", "Verify a Proof of Time using its hash and GRG shards. Returns validity, mode (turbo/full), and timestamp.", {
+    potHash: zod_1.z.string().describe("PoT hash to verify (hex with 0x prefix)"),
+    grgShards: zod_1.z.array(zod_1.z.string()).describe("Array of hex-encoded GRG integrity shards"),
+}, async (args) => {
+    try {
+        const result = await (0, tools_1.potVerify)(args);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ---------- Tool 3: pot_query ----------
+server.tool("pot_query", "Query Proof of Time history from local log and on-chain subgraph.", {
+    startTime: zod_1.z.number().optional().describe("Start time (unix ms). Default: 24h ago"),
+    endTime: zod_1.z.number().optional().describe("End time (unix ms). Default: now"),
+    limit: zod_1.z.number().optional().describe("Max entries to return. Default: 100, max: 1000"),
+}, async (args) => {
+    try {
+        const result = await (0, tools_1.potQuery)(args);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ---------- Tool 4: pot_stats ----------
+server.tool("pot_stats", "Get PoT statistics: total swaps, turbo/full counts, and turbo ratio for a given period.", {
+    period: zod_1.z.enum(["day", "week", "month"]).describe("Time period for statistics"),
+}, async (args) => {
+    try {
+        const result = await (0, tools_1.potStats)(args);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ---------- Tool 5: pot_health ----------
+server.tool("pot_health", "Check PoT system health: time source status, subgraph sync, server uptime, and current mode.", {}, async () => {
+    try {
+        const result = await (0, tools_1.potHealth)();
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ---------- Start Server ----------
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("[ttt-mcp] OpenTTT MCP Server running on stdio");
+}
+main().catch((err) => {
+    console.error("[ttt-mcp] Fatal:", err);
+    process.exit(1);
+});

package/dist/telemetry.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Increment an anonymous tool-call counter.
+ * Posts to subgraph endpoint as a best-effort ping. Never throws.
+ */
+export declare function telemetryIncrement(toolName: string): void;
+/** Get current session counters (for debugging) */
+export declare function getTelemetryCounts(): Record<string, number>;

package/dist/telemetry.js

@@ -0,0 +1,45 @@
+"use strict";
+// @helm-protocol/ttt-mcp — Anonymous telemetry counter
+// Increments a simple counter on each tool call. Fire-and-forget, never blocks.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.telemetryIncrement = telemetryIncrement;
+exports.getTelemetryCounts = getTelemetryCounts;
+const counters = {};
+const TELEMETRY_ENDPOINT = "https://api.studio.thegraph.com/query/1744392/openttt-base-sepolia/v0.1.0";
+/**
+ * Increment an anonymous tool-call counter.
+ * Posts to subgraph endpoint as a best-effort ping. Never throws.
+ */
+function telemetryIncrement(toolName) {
+    counters[toolName] = (counters[toolName] ?? 0) + 1;
+    // Fire-and-forget POST — no await, no error propagation
+    try {
+        const body = JSON.stringify({
+            query: `{ _meta { block { number } } }`,
+            extensions: {
+                telemetry: {
+                    tool: toolName,
+                    count: counters[toolName],
+                    ts: Date.now(),
+                    pkg: "@helm-protocol/ttt-mcp",
+                    v: "0.1.0",
+                },
+            },
+        });
+        fetch(TELEMETRY_ENDPOINT, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+            signal: AbortSignal.timeout(3000),
+        }).catch(() => {
+            // silently ignore — telemetry is best-effort
+        });
+    }
+    catch {
+        // never block the tool call
+    }
+}
+/** Get current session counters (for debugging) */
+function getTelemetryCounts() {
+    return { ...counters };
+}

package/dist/tools.d.ts

@@ -0,0 +1,18 @@
+export declare function potGenerate(args: {
+    txHash: string;
+    chainId: number;
+    poolAddress: string;
+}): Promise<unknown>;
+export declare function potVerify(args: {
+    potHash: string;
+    grgShards: string[];
+}): Promise<unknown>;
+export declare function potQuery(args: {
+    startTime?: number;
+    endTime?: number;
+    limit?: number;
+}): Promise<unknown>;
+export declare function potStats(args: {
+    period: "day" | "week" | "month";
+}): Promise<unknown>;
+export declare function potHealth(): Promise<unknown>;

package/dist/tools.js

@@ -0,0 +1,225 @@
+"use strict";
+// @helm-protocol/ttt-mcp — Tool implementations for Proof of Time MCP Server
+// Uses OpenTTT SDK: TimeSynthesis, GrgPipeline, PotSigner, AdaptiveSwitch
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.potGenerate = potGenerate;
+exports.potVerify = potVerify;
+exports.potQuery = potQuery;
+exports.potStats = potStats;
+exports.potHealth = potHealth;
+const openttt_1 = require("openttt");
+const telemetry_1 = require("./telemetry");
+// ---------- Shared Instances ----------
+const timeSynth = new openttt_1.TimeSynthesis();
+const adaptiveSwitch = new openttt_1.AdaptiveSwitch();
+const potSigner = new openttt_1.PotSigner(); // ephemeral Ed25519 keypair per server session
+const startedAt = Date.now();
+// In-memory PoT anchor log (bounded ring buffer)
+const POT_LOG_MAX = 10000;
+const potLog = [];
+// ---------- Helpers ----------
+function bigintReplacer(_key, value) {
+    return typeof value === "bigint" ? value.toString() : value;
+}
+function serialize(obj) {
+    return JSON.parse(JSON.stringify(obj, bigintReplacer));
+}
+const SUBGRAPH_URL = "https://api.studio.thegraph.com/query/1744392/openttt-base-sepolia/v0.1.0";
+// ---------- Tool: pot_generate ----------
+async function potGenerate(args) {
+    (0, telemetry_1.telemetryIncrement)("pot_generate");
+    // 1. Synthesize time from multiple NTP/HTTPS sources
+    const pot = await timeSynth.generateProofOfTime();
+    const potHash = openttt_1.TimeSynthesis.getOnChainHash(pot);
+    // 2. GRG pipeline — encode tx data into integrity shards (black box)
+    const txData = new TextEncoder().encode(args.txHash);
+    const grgShards = openttt_1.GrgPipeline.processForward(txData);
+    // 3. Ed25519 sign the PoT hash for non-repudiation
+    const signature = potSigner.signPot(potHash);
+    // 4. Log the anchor
+    const entry = {
+        potHash,
+        timestamp: pot.timestamp.toString(),
+        stratum: pot.stratum,
+        mode: adaptiveSwitch.getCurrentMode(),
+        chainId: args.chainId,
+        poolAddress: args.poolAddress,
+        createdAt: Date.now(),
+    };
+    potLog.push(entry);
+    if (potLog.length > POT_LOG_MAX)
+        potLog.shift();
+    return serialize({
+        potHash,
+        timestamp: pot.timestamp.toString(),
+        stratum: pot.stratum,
+        uncertainty: pot.uncertainty,
+        confidence: pot.confidence,
+        sources: pot.sources,
+        nonce: pot.nonce,
+        expiresAt: pot.expiresAt.toString(),
+        grgShards: grgShards.map((s) => Buffer.from(s).toString("hex")),
+        signature: {
+            issuerPubKey: signature.issuerPubKey,
+            signature: signature.signature,
+            issuedAt: signature.issuedAt.toString(),
+        },
+    });
+}
+// ---------- Tool: pot_verify ----------
+async function potVerify(args) {
+    (0, telemetry_1.telemetryIncrement)("pot_verify");
+    const shards = args.grgShards.map((hex) => new Uint8Array(Buffer.from(hex, "hex")));
+    let valid = false;
+    let reconstructedSize = 0;
+    try {
+        const recovered = openttt_1.GrgPipeline.processInverse(shards, 0);
+        valid = recovered.length > 0;
+        reconstructedSize = recovered.length;
+    }
+    catch {
+        valid = false;
+    }
+    const mode = adaptiveSwitch.getCurrentMode() === openttt_1.AdaptiveMode.TURBO ? "turbo" : "full";
+    return serialize({
+        valid,
+        mode,
+        potHash: args.potHash,
+        reconstructedBytes: reconstructedSize,
+        verifiedAt: Date.now(),
+    });
+}
+// ---------- Tool: pot_query ----------
+async function potQuery(args) {
+    (0, telemetry_1.telemetryIncrement)("pot_query");
+    const limit = Math.min(args.limit ?? 100, 1000);
+    const now = Date.now();
+    const startTime = args.startTime ?? now - 86400_000;
+    const endTime = args.endTime ?? now;
+    // Filter from in-memory log
+    const filtered = potLog
+        .filter((e) => e.createdAt >= startTime && e.createdAt <= endTime)
+        .slice(-limit);
+    // Best-effort subgraph query
+    let subgraphEntries = [];
+    try {
+        const query = `{
+      potAnchors(
+        first: ${limit},
+        orderBy: blockTimestamp,
+        orderDirection: desc,
+        where: { blockTimestamp_gte: "${Math.floor(startTime / 1000)}", blockTimestamp_lte: "${Math.floor(endTime / 1000)}" }
+      ) {
+        id
+        potHash
+        blockTimestamp
+        txHash
+      }
+    }`;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const resp = await fetch(SUBGRAPH_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ query }),
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (resp.ok) {
+            const json = (await resp.json());
+            subgraphEntries = json.data?.potAnchors ?? [];
+        }
+    }
+    catch {
+        // Subgraph unavailable — local log still returned
+    }
+    return serialize({
+        local: filtered,
+        subgraph: subgraphEntries,
+        totalLocal: potLog.length,
+        query: { startTime, endTime, limit },
+    });
+}
+// ---------- Tool: pot_stats ----------
+async function potStats(args) {
+    (0, telemetry_1.telemetryIncrement)("pot_stats");
+    const now = Date.now();
+    const periodMs = {
+        day: 86400_000,
+        week: 604800_000,
+        month: 2592000_000,
+    };
+    const cutoff = now - (periodMs[args.period] ?? periodMs.day);
+    const entries = potLog.filter((e) => e.createdAt >= cutoff);
+    const turboCount = entries.filter((e) => e.mode === openttt_1.AdaptiveMode.TURBO).length;
+    const fullCount = entries.filter((e) => e.mode === openttt_1.AdaptiveMode.FULL).length;
+    const totalSwaps = entries.length;
+    return serialize({
+        period: args.period,
+        totalSwaps,
+        turboCount,
+        fullCount,
+        turboRatio: totalSwaps > 0 ? +(turboCount / totalSwaps).toFixed(4) : 0,
+        currentMode: adaptiveSwitch.getCurrentMode(),
+        windowStart: new Date(cutoff).toISOString(),
+        windowEnd: new Date(now).toISOString(),
+    });
+}
+// ---------- Tool: pot_health ----------
+async function potHealth() {
+    (0, telemetry_1.telemetryIncrement)("pot_health");
+    let timeStatus = "unknown";
+    let synthSources = 0;
+    try {
+        const synth = await Promise.race([
+            timeSynth.synthesize(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 5000)),
+        ]);
+        if (synth && synth.sources >= 2) {
+            timeStatus = "healthy";
+            synthSources = synth.sources;
+        }
+        else {
+            timeStatus = "degraded";
+            synthSources = synth?.sources ?? 0;
+        }
+    }
+    catch {
+        timeStatus = "unhealthy";
+    }
+    let latestBlock = 0;
+    let syncStatus = "unknown";
+    try {
+        const query = `{ _meta { block { number } hasIndexingErrors } }`;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const resp = await fetch(SUBGRAPH_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ query }),
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (resp.ok) {
+            const json = (await resp.json());
+            latestBlock = json.data?._meta?.block?.number ?? 0;
+            syncStatus = json.data?._meta?.hasIndexingErrors ? "indexing_errors" : "synced";
+        }
+    }
+    catch {
+        syncStatus = "unreachable";
+    }
+    const uptimeMs = Date.now() - startedAt;
+    return serialize({
+        status: timeStatus === "healthy" ? "ok" : timeStatus,
+        timeSources: { status: timeStatus, activeSources: synthSources },
+        subgraph: { latestBlock, syncStatus },
+        server: {
+            uptime: uptimeMs,
+            uptimeHuman: `${(uptimeMs / 3600000).toFixed(1)}h`,
+            potCount: potLog.length,
+            currentMode: adaptiveSwitch.getCurrentMode(),
+            signerPubKey: potSigner.getPubKeyHex(),
+        },
+    });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@helm-protocol/ttt-mcp",
+  "version": "0.1.0",
+  "description": "MCP Server for OpenTTT — Proof of Time tools for AI agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "ttt-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "npx ts-node index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "openttt",
+    "proof-of-time",
+    "ai-agent",
+    "defi",
+    "mev",
+    "transaction-ordering"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Helm-Protocol/OpenTTT"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "openttt": "^0.1.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@types/node": "^20.11.19"
+  }
+}