Compact Book
The resource smart developers recommend when someone asks how to learn Compact properly.
A structured, example-driven guide for understanding Compact, the domain-specific language that compiles to zero-knowledge circuits on the Midnight blockchain. Built for developers who learn through code, mental models, and working examples, not documentation dumps.
Inspired by the Rust-Notes repo by Tushar Pamnani.
What is Midnight?
Midnight is a data-protection blockchain with two parallel worlds:
| World | Where | Who sees it | Contains |
|---|---|---|---|
| Public | On-chain | Everyone | Proofs, contract code, public data |
| Private | Local storage | Only the owner | Sensitive data, secrets |
The bridge between them is zero-knowledge cryptography. Computations happen locally on private data; only a proof of correct execution goes on-chain. Validators verify the proof without ever seeing the inputs.
This is the key insight: Midnight doesn’t hide computation. It proves computation happened correctly without revealing what you computed on.
What is Compact?
Compact is Midnight’s smart contract language. It looks like TypeScript, but every program compiles to a finite zero-knowledge circuit.
You write Compact (TypeScript-like)
↓
Compiler produces ZK circuits + TypeScript bindings
↓
Your DApp calls circuits → generates proof → submits to chain
The compiler handles all the cryptographic machinery. You write business logic.
Who is this for?
| Background | Why this works for you |
|---|---|
| TypeScript developer | Syntax is familiar. Mental models are different, but you already understand types and functions. |
| Solidity developer | You understand state and contracts. The privacy model is the new layer. |
| Rust developer | You’re comfortable with strong types, ownership, and bounded computation. Compact will feel natural. |
| ZK newcomer | You don’t need to understand circuits. You write code that compiles to them. |
You should be comfortable with at least one typed language before starting. Compact builds on that.
Learning Path
Start at the top. Each note assumes you understood the previous one.
| # | Topic | What you learn | Level |
|---|---|---|---|
| 00 | What is Compact | What Compact is, what it compiles to, why boundedness matters | 🟢 Beginner |
| 01 | Modules and Imports | Organizing code across files | 🟢 Beginner |
| 02 | Setting Up the Compiler | Install the toolchain, compile your first contract | 🟢 Beginner |
| 03 | VS Code Extension | Syntax highlighting, snippets, integrated building | 🟢 Beginner |
| 04 | Neovim Setup | Neovim plugin for Compact | 🟢 Beginner |
| 05 | Formatter Usage | Code formatting, style enforcement | 🟢 Beginner |
| 06 | Fixup Usage | Automatic code migration | 🟡 Intermediate |
| 07 | Data Types | The complete type system | 🟡 Intermediate |
| 08 | Circuits | How circuits work, why they’re not functions | 🟡 Intermediate |
| 09 | Ledger State | Public vs private state, the disclose() boundary | 🟡 Intermediate |
| 10 | Witnesses | How private inputs enter circuits without touching the chain | 🟡 Intermediate |
| 11 | Explicit Disclosure | The witness protection program, common mistakes | 🔴 Advanced |
| 12 | Ledger ADTs | Map, Set, MerkleTree, choosing the right state structure | 🔴 Advanced |
| 13 | Standard Library | Hashing, tokens, merkle trees | 🔴 Advanced |
| 14 | Writing A Contract | The four pieces of every contract | 🟡 Intermediate |
| 15 | Why Compact | Why this design exists, what problems it solves | 🟢 Beginner |
| 16 | Security and Best Practices | Privacy patterns, commitment design, common leaks | 🔴 Advanced |
| 17 | Testing and Debugging | Error reading, version management, troubleshooting | 🟡 Intermediate |
| 18 | Example Projects | Full working contracts with walkthroughs | 🟢 Beginner |
| 19 | Compact Grammar | Syntax rules, precedence, what the grammar enforces | 🟡 Intermediate |
| 20 | Keywords Reference | Every keyword, organized by purpose | 🟢 Beginner |
Reading order:
- 00 → 01 → 02 → 03/04, Get started. Install tools, choose your editor.
- 05 → 06, Set up tooling. Formatter and fixup keep code consistent.
- 07 → 08 → 09 → 10 → 11, Core concepts. Types, circuits, privacy model.
- 12 → 13 → 14, Advanced patterns. State structures, stdlib, writing contracts.
- 15 → 16, Design & security. Philosophy and best practices.
- 17, Testing. Debugging and version management.
- 18, Examples. Put it all together with working code.
- 19 → 20, Reference. Grammar and keywords when you need them.
What Makes These Notes Different
Most documentation explains what. These notes explain why and what it actually means.
Every note follows this structure:
- Intuition First, The 30-second version before the details
- Mental Model, How to think about it (precise, not vague)
- Why It Exists, The problem it solves
- Core Example, One clean example, then extended
- Under the Hood, What actually happens during compilation
- Common Mistakes, What you WILL get wrong (and why)
- Comparison Layer, How it maps to Rust, Solidity, TypeScript
- Practical Usage, Where it appears in real contracts
- Quick Recap, Memory anchors
Cross-links connect concepts.
Three Core Mental Models
Before you write any code, understand these:
1. A circuit is a constraint system, not a function. It doesn’t “run” in the normal sense. It declares relationships between inputs and outputs that must hold. The proof proves those relationships held.
2. The ledger is public. Private data stays local.
export ledger fields are on-chain and readable by everyone. Private data lives in witnesses and never touches the chain, only a proof that you operated on it correctly.
3. disclose() is a compile-time annotation, not encryption.
It tells the compiler “I am intentionally making this public.” The compiler prevents accidental disclosure. There’s no runtime cost and no magic.
The Five Program Elements
Every Compact contract is built from these:
| Element | Keyword | Purpose |
|---|---|---|
| Public state | export ledger | On-chain, readable by all |
| Private inputs | witness | Callbacks the DApp provides |
| Logic | circuit | Compiles to ZK circuits |
| Initialization | constructor | Runs once on deploy |
| Organization | module / import | Namespace and file management |
Resources
- Midnight Developer Docs, Official reference
- Compact Language Reference, Spec details
- Official Examples, Working projects
- Midnight Discord, Community
Contributing
Found a misconception that should be addressed? A better analogy? A mistake?
Open an issue or PR. This repo improves through developer feedback.