An Agent Skill for writing, testing, and deploying Compact smart contracts on the Midnight blockchain. Built from Discord community knowledge, compiler validation, and real-world gotchas. This project extends the Midnight Network with additional developer tooling.
Supports Claude Code, Cursor, Gemini CLI, VS Code Copilot, and 30+ other AI coding assistants.
Important: These examples are educational references. Any smart contract generated using this skill should be professionally audited before deployment to mainnet. AI-assisted code generation does not replace security review.
All examples compiled and tested against Compact 0.30.0 (compact-runtime 0.15.0, ledger v8). Also compatible with Compact 0.29.0 (ledger v7). See gotcha #74 for migration guide.
| Example | Circuits | Tests | Status |
|---|---|---|---|
| Counter | 3 | 5/5 | Validated |
| Bulletin Board | 3 | 8/8 | Validated |
| Fungible Token | 7 | 6/6 | Validated (OZ modules) |
| NFT | 7 | 6/6 | Validated |
| Rock-Paper-Scissors | 3 | 6/6 | Validated |
| Shielded Voting | 6 | 9/9 | Validated |
| Sealed-Bid Auction | 6 | 8/8 | Validated |
| Identity Proof | 4 | 6/6 | Validated |
| Credential Registry | 5 | 6/6 | Validated |
| Prescription | 5 | 6/6 | Validated |
| Escrow | 5 | 8/8 | Validated |
| Time Lock | 3 | 7/7 | Validated |
| Multi-Sig | 6 | 6/6 | Validated |
| Staking | 5 | 6/6 | Validated |
| Crowdfunding | 5 | 6/6 | Validated |
| Lending | 6 | 6/6 | Validated |
| Prediction Market | 5 | 7/7 | Validated |
| Oracle Feed | 5 | 6/6 | Validated |
| Access Control | 8 | 6/6 | Validated |
| DID Registry | 5 | 6/6 | Validated |
| Micro-DAO | 7 | 7/7 | Validated |
| Contract Upgradability | V1: 3, V2: 7 | 8/8 | Validated |
| Token Swap | 6 | — | Preprod deployed |
| Token Minting | 3 | — | Preprod deployed |
| Privacy Mixer | 3 | 7/7 | Validated |
| Lottery | 4 | 8/8 | Validated |
| Vesting | 4 | 8/8 | Validated |
| Revenue Sharing | 3 | 7/7 | Validated |
| Supply Chain | 4 | 7/7 | Validated |
29/29 compile on Compact 0.30.0. 143 circuits. 29/29 simulator-validated on compact-runtime 0.15.0. 6 contracts deployed on v8 preprod.
Token Swap and Token Minting use Zswap coin operations (receiveShielded, sendImmediateShielded, mintToken) that require the full network stack for circuit calls. Both compile and deploy successfully.
6 contracts deployed to Midnight preprod on Ledger v8 (protocol v22000). Representative sample validating all major patterns.
| Contract | Pattern | Circuits | DUST Fee | Deploy Time | Block |
|---|---|---|---|---|---|
| Counter | simplest | 3 | 252B | 17.8s | 114208 |
| Bulletin Board | auth | 2 | 267B | 19.1s | 114211 |
| Sealed-Bid Auction | commit-reveal + state machine | 5 | 554B | 16.9s | 114214 |
| Oracle Feed | time-based | 5 | 504B | 19.0s | 114217 |
| Multi-Sig | multi-party | 6 | 574B | 17.5s | 114220 |
| LOK | token ops (receiveUnshielded) | 4 | 423B | 17.4s | 114223 |
receiveUnshielded (wallet→contract token transfer) confirmed working on v8 — Issue #151 resolved.
30 contracts were previously deployed on Ledger v7 (protocol v21000). Chain state was reset with the v8 upgrade on March 25, 2026.
DUST is Midnight's fee token — generated continuously from tNight. Must register NIGHT UTxOs for dust generation before any deployment (gotcha #75).
- Generation rate: 5 DUST per NIGHT, ~1 week to cap
- Deploy time: 16-22s per contract on preprod
- Practical cost: 1000 tNight from faucet generates ample DUST for dozens of deployments
- Compact language — types, syntax, circuits, witnesses, disclosure, module system
- Privacy model — shielded vs unshielded state, ZK proof flow, witness security
- Security — 10 ZK-specific attack categories with mitigations
- Testing — simulator, standalone network, testnet (3-level testing approach)
- Design patterns — authentication, OZ composition, off-chain computation, circuit optimization
- Off-chain integration — TypeScript SDK, wallet connectivity, provider pattern, deployment
- Gotchas — compiler bugs, SDK pitfalls, proof server issues, design traps (sourced from Discord + real compilation)
- 29 worked examples — core patterns through DeFi, governance, identity, contract upgradability, and supply chain
mkdir -p .claude/skills
git clone https://github.com/adavault/midnight-skill.git .claude/skills/midnight-compactgit clone https://github.com/adavault/midnight-skill.git ~/.claude/skills/midnight-compactThe skill auto-activates on keywords: Midnight, Compact, circuit, witness, ledger, disclose, proof server, DUST, NIGHT, Zswap, shielded.
Or invoke explicitly: /midnight-compact
midnight-skill/
├── SKILL.md # Core skill — workflow, syntax, patterns
├── README.md # This file
├── LICENSE # MIT
├── reference/ # Deep-dive reference documents
│ ├── language.md # Compact types, syntax, modules, operators
│ ├── privacy-model.md # Shielded/unshielded state, ZK proof flow
│ ├── security.md # 10 ZK attack categories and mitigations
│ ├── testing.md # Simulator, standalone, testnet testing
│ ├── patterns.md # Design patterns and circuit optimization
│ ├── stdlib.md # CompactStandardLibrary reference
│ ├── gotchas.md # 79 real-world issues from Discord + compilation
│ ├── offchain.md # TypeScript SDK, wallet, deployment
│ └── auditing.md # ZK contract audit methodology
└── examples/ # Working examples with tests
├── counter.md # Simplest contract — state + increment
├── bulletin-board.md # Witness auth, CRUD, multi-user
├── fungible-token.md # OZ module composition (FT + Ownable + Pausable)
├── nft.md # Commitment-based NFT ownership
├── rock-paper-scissors.md # Commit-reveal 2-player game
├── shielded-voting.md # Commit-reveal private ballot
├── sealed-bid-auction.md # Commit-reveal with state machine
├── identity-proof.md # Selective disclosure, parameterized witnesses
├── credential-registry.md # Nullifier-based double-use prevention
├── prescription.md # Batch registration, nullifier for healthcare
├── escrow.md # Two-party exchange with deadline
├── time-lock.md # Time-based LOK/RELEASE pattern
├── multi-sig.md # M-of-N authorization, composite keys
├── staking.md # Lock period + ZK reward calculation
├── crowdfunding.md # Anonymous backing, ZK refund proofs
├── lending.md # Collateral, health factor, liquidation
├── prediction-market.md # Commitment-based bets, ZK payout
├── oracle-feed.md # External data, freshness checks
├── token-swap.md # Atomic swap (coin operations)
├── access-control.md # Role hierarchy, internal guards
├── did-registry.md # DID document lifecycle management
├── micro-dao.md # Token-gated voting, treasury
├── contract-upgradability.md # V1/V2 migration pattern
├── token-minting.md # Zswap coin creation (mintShieldedToken)
├── privacy-mixer.md # Nullifier-based deposit/withdraw mixer
├── lottery.md # Commit-reveal multi-party randomness
├── vesting.md # Time-based tranche release schedule
├── revenue-sharing.md # Private share allocations, ZK withdrawal
└── supply-chain.md # Selective disclosure provenance tracking
Compiling all examples against the real compiler uncovered several patterns not documented elsewhere:
- No sequence counter for registered key sets — contracts with multi-party key registries (multi-sig, ACL, oracle, identity) must use deterministic keys. A sequence increment invalidates all registered keys.
Uint<N> + literaltype widening —Uint<32> + 1producesUint<0..4294967297>. Fix:(expr + 1) as Uint<32>.- Parameterized witnesses work —
witness fn(param: T): Upasses circuit arguments to TypeScript witnesses as additional function parameters. - Internal circuits can access ledger — non-exported
circuit(notpure circuit) can read/writeexport ledgerstate, enabling reusable guard patterns. - Boolean/literal assignments skip
disclose()— compile-time constants written toexport ledgerdon't need disclosure wrapping.
All findings are documented in gotchas.md (#49-#52) and in each example's Key Concepts section.
The Ledger v8 release (March 2026) introduced significant SDK changes discovered during validation:
- Witness tuple return — witnesses now return
[nextPrivateState, value]instead of justvalue(gotcha #79) - Simulator API —
contract.initialState(ctx, ...args)replacescontract.constructor(ctx)(gotcha #79) - Dust registration required — must call
registerNightUtxosForDustGeneration()before any deployment (gotcha #75) signRecipebug fixed — wallet-sdk-facade 3.0.0 handles proof markers correctly (gotcha #76)nativeToken()trap — useunshieldedToken().rawfrom ledger-v7 for balance lookups (gotcha #77)- Private state encryption —
levelPrivateStateProvidernow requires encryption config (gotcha #78)
Built from:
- Midnight Discord dev-chat (Feb 2024 — Mar 2026)
- OpenZeppelin/compact-contracts — canonical Compact library
- Official Midnight examples — counter, bulletin board, counter-cli migration guide
- Brick Towers projects — seabattle, local-network, proof-server, RWA
- Existing community skills — UvRoxx, FractionEstate, OverGuild, mzf11125
- Compiler validation — every example compiled against Compact 0.29.0 and 0.30.0
- Simulator validation — 29/29 examples pass on compact-runtime 0.15.0
- Preprod deployment — 6 contracts deployed on v8 preprod (Ledger 8.0.3, protocol v22000)
- midnight-mcp — MCP server for searching across 102+ Midnight repos. Complementary tool: the MCP provides live search, this skill provides validated patterns. Several gotchas (#64, #65) were discovered via MCP search.
- docs.midnight.network/relnotes/overview — official v8 compatibility matrix
PRs welcome — especially from Midnight developers, ZK researchers, and privacy protocol builders. Areas of interest:
- New contract patterns or examples
- Security findings or additional ZK attack vectors
- Corrections to existing reference material
- Off-chain integration patterns for new SDK versions
- cardano-skill — Aiken smart contracts on Cardano (eUTxO, multi-validator, CIP-113)
- cardano-offchain-skill — CIP-30 wallets, MeshJS transactions, Ogmios/Kupo, Playwright testing
MIT — see LICENSE.
Built by ADAvault