Documenting Compact: Lessons from Midnight's Smart Contract Language

Compact is not Solidity. It's not Rust. It's a purpose-built language for writing zero-knowledge smart contracts on Midnight Network — and documenting it required rethinking how we explain smart contract behavior entirely.

Why Compact is different

Most smart contract languages let you write arbitrary on-chain logic. Compact takes a fundamentally different approach: every operation compiles down to a zero-knowledge circuit. This means:

• No arbitrary loops — circuit size must be deterministic at compile time
• No dynamic memory — data structures are fixed
• Privacy is structural — you don't add privacy to a Compact contract; privacy is the default

For a technical writer, this is both a challenge and an opportunity. The challenge is that most developers arrive with Solidity-shaped mental models. The opportunity is that you can use documentation to reshape those models.

Strategies that worked

Start with what it's NOT

Our Smart Contracts page opens with a clear framing:

DPO2U utilizes the Midnight Network and its Compact language to write smart contracts that guarantee compliance immutability without ever compromising sensitive personal data.

Notice: we don't start with syntax. We start with the guarantee. Developers reading Compact documentation need to understand the "why" before the "how" — otherwise the constraints feel arbitrary.

Use parallel examples

When explaining Compact's contract structure, showing the conceptual equivalent alongside traditional approaches helps bridge the mental model gap:

Traditional approach:        Compact approach:
Store raw data on-chain  →   Store only hashes
Verify in the open       →   Verify via zk-SNARK proof
Public state mutations   →   Private state transitions

This isn't actual code — it's a conceptual comparison. We found that developers grasp Compact's model faster when they can see what was removed from the traditional approach.

Document the contracts as a system

Individual contract documentation is necessary but insufficient. DPO2U has six Compact contracts that form an interconnected system:

1. ComplianceRegistry.compact — the central attestation registry
2. DocumentTimestamp.compact — temporal existence proofs
3. AgentWalletFactory.compact — programmatic wallet creation
4. FeeDistributor.compact — agent compensation
5. Treasury.compact — fund management
6. AgentRegistry.compact — approved agent identities
7. PaymentGateway.compact — client payment interface

Documenting each contract in isolation would miss the point. We structured the documentation to show the flow between contracts — how a payment enters through the Gateway, flows to the Treasury, triggers an Agent, and results in an Attestation stored in the Registry.

The role of diagrams

Mermaid diagrams became essential for communicating contract interactions. A diagram like this conveys in seconds what would take paragraphs of text:

We use the graph LR direction consistently across the docs — left-to-right matches the natural reading direction and the conceptual flow from input to on-chain state.

Takeaways

If you're documenting a novel smart contract language:

1. Start with guarantees, not syntax — the "why" creates the frame for the "how"
2. Bridge from familiar models — show developers what concepts map (and what doesn't)
3. Document the system, not just the units — contracts exist in relationships
4. Use directional diagrams — data flow is the story; let the arrows tell it
5. Maintain a terminology table — novel languages introduce novel terms; be consistent

Compact is still young, and the documentation will evolve as the language matures. But the principles above have held steady as our contract suite has grown from two contracts to six.