midnight-mcp 0.1.32 → 0.1.34

package/README.md

@@ -93,7 +93,7 @@ Or manually update your config:
 | Category          | Tools                                                                                                                             | Description                                      |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
 | **Search**        | `search-compact`, `search-typescript`, `search-docs`                                                                              | Semantic search across Midnight codebase         |
-| **Analysis**      | `analyze-contract`, `explain-circuit`, `extract-contract-structure`                                                               | Static analysis and pattern detection            |
+| **Analysis**      | `analyze-contract`, `explain-circuit`, `extract-contract-structure`                                                               | Static analysis with 15+ checks (P0-P2 severity) |
 | **Repository**    | `get-file`, `list-examples`, `get-latest-updates`                                                                                 | Access files and examples                        |
 | **Versioning**    | `get-version-info`, `check-breaking-changes`, `get-migration-guide`, `get-file-at-version`, `compare-syntax`, `get-latest-syntax` | Version tracking and migration                   |
 | **AI Generation** | `generate-contract`, `review-contract`, `document-contract`                                                                       | AI-powered code generation _(requires sampling)_ |
@@ -119,13 +119,26 @@ All tools are prefixed with `midnight-` (e.g., `midnight-search-compact`).
 
 Quick references available offline:
 
-- Compact syntax guide
+- Compact syntax guide (v0.16-0.18)
 - SDK API reference
 - OpenZeppelin contracts
 - Tokenomics overview
 - Wallet integration
 - Common errors & solutions
 
+### Static Analysis
+
+`extract-contract-structure` catches common mistakes before compilation:
+
+| Check                     | Severity | Description                                             |
+| ------------------------- | -------- | ------------------------------------------------------- |
+| `deprecated_ledger_block` | P0       | Catches `ledger { }` → use `export ledger field: Type;` |
+| `invalid_void_type`       | P0       | Catches `Void` → use `[]` (empty tuple)                 |
+| `invalid_pragma_format`   | P0       | Catches old pragma → use `>= 0.16 && <= 0.18`           |
+| `unexported_enum`         | P1       | Enums need `export` for TypeScript access               |
+| `module_level_const`      | P0       | Use `pure circuit` instead                              |
+| + 10 more checks          | P1-P2    | Overflow, division, assertions, etc.                    |
+
 ### 5 Prompts
 
 - `create-contract` — Generate new contracts

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

@@ -0,0 +1,68 @@
+/**
+ * Compact Language Version Configuration
+ *
+ * MAINTAINER: Update these values when Compact language syntax changes!
+ * See docs/SYNTAX_MAINTENANCE.md for the full update checklist.
+ */
+/**
+ * Supported Compact language version range
+ * Update when new compiler versions are released
+ */
+export declare const COMPACT_VERSION: {
+    /** Minimum supported version */
+    min: string;
+    /** Maximum supported version */
+    max: string;
+    /** When this config was last updated */
+    lastUpdated: string;
+    /** Source of truth for syntax patterns */
+    referenceSource: string;
+};
+/**
+ * Current pragma format that should be used in contracts
+ */
+export declare const RECOMMENDED_PRAGMA: string;
+/**
+ * Known deprecated patterns (add new ones here when Compact evolves)
+ */
+export declare const DEPRECATED_PATTERNS: {
+    /** Deprecated in: 0.16 */
+    ledgerBlock: {
+        pattern: RegExp;
+        since: string;
+        replacement: string;
+        description: string;
+    };
+    /** Deprecated in: 0.15 */
+    cellWrapper: {
+        pattern: RegExp;
+        since: string;
+        replacement: string;
+        description: string;
+    };
+    /** Never existed */
+    voidType: {
+        pattern: RegExp;
+        since: string;
+        replacement: string;
+        description: string;
+    };
+};
+/**
+ * Reference contracts known to compile successfully
+ * Use these to verify syntax is still correct
+ */
+export declare const REFERENCE_CONTRACTS: {
+    name: string;
+    repo: string;
+    description: string;
+}[];
+/**
+ * Get the version info as a string for display
+ */
+export declare function getVersionInfo(): string;
+/**
+ * Check if a version is within supported range
+ */
+export declare function isVersionSupported(version: string): boolean;
+//# sourceMappingURL=compact-version.d.ts.map

package/dist/config/compact-version.js

@@ -0,0 +1,95 @@
+/**
+ * Compact Language Version Configuration
+ *
+ * MAINTAINER: Update these values when Compact language syntax changes!
+ * See docs/SYNTAX_MAINTENANCE.md for the full update checklist.
+ */
+/**
+ * Supported Compact language version range
+ * Update when new compiler versions are released
+ */
+export const COMPACT_VERSION = {
+    /** Minimum supported version */
+    min: "0.16",
+    /** Maximum supported version */
+    max: "0.18",
+    /** When this config was last updated */
+    lastUpdated: "2025-01-26",
+    /** Source of truth for syntax patterns */
+    referenceSource: "https://github.com/piotr-iohk/template-contract",
+};
+/**
+ * Current pragma format that should be used in contracts
+ */
+export const RECOMMENDED_PRAGMA = `pragma language_version >= ${COMPACT_VERSION.min} && <= ${COMPACT_VERSION.max};`;
+/**
+ * Known deprecated patterns (add new ones here when Compact evolves)
+ */
+export const DEPRECATED_PATTERNS = {
+    /** Deprecated in: 0.16 */
+    ledgerBlock: {
+        pattern: /ledger\s*\{/,
+        since: "0.16",
+        replacement: "export ledger fieldName: Type;",
+        description: "Block-style ledger declarations",
+    },
+    /** Deprecated in: 0.15 */
+    cellWrapper: {
+        pattern: /Cell\s*<\s*\w+\s*>/,
+        since: "0.15",
+        replacement: "Type (without Cell wrapper)",
+        description: "Cell<T> type wrapper",
+    },
+    /** Never existed */
+    voidType: {
+        pattern: /:\s*Void\b/,
+        since: "always",
+        replacement: "[] (empty tuple)",
+        description: "Void return type",
+    },
+};
+/**
+ * Reference contracts known to compile successfully
+ * Use these to verify syntax is still correct
+ */
+export const REFERENCE_CONTRACTS = [
+    {
+        name: "template-contract",
+        repo: "piotr-iohk/template-contract",
+        description: "Official Midnight template contract",
+    },
+    {
+        name: "tokenomics-project",
+        repo: "piotr-iohk/tokenomics-project",
+        description: "Token implementation example",
+    },
+    {
+        name: "zswap-example",
+        repo: "piotr-iohk/zswap-example",
+        description: "Privacy-preserving swap example",
+    },
+    {
+        name: "reentrancy-example",
+        repo: "piotr-iohk/reentrancy-example",
+        description: "Cross-contract call patterns",
+    },
+];
+/**
+ * Get the version info as a string for display
+ */
+export function getVersionInfo() {
+    return `Compact ${COMPACT_VERSION.min}-${COMPACT_VERSION.max} (updated ${COMPACT_VERSION.lastUpdated})`;
+}
+/**
+ * Check if a version is within supported range
+ */
+export function isVersionSupported(version) {
+    const [major, minor] = version.split(".").map(Number);
+    const [minMajor, minMinor] = COMPACT_VERSION.min.split(".").map(Number);
+    const [maxMajor, maxMinor] = COMPACT_VERSION.max.split(".").map(Number);
+    const versionNum = major * 100 + minor;
+    const minNum = minMajor * 100 + minMinor;
+    const maxNum = maxMajor * 100 + maxMinor;
+    return versionNum >= minNum && versionNum <= maxNum;
+}
+//# sourceMappingURL=compact-version.js.map

package/dist/prompts/templates.js

@@ -128,6 +128,35 @@ function generateCreateContractPrompt(args) {
 **Privacy Level:** ${privacyLevel}
 **Complexity:** ${complexity}
 
+## ⚠️ MANDATORY WORKFLOW - Follow these steps IN ORDER:
+
+### Step 1: Get Current Syntax
+Call \`midnight-get-latest-syntax\` FIRST to get:
+- The \`quickStartTemplate\` (use as your base)
+- The \`commonMistakes\` array (avoid these errors)
+- Current pragma format: \`pragma language_version >= 0.16 && <= 0.18;\`
+
+### Step 2: Generate Contract
+Based on syntax reference, generate the contract using:
+- Individual ledger declarations: \`export ledger field: Type;\` (NOT \`ledger { }\` blocks)
+- Empty tuple return: \`circuit fn(): []\` (NOT \`Void\`)
+- Export enums: \`export enum State { ... }\`
+- Wrap witness conditionals: \`if (disclose(witness == value))\`
+
+### Step 3: Validate Before Returning
+Call \`midnight-extract-contract-structure\` with your generated code to check for:
+- deprecated_ledger_block
+- invalid_void_type
+- invalid_pragma_format
+- unexported_enum
+- deprecated_cell_wrapper
+
+If ANY errors are found, fix them before returning the code to the user.
+
+---
+
+## Contract Requirements
+
 Please help me design and implement this contract. Consider:
 
 1. **State Design**
@@ -179,33 +208,57 @@ ${contractCode}
 
 **Focus Areas:** ${focusAreas}
 
+## ⚠️ MANDATORY WORKFLOW:
+
+### Step 1: Validate Syntax
+Call \`midnight-extract-contract-structure\` with the contract code to check for:
+- deprecated_ledger_block (should use \`export ledger field: Type;\`)
+- invalid_void_type (should use \`[]\` not \`Void\`)
+- invalid_pragma_format (should use \`>= 0.16 && <= 0.18\`)
+- unexported_enum (enums need \`export\`)
+- deprecated_cell_wrapper
+
+Report ALL static analysis findings first.
+
+### Step 2: Get Latest Syntax Reference
+If syntax errors are found, call \`midnight-get-latest-syntax\` to get:
+- The \`commonMistakes\` array showing correct patterns
+- Current syntax reference
+
+---
+
 Please analyze:
 
-1. **Security Analysis**
+1. **Static Analysis Results** (from midnight-extract-contract-structure)
+   - Syntax errors found
+   - Deprecated patterns detected
+   - Required fixes
+
+2. **Security Analysis**
    - Input validation
    - Access control
    - State manipulation vulnerabilities
    - Assertion coverage
 
-2. **Privacy Assessment**
+3. **Privacy Assessment**
    - Proper use of @private state
    - Information leakage risks
    - Correct use of disclose() and commit()
    - Privacy guarantees provided
 
-3. **Best Practices**
+4. **Best Practices**
    - Code organization
    - Naming conventions
    - Documentation
    - Error messages
 
-4. **Performance**
+5. **Performance**
    - Circuit complexity
    - State access patterns
    - Optimization opportunities
 
-5. **Recommendations**
-   - Critical issues to fix
+6. **Recommendations**
+   - Critical issues to fix (start with P0 syntax errors)
    - Improvements to consider
    - Alternative approaches
 
@@ -319,25 +372,46 @@ ${contractCode}
 
 **Error/Issue:** ${errorMessage}
 
+## ⚠️ MANDATORY WORKFLOW:
+
+### Step 1: Run Static Analysis
+Call \`midnight-extract-contract-structure\` FIRST to check for common syntax errors:
+- deprecated_ledger_block → should use \`export ledger field: Type;\`
+- invalid_void_type → should use \`[]\` not \`Void\`
+- invalid_pragma_format → should use \`>= 0.16 && <= 0.18\`
+- unexported_enum → enums need \`export\` keyword
+
+### Step 2: Get Correct Syntax
+If syntax errors found, call \`midnight-get-latest-syntax\` to get:
+- The \`commonMistakes\` array with correct patterns
+- Current \`quickStartTemplate\` for reference
+
+---
+
 Please help me debug by:
 
-1. **Identifying the Problem**
+1. **Static Analysis Results**
+   - Run midnight-extract-contract-structure
+   - List all P0 syntax errors found
+   - Show the correct syntax for each error
+
+2. **Identifying the Problem**
    - What's causing the error?
    - Which line(s) are problematic?
 
-2. **Explaining Why**
+3. **Explaining Why**
    - Root cause analysis
    - How Compact/ZK constraints work
 
-3. **Providing a Fix**
-   - Corrected code
+4. **Providing a Fix**
+   - Corrected code (validated against static analysis)
    - Explanation of changes
 
-4. **Preventing Future Issues**
+5. **Preventing Future Issues**
    - Related pitfalls to watch for
    - Testing strategies
 
-5. **Additional Improvements**
+6. **Additional Improvements**
    - Code quality suggestions
    - Best practices`,
             },

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

@@ -11,262 +11,388 @@
  * use the search_docs tool which queries the Vector DB.
  */
 export const EMBEDDED_DOCS = {
-    "midnight://docs/compact-reference": `# Compact Language Quick Reference
+    "midnight://docs/compact-reference": `# Compact Language Syntax Reference (v0.16 - v0.18)
 
-A curated syntax reference for Compact - Midnight's smart contract language.
+> **CRITICAL**: This reference is derived from **actual compiling contracts** in the Midnight ecosystem.
+> Always verify syntax against this reference before generating contracts.
 
-> **Version Note**: This reference is for Compact 0.16+ (current). Some older examples may use deprecated syntax like \`Cell<T>\` wrappers - see "Common Pitfalls" section below.
+## Quick Start Template
 
-## Basic Structure
+Use this as a starting point - it compiles successfully:
 
 \`\`\`compact
-pragma language_version >= 0.14.0;
+pragma language_version >= 0.16 && <= 0.18;
 
-include "std";
+import CompactStandardLibrary;
+
+// Ledger state (individual declarations, NOT a block)
+export ledger counter: Counter;
+export ledger owner: Bytes<32>;
+
+// Witness for private/off-chain data
+witness local_secret_key(): Bytes<32>;
+
+// Circuit (returns [] not Void)
+export circuit increment(): [] {
+  counter.increment(1);
+}
+\`\`\`
+
+---
+
+## 1. Pragma (Version Declaration)
+
+**CORRECT** - use bounded range without patch version:
+\`\`\`compact
+pragma language_version >= 0.16 && <= 0.18;
+\`\`\`
+
+**WRONG** - these will cause parse errors:
+\`\`\`compact
+pragma language_version >= 0.14.0;           // ❌ patch version not needed
+pragma language_version >= 0.16.0 < 0.19.0;  // ❌ wrong operator format
+\`\`\`
+
+---
+
+## 2. Imports
+
+Always import the standard library:
+\`\`\`compact
+import CompactStandardLibrary;
+\`\`\`
+
+For multi-file contracts, use \`include\`:
+\`\`\`compact
+include "types";
+include "ledger";
+include "circuits";
+\`\`\`
+
+---
+
+## 3. Ledger Declarations
+
+**CORRECT** - individual declarations with \`export ledger\`:
+\`\`\`compact
+export ledger counter: Counter;
+export ledger owner: Bytes<32>;
+export ledger balances: Map<Bytes<32>, Uint<64>>;
+
+// Private state (off-chain only)
+ledger secretValue: Field;  // no export = private
+\`\`\`
 
+**WRONG** - block syntax is deprecated:
+\`\`\`compact
+// ❌ This causes parse error: found "{" looking for an identifier
 ledger {
-  // Public state (on-chain, visible to everyone)
   counter: Counter;
-  
-  // Private state (off-chain, only owner can see)
-  @private
-  secretValue: Field;
+  owner: Bytes<32>;
 }
+\`\`\`
 
-// Circuit - generates ZK proof
-export circuit increment(amount: Field): Void {
-  assert(amount > 0);
-  ledger.counter.increment(amount);
-}
+### Ledger Modifiers
 
-// Witness - off-chain computation
-witness getSecret(): Field {
-  return ledger.secretValue;
-}
+\`\`\`compact
+export ledger publicData: Field;           // Public, readable by anyone
+export sealed ledger immutableData: Field; // Set once in constructor, cannot change
+ledger privateData: Field;                 // Private, not exported
 \`\`\`
 
-## Data Types
+---
+
+## 4. Data Types
 
 ### Primitive Types
-- \`Field\` - Finite field element (basic numeric type)
-- \`Boolean\` - True or false
-- \`Bytes<N>\` - Fixed-size byte array
-- \`Uint<N>\` - Unsigned integer (N = 8, 16, 32, 64, 128, 256)
+| Type | Description | Example |
+|------|-------------|---------|
+| \`Field\` | Finite field element (basic numeric) | \`amount: Field\` |
+| \`Boolean\` | True or false | \`isActive: Boolean\` |
+| \`Bytes<N>\` | Fixed-size byte array | \`hash: Bytes<32>\` |
+| \`Uint<N>\` | Unsigned integer (N = 8, 16, 32, 64, 128, 256) | \`balance: Uint<64>\` |
+| \`Uint<MIN..MAX>\` | Bounded unsigned integer | \`score: Uint<0..100>\` |
 
 ### Collection Types
-- \`Counter\` - Incrementable/decrementable counter
-- \`Map<K, V>\` - Key-value mapping
-- \`Set<T>\` - Collection of unique values
-- \`Opaque<T>\` - Type-safe wrapper for arbitrary data
-
-## Circuits
-
-Circuits are functions that generate zero-knowledge proofs:
+| Type | Description | Example |
+|------|-------------|---------|
+| \`Counter\` | Incrementable/decrementable | \`count: Counter\` |
+| \`Map<K, V>\` | Key-value mapping | \`Map<Bytes<32>, Uint<64>>\` |
+| \`Set<T>\` | Unique value collection | \`Set<Bytes<32>>\` |
+| \`Vector<N, T>\` | Fixed-size array | \`Vector<3, Field>\` |
+| \`List<T>\` | Dynamic list | \`List<Bytes<32>>\` |
+| \`Maybe<T>\` | Optional value | \`Maybe<Bytes<32>>\` |
+| \`Either<L, R>\` | Union type | \`Either<Field, Bytes<32>>\` |
+| \`Opaque<"type">\` | External type from TypeScript | \`Opaque<"string">\` |
+
+### Custom Types
+
+**Enums** - must use \`export\` to access from TypeScript:
+\`\`\`compact
+export enum GameState { waiting, playing, finished }
+export enum Choice { rock, paper, scissors }
+\`\`\`
 
+**Structs**:
 \`\`\`compact
-export circuit transfer(to: Address, amount: Field): Void {
-  // Assertions create ZK constraints
-  assert(amount > 0);
-  assert(ledger.balance.value() >= amount);
-  
-  // State modifications
-  ledger.balance.decrement(amount);
+export struct PlayerConfig {
+  name: Opaque<"string">,
+  score: Uint<32>,
+  isActive: Boolean,
 }
 \`\`\`
 
-### Key Points:
-- \`export\` makes circuit callable from outside
-- Must be deterministic (same inputs = same outputs)
-- Cannot access external data directly (use witnesses)
-- Assertions become ZK constraints
+---
+
+## 5. Circuits
 
-## Witnesses
+Circuits are on-chain functions that generate ZK proofs.
 
-Witnesses provide off-chain data to circuits:
+**CRITICAL**: Return type is \`[]\` (empty tuple), NOT \`Void\`:
 
 \`\`\`compact
-witness getCurrentPrice(): Field {
-  // This runs off-chain
-  return fetchPrice();
+// CORRECT - returns []
+export circuit increment(): [] {
+  counter.increment(1);
+}
+
+// CORRECT - with parameters
+export circuit transfer(to: Bytes<32>, amount: Uint<64>): [] {
+  assert(amount > 0, "Amount must be positive");
+  // ... logic
+}
+
+// CORRECT - with return value
+export circuit getBalance(addr: Bytes<32>): Uint<64> {
+  return balances.lookup(addr);
 }
 
-export circuit buyAtMarketPrice(maxPrice: Field): Void {
-  const price = getCurrentPrice();
-  assert(price <= maxPrice);
-  // ... execute purchase
+// WRONG - Void does not exist
+export circuit broken(): Void {  // ❌ Parse error
+  counter.increment(1);
 }
 \`\`\`
 
-### Key Points:
-- Run locally, not on-chain
-- Can access external APIs, databases
-- Cannot modify ledger state directly
-- Results are private unless disclosed
+### Circuit Modifiers
 
-## State Management
+\`\`\`compact
+export circuit publicFn(): []      // Callable externally
+circuit internalFn(): []           // Internal only, not exported
+export pure circuit hash(x: Field): Bytes<32>  // No state access
+\`\`\`
+
+---
+
+## 6. Witnesses
+
+Witnesses provide off-chain/private data to circuits. They run locally, not on-chain.
 
-### Public State
 \`\`\`compact
-ledger {
-  publicCounter: Counter;
-  publicMap: Map<Field, Field>;
-}
+// Basic witness - returns private data
+witness local_secret_key(): Bytes<32>;
+
+// Witness with parameters
+witness get_merkle_path(leaf: Bytes<32>): MerkleTreePath<10, Bytes<32>>;
+
+// Witness that returns nothing (side effect only)
+witness store_locally(data: Field): [];
+
+// Witness returning optional
+witness find_user(id: Bytes<32>): Maybe<UserData>;
 \`\`\`
 
-### Private State
+---
+
+## 7. Constructor
+
+Optional - initializes sealed ledger fields at deploy time:
+
 \`\`\`compact
-ledger {
-  @private
-  secretBalance: Field;
-  
-  @private
-  hiddenVotes: Map<Address, Field>;
+export sealed ledger owner: Bytes<32>;
+export sealed ledger nonce: Bytes<32>;
+
+constructor(initNonce: Bytes<32>) {
+  owner = disclose(public_key(local_secret_key()));
+  nonce = disclose(initNonce);
 }
 \`\`\`
 
-## Common Patterns
+---
 
-### Access Control
+## 8. Common Patterns
+
+### Authentication Pattern
 \`\`\`compact
-ledger {
-  owner: Opaque<"address">;
-}
+witness local_secret_key(): Bytes<32>;
 
-witness getCaller(): Opaque<"address"> {
-  return context.caller;
+circuit get_public_key(sk: Bytes<32>): Bytes<32> {
+  return persistentHash<Vector<2, Bytes<32>>>([pad(32, "myapp:pk:"), sk]);
 }
 
-export circuit ownerOnly(): Void {
-  assert(getCaller() == ledger.owner, "Not owner");
+export circuit authenticated_action(): [] {
+  const sk = local_secret_key();
+  const caller = get_public_key(sk);
+  assert(disclose(caller == owner), "Not authorized");
+  // ... action
 }
 \`\`\`
 
-### Disclosure
+### Commit-Reveal Pattern
 \`\`\`compact
-export circuit revealSecret(): Field {
-  const secret = getPrivateData();
-  return disclose(secret); // Makes private data public
+export ledger commitment: Bytes<32>;
+export ledger revealed: Boolean;
+
+witness get_stored_value(): Field;
+witness store_value(v: Field): [];
+
+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
+  ]));
+}
+
+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;
+  return disclose(value);
 }
 \`\`\`
 
-### Disclosure in Conditionals (IMPORTANT)
-When using witness values in if/else conditions, you MUST explicitly disclose the comparison result:
+### Disclosure in Conditionals
+When branching on witness values, wrap comparisons in \`disclose()\`:
 
 \`\`\`compact
-// ❌ WRONG - compiler error: "potential witness-value disclosure must be declared"
-witness getSecret(): Field { return 42; }
-export circuit checkValue(guess: Field): Boolean {
-  const secret = getSecret();
-  if (guess == secret) {  // ERROR: implicit disclosure
+// CORRECT
+export circuit check(guess: Field): Boolean {
+  const secret = get_secret();  // witness
+  if (disclose(guess == secret)) {
     return true;
   }
   return false;
 }
 
-// ✅ CORRECT - wrap comparison in disclose()
-export circuit checkValue(guess: Field): Boolean {
-  const secret = getSecret();
-  if (disclose(guess == secret)) {  // Explicitly acknowledge disclosure
+// WRONG - will not compile
+export circuit check_broken(guess: Field): Boolean {
+  const secret = get_secret();
+  if (guess == secret) {  // ❌ implicit disclosure error
     return true;
   }
   return false;
 }
-
-// ✅ Multiple comparisons
-export circuit giveHint(guess: Field): Hint {
-  const secret = getSecret();
-  if (disclose(guess == secret)) {
-    return Hint.correct;
-  } else if (disclose(guess > secret)) {
-    return Hint.too_high;
-  } else {
-    return Hint.too_low;
-  }
-}
 \`\`\`
 
-**Why?** When you branch on a comparison involving private (witness) values, the boolean result becomes observable on-chain. Compact requires explicit acknowledgment via \`disclose()\` to prevent accidental privacy leaks.
+---
 
-### Assertions
+## 9. Common Operations
+
+### Counter Operations
 \`\`\`compact
-assert(condition);                    // Basic assertion
-assert(condition, "Error message");   // With message
+counter.increment(1);
+counter.decrement(1);
+const val = counter.value();  // Note: returns as Field
 \`\`\`
 
-## Common Pitfalls & Solutions
-
-### 1. Cell<T> Wrapper (Deprecated)
+### Map Operations
 \`\`\`compact
-// ❌ OLD SYNTAX (pre-0.15) - causes "unbound identifier Cell"
-export ledger myValue: Cell<Field>;
-myValue.write(42);
-const x = myValue.read();
-
-// ✅ CURRENT SYNTAX (0.16+) - direct declaration
-export ledger myValue: Field;
-myValue = 42;
-const x = myValue;
+balances.insert(address, 100);
+const balance = balances.lookup(address);
+const exists = balances.member(address);
 \`\`\`
 
-### 2. Opaque String Assignment
+### Set Operations
 \`\`\`compact
-// ❌ WRONG - cannot assign string literals to Opaque
-export ledger message: Opaque<"string">;
-export circuit setMessage(): Void {
-  message = "hello";  // ERROR!
-}
+members.insert(address);
+const isMember = members.member(address);
+\`\`\`
 
-// ✅ CORRECT - use enum for fixed values
-export enum Status { pending, approved, rejected }
-export ledger status: Status;
-export circuit setStatus(): Void {
-  status = Status.approved;  // Works!
-}
+### Maybe Operations
+\`\`\`compact
+const opt: Maybe<Field> = some<Field>(42);
+const empty: Maybe<Field> = none<Field>();
 
-// ✅ Or receive Opaque from parameter/witness
-export circuit setMessage(msg: Opaque<"string">): Void {
-  message = msg;  // msg comes from TypeScript
+if (opt.is_some) {
+  const val = opt.value;
 }
 \`\`\`
 
-### 3. Counter vs Field
+### Type Casting
 \`\`\`compact
-// Counter has special methods
-export ledger count: Counter;
-count.increment(1);
-count.decrement(1);
-const val = count.value();
-
-// Field uses direct assignment
-export ledger amount: Field;
-amount = amount + 1;
-const val = amount;
+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
 \`\`\`
 
-### 4. Map Initialization
+### Hashing
 \`\`\`compact
-// Maps don't need initialization
-export ledger balances: Map<Bytes<32>, Field>;
+// Persistent hash (same input = same output across calls)
+const hash = persistentHash<Vector<2, Bytes<32>>>([data1, data2]);
 
-// Access with .member()
-const balance = balances.member(address);
-balances.insert(address, 100);
+// Transient hash (includes randomness)  
+const commit = transientCommit<Field>(value, randomness);
 \`\`\`
 
-### 5. Boolean Returns with Witnesses
+---
+
+## 10. Assertions
+
 \`\`\`compact
-// ❌ WRONG - returns private boolean without disclosure
-export circuit isOwner(): Boolean {
-  const caller = getCaller();  // witness
-  return caller == owner;      // ERROR: undisclosed
-}
+assert(condition, "Error message");
+assert(amount > 0, "Amount must be positive");
+assert(disclose(caller == owner), "Not authorized");
+\`\`\`
 
-// ✅ CORRECT - disclose the result
-export circuit isOwner(): Boolean {
-  const caller = getCaller();
-  return disclose(caller == owner);
-}
+---
+
+## 11. Common Mistakes to Avoid
+
+| Mistake | Correct |
+|---------|---------|
+| \`ledger { field: Type; }\` | \`export ledger field: Type;\` |
+| \`circuit fn(): Void\` | \`circuit fn(): []\` |
+| \`pragma >= 0.16.0\` | \`pragma >= 0.16 && <= 0.18\` |
+| \`enum State { ... }\` | \`export enum State { ... }\` |
+| \`if (witness_val == x)\` | \`if (disclose(witness_val == x))\` |
+| \`Cell<Field>\` | \`Field\` (Cell is deprecated) |
+| \`myValue.read()\` / \`.write()\` | Direct assignment: \`myValue = x\` |
+
+---
+
+## 12. Exports for TypeScript
+
+To use types/values in TypeScript, they must be exported:
+
+\`\`\`compact
+// These are accessible from TypeScript
+export enum GameState { waiting, playing }
+export struct Config { value: Field }
+export ledger counter: Counter;
+export circuit play(): []
+
+// Standard library re-exports (if needed in TS)
+export { Maybe, Either, CoinInfo };
 \`\`\`
+
+---
+
+## Reference Contracts
+
+These contracts compile successfully and demonstrate correct patterns:
+
+1. **Counter** (beginner): \`midnightntwrk/example-counter\`
+2. **Bulletin Board** (intermediate): \`midnightntwrk/example-bboard\`  
+3. **Naval Battle Game** (advanced): \`ErickRomeroDev/naval-battle-game_v2\`
+4. **Sea Battle** (advanced): \`bricktowers/midnight-seabattle\`
+
+When in doubt, reference these repos for working syntax.
 `,
     "midnight://docs/sdk-api": `# Midnight TypeScript SDK Quick Reference
 

package/dist/server.d.ts

@@ -8,6 +8,10 @@ export declare function getUpdateWarning(): string | null;
  * Clear all subscriptions (useful for server restart/testing)
  */
 export declare function clearSubscriptions(): void;
+/**
+ * Mark server as connected (safe to send notifications)
+ */
+export declare function setServerConnected(connected: boolean): void;
 /**
  * Send a log message to the MCP client
  * This allows clients to see server logs for debugging

package/dist/server.js

@@ -8,7 +8,7 @@ import { allResources, getDocumentation, getCode, getSchema, } from "./resources
 import { promptDefinitions, generatePrompt } from "./prompts/index.js";
 import { registerSamplingCallback } from "./services/index.js";
 // Server information - version should match package.json
-const CURRENT_VERSION = "0.1.32";
+const CURRENT_VERSION = "0.1.33";
 const SERVER_INFO = {
     name: "midnight-mcp",
     version: CURRENT_VERSION,
@@ -101,12 +101,21 @@ const resourceTemplates = [
 let mcpLogLevel = "info";
 // Server instance for sending notifications
 let serverInstance = null;
+// Track if server is connected (can send notifications)
+let isConnected = false;
+/**
+ * Mark server as connected (safe to send notifications)
+ */
+export function setServerConnected(connected) {
+    isConnected = connected;
+}
 /**
  * Send a log message to the MCP client
  * This allows clients to see server logs for debugging
  */
 export function sendLogToClient(level, loggerName, data) {
-    if (!serverInstance)
+    // Only send if server exists AND is connected
+    if (!serverInstance || !isConnected)
         return;
     // Map levels to numeric values for comparison
     const levelValues = {
@@ -667,6 +676,8 @@ export async function startServer() {
     const server = await initializeServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // Now safe to send notifications
+    setServerConnected(true);
     logger.info("Midnight MCP Server running on stdio");
 }
 //# sourceMappingURL=server.js.map

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

@@ -158,13 +158,29 @@ export declare function compareSyntax(input: CompareSyntaxInput): Promise<{
  * This is the source of truth for writing valid, compilable contracts
  */
 export declare function getLatestSyntax(input: GetLatestSyntaxInput): Promise<{
+    quickStartTemplate: string;
+    commonMistakes: {
+        wrong: string;
+        correct: string;
+        error: string;
+    }[];
     syntaxReference: string;
     sections: string[];
-    pitfalls: string[];
+    referenceContracts: {
+        name: string;
+        repo: string;
+        description: string;
+    }[];
     note: string;
     versionWarning?: string | undefined;
     repository: string;
     version: string;
+    versionConfig: {
+        min: string;
+        max: string;
+        lastUpdated: string;
+        maintenanceGuide: string;
+    };
     warning?: undefined;
     syntaxFiles?: undefined;
     examplePaths?: undefined;

package/dist/tools/repository/handlers.js

@@ -8,6 +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";
 // Re-export validation handlers from validation.ts
 export { extractContractStructure } from "./validation.js";
 /**
@@ -310,7 +311,7 @@ export async function getLatestSyntax(input) {
     if (repoName === "compact" || repoName === "midnight-compact") {
         const compactReference = EMBEDDED_DOCS["midnight://docs/compact-reference"];
         // Check if there's a newer release we might not have documented
-        const EMBEDDED_DOCS_VERSION = "0.16"; // Version our docs are based on
+        // Version config is centralized in src/config/compact-version.ts
         let versionWarning;
         try {
             const versionInfo = await releaseTracker.getVersionInfo("midnightntwrk", "compact");
@@ -322,12 +323,9 @@ export async function getLatestSyntax(input) {
                     .split(".")
                     .slice(0, 2)
                     .join(".");
-                const embeddedMajorMinor = EMBEDDED_DOCS_VERSION.split(".")
-                    .slice(0, 2)
-                    .join(".");
-                if (latestVersion !== embeddedMajorMinor &&
-                    parseFloat(latestVersion) > parseFloat(embeddedMajorMinor)) {
-                    versionWarning = `⚠️ Compact ${latestTag} is available. This reference is based on ${EMBEDDED_DOCS_VERSION}. Some syntax may have changed - check release notes for breaking changes.`;
+                if (latestVersion !== COMPACT_VERSION.max &&
+                    parseFloat(latestVersion) > parseFloat(COMPACT_VERSION.max)) {
+                    versionWarning = `⚠️ Compact ${latestTag} is available. This reference is based on ${COMPACT_VERSION.max}. Some syntax may have changed - check release notes for breaking changes. See docs/SYNTAX_MAINTENANCE.md for update instructions.`;
                 }
             }
         }
@@ -337,27 +335,83 @@ export async function getLatestSyntax(input) {
         if (compactReference) {
             return {
                 repository: "midnightntwrk/compact",
-                version: "0.16+ (current)",
+                version: `${COMPACT_VERSION.min}-${COMPACT_VERSION.max} (current)`,
+                versionConfig: {
+                    min: COMPACT_VERSION.min,
+                    max: COMPACT_VERSION.max,
+                    lastUpdated: COMPACT_VERSION.lastUpdated,
+                    maintenanceGuide: "See docs/SYNTAX_MAINTENANCE.md for update instructions",
+                },
                 ...(versionWarning && { versionWarning }),
+                // Quick start template - ALWAYS compiles
+                quickStartTemplate: `${RECOMMENDED_PRAGMA}
+
+import CompactStandardLibrary;
+
+export ledger counter: Counter;
+export ledger owner: Bytes<32>;
+
+witness local_secret_key(): Bytes<32>;
+
+export circuit increment(): [] {
+  counter.increment(1);
+}`,
+                // Common mistakes that cause compilation failures
+                commonMistakes: [
+                    {
+                        wrong: "ledger { field: Type; }",
+                        correct: "export ledger field: Type;",
+                        error: 'parse error: found "{" looking for an identifier',
+                    },
+                    {
+                        wrong: "circuit fn(): Void",
+                        correct: "circuit fn(): []",
+                        error: 'parse error: found "{" looking for ";"',
+                    },
+                    {
+                        wrong: "pragma language_version >= 0.14.0;",
+                        correct: RECOMMENDED_PRAGMA,
+                        error: "version mismatch or parse error",
+                    },
+                    {
+                        wrong: "enum State { a, b }",
+                        correct: "export enum State { a, b }",
+                        error: "enum not accessible from TypeScript",
+                    },
+                    {
+                        wrong: "if (witness_val == x)",
+                        correct: "if (disclose(witness_val == x))",
+                        error: "implicit disclosure error",
+                    },
+                    {
+                        wrong: "Cell<Field>",
+                        correct: "Field",
+                        error: "unbound identifier Cell (deprecated)",
+                    },
+                ],
                 syntaxReference: compactReference,
                 sections: [
-                    "Basic Structure",
+                    "Quick Start Template",
+                    "Pragma (Version Declaration)",
+                    "Imports",
+                    "Ledger Declarations",
                     "Data Types",
                     "Circuits",
                     "Witnesses",
-                    "State Management",
+                    "Constructor",
                     "Common Patterns",
-                    "Disclosure in Conditionals (IMPORTANT)",
-                    "Common Pitfalls & Solutions",
-                ],
-                pitfalls: [
-                    "Cell<T> wrapper deprecated in 0.15+ - use direct type",
-                    'Cannot assign string literals to Opaque<"string"> - use enum or parameters',
-                    "Must disclose() comparisons used in if/else conditions",
-                    "Counter uses .increment()/.value(), Field uses direct assignment",
-                    "Boolean returns from witnesses need disclose()",
+                    "Common Operations",
+                    "Assertions",
+                    "Common Mistakes to Avoid",
+                    "Exports for TypeScript",
+                    "Reference Contracts",
                 ],
-                note: "This is the curated syntax reference for Compact 0.16+. Includes common pitfalls and correct patterns.",
+                referenceContracts: REFERENCE_CONTRACTS.map((rc) => ({
+                    name: rc.name,
+                    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}).`,
             };
         }
     }

package/dist/tools/repository/tools.js

@@ -359,10 +359,12 @@ export const repositoryTools = [
     {
         name: "midnight-extract-contract-structure",
         description: "Extract and analyze Compact contract structure (circuits, witnesses, ledger). " +
-            "Detects common issues: module-level const, stdlib name collisions, if-expression in assignments, Void return type, " +
-            "Counter.value access, division operator, missing disclose() calls. " +
-            "Use for understanding contract structure and catching common syntax mistakes. " +
-            "Note: This is static analysis - it catches common patterns but cannot verify semantic correctness.",
+            "CRITICAL CHECKS: deprecated 'ledger { }' block syntax, 'Void' return type (should be []), " +
+            "old pragma format, unexported enums, deprecated Cell<T> wrapper. " +
+            "Also detects: module-level const, stdlib name collisions, division operator, " +
+            "Counter.value access, missing disclose() calls, potential overflow. " +
+            "Use BEFORE generating contracts to catch syntax errors. " +
+            "Note: Static analysis only - catches common patterns but not semantic errors.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/tools/repository/validation.js

@@ -440,6 +440,77 @@ export async function extractContractStructure(input) {
         "Opaque",
         "Vector",
     ];
+    // ========== CRITICAL SYNTAX CHECKS (P0 - causes immediate compilation failure) ==========
+    // P0-1. Detect deprecated ledger block syntax
+    const ledgerBlockPattern = /ledger\s*\{/g;
+    let ledgerBlockMatch;
+    while ((ledgerBlockMatch = ledgerBlockPattern.exec(code)) !== null) {
+        const lineNum = lineByIndex[ledgerBlockMatch.index] || 1;
+        potentialIssues.push({
+            type: "deprecated_ledger_block",
+            line: lineNum,
+            message: `Deprecated ledger block syntax 'ledger { }' - causes parse error`,
+            suggestion: `Use individual declarations: 'export ledger fieldName: Type;'`,
+            severity: "error",
+        });
+    }
+    // P0-2. Detect Void return type (doesn't exist in Compact)
+    const voidReturnPattern = /circuit\s+\w+\s*\([^)]*\)\s*:\s*Void\b/g;
+    let voidMatch;
+    while ((voidMatch = voidReturnPattern.exec(code)) !== null) {
+        const lineNum = lineByIndex[voidMatch.index] || 1;
+        potentialIssues.push({
+            type: "invalid_void_type",
+            line: lineNum,
+            message: `Invalid return type 'Void' - Void does not exist in Compact`,
+            suggestion: `Use '[]' (empty tuple) for circuits that return nothing: 'circuit fn(): []'`,
+            severity: "error",
+        });
+    }
+    // P0-3. Detect old pragma format with patch version
+    const oldPragmaPattern = /pragma\s+language_version\s*>=?\s*\d+\.\d+\.\d+/g;
+    let oldPragmaMatch;
+    while ((oldPragmaMatch = oldPragmaPattern.exec(code)) !== null) {
+        const lineNum = lineByIndex[oldPragmaMatch.index] || 1;
+        potentialIssues.push({
+            type: "invalid_pragma_format",
+            line: lineNum,
+            message: `Pragma includes patch version which may cause parse errors`,
+            suggestion: `Use bounded range format: 'pragma language_version >= 0.16 && <= 0.18;'`,
+            severity: "error",
+        });
+    }
+    // P0-4. Detect missing export on enums (won't be accessible from TypeScript)
+    const unexportedEnumPattern = /(?<!export\s+)enum\s+(\w+)\s*\{/g;
+    let unexportedEnumMatch;
+    while ((unexportedEnumMatch = unexportedEnumPattern.exec(code)) !== null) {
+        // Double check it's not preceded by export
+        const before = code.substring(Math.max(0, unexportedEnumMatch.index - 10), unexportedEnumMatch.index);
+        if (!before.includes("export")) {
+            const lineNum = lineByIndex[unexportedEnumMatch.index] || 1;
+            potentialIssues.push({
+                type: "unexported_enum",
+                line: lineNum,
+                message: `Enum '${unexportedEnumMatch[1]}' is not exported - won't be accessible from TypeScript`,
+                suggestion: `Add 'export' keyword: 'export enum ${unexportedEnumMatch[1]} { ... }'`,
+                severity: "warning",
+            });
+        }
+    }
+    // P0-5. Detect Cell<T> wrapper (deprecated since 0.15)
+    const cellPattern = /Cell\s*<\s*\w+\s*>/g;
+    let cellMatch;
+    while ((cellMatch = cellPattern.exec(code)) !== null) {
+        const lineNum = lineByIndex[cellMatch.index] || 1;
+        potentialIssues.push({
+            type: "deprecated_cell_wrapper",
+            line: lineNum,
+            message: `'Cell<T>' wrapper is deprecated since Compact 0.15`,
+            suggestion: `Use the type directly: 'Field' instead of 'Cell<Field>'`,
+            severity: "error",
+        });
+    }
+    // ========== EXISTING CHECKS ==========
     // 1. Detect module-level const (not supported in Compact)
     const constPattern = /^const\s+(\w+)\s*:/gm;
     let constMatch;
@@ -693,19 +764,7 @@ export async function extractContractStructure(input) {
             severity: "error",
         });
     }
-    // 12. Detect "Void" return type (should use [] empty tuple)
-    const voidReturnPattern = /circuit\s+\w+\s*\([^)]*\)\s*:\s*Void\b/g;
-    let voidMatch;
-    while ((voidMatch = voidReturnPattern.exec(code)) !== null) {
-        const lineNum = lineByIndex[voidMatch.index] || 1;
-        potentialIssues.push({
-            type: "invalid_void_type",
-            line: lineNum,
-            message: `'Void' is not a valid type in Compact`,
-            suggestion: `Use empty tuple '[]' for circuits with no return value: 'circuit name(): []'`,
-            severity: "error",
-        });
-    }
+    // 12. (Moved to P0-2 above - Void return type check)
     const summary = [];
     if (circuits.length > 0) {
         summary.push(`${circuits.length} circuit(s)`);

package/package.json

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