@parad0x_labs/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# @parad0x_labs/mcp-server
+
+Exposes the Parad0x Labs stack as MCP tools. Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible agent runtime.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `x402_get_quote` | Get a payment quote for an x402-gated API endpoint |
+| `anchor_receipt` | Anchor a 32-byte receipt hash on Solana mainnet via `receipt_anchor` |
+| `lookup_passport` | Check if an ETH address or Solana wallet has a verified Dark Passport binding |
+| `build_outcome_receipt` | Build a signed outcome receipt with PnL, accuracy, or delivery result |
+| `compress_receipts` | Compress a batch of receipts (Liquefy format, 83x typical ratio) |
+| `get_stack_status` | Discover all live Parad0x Labs mainnet program addresses |
+
+## Install
+
+```bash
+npm install -g @parad0x_labs/mcp-server
+```
+
+Or use directly via `npx` without installing.
+
+## Claude Desktop config
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "parad0x": {
+      "command": "npx",
+      "args": ["-y", "@parad0x_labs/mcp-server"],
+      "env": {
+        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",
+        "SOLANA_KEYPAIR": "[1,2,3,...]"
+      }
+    }
+  }
+}
+```
+
+`SOLANA_KEYPAIR` is a JSON array of 64 bytes (the standard Solana keypair format output by `solana-keygen`). Without it, `anchor_receipt` runs in dry-run mode and returns a mock transaction for format inspection.
+
+## Cursor / Windsurf config
+
+Add to `.cursor/mcp.json` or `.windsurf/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "parad0x": {
+      "command": "npx",
+      "args": ["-y", "@parad0x_labs/mcp-server"],
+      "env": {
+        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com"
+      }
+    }
+  }
+}
+```
+
+## Build from source
+
+```bash
+cd packages/mcp-server
+npm install
+npm run build
+npm start
+```
+
+## Env vars
+
+| Variable | Default | Description |
+|---|---|---|
+| `SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint |
+| `SOLANA_KEYPAIR` | _(unset)_ | JSON array of 64 bytes — enables real transaction submission |
+
+## Programs (mainnet)
+
+| Program | Address |
+|---|---|
+| receipt_anchor | `6HSRGivdYR5D7yTDy1TFMCM8h3LzXxRtKU1RA3RnCMRN` |
+| dark_secp256r1_vault | `3hbbtjeSrTVYXq6eRwjeofDe2DCPh3n8cfN6kZcQfewi` |
+| dark_secp256k1_auth | `AqwBbV13AoczhoELwP8oxT3nDqB6MsLWXauNzHkssZ9B` |
+| dark_bn254_gate | `GCptvBYF8S6eVYoh15B7WAESc54FUHCpN1Ui6aHeQYZd` |
+| dark_semaphore | `Ev7HEFhhKTXk6kS2Y6ssbUcK9C7E6yZ589jJNjUrQV5p` |
+| null_token | `8EeDdvCRmFAzVD4takkBrNNwkeUTUQh4MscRK5Fzpump` |

package/dist/anchor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * receipt_anchor instruction encoder (host-free, byte-exact, unit-tested).
+ *
+ * Built from the verified on-chain ABI of receipt_anchor (6HSRGivd…):
+ *   data = [0x01 version][flags][32-byte hash]( [u64 LE bucket_id] )
+ *   - 34-byte form: flags=0x00, program derives the bucket from its Clock hour
+ *   - 42-byte form: flags=0x01, client pins bucket_id (this is what we use)
+ *   keys = [payer(signer,writable), bucket PDA(writable), system_program]
+ *   bucket PDA seeds = ["bucket", u64 LE bucket_id], bucket_id = floor(unix/3600)
+ *
+ * We use the 42-byte pinned-bucket form so the bucket PDA the client derives
+ * always matches the one the program writes (the 34-byte form would let the
+ * validator's Clock hour drift from the client's near an hour boundary).
+ */
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+export declare const RECEIPT_ANCHOR_VERSION = 1;
+export declare const FLAG_HAS_BUCKET_ID = 1;
+/** The program's hourly bucket id: floor(unix_seconds / 3600); 0 for non-positive. */
+export declare function bucketIdForUnix(unixSeconds: number): bigint;
+/** Derive the AnchorBucket PDA for a bucket id: ["bucket", u64 LE bucket_id]. */
+export declare function deriveBucketPda(bucketId: bigint, programId: string): PublicKey;
+/** Build the single-anchor instruction (42-byte pinned-bucket form). */
+export declare function buildAnchorIx(opts: {
+    payer: string;
+    receiptHashHex: string;
+    programId: string;
+    bucketId: bigint;
+}): TransactionInstruction;
+//# sourceMappingURL=anchor.d.ts.map

package/dist/anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../src/anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAiB,MAAM,iBAAiB,CAAC;AAEnF,eAAO,MAAM,sBAAsB,IAAO,CAAC;AAC3C,eAAO,MAAM,kBAAkB,IAAO,CAAC;AAIvC,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D;AAQD,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CAM9E;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,sBAAsB,CAkBzB"}

package/dist/anchor.js

@@ -0,0 +1,54 @@
+/**
+ * receipt_anchor instruction encoder (host-free, byte-exact, unit-tested).
+ *
+ * Built from the verified on-chain ABI of receipt_anchor (6HSRGivd…):
+ *   data = [0x01 version][flags][32-byte hash]( [u64 LE bucket_id] )
+ *   - 34-byte form: flags=0x00, program derives the bucket from its Clock hour
+ *   - 42-byte form: flags=0x01, client pins bucket_id (this is what we use)
+ *   keys = [payer(signer,writable), bucket PDA(writable), system_program]
+ *   bucket PDA seeds = ["bucket", u64 LE bucket_id], bucket_id = floor(unix/3600)
+ *
+ * We use the 42-byte pinned-bucket form so the bucket PDA the client derives
+ * always matches the one the program writes (the 34-byte form would let the
+ * validator's Clock hour drift from the client's near an hour boundary).
+ */
+import { PublicKey, TransactionInstruction, SystemProgram } from "@solana/web3.js";
+export const RECEIPT_ANCHOR_VERSION = 0x01;
+export const FLAG_HAS_BUCKET_ID = 0x01;
+const BUCKET_SEED_PREFIX = "bucket";
+const BUCKET_WINDOW_SECONDS = 3600;
+/** The program's hourly bucket id: floor(unix_seconds / 3600); 0 for non-positive. */
+export function bucketIdForUnix(unixSeconds) {
+    return unixSeconds <= 0 ? 0n : BigInt(Math.floor(unixSeconds / BUCKET_WINDOW_SECONDS));
+}
+function u64le(n) {
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64LE(n);
+    return b;
+}
+/** Derive the AnchorBucket PDA for a bucket id: ["bucket", u64 LE bucket_id]. */
+export function deriveBucketPda(bucketId, programId) {
+    const [pda] = PublicKey.findProgramAddressSync([Buffer.from(BUCKET_SEED_PREFIX), u64le(bucketId)], new PublicKey(programId));
+    return pda;
+}
+/** Build the single-anchor instruction (42-byte pinned-bucket form). */
+export function buildAnchorIx(opts) {
+    if (!/^[0-9a-fA-F]{64}$/.test(opts.receiptHashHex)) {
+        throw new Error("receipt_hash_hex must be exactly 64 hex characters (32 bytes).");
+    }
+    const data = Buffer.concat([
+        Buffer.from([RECEIPT_ANCHOR_VERSION, FLAG_HAS_BUCKET_ID]),
+        Buffer.from(opts.receiptHashHex, "hex"),
+        u64le(opts.bucketId),
+    ]);
+    return new TransactionInstruction({
+        programId: new PublicKey(opts.programId),
+        keys: [
+            { pubkey: new PublicKey(opts.payer), isSigner: true, isWritable: true },
+            { pubkey: deriveBucketPda(opts.bucketId, opts.programId), isSigner: false, isWritable: true },
+            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+        ],
+        data,
+    });
+}
+//# sourceMappingURL=anchor.js.map

package/dist/anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.js","sourceRoot":"","sources":["../src/anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEnF,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAC3C,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AACvC,MAAM,kBAAkB,GAAG,QAAQ,CAAC;AACpC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAEnC,sFAAsF;AACtF,MAAM,UAAU,eAAe,CAAC,WAAmB;IACjD,OAAO,WAAW,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,qBAAqB,CAAC,CAAC,CAAC;AACzF,CAAC;AAED,SAAS,KAAK,CAAC,CAAS;IACtB,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACtB,OAAO,CAAC,CAAC;AACX,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,SAAiB;IACjE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,sBAAsB,CAC5C,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,EAClD,IAAI,SAAS,CAAC,SAAS,CAAC,CACzB,CAAC;IACF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAAC,IAK7B;IACC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC;QACzB,MAAM,CAAC,IAAI,CAAC,CAAC,sBAAsB,EAAE,kBAAkB,CAAC,CAAC;QACzD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;KACrB,CAAC,CAAC;IACH,OAAO,IAAI,sBAAsB,CAAC;QAChC,SAAS,EAAE,IAAI,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC;QACxC,IAAI,EAAE;YACJ,EAAE,MAAM,EAAE,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE;YACvE,EAAE,MAAM,EAAE,eAAe,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE;YAC7F,EAAE,MAAM,EAAE,aAAa,CAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE;SACxE;QACD,IAAI;KACL,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}