@helm-protocol/ttt-mcp 0.1.9 → 0.2.2

package/LICENSE

@@ -1,21 +1,22 @@
-MIT License
+Business Source License 1.1
 
-Copyright (c) 2026 Helm Protocol Foundation
+Parameters
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Licensor: Heime-Jorgen (Peter Jang)
+Licensed Work: @helm-protocol/ttt-mcp
+Change Date: 2029-05-28
+Change License: Apache License, Version 2.0
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+Additional Use Grant:
+The following uses are permitted without a commercial license:
+- Non-commercial use (research, education, personal projects)
+- Commercial use generating less than $10,000 USD/year in revenue
+- Individual MEV bots or arbitrage bots operated for personal account
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+For all other commercial use, a license is required. See:
+https://kenosian.com/pricing
+
+---
+
+Business Source License 1.1 terms apply. The full text is available at:
+https://mariadb.com/bsl11/

package/README.md

@@ -144,6 +144,151 @@ Config file locations:
 - Node.js >= 18
 - Network access for time synthesis (HTTPS to time.nist.gov, time.google.com, time.cloudflare.com)
 
+---
+
+## Use Cases
+
+### 1. MEV Bot — Transaction Ordering Proof
+
+**Problem**: You got front-run. You know it happened. You can't prove it — mempool timestamps are per-node, unsigned, and non-authoritative. No evidence, no recourse.
+
+**Solution**: Call `pot_generate` before submitting every transaction. The PoT receipt is cryptographically signed by three independent time sources (NIST, Google, Cloudflare), hashed on-chain to Base Sepolia TTT ERC-1155. If front-running occurs, you have a timestamped, on-chain-anchored record of your original submission that predates the attacker's block inclusion.
+
+```typescript
+// Before tx submission
+const pot = await client.callTool({ name: "pot_generate", arguments: { txHash: pendingTxHash, chainId: 8453 } });
+// Store pot.potHash alongside your trade log
+// If front-run: pot.potHash is your evidence, timestamped by NIST+Google+Cloudflare
+```
+
+**V2 path**: When builder staking goes live, `S(V) ≥ V − c₀` makes reordering economically irrational for any V. Not just evidence — prevention.
+
+---
+
+### 2. DEX Protocol — AdaptiveSwitch Sandwich Deterrence
+
+**Problem**: Small-to-mid value sandwich attacks (V < ~$87) are constant background noise on any AMM. Each one is individually too small to litigate, collectively significant. No governance mechanism moves fast enough to respond.
+
+**Solution**: Integrate `TTTHookSimple` (Uniswap V4 hook, Base Sepolia: `0x8C633b05b833a476925F7d9818da6E215760F2c7`). Honest builders who preserve PoT-verified ordering get `turbo` mode (~50ms path). Builders who tamper are flagged to `full` mode (~127ms + exponential backoff up to 320 blocks). The 77ms throughput differential makes reordering cost exceed opportunity value for the V* range. No vote. No committee. Economics.
+
+```typescript
+// Query current switch state for a pool
+const status = await client.callTool({ name: "pot_stats", arguments: { poolAddress: "0x..." } });
+// status.adaptiveMode: "turbo" | "full"
+// status.currentV_star: estimated MEV threshold being deterred
+```
+
+**Outcome**: ~80% reduction in sub-threshold sandwich attacks. Provable per-block audit trail.
+
+---
+
+### 3. Hedge Fund / Prop Desk — MiFIR Art.22c Compliance
+
+**Problem**: MiFIR Article 22c / RTS 25 requires microsecond-precision UTC-synchronized timestamps for every trade on regulated venues. The standard hardware solution (PTP/IEEE 1588 appliances) costs $50K–$500K and requires dedicated ops. Most DeFi-adjacent funds run manual reconciliation between two separate timestamp systems.
+
+**Solution**: `pot_generate` produces an Ed25519-signed timestamp with uncertainty bound, confidence score, and multi-source attestation. The output is structurally compatible with RTS 25 audit record requirements. No hardware appliance. No dedicated ops. One API call per trade.
+
+```typescript
+const audit = await client.callTool({
+  name: "pot_generate",
+  arguments: { txHash: tradeHash, chainId: 8453, metadata: { desk: "MACRO-1", trader: "algo-07" } }
+});
+// audit.timestamp: nanosecond precision
+// audit.uncertainty: +/- ms bound (required field in RTS 25 record)
+// audit.confidence: fraction of sources that agreed
+// audit.ed25519_sig: non-repudiation signature
+// Export to your compliance system — same format, every trade
+```
+
+**Outcome**: MiFIR-grade audit trail at ~$0.04/1K calls (DEX tier). Replaces $50K+ hardware setup. IETF standardized via `draft-helmprotocol-tttps-00`.
+
+---
+
+### 4. Liquidity Provider — Position Timeline for Dispute Resolution
+
+**Problem**: LP enters and exits positions based on market conditions. When impermanent loss occurs due to a suspected protocol exploit or ordering manipulation, proving the sequence of events (position entry → exploit event → position exit) requires timestamped evidence that the current stack doesn't provide.
+
+**Solution**: Stamp every LP action (add liquidity, remove liquidity, fee harvest) with a PoT receipt. The receipt chain creates an unforgeable causal timeline: each action's potHash references the previous, anchored on Base Sepolia. Legally defensible for tax documentation, insurance claims, and protocol dispute resolution.
+
+```typescript
+// On liquidity add
+const entryPot = await client.callTool({ name: "pot_generate", arguments: { txHash: addLiqTx, chainId: 8453 } });
+
+// On liquidity remove
+const exitPot = await client.callTool({ name: "pot_generate", arguments: { txHash: removeLiqTx, chainId: 8453 } });
+
+// Verify the causal chain
+const chain = await client.callTool({ name: "pot_verify", arguments: { potHash: exitPot.potHash, precedingHash: entryPot.potHash } });
+// chain.valid: true means exit cryptographically followed entry
+```
+
+---
+
+### 5. AI Agent Coordination — Multi-Agent Causal Ordering
+
+**Problem**: When multiple AI agents interact in a pipeline (Agent A signals → Agent B acts → Agent C settles), the causal order matters for debugging, auditing, and liability. Agent logs are unverifiable—any agent can claim any timestamp.
+
+**Solution**: Each agent calls `pot_generate` before acting. The resulting potHash chain is independently verifiable: "Agent A's signal at T₁ preceded Agent B's action at T₂" can be proven without trusting either agent's self-reported logs. The on-chain anchor makes the ordering dispute-proof.
+
+```typescript
+// Agent A (signal generator)
+const signalPot = await client.callTool({ name: "pot_generate", arguments: { txHash: signalId } });
+
+// Agent B (executor) — references Agent A's pot
+const execPot = await client.callTool({
+  name: "pot_generate",
+  arguments: { txHash: execId, precedingPotHash: signalPot.potHash }
+});
+
+// Any third party can verify the causal chain
+const verified = await client.callTool({ name: "pot_verify", arguments: { potHash: execPot.potHash, precedingHash: signalPot.potHash } });
+```
+
+**Outcome**: Unforgeable causal chain across autonomous agents. Useful for multi-agent DeFi strategies, audit compliance, and cross-agent dispute resolution.
+
+---
+
+## TypeScript: MEV Bot Integration
+
+```typescript
+import { McpClient } from "@modelcontextprotocol/sdk/client/mcp.js";
+
+// Generate a Proof of Time for a transaction
+const result = await client.callTool({
+  name: "pot_generate",
+  arguments: {
+    txHash: "0xabc123...",
+    chainId: 8453,
+    poolAddress: "0xdef456..."
+  }
+});
+// Returns: { potHash, timestamp, stratum, grg_shards }
+```
+
+## Python: Hedge Fund Audit
+
+```python
+import subprocess, json
+
+result = subprocess.run(
+    ["npx", "-y", "@helm-protocol/ttt-mcp"],
+    input=json.dumps({
+        "tool": "pot_verify",
+        "potHash": "0x...",
+        "expectedChainId": 8453
+    }),
+    capture_output=True, text=True
+)
+```
+
+## Rate Limits & Pricing
+
+```
+Free Tier:   100 calls/day per IP — no API key needed
+Paid Tier:   Set TTT_API_KEY env var — unlimited
+Commercial:  peter@kenosian.com (hedge funds, DEX protocols, OTC desks)
+```
+
 ## Learn More
 
 - [OpenTTT SDK](https://www.npmjs.com/package/openttt) — The underlying SDK
@@ -152,4 +297,9 @@ Config file locations:
 
 ## License
 
-MIT
+BSL-1.1 — free for non-commercial use.
+
+**Commercial use** (production bots, hedge funds, prop desks) requires a license.  
+→ [kenosian.com/pricing](https://kenosian.com/pricing)
+
+Change Date: 2029-05-28 → Apache 2.0

package/dist/auth.js

@@ -28,230 +28,77 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var auth_exports = {};
 __export(auth_exports, {
-  AUTH_ERROR_MESSAGE: () => AUTH_ERROR_MESSAGE,
-  verifyHelmApiKey: () => verifyHelmApiKey
+  FREE_TIER_LIMIT: () => FREE_TIER_LIMIT,
+  checkRateLimit: () => checkRateLimit,
+  resolveApiKey: () => resolveApiKey
 });
 module.exports = __toCommonJS(auth_exports);
-var import_crypto = require("crypto");
-var https = __toESM(require("https"));
-var import_crypto2 = require("crypto");
-const HELM_PUBLIC_KEY_B64 = process.env.HELM_PUBLIC_KEY ?? "PLACEHOLDER_REPLACE_BEFORE_DEPLOY";
-const HELM_AUTH_SERVER_URL = process.env.HELM_AUTH_SERVER_URL;
-if (HELM_AUTH_SERVER_URL !== void 0) {
-  if (!HELM_AUTH_SERVER_URL.startsWith("https://")) {
-    throw new Error(
-      "[ttt-mcp] HELM_AUTH_SERVER_URL must use HTTPS (got: " + HELM_AUTH_SERVER_URL + "). Refusing to start to protect API keys in transit."
-    );
-  }
-}
-const CLIENT_VERSION = "0.2.0";
-const authCache = /* @__PURE__ */ new Map();
-function getCached(apiKey, toolName) {
-  const key = `${apiKey}:${toolName}`;
-  const entry = authCache.get(key);
-  if (!entry) return null;
-  if (Date.now() > entry.expiresAt) {
-    authCache.delete(key);
-    return null;
-  }
-  return entry;
-}
-function setCached(apiKey, toolName, allowed, planTier, cacheTtlMs) {
-  const key = `${apiKey}:${toolName}`;
-  authCache.set(key, {
-    allowed,
-    planTier,
-    expiresAt: Date.now() + cacheTtlMs
-  });
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var os = __toESM(require("os"));
+const FREE_TIER_LIMIT = parseInt(process.env.FREE_TIER_LIMIT ?? "100", 10);
+const USAGE_DIR = path.join(os.homedir(), ".ttt-mcp");
+const USAGE_FILE = path.join(USAGE_DIR, "usage.json");
+const buckets = /* @__PURE__ */ new Map();
+function nextMidnightUtc() {
+  const now = /* @__PURE__ */ new Date();
+  const midnight = new Date(
+    Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1)
+  );
+  return midnight.getTime();
 }
-const CIRCUIT_FAILURE_THRESHOLD = 3;
-const CIRCUIT_OPEN_DURATION_MS = 5 * 60 * 1e3;
-const circuit = {
-  state: "CLOSED",
-  consecutiveFailures: 0,
-  openedAt: 0
-};
-function circuitRecordSuccess() {
-  circuit.consecutiveFailures = 0;
-  circuit.state = "CLOSED";
-}
-function circuitRecordFailure() {
-  circuit.consecutiveFailures += 1;
-  if (circuit.consecutiveFailures >= CIRCUIT_FAILURE_THRESHOLD) {
-    circuit.state = "OPEN";
-    circuit.openedAt = Date.now();
-  }
-}
-function circuitCanAttempt() {
-  if (circuit.state === "CLOSED") return true;
-  if (circuit.state === "OPEN") {
-    if (Date.now() - circuit.openedAt >= CIRCUIT_OPEN_DURATION_MS) {
-      circuit.state = "HALF_OPEN";
-      return true;
+function readUsageFile() {
+  try {
+    if (!fs.existsSync(USAGE_DIR)) fs.mkdirSync(USAGE_DIR, { recursive: true });
+    if (fs.existsSync(USAGE_FILE)) {
+      return JSON.parse(fs.readFileSync(USAGE_FILE, "utf8"));
     }
-    return false;
+  } catch {
   }
-  return true;
+  return { count: 0, resetAt: nextMidnightUtc() };
 }
-function callAuthServer(serverUrl, apiKey, toolName) {
-  return new Promise((resolve, reject) => {
-    const requestId = (0, import_crypto2.randomUUID)();
-    const body = JSON.stringify({
-      api_key: apiKey,
-      tool_name: toolName,
-      request_id: requestId,
-      timestamp_ms: Date.now(),
-      client_version: CLIENT_VERSION
-    });
-    const url = new URL("/v1/auth/verify", serverUrl);
-    const options = {
-      hostname: url.hostname,
-      port: url.port || 443,
-      path: url.pathname,
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Content-Length": Buffer.byteLength(body),
-        "X-Request-ID": requestId
-      }
-    };
-    const req = https.request(options, (res) => {
-      let data = "";
-      res.on("data", (chunk) => {
-        data += chunk.toString();
-      });
-      res.on("end", () => {
-        try {
-          const parsed = JSON.parse(data);
-          resolve(parsed);
-        } catch {
-          reject(new Error("Auth server returned non-JSON response"));
-        }
-      });
-    });
-    req.setTimeout(3e3, () => {
-      req.destroy(new Error("Auth server request timed out (3000ms)"));
-    });
-    req.on("error", (err) => {
-      reject(err);
-    });
-    req.write(body);
-    req.end();
-  });
-}
-async function serverSideGate(apiKey, toolName) {
-  if (!HELM_AUTH_SERVER_URL) {
-    return null;
-  }
-  const cached = getCached(apiKey, toolName);
-  if (cached !== null) {
-    if (!cached.allowed) {
-      return `Access denied by Helm Auth Server (plan: ${cached.planTier}, cached)`;
-    }
-    return null;
-  }
-  if (!circuitCanAttempt()) {
-    return "Helm Auth Server is temporarily unreachable. Access denied (fail-closed). Please retry in a few minutes.";
-  }
+function writeUsageFile(entry) {
   try {
-    const resp = await callAuthServer(HELM_AUTH_SERVER_URL, apiKey, toolName);
-    const ttl = typeof resp.cache_ttl_ms === "number" && resp.cache_ttl_ms > 0 ? resp.cache_ttl_ms : 3e5;
-    setCached(apiKey, toolName, resp.allowed, resp.plan_tier ?? "unknown", ttl);
-    circuitRecordSuccess();
-    if (!resp.allowed) {
-      const reason = resp.reason ? ` Reason: ${resp.reason}` : "";
-      return `Access denied by Helm Auth Server (plan: ${resp.plan_tier}).${reason}`;
-    }
-    return null;
+    if (!fs.existsSync(USAGE_DIR)) fs.mkdirSync(USAGE_DIR, { recursive: true });
+    fs.writeFileSync(USAGE_FILE, JSON.stringify(entry), "utf8");
   } catch {
-    circuitRecordFailure();
-    return "Helm Auth Server is unreachable. Access denied (fail-closed). Please retry later.";
   }
 }
-async function verifyHelmApiKey(apiKey, opts) {
-  if (!apiKey) {
-    return { valid: false, error: "No API key provided" };
-  }
-  if (!apiKey.startsWith("hk-")) {
-    return { valid: false, error: "Invalid key format" };
+function checkRateLimit(apiKey, clientIp) {
+  if (apiKey && apiKey.trim().length > 0) {
+    return { allowed: true, remaining: -1, tier: "paid" };
   }
-  if (HELM_PUBLIC_KEY_B64 === "PLACEHOLDER_REPLACE_BEFORE_DEPLOY") {
-    if (process.env.HELM_DEV_MODE === "true") {
-      return { valid: true, tier: 0, orgId: "dev-mode" };
+  const now = Date.now();
+  if (clientIp === "stdio") {
+    let entry2 = readUsageFile();
+    if (now >= entry2.resetAt) {
+      entry2 = { count: 0, resetAt: nextMidnightUtc() };
     }
-    return { valid: false, error: "Server misconfiguration: HELM_PUBLIC_KEY not set" };
+    if (entry2.count >= FREE_TIER_LIMIT) {
+      return { allowed: false, remaining: 0, tier: "free" };
+    }
+    entry2.count += 1;
+    writeUsageFile(entry2);
+    return { allowed: true, remaining: FREE_TIER_LIMIT - entry2.count, tier: "free" };
   }
-  const jwt = apiKey.slice(3);
-  const parts = jwt.split(".");
-  if (parts.length !== 3) {
-    return { valid: false, error: "Malformed JWT" };
+  const bucketKey = `ip:${clientIp}`;
+  let entry = buckets.get(bucketKey);
+  if (!entry || now >= entry.resetAt) {
+    entry = { count: 0, resetAt: nextMidnightUtc() };
+    buckets.set(bucketKey, entry);
   }
-  try {
-    const payload = JSON.parse(
-      Buffer.from(parts[1], "base64url").toString("utf8")
-    );
-    if (typeof payload.exp !== "number" || payload.exp < Math.floor(Date.now() / 1e3)) {
-      return { valid: false, error: "Key expired" };
-    }
-    if (payload.iss !== "helm-protocol") {
-      return { valid: false, error: "Invalid issuer" };
-    }
-    const publicKey = (0, import_crypto.createPublicKey)({
-      key: Buffer.from(HELM_PUBLIC_KEY_B64, "base64"),
-      format: "der",
-      type: "spki"
-    });
-    const sigInput = Buffer.from(`${parts[0]}.${parts[1]}`);
-    const sig = Buffer.from(parts[2], "base64url");
-    const isValid = (0, import_crypto.verify)(null, sigInput, publicKey, sig);
-    if (!isValid) {
-      return { valid: false, error: "Invalid signature" };
-    }
-    if (opts?.redisClient && payload.type === "short" && payload.jti) {
-      const redisKey = `helm:jti:${payload.jti}`;
-      const ttl = Math.max(
-        1,
-        payload.exp - Math.floor(Date.now() / 1e3)
-      );
-      const isNew = await opts.redisClient.set(redisKey, "1", {
-        NX: true,
-        EX: ttl
-      });
-      if (isNew === null) {
-        opts.onReplayDetected?.(payload.jti);
-        return { valid: false, error: "Replay detected" };
-      }
-    }
-    if (opts?.toolName) {
-      const gateError = await serverSideGate(apiKey, opts.toolName);
-      if (gateError !== null) {
-        return { valid: false, error: gateError };
-      }
-    }
-    return {
-      valid: true,
-      tier: typeof payload.tier === "number" ? payload.tier : 0,
-      orgId: payload.sub
-    };
-  } catch {
-    return { valid: false, error: "Verification error" };
+  if (entry.count >= FREE_TIER_LIMIT) {
+    return { allowed: false, remaining: 0, tier: "free" };
   }
+  entry.count += 1;
+  return { allowed: true, remaining: FREE_TIER_LIMIT - entry.count, tier: "free" };
+}
+function resolveApiKey(headerValue) {
+  return headerValue?.trim() || process.env.TTT_API_KEY?.trim() || void 0;
 }
-const AUTH_ERROR_MESSAGE = `This tool requires a Helm Protocol API key.
-
-To get access:
-  1. Contact enterprise@helmprotocol.io
-  2. Add the key to your MCP config:
-     { "env": { "HELM_API_KEY": "hk-..." } }
-
-Optional server-side validation:
-  Set HELM_AUTH_SERVER_URL=https://auth.helm-protocol.com for additional
-  server-side gate (quota enforcement, revocation, plan tier checks).
-  HTTPS is required \u2014 HTTP URLs are rejected at startup.
-
-Free tools available without a key: pot_health, pot_stats`;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  AUTH_ERROR_MESSAGE,
-  verifyHelmApiKey
+  FREE_TIER_LIMIT,
+  checkRateLimit,
+  resolveApiKey
 });