ceaser-mcp 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+# ceaser-mcp
+
+MCP server for the [Ceaser](https://ceaser.org) privacy protocol. Shield and unshield ETH privately on Base L2 using ZK proofs, directly from Claude Code or any MCP-compatible AI agent.
+
+## Quick Start
+
+### Claude Code (local, stdio)
+
+```bash
+claude mcp add --transport stdio ceaser -- npx -y ceaser-mcp
+```
+
+Or add to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ceaser": {
+      "command": "npx",
+      "args": ["-y", "ceaser-mcp"],
+      "env": {
+        "CEASER_API_URL": "https://ceaser.org"
+      }
+    }
+  }
+}
+```
+
+### Claude API Agents (remote HTTP)
+
+```json
+{
+  "mcp_servers": [{
+    "type": "url",
+    "url": "https://ceaser.org/mcp",
+    "name": "ceaser"
+  }]
+}
+```
+
+## Tools
+
+### Read-Only (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `ceaser_get_denominations` | Valid deposit amounts with fee breakdown |
+| `ceaser_get_fees` | Fee calculation for any ETH amount |
+| `ceaser_get_merkle_root` | Current Merkle tree root |
+| `ceaser_get_pool_info` | Pool TVL, notes, fees |
+| `ceaser_check_nullifier` | Check if a nullifier is spent |
+| `ceaser_get_status` | Facilitator health and stats |
+
+### Shield (1 tool)
+
+| Tool | Description |
+|------|-------------|
+| `ceaser_shield_eth` | Generate ZK proof + unsigned shield transaction |
+
+### Unshield (1 tool)
+
+| Tool | Description |
+|------|-------------|
+| `ceaser_unshield` | Generate ZK proof + gasless withdrawal via facilitator |
+
+### Note Management (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `ceaser_list_notes` | List stored privacy notes |
+| `ceaser_import_note` | Import a note from backup string |
+
+## How It Works
+
+1. **Shield**: Agent generates a ZK proof locally, returns an unsigned transaction. User signs and sends from their wallet. A note (containing secrets) is stored locally.
+
+2. **Unshield**: Agent loads the note, rebuilds the Merkle tree from the indexer, generates a burn ZK proof, and submits it to the facilitator for gasless settlement. No wallet needed.
+
+3. **Notes**: Contain the secret and nullifier needed to spend shielded funds. Never transmitted over the MCP stream. Stored at `~/.ceaser-mcp/notes.json`.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CEASER_API_URL` | `https://ceaser.org` | Facilitator API base URL |
+| `CEASER_CONTRACT_ADDRESS` | `0x278652...BcD368` | zkWrapper contract address |
+| `CEASER_CHAIN_ID` | `8453` | Chain ID (Base mainnet) |
+| `CEASER_CIRCUIT_URL` | `https://ceaser.org/circuits` | Circuit artifact download URL |
+| `CEASER_DATA_DIR` | `~/.ceaser-mcp` | Data directory for notes and cached circuits |
+
+## Architecture
+
+- **Local mode** (stdio): Full 10 tools. Proof generation runs in-process via `@noir-lang/noir_js` + `@aztec/bb.js`.
+- **Remote mode** (HTTP): Read-only 6 tools. Mounted at `/mcp` on the facilitator. No proof generation (too slow for HTTP timeouts).
+
+## Version Alignment
+
+These versions must match the Ceaser contracts and frontend exactly:
+
+| Package | Version |
+|---------|---------|
+| `@aztec/bb.js` | ^2.1.11 |
+| `@noir-lang/noir_js` | 1.0.0-beta.18 |
+| `circomlibjs` | ^0.1.7 |
+
+## License
+
+MIT

package/bin/ceaser-mcp.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+/**
+ * Ceaser MCP Server - CLI entry point.
+ *
+ * Starts the MCP server with stdio transport for local use with Claude Code.
+ *
+ * Usage:
+ *   npx ceaser-mcp
+ *   claude mcp add --transport stdio ceaser -- npx -y ceaser-mcp
+ */
+
+import { startStdio } from '../src/transport/stdio.js';
+
+startStdio();

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "ceaser-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Ceaser privacy protocol - shield and unshield ETH privately on Base L2",
+  "type": "module",
+  "bin": {
+    "ceaser-mcp": "./bin/ceaser-mcp.js"
+  },
+  "main": "src/server.js",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/ceaser-mcp.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Zyra-V21/ceaaser-privacy.git",
+    "directory": "ceaser-mcp"
+  },
+  "author": "ZYRKOM",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@aztec/bb.js": "^2.1.11",
+    "@noir-lang/noir_js": "1.0.0-beta.18",
+    "circomlibjs": "^0.1.7",
+    "ethers": "^6.9.0",
+    "zod": "^3.23.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "privacy",
+    "zk-proofs",
+    "ethereum",
+    "base-l2",
+    "ceaser",
+    "claude",
+    "ai-agent"
+  ],
+  "license": "MIT"
+}

package/src/constants.js

@@ -0,0 +1,37 @@
+// BN254 scalar field
+export const SNARK_SCALAR_FIELD = BigInt(
+  '21888242871839275222246405745257275088548364400416034343698204186575808495617'
+);
+
+// Protocol fee (basis points)
+export const PROTOCOL_FEE_BPS = 25n;
+export const BPS_DENOMINATOR = 10000n;
+
+// Merkle tree depth
+export const TREE_LEVELS = 24;
+
+// Valid denominations (ETH, in wei)
+export const DENOMINATIONS = [
+  { label: '0.001 ETH', value: '0.001', wei: '1000000000000000' },
+  { label: '0.01 ETH',  value: '0.01',  wei: '10000000000000000' },
+  { label: '0.1 ETH',   value: '0.1',   wei: '100000000000000000' },
+  { label: '1 ETH',     value: '1',      wei: '1000000000000000000' },
+  { label: '10 ETH',    value: '10',     wei: '10000000000000000000' },
+  { label: '100 ETH',   value: '100',    wei: '100000000000000000000' },
+];
+
+// Contract ABI (minimal, for building unsigned txs)
+export const ZKWRAPPER_ABI = [
+  'function shieldETH(bytes calldata proof, bytes32 commitment, uint256 amount) external payable',
+  'function shieldERC20(bytes calldata proof, bytes32 commitment, uint256 amount, uint256 assetId) external',
+  'function unshield(bytes calldata proof, bytes32 nullifierHash, uint256 amount, uint256 assetId, address recipient, bytes32 root) external',
+  'function privateTransfer(bytes calldata proof, bytes32 nullifierHash, bytes32 newCommitment, bytes32 root, uint256 assetId) external',
+  'function getLastRoot() external view returns (bytes32)',
+  'function isKnownRoot(bytes32 root) external view returns (bool)',
+  'function totalNotesCreated() external view returns (uint64)',
+  'function totalLocked(uint256 assetId) external view returns (uint256)',
+  'function nullifiers(bytes32) external view returns (bool)',
+  'event Shield(bytes32 indexed commitment, uint32 leafIndex, uint256 indexed assetId, uint256 timestamp)',
+  'event PrivateTransfer(bytes32 indexed nullifierHash, bytes32 indexed newCommitment, uint256 indexed assetId, uint32 newLeafIndex)',
+  'event Unshield(bytes32 indexed nullifierHash, address indexed recipient, uint256 indexed assetId)',
+];

package/src/lib/api.js

@@ -0,0 +1,87 @@
+/**
+ * HTTP client for the Ceaser facilitator API.
+ */
+
+import { config } from './config.js';
+import { logError } from './log.js';
+
+function apiUrl(path) {
+  return `${config.apiUrl}${path}`;
+}
+
+async function get(path) {
+  const url = apiUrl(path);
+  const res = await fetch(url);
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`API ${res.status}: ${body || res.statusText}`);
+  }
+  return res.json();
+}
+
+async function post(path, body) {
+  const url = apiUrl(path);
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`API ${res.status}: ${text || res.statusText}`);
+  }
+  return res.json();
+}
+
+// -- Read-only endpoints --
+
+export async function getMerkleRoot() {
+  return get('/api/ceaser/merkle-root');
+}
+
+export async function checkNullifier(hash) {
+  return get(`/api/ceaser/nullifier/${encodeURIComponent(hash)}`);
+}
+
+export async function getPoolInfo(assetId = '0') {
+  return get(`/api/ceaser/pool/${encodeURIComponent(assetId)}`);
+}
+
+export async function getFacilitatorStatus() {
+  return get('/status');
+}
+
+export async function getFees(amountWei) {
+  return get(`/api/ceaser/fees/${amountWei}`);
+}
+
+// -- Indexer endpoints --
+
+export async function getIndexerStatus() {
+  return get('/api/ceaser/indexer/status');
+}
+
+export async function getIndexerCommitments(offset = 0, limit = 1000) {
+  return get(`/api/ceaser/indexer/commitments?offset=${offset}&limit=${limit}`);
+}
+
+export async function getIndexerCommitment(index) {
+  return get(`/api/ceaser/indexer/commitment/${index}`);
+}
+
+// -- Write endpoints --
+
+export async function settle(proof, nullifierHash, amount, assetId, recipient, root) {
+  return post('/settle', {
+    protocol: 'ceaser',
+    network: 'eip155:8453',
+    payload: {
+      proof,
+      nullifierHash,
+      amount,
+      assetId,
+      recipient,
+      root,
+    },
+  });
+}

package/src/lib/artifacts.js

@@ -0,0 +1,102 @@
+/**
+ * Circuit artifact management.
+ * Downloads compiled Noir circuit JSONs from ceaser.org and caches them locally.
+ * Verifies SHA-256 integrity to prevent circuit substitution attacks.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
+import { config } from './config.js';
+import { log } from './log.js';
+
+const CIRCUIT_NAMES = ['shield', 'burn'];
+
+// Pinned SHA-256 hashes for circuit integrity verification
+const CIRCUIT_HASHES = {
+  shield: 'd366b60e6436fdfa329cf0b4af49c4176c06faf11f20f6e8c94344942b8acbeb',
+  burn: '4dd11647a511a9cefa25fbc2dd82a391833a4ecdc378d2096495557422f5ddce',
+};
+
+function getCircuitsDir() {
+  const dir = join(config.dataDir, 'circuits');
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  return dir;
+}
+
+function sha256(data) {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * Download a circuit JSON if not already cached.
+ * Verifies SHA-256 hash against pinned value.
+ */
+async function downloadCircuit(name) {
+  const circuitsDir = getCircuitsDir();
+  const localPath = join(circuitsDir, `${name}.json`);
+
+  if (existsSync(localPath)) {
+    const cached = readFileSync(localPath, 'utf8');
+    const hash = sha256(cached);
+    if (hash !== CIRCUIT_HASHES[name]) {
+      log(`Circuit ${name} cache corrupted (hash mismatch), re-downloading`);
+    } else {
+      log(`Circuit ${name} found in cache (hash verified)`);
+      return JSON.parse(cached);
+    }
+  }
+
+  const url = `${config.circuitBaseUrl}/${name}.json`;
+  log(`Downloading circuit ${name} from ${url}...`);
+
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download ${name} circuit: ${response.status} ${response.statusText}`);
+  }
+
+  const text = await response.text();
+
+  // Verify integrity
+  const hash = sha256(text);
+  if (hash !== CIRCUIT_HASHES[name]) {
+    throw new Error(
+      `Circuit ${name} integrity check failed. Expected ${CIRCUIT_HASHES[name]}, got ${hash}. ` +
+      'This could indicate a compromised source. Aborting.'
+    );
+  }
+
+  // Validate JSON structure
+  const circuit = JSON.parse(text);
+  if (!circuit.bytecode) {
+    throw new Error(`Invalid circuit artifact for ${name}: missing bytecode`);
+  }
+
+  writeFileSync(localPath, text, 'utf8');
+  log(`Circuit ${name} cached at ${localPath} (hash verified)`);
+
+  return circuit;
+}
+
+/**
+ * Ensure all required circuits are downloaded and return them.
+ */
+export async function loadCircuits() {
+  const circuits = {};
+  for (const name of CIRCUIT_NAMES) {
+    circuits[name] = await downloadCircuit(name);
+  }
+  return circuits;
+}
+
+/**
+ * Load a single circuit by name.
+ */
+export async function loadCircuit(name) {
+  if (!CIRCUIT_NAMES.includes(name)) {
+    throw new Error(`Unknown circuit: ${name}. Valid: ${CIRCUIT_NAMES.join(', ')}`);
+  }
+  return downloadCircuit(name);
+}

package/src/lib/config.js

@@ -0,0 +1,19 @@
+import { homedir } from 'os';
+import { join } from 'path';
+
+export const config = {
+  // Facilitator API base URL
+  apiUrl: process.env.CEASER_API_URL || 'https://ceaser.org',
+
+  // Contract address (Base mainnet)
+  contractAddress: process.env.CEASER_CONTRACT_ADDRESS || '0x278652aA8383cBa29b68165926d0534e52BcD368',
+
+  // Chain ID (Base mainnet = 8453)
+  chainId: parseInt(process.env.CEASER_CHAIN_ID || '8453'),
+
+  // Data directory for cached circuits and notes
+  dataDir: process.env.CEASER_DATA_DIR || join(homedir(), '.ceaser-mcp'),
+
+  // Circuit artifact URLs (served by facilitator / ceaser.org)
+  circuitBaseUrl: process.env.CEASER_CIRCUIT_URL || 'https://ceaser.org/circuits',
+};

package/src/lib/crypto.js

@@ -0,0 +1,76 @@
+/**
+ * Cryptographic primitives for Ceaser protocol.
+ * Poseidon hashing over BN254 using circomlibjs (same as Noir stdlib).
+ */
+
+import { buildPoseidon } from 'circomlibjs';
+import { randomBytes } from 'crypto';
+import { keccak256, toUtf8Bytes } from 'ethers';
+import { SNARK_SCALAR_FIELD, TREE_LEVELS } from '../constants.js';
+
+let poseidon;
+let F;
+
+/**
+ * Initialize Poseidon (lazy, cached).
+ */
+export async function initPoseidon() {
+  if (!poseidon) {
+    poseidon = await buildPoseidon();
+    F = poseidon.F;
+  }
+  return { poseidon, F };
+}
+
+/**
+ * Generate a cryptographically secure random BN254 field element.
+ */
+export function randomField() {
+  const bytes = randomBytes(31);
+  return BigInt('0x' + bytes.toString('hex')) % SNARK_SCALAR_FIELD;
+}
+
+/**
+ * Poseidon hash with N inputs.
+ */
+export async function poseidonHash(inputs) {
+  const { poseidon, F } = await initPoseidon();
+  const hash = poseidon(inputs.map((x) => F.e(x)));
+  return F.toObject(hash);
+}
+
+/**
+ * Compute commitment = Poseidon(secret, nullifier, amount, assetId)
+ */
+export async function computeCommitment(secret, nullifier, amount, assetId = 0n) {
+  return poseidonHash([secret, nullifier, amount, assetId]);
+}
+
+/**
+ * Compute nullifierHash = Poseidon(nullifier, leafIndex)
+ */
+export async function computeNullifierHash(nullifier, leafIndex) {
+  return poseidonHash([nullifier, leafIndex]);
+}
+
+/**
+ * Zero value matching Solidity: keccak256("zkETH") % SNARK_SCALAR_FIELD
+ */
+export function getZeroValue() {
+  const hash = keccak256(toUtf8Bytes('zkETH'));
+  return BigInt(hash) % SNARK_SCALAR_FIELD;
+}
+
+/**
+ * Format a BigInt as a 0x-prefixed 32-byte hex string (bytes32).
+ */
+export function toBytes32(value) {
+  return '0x' + BigInt(value).toString(16).padStart(64, '0');
+}
+
+/**
+ * Format UltraHonk proof (Uint8Array) to hex string for Solidity.
+ */
+export function formatProofHex(proof) {
+  return '0x' + Array.from(proof).map((b) => b.toString(16).padStart(2, '0')).join('');
+}

package/src/lib/log.js

@@ -0,0 +1,11 @@
+/**
+ * Logging to stderr (never stdout, which is the MCP JSON-RPC stream).
+ */
+
+export function log(...args) {
+  process.stderr.write(`[ceaser-mcp] ${args.join(' ')}\n`);
+}
+
+export function logError(...args) {
+  process.stderr.write(`[ceaser-mcp] ERROR: ${args.join(' ')}\n`);
+}

package/src/lib/merkleTree.js

@@ -0,0 +1,126 @@
+/**
+ * Incremental Poseidon Merkle tree (24 levels).
+ *
+ * Mirrors Solidity MerkleTreeComponent filledSubtrees pattern for O(log n) inserts.
+ * Also supports getProof() for generating ZK proofs (path elements + indices).
+ */
+
+import { TREE_LEVELS } from '../constants.js';
+import { initPoseidon, poseidonHash, getZeroValue } from './crypto.js';
+
+export class MerkleTree {
+  constructor() {
+    this.levels = TREE_LEVELS;
+    this.zeros = [];
+    this.filledSubtrees = [];
+    this.leaves = [];
+    this.root = null;
+    this._initialized = false;
+  }
+
+  async init() {
+    if (this._initialized) return;
+
+    await initPoseidon();
+
+    let currentZero = getZeroValue();
+
+    for (let i = 0; i < this.levels; i++) {
+      this.zeros.push(currentZero);
+      this.filledSubtrees.push(currentZero);
+      currentZero = await poseidonHash([currentZero, currentZero]);
+    }
+
+    this.root = currentZero;
+    this._initialized = true;
+  }
+
+  /**
+   * Insert a leaf (commitment) into the tree.
+   * @param {BigInt|string} leaf
+   * @returns {{ leafIndex: number, root: BigInt }}
+   */
+  async insert(leaf) {
+    if (!this._initialized) await this.init();
+
+    const leafBigInt = BigInt(leaf);
+    const leafIndex = this.leaves.length;
+    this.leaves.push(leafBigInt);
+
+    let currentIndex = leafIndex;
+    let currentHash = leafBigInt;
+
+    for (let i = 0; i < this.levels; i++) {
+      if (currentIndex % 2 === 0) {
+        this.filledSubtrees[i] = currentHash;
+        currentHash = await poseidonHash([currentHash, this.zeros[i]]);
+      } else {
+        currentHash = await poseidonHash([this.filledSubtrees[i], currentHash]);
+      }
+      currentIndex = Math.floor(currentIndex / 2);
+    }
+
+    this.root = currentHash;
+    return { leafIndex, root: this.root };
+  }
+
+  /**
+   * Generate a Merkle proof for a given leaf index.
+   * Returns pathElements (siblings) and pathIndices (0=left, 1=right).
+   */
+  async getProof(leafIndex) {
+    if (!this._initialized) await this.init();
+
+    if (leafIndex >= this.leaves.length) {
+      throw new Error(`Leaf index ${leafIndex} not found`);
+    }
+
+    const pathElements = [];
+    const pathIndices = [];
+    let currentIndex = leafIndex;
+
+    for (let i = 0; i < this.levels; i++) {
+      const isRight = currentIndex % 2 === 1;
+      pathIndices.push(isRight ? 1 : 0);
+
+      const siblingIndex = isRight ? currentIndex - 1 : currentIndex + 1;
+      const siblingStart = siblingIndex * (1 << i);
+
+      if (siblingStart >= this.leaves.length) {
+        pathElements.push(this.zeros[i]);
+      } else {
+        const sibling = await this._getNodeHash(i, isRight ? currentIndex - 1 : currentIndex + 1);
+        pathElements.push(sibling);
+      }
+
+      currentIndex = Math.floor(currentIndex / 2);
+    }
+
+    return { pathElements, pathIndices };
+  }
+
+  /**
+   * Recursively compute the hash of a node at a given level and index.
+   */
+  async _getNodeHash(level, index) {
+    if (level === 0) {
+      return index < this.leaves.length ? this.leaves[index] : this.zeros[0];
+    }
+
+    const leftChild = index * 2;
+    const rightChild = index * 2 + 1;
+
+    const leftHash = await this._getNodeHash(level - 1, leftChild);
+    const rightHash = await this._getNodeHash(level - 1, rightChild);
+
+    return poseidonHash([leftHash, rightHash]);
+  }
+
+  getRoot() {
+    return this.root;
+  }
+
+  getLeafCount() {
+    return this.leaves.length;
+  }
+}