midnight-mcp 0.1.34 → 0.1.36

package/dist/config/compact-version.d.ts

@@ -65,4 +65,107 @@ export declare function getVersionInfo(): string;
  * Check if a version is within supported range
  */
 export declare function isVersionSupported(version: string): boolean;
+/**
+ * Built-in functions vs patterns you must implement yourself
+ * CRITICAL: These are the actual stdlib functions available in Compact
+ */
+export declare const BUILTIN_FUNCTIONS: {
+    /** Actually built into the language/stdlib */
+    stdlib: {
+        name: string;
+        signature: string;
+        description: string;
+    }[];
+    /** NOT built-in - you must implement these patterns yourself */
+    notBuiltIn: {
+        name: string;
+        wrongUsage: string;
+        correctPattern: string;
+        description: string;
+    }[];
+};
+/**
+ * Type compatibility rules - what types can be compared/operated together
+ */
+export declare const TYPE_COMPATIBILITY: {
+    comparisons: ({
+        types: string;
+        works: boolean;
+        note: string;
+        fix?: undefined;
+    } | {
+        types: string;
+        works: boolean;
+        fix: string;
+        note?: undefined;
+    })[];
+    arithmetic: ({
+        types: string;
+        works: boolean;
+        note: string;
+        fix?: undefined;
+    } | {
+        types: string;
+        works: boolean;
+        fix: string;
+        note?: undefined;
+    })[];
+    assignments: {
+        types: string;
+        works: boolean;
+        fix: string;
+    }[];
+    tips: string[];
+};
+/**
+ * Ledger type limitations - what works in circuits vs TypeScript
+ */
+export declare const LEDGER_TYPE_LIMITS: {
+    Counter: {
+        circuitOperations: {
+            method: string;
+            works: boolean;
+            note: string;
+        }[];
+        typescriptAccess: string;
+        reason: string;
+    };
+    Map: {
+        circuitOperations: {
+            method: string;
+            works: boolean;
+            note: string;
+        }[];
+        typescriptAccess: string;
+        reason: string;
+        pattern: string;
+    };
+    Set: {
+        circuitOperations: {
+            method: string;
+            works: boolean;
+            note: string;
+        }[];
+        typescriptAccess: string;
+        reason: string;
+    };
+    MerkleTree: {
+        circuitOperations: {
+            method: string;
+            works: boolean;
+            note: string;
+        }[];
+        typescriptAccess: string;
+        pattern: string;
+    };
+};
+/**
+ * Common compilation errors with their fixes
+ * Maps actual compiler error messages to solutions
+ */
+export declare const COMMON_ERRORS: {
+    error: string;
+    cause: string;
+    fix: string;
+}[];
 //# sourceMappingURL=compact-version.d.ts.map

package/dist/config/compact-version.js

@@ -92,4 +92,271 @@ export function isVersionSupported(version) {
     const maxNum = maxMajor * 100 + maxMinor;
     return versionNum >= minNum && versionNum <= maxNum;
 }
+/**
+ * Built-in functions vs patterns you must implement yourself
+ * CRITICAL: These are the actual stdlib functions available in Compact
+ */
+export const BUILTIN_FUNCTIONS = {
+    /** Actually built into the language/stdlib */
+    stdlib: [
+        {
+            name: "persistentHash",
+            signature: "persistentHash<T>(value: T): Bytes<32>",
+            description: "Poseidon hash that produces consistent results across calls",
+        },
+        {
+            name: "persistentCommit",
+            signature: "persistentCommit<T>(value: T): Bytes<32>",
+            description: "Creates a hiding commitment to a value",
+        },
+        {
+            name: "pad",
+            signature: "pad(length: number, value: string): Bytes<N>",
+            description: "Pads a string to fixed-length bytes",
+        },
+        {
+            name: "disclose",
+            signature: "disclose(value: T): T",
+            description: "Explicitly reveals a witness value (required in conditionals)",
+        },
+        {
+            name: "assert",
+            signature: "assert(condition: Boolean, message?: string): []",
+            description: "Fails circuit if condition is false",
+        },
+        {
+            name: "default",
+            signature: "default<T>(): T",
+            description: "Returns default value for a type (0 for numbers, empty for collections)",
+        },
+    ],
+    /** NOT built-in - you must implement these patterns yourself */
+    notBuiltIn: [
+        {
+            name: "public_key",
+            wrongUsage: "public_key(sk) // ERROR: unbound identifier",
+            correctPattern: `// Derive public key using persistentHash
+const pk = persistentHash<Vector<2, Bytes<32>>>([
+  pad(32, "midnight:pk:"),
+  sk
+]);`,
+            description: "Public key derivation is NOT a builtin - use persistentHash pattern",
+        },
+        {
+            name: "verify_signature",
+            wrongUsage: "verify_signature(msg, sig, pk) // Does not exist",
+            correctPattern: `// Signature verification must be done via witnesses
+// The prover verifies off-chain, then provides the boolean result
+witness signature_valid(): Boolean;`,
+            description: "Signature verification is done off-chain in the prover",
+        },
+        {
+            name: "random",
+            wrongUsage: "random() // Does not exist in ZK circuits",
+            correctPattern: `// Randomness must come from witnesses (prover-provided)
+witness get_random_value(): Field;`,
+            description: "ZK circuits are deterministic - randomness must come from witnesses",
+        },
+    ],
+};
+/**
+ * Type compatibility rules - what types can be compared/operated together
+ */
+export const TYPE_COMPATIBILITY = {
+    comparisons: [
+        { types: "Field == Field", works: true, note: "Direct comparison" },
+        {
+            types: "Field == Uint<N>",
+            works: false,
+            fix: "Cast with `value as Field`",
+        },
+        {
+            types: "Field >= 0",
+            works: false,
+            fix: "Use bounded Uint<0..N> parameter instead",
+        },
+        { types: "Uint<N> == Uint<N>", works: true, note: "Same-width comparison" },
+        {
+            types: "Uint<0..2> == Uint<0..2>",
+            works: true,
+            note: "Bounded integers",
+        },
+        { types: "Bytes<32> == Bytes<32>", works: true, note: "Direct comparison" },
+        { types: "Boolean == Boolean", works: true, note: "Direct comparison" },
+    ],
+    arithmetic: [
+        { types: "Field + Field", works: true, note: "Field arithmetic" },
+        { types: "Field + Uint<N>", works: false, fix: "Cast Uint to Field first" },
+        {
+            types: "Uint<N> + Uint<N>",
+            works: true,
+            note: "Must fit in result width",
+        },
+    ],
+    assignments: [
+        {
+            types: "Field = Uint<N>",
+            works: false,
+            fix: "Cast with `value as Field`",
+        },
+        {
+            types: "Uint<N> = Field",
+            works: false,
+            fix: "Use bounded param or explicit cast",
+        },
+    ],
+    tips: [
+        "Use Uint<0..N> for circuit parameters that need range validation",
+        "Field is unbounded - use for hashes, commitments, general computation",
+        "Uint<N> is bounded - use when you need range checks",
+        "Casting with `as Field` is safe but loses range information",
+    ],
+};
+/**
+ * Ledger type limitations - what works in circuits vs TypeScript
+ */
+export const LEDGER_TYPE_LIMITS = {
+    Counter: {
+        circuitOperations: [
+            { method: ".increment(n)", works: true, note: "Adds n to counter" },
+            {
+                method: ".decrement(n)",
+                works: true,
+                note: "Subtracts n from counter",
+            },
+            { method: ".resetToDefault()", works: true, note: "Resets to 0" },
+            { method: ".value()", works: false, note: "NOT available in circuits" },
+        ],
+        typescriptAccess: "Access counter value via `ledgerState.counter` in TypeScript SDK",
+        reason: "ZK circuits cannot read current ledger state - only modify it",
+    },
+    Map: {
+        circuitOperations: [
+            {
+                method: ".insert(key, value)",
+                works: true,
+                note: "Adds/updates entry",
+            },
+            { method: ".remove(key)", works: true, note: "Removes entry" },
+            {
+                method: ".lookup(key)",
+                works: false,
+                note: "NOT available in circuits",
+            },
+            {
+                method: ".member(key)",
+                works: false,
+                note: "NOT available in circuits",
+            },
+        ],
+        typescriptAccess: "Query map via `contractState.data.get(key)` in TypeScript SDK",
+        reason: "ZK circuits prove transitions, not current state. Use witnesses for reads.",
+        pattern: `// To read a map value in a circuit, use a witness:
+witness get_stored_value(key: Bytes<32>): Field;
+
+export circuit update_if_exists(key: Bytes<32>, new_value: Field): [] {
+  const current = get_stored_value(key);  // Prover fetches from ledger
+  // ... use current value
+  data.insert(key, new_value);  // Update is allowed
+}`,
+    },
+    Set: {
+        circuitOperations: [
+            { method: ".insert(value)", works: true, note: "Adds to set" },
+            { method: ".remove(value)", works: true, note: "Removes from set" },
+            {
+                method: ".member(value)",
+                works: false,
+                note: "NOT available in circuits",
+            },
+        ],
+        typescriptAccess: "Check membership via `contractState.set.has(value)` in TypeScript SDK",
+        reason: "Same as Map - use witnesses for membership checks",
+    },
+    MerkleTree: {
+        circuitOperations: [
+            { method: ".insert(leaf)", works: true, note: "Adds leaf to tree" },
+            { method: ".root()", works: false, note: "NOT available in circuits" },
+        ],
+        typescriptAccess: "Get root via `contractState.tree.root` in TypeScript SDK",
+        pattern: `// To verify a merkle proof in circuit:
+witness get_merkle_root(): Bytes<32>;
+witness get_merkle_proof(leaf: Bytes<32>): Vector<32, Bytes<32>>;
+
+// Verify proof using persistentHash to compute expected root`,
+    },
+};
+/**
+ * Common compilation errors with their fixes
+ * Maps actual compiler error messages to solutions
+ */
+export const COMMON_ERRORS = [
+    {
+        error: 'unbound identifier "public_key"',
+        cause: "Trying to use public_key() as if it's a builtin function",
+        fix: `Use persistentHash pattern instead:
+const pk = persistentHash<Vector<2, Bytes<32>>>([pad(32, "midnight:pk:"), sk]);`,
+    },
+    {
+        error: "incompatible combination of types Field and Uint",
+        cause: "Comparing or operating on Field with Uint without casting",
+        fix: `Cast Uint to Field: (myUint as Field)
+Or use bounded Uint<0..N> for parameters that need constraints`,
+    },
+    {
+        error: 'operation "value" undefined for ledger field type Counter',
+        cause: "Trying to read Counter.value() inside a circuit",
+        fix: `Counter values cannot be read in circuits. Options:
+1. Use a witness: witness get_counter_value(): Uint<64>;
+2. Read from TypeScript SDK: ledgerState.counter
+3. Track the value in a separate Field ledger variable`,
+    },
+    {
+        error: "implicit disclosure of witness value",
+        cause: "Using witness value in conditional without disclose()",
+        fix: `Wrap witness comparisons in disclose():
+if (disclose(witness_value == expected)) { ... }`,
+    },
+    {
+        error: 'parse error: found "{" looking for an identifier',
+        cause: "Using old ledger { } block syntax",
+        fix: `Use individual exports instead:
+export ledger field1: Type1;
+export ledger field2: Type2;`,
+    },
+    {
+        error: 'parse error: found "{" looking for ";"',
+        cause: "Using Void as return type (doesn't exist)",
+        fix: `Use empty tuple [] for no return value:
+export circuit myCircuit(): [] { ... }`,
+    },
+    {
+        error: 'unbound identifier "Cell"',
+        cause: "Using deprecated Cell<T> wrapper (removed in 0.15)",
+        fix: `Remove Cell wrapper, just use the type directly:
+export ledger myField: Field;  // Not Cell<Field>`,
+    },
+    {
+        error: "member access requires struct type",
+        cause: "Trying to use .member() or .lookup() on Map/Set in circuit",
+        fix: `Map/Set queries are not available in circuits.
+Use a witness to fetch the value from the prover:
+witness lookup_value(key: Bytes<32>): Field;`,
+    },
+    {
+        error: "cannot prove assertion",
+        cause: "Assert condition cannot be proven true",
+        fix: `Check your logic. Common causes:
+1. Witness returns unexpected value
+2. Range check fails (use bounded Uint)
+3. Logic error in circuit`,
+    },
+    {
+        error: 'parse error: found ":" looking for ")"',
+        cause: "Using Rust-style :: for enum variant access",
+        fix: `Use dot notation for enum variants:
+WRONG:  Choice::rock, GameState::waiting
+CORRECT: Choice.rock, GameState.waiting`,
+    },
+];
 //# sourceMappingURL=compact-version.js.map

package/dist/resources/content/docs-content.js

@@ -133,6 +133,16 @@ export enum GameState { waiting, playing, finished }
 export enum Choice { rock, paper, scissors }
 \`\`\`
 
+**Enum Access Syntax** - use DOT notation (not Rust-style ::):
+\`\`\`compact
+// CORRECT - dot notation
+if (choice == Choice.rock) { ... }
+game_state = GameState.waiting;
+
+// WRONG - Rust-style double colon
+if (choice == Choice::rock) { ... }  // ❌ Parse error: found ":" looking for ")"
+\`\`\`
+
 **Structs**:
 \`\`\`compact
 export struct PlayerConfig {
@@ -225,6 +235,7 @@ constructor(initNonce: Bytes<32>) {
 \`\`\`compact
 witness local_secret_key(): Bytes<32>;
 
+// IMPORTANT: public_key() is NOT a builtin - use this pattern
 circuit get_public_key(sk: Bytes<32>): Bytes<32> {
   return persistentHash<Vector<2, Bytes<32>>>([pad(32, "myapp:pk:"), sk]);
 }
@@ -237,32 +248,47 @@ export circuit authenticated_action(): [] {
 }
 \`\`\`
 
-### Commit-Reveal Pattern
+### Commit-Reveal Pattern (COMPLETE, VALIDATED)
 \`\`\`compact
+pragma language_version >= 0.16 && <= 0.18;
+
+import CompactStandardLibrary;
+
+// Ledger state
 export ledger commitment: Bytes<32>;
-export ledger revealed: Boolean;
+export ledger revealed_value: Field;
+export ledger is_revealed: Boolean;
 
-witness get_stored_value(): Field;
-witness store_value(v: Field): [];
+// Witnesses for off-chain storage
+witness local_secret_key(): Bytes<32>;
+witness store_secret_value(v: Field): [];
+witness get_secret_value(): Field;
+
+// Helper: compute commitment hash
+circuit compute_commitment(value: Field, salt: Bytes<32>): Bytes<32> {
+  // Convert Field to Bytes for hashing
+  const value_bytes = value as Bytes<32>;
+  return persistentHash<Vector<2, Bytes<32>>>([value_bytes, salt]);
+}
 
+// Commit phase: store hash on-chain, value off-chain
 export circuit commit(value: Field): [] {
-  const sk = local_secret_key();
-  store_value(value);
-  commitment = disclose(persistentHash<Vector<2, Bytes<32>>>([
-    value as Bytes<32>, 
-    sk
-  ]));
+  const salt = local_secret_key();
+  store_secret_value(value);
+  commitment = disclose(compute_commitment(value, salt));
+  is_revealed = false;
 }
 
+// Reveal phase: verify stored value matches commitment
 export circuit reveal(): Field {
-  const sk = local_secret_key();
-  const value = get_stored_value();
-  const expected = persistentHash<Vector<2, Bytes<32>>>([
-    value as Bytes<32>, 
-    sk
-  ]);
-  assert(disclose(expected == commitment), "Mismatch");
-  revealed = true;
+  const salt = local_secret_key();
+  const value = get_secret_value();
+  const expected = compute_commitment(value, salt);
+  assert(disclose(expected == commitment), "Value doesn't match commitment");
+  assert(disclose(!is_revealed), "Already revealed");
+  
+  revealed_value = disclose(value);
+  is_revealed = true;
   return disclose(value);
 }
 \`\`\`
@@ -296,22 +322,39 @@ export circuit check_broken(guess: Field): Boolean {
 
 ### Counter Operations
 \`\`\`compact
+// These work in circuits:
 counter.increment(1);
 counter.decrement(1);
-const val = counter.value();  // Note: returns as Field
+counter.resetToDefault();
+
+// ⚠️ DOES NOT WORK IN CIRCUITS:
+// const val = counter.value();  // ERROR: operation undefined
+// Instead, read counter value in TypeScript SDK: ledgerState.counter
 \`\`\`
 
 ### Map Operations
 \`\`\`compact
+// These work in circuits:
 balances.insert(address, 100);
-const balance = balances.lookup(address);
-const exists = balances.member(address);
+balances.remove(address);
+
+// ⚠️ DOES NOT WORK IN CIRCUITS:
+// const balance = balances.lookup(address);  // ERROR
+// const exists = balances.member(address);   // ERROR
+// Instead, use witnesses to read values:
+witness get_balance(addr: Bytes<32>): Uint<64>;
 \`\`\`
 
 ### Set Operations
 \`\`\`compact
+// These work in circuits:
 members.insert(address);
-const isMember = members.member(address);
+members.remove(address);
+
+// ⚠️ DOES NOT WORK IN CIRCUITS:
+// const isMember = members.member(address);  // ERROR
+// Use witness instead:
+witness is_member(addr: Bytes<32>): Boolean;
 \`\`\`
 
 ### Maybe Operations
@@ -326,9 +369,9 @@ if (opt.is_some) {
 
 ### Type Casting
 \`\`\`compact
-const f: Field = counter.value();           // Counter to Field
-const bytes: Bytes<32> = f as Bytes<32>;    // Field to Bytes
-const num: Uint<64> = f as Uint<64>;        // Field to Uint
+const bytes: Bytes<32> = myField as Bytes<32>;  // Field to Bytes
+const num: Uint<64> = myField as Uint<64>;      // Field to Uint (bounds not checked!)
+const field: Field = myUint as Field;           // Uint to Field (safe)
 \`\`\`
 
 ### Hashing
@@ -336,8 +379,8 @@ const num: Uint<64> = f as Uint<64>;        // Field to Uint
 // Persistent hash (same input = same output across calls)
 const hash = persistentHash<Vector<2, Bytes<32>>>([data1, data2]);
 
-// Transient hash (includes randomness)  
-const commit = transientCommit<Field>(value, randomness);
+// Persistent commit (hiding commitment)
+const commit = persistentCommit<Field>(value);
 \`\`\`
 
 ---

package/dist/tools/repository/handlers.d.ts

@@ -159,6 +159,93 @@ export declare function compareSyntax(input: CompareSyntaxInput): Promise<{
  */
 export declare function getLatestSyntax(input: GetLatestSyntaxInput): Promise<{
     quickStartTemplate: string;
+    builtinFunctions: {
+        stdlib: {
+            name: string;
+            signature: string;
+            description: string;
+        }[];
+        notBuiltIn: {
+            name: string;
+            wrongUsage: string;
+            correctPattern: string;
+            description: string;
+        }[];
+    };
+    typeCompatibility: {
+        comparisons: ({
+            types: string;
+            works: boolean;
+            note: string;
+            fix?: undefined;
+        } | {
+            types: string;
+            works: boolean;
+            fix: string;
+            note?: undefined;
+        })[];
+        arithmetic: ({
+            types: string;
+            works: boolean;
+            note: string;
+            fix?: undefined;
+        } | {
+            types: string;
+            works: boolean;
+            fix: string;
+            note?: undefined;
+        })[];
+        assignments: {
+            types: string;
+            works: boolean;
+            fix: string;
+        }[];
+        tips: string[];
+    };
+    ledgerTypeLimits: {
+        Counter: {
+            circuitOperations: {
+                method: string;
+                works: boolean;
+                note: string;
+            }[];
+            typescriptAccess: string;
+            reason: string;
+        };
+        Map: {
+            circuitOperations: {
+                method: string;
+                works: boolean;
+                note: string;
+            }[];
+            typescriptAccess: string;
+            reason: string;
+            pattern: string;
+        };
+        Set: {
+            circuitOperations: {
+                method: string;
+                works: boolean;
+                note: string;
+            }[];
+            typescriptAccess: string;
+            reason: string;
+        };
+        MerkleTree: {
+            circuitOperations: {
+                method: string;
+                works: boolean;
+                note: string;
+            }[];
+            typescriptAccess: string;
+            pattern: string;
+        };
+    };
+    commonErrors: {
+        error: string;
+        cause: string;
+        fix: string;
+    }[];
     commonMistakes: {
         wrong: string;
         correct: string;

package/dist/tools/repository/handlers.js

@@ -8,7 +8,7 @@ import { logger, DEFAULT_REPOSITORIES, SelfCorrectionHints, } from "../../utils/
 import { sendProgressNotification } from "../../server.js";
 import { REPO_ALIASES, EXAMPLES } from "./constants.js";
 import { EMBEDDED_DOCS } from "../../resources/content/docs-content.js";
-import { COMPACT_VERSION, RECOMMENDED_PRAGMA, REFERENCE_CONTRACTS, } from "../../config/compact-version.js";
+import { COMPACT_VERSION, RECOMMENDED_PRAGMA, REFERENCE_CONTRACTS, BUILTIN_FUNCTIONS, TYPE_COMPATIBILITY, LEDGER_TYPE_LIMITS, COMMON_ERRORS, } from "../../config/compact-version.js";
 // Re-export validation handlers from validation.ts
 export { extractContractStructure } from "./validation.js";
 /**
@@ -356,6 +356,14 @@ witness local_secret_key(): Bytes<32>;
 export circuit increment(): [] {
   counter.increment(1);
 }`,
+                // Built-in functions vs patterns (CRITICAL knowledge)
+                builtinFunctions: BUILTIN_FUNCTIONS,
+                // Type compatibility rules
+                typeCompatibility: TYPE_COMPATIBILITY,
+                // Ledger type limitations in circuits
+                ledgerTypeLimits: LEDGER_TYPE_LIMITS,
+                // Common compilation errors with fixes
+                commonErrors: COMMON_ERRORS,
                 // Common mistakes that cause compilation failures
                 commonMistakes: [
                     {
@@ -388,6 +396,26 @@ export circuit increment(): [] {
                         correct: "Field",
                         error: "unbound identifier Cell (deprecated)",
                     },
+                    {
+                        wrong: "public_key(sk)",
+                        correct: 'persistentHash<Vector<2, Bytes<32>>>([pad(32, "midnight:pk:"), sk])',
+                        error: 'unbound identifier "public_key"',
+                    },
+                    {
+                        wrong: "counter.value()",
+                        correct: "// Read via witness or TypeScript SDK",
+                        error: 'operation "value" undefined for Counter',
+                    },
+                    {
+                        wrong: "data.lookup(key)",
+                        correct: "// Use witness: witness get_value(key): Type;",
+                        error: "member access requires struct type",
+                    },
+                    {
+                        wrong: "Choice::rock (Rust-style)",
+                        correct: "Choice.rock (dot notation)",
+                        error: 'parse error: found ":" looking for ")"',
+                    },
                 ],
                 syntaxReference: compactReference,
                 sections: [
@@ -396,6 +424,9 @@ export circuit increment(): [] {
                     "Imports",
                     "Ledger Declarations",
                     "Data Types",
+                    "Built-in Functions",
+                    "Type Compatibility",
+                    "Ledger Type Limits",
                     "Circuits",
                     "Witnesses",
                     "Constructor",
@@ -403,6 +434,7 @@ export circuit increment(): [] {
                     "Common Operations",
                     "Assertions",
                     "Common Mistakes to Avoid",
+                    "Common Errors & Fixes",
                     "Exports for TypeScript",
                     "Reference Contracts",
                 ],
@@ -411,7 +443,13 @@ export circuit increment(): [] {
                     repo: rc.repo,
                     description: rc.description,
                 })),
-                note: `CRITICAL: Use quickStartTemplate as your base. Check commonMistakes before submitting code. This reference is for Compact ${COMPACT_VERSION.min}-${COMPACT_VERSION.max} (last updated: ${COMPACT_VERSION.lastUpdated}).`,
+                note: `CRITICAL: Use quickStartTemplate as your base. Check commonMistakes and commonErrors before submitting code. 
+KEY GOTCHAS:
+1. public_key() is NOT a builtin - use persistentHash pattern
+2. Counter.value() NOT available in circuits - use witnesses
+3. Map.lookup()/Set.member() NOT available in circuits - use witnesses
+4. Field vs Uint comparison requires casting
+This reference is for Compact ${COMPACT_VERSION.min}-${COMPACT_VERSION.max} (last updated: ${COMPACT_VERSION.lastUpdated}).`,
             };
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "midnight-mcp",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "Model Context Protocol Server for Midnight Blockchain Development",
   "type": "module",
   "main": "dist/index.js",