compact-core:compact-debugging

Compact Contract Debugging

Overview

Core principle: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

Debugging flow: Don't guess → Hypothesize → Instrument → Reproduce → Analyze → Fix → Verify.

This skill is process orchestration — it routes to existing compact-core skills for domain knowledge and does NOT duplicate their content.

Early Triage Fork

First determine: "Is this a code bug or a compatibility issue?"

Code bug indicators:

• Compiler error with specific line/char reference
• Logic error in circuit behavior
• Type mismatch in contract code
• Disclosure error

Compatibility issue indicators:

• "Worked before, broke after update"
• Deployment succeeds but runtime rejects
• SDK types don't match generated types
• Proof server rejects valid proof
• Version mismatch mentioned

If compatibility: fetch live support matrix from midnightntwrk/midnight-docs (docs/relnotes/support-matrix.mdx), compare against installed versions. Recommend /midnight-tooling:doctor for automated diagnostics.

Functional Area	Components
Network	Node
Runtime & Contracts	Compact Compiler, Compact Runtime, Compact JS, On-chain Runtime, Ledger
SDKs & APIs	Wallet SDK, Midnight.js, DApp Connector API
Indexing & Data	Midnight Indexer
ZK & Proving	Proof Server

If code bug: proceed to triage table.

Step 0 — Mechanical Verification Baseline

Before any investigation, run /midnight-verify:verify on the contract:

/midnight-verify:verify <file.compact>

If the issue involves witnesses:

/midnight-verify:verify <contract.compact> <witnesses.ts>

The verification result immediately narrows the problem space:

• Compilation failure → the issue is in the Compact source (proceed to triage table with compiler error)
• Type check failure → the witness types don't match the contract (check type mappings)
• Structural check failure → witness patterns are wrong (name mismatch, missing tuple wrapper, etc.)
• Execution failure → the contract logic fails at runtime (proceed to hypothesis phase)
• All pass → the contract is mechanically correct; the issue may be environmental or integration-related

If /midnight-verify:verify identifies the issue directly, present the finding — no further investigation may be needed.

Symptom-Driven Triage Table

Symptom	Route To Skill	Investigation Phase
parse error: found...	compact-language-ref (troubleshooting)	Root Cause
unbound identifier	compact-language-ref + compact-standard-library (hallucination traps)	Root Cause
potential witness-value disclosure	compact-privacy-disclosure (debugging-disclosure)	Root Cause
implicit disclosure of witness value	compact-privacy-disclosure (debugging-disclosure)	Root Cause
incompatible combination of types	compact-language-ref (types-and-values)	Root Cause
cannot cast from type	compact-language-ref (types-and-values)	Root Cause
cannot prove assertion	compact-language-ref (troubleshooting, runtime section)	Hypothesis
operation undefined for type	compact-ledger (types-and-operations)	Root Cause
TypeScript type mismatch	compact-witness-ts (type-mappings)	Root Cause
Witness returns unexpected value	compact-witness-ts (witness-implementation)	Hypothesis
Token mint/transfer fails	compact-tokens (token-operations)	Pattern Analysis
MerkleTree proof fails	compact-privacy-disclosure + compact-standard-library	Hypothesis
"Works locally, fails on devnet"	compact-witness-ts (contract-runtime)	Pattern Analysis
Contract deploys but can't query state	Compatibility check (Indexer ↔ Ledger)	Compatibility
Proof generation hangs or fails	Compatibility check (Proof Server ↔ Compiler)	Compatibility
Wallet can't sign transactions	Compatibility check (Wallet SDK ↔ DApp Connector ↔ Midnight.js)	Compatibility
SDK bindings don't match generated types	Compatibility check (Compact JS ↔ Compiler)	Compatibility
Node rejects transaction	Compatibility check (Node ↔ On-chain Runtime)	Compatibility
import not found / module not found	compact-language-ref (modules-and-imports)	Root Cause
Adding disclose() keeps causing new errors	compact-privacy-disclosure (step 5: restructure)	Pattern Analysis
Constructor errors or missing initialization	compact-structure (patterns) + compact-ledger (state-design)	Root Cause
Enum variant access errors	compact-language-ref (troubleshooting)	Root Cause

Investigation Phases

Entered based on triage result, not enforced sequentially.

Phase 1 — Root Cause Investigation

• Read the full error message, including the compiler's path trace if present
• Trace data flow from source (witness/parameter) to error point
• Cross-reference with the routed skill's reference material
• Identify the specific line and expression causing the issue

Phase 2 — Pattern Analysis

• Is this a known pattern from the triage table?
• Have we seen this category of error before in this session?
• Are consecutive failures appearing in different areas? (escalation trigger)
• Check if the issue is structural (design problem) vs. local (typo/oversight)

Phase 3 — Hypothesis and Testing

• Form a specific, testable hypothesis about WHY the error occurs
• State the hypothesis explicitly before attempting any fix
• If compiler available: instrument and verify with skipZk=true
• If not: reason through the hypothesis against the contract logic

Phase 4 — Implementation

• Apply the fix based on confirmed hypothesis
• Verify via compilation (if tools available)
• Audit side effects:
  • For disclose() additions: "What can an on-chain observer learn from this value?"
  • For structural changes: check that other circuits still have access to what they need
  • For type changes: verify downstream cast chains still hold

Silent Fix Tracking

Track every fix attempt internally using this format:

Fix #1: [category] [what was tried] [result: resolved | new error | same error]
Fix #2: ...

Escalation triggers:

• 3+ consecutive fixes revealing new errors in different areas: Surface: "Multiple fixes are uncovering errors in different areas. This may indicate an architectural issue. Before continuing, let's step back and review what we've found so far." Present summary of all attempted fixes and outcomes. Recommend discussing design before further patching.
• Same error category attempted 3+ times: Surface: "We've attempted this category of fix multiple times. Let's reconsider our hypothesis."

Process Violation Detection

Surface a warning (non-blocking) when detecting:

Pattern	Warning
Fix applied without stated hypothesis	"What's our hypothesis for why this will work?"
Same error category failed 3+ times	"We've tried this approach multiple times. Let's reconsider."
Fix in area A causes new error in area B	"This fix introduced a new issue elsewhere. Possible architectural concern."
Rapid successive fix attempts	"Let's slow down and verify our understanding before the next attempt."

Red Flags — Stop Immediately

Stop immediately if the reasoning pattern matches any of the following.

• Applying a quick fix with the intention of investigating later
• Attempting yet another fix after multiple consecutive failures without re-evaluating the approach
• Proceeding with a fix without understanding why it should work
• Trying something without first forming a testable hypothesis
• Dismissing an environment difference without investigating it

If any of these apply: Stop. Return to Phase 1 (Root Cause Investigation) before attempting any fix.

Warning Signs of Deeper Problems

Consecutive fixes revealing new problems in different areas indicates architectural issues: stop patching, document findings, discuss with team, consider design rethink.

Verification Protocol

After every fix:

1. Compile — if tools available, run with skipZk=true. If unavailable, advise manual compilation.
2. Privacy audit — for any disclose() added, trace value to source and document what becomes public.
3. Regression check — verify the fix didn't break other circuits or change intended privacy properties.
4. Update fix tracker — record result for escalation monitoring.

Referenced Skills and Tools

Skills (loaded on demand via triage routing):

• compact-language-ref — compiler errors, syntax, types, troubleshooting
• compact-privacy-disclosure — disclosure errors, privacy patterns, debugging process
• compact-structure — contract anatomy, common mistakes
• compact-standard-library — stdlib verification, hallucination traps
• compact-witness-ts — TypeScript witnesses, type mappings, contract runtime
• compact-ledger — state design, ADT operations
• compact-tokens — token operations, mint/transfer patterns

Cross-plugin references:

• /midnight-tooling:doctor — automated version diagnostics, environment health
• Live support matrix: midnightntwrk/midnight-docs → docs/relnotes/support-matrix.mdx

What This Skill Does NOT Contain

• No compiler error explanations (in compact-language-ref)
• No disclosure debugging steps (in compact-privacy-disclosure)
• No wrong→correct syntax patterns (in compact-structure)
• No hallucination traps (in compact-standard-library)
• No type mapping tables (in compact-witness-ts)

This skill is purely process orchestration + triage routing + fix tracking.