{"id":47577854,"url":"https://github.com/adavault/midnight-skill","last_synced_at":"2026-04-15T04:00:34.954Z","repository":{"id":344033043,"uuid":"1179889732","full_name":"ADAvault/midnight-skill","owner":"ADAvault","description":"Claude Code skill for writing and testing Compact smart contracts on Midnight","archived":false,"fork":false,"pushed_at":"2026-03-29T10:30:32.000Z","size":621,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T12:51:43.082Z","etag":null,"topics":["agent-skills","claude-code","compact","midnight","midnightntwrk","skill","smart-contracts","zero-knowledge"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ADAvault.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-12T13:40:21.000Z","updated_at":"2026-03-29T10:30:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ADAvault/midnight-skill","commit_stats":null,"previous_names":["adavault/midnight-skill"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ADAvault/midnight-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ADAvault%2Fmidnight-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ADAvault%2Fmidnight-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ADAvault%2Fmidnight-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ADAvault%2Fmidnight-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ADAvault","download_url":"https://codeload.github.com/ADAvault/midnight-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ADAvault%2Fmidnight-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31825515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"online","status_checked_at":"2026-04-15T02:00:06.175Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","claude-code","compact","midnight","midnightntwrk","skill","smart-contracts","zero-knowledge"],"created_at":"2026-03-31T07:00:24.934Z","updated_at":"2026-04-15T04:00:34.942Z","avatar_url":"https://github.com/ADAvault.png","language":null,"funding_links":[],"categories":["Developer Tools"],"sub_categories":[],"readme":"# Midnight Compact Smart Contract Skill\n\nAn [Agent Skill](https://agentskills.io) 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](https://midnight.network) with additional developer tooling.\n\nSupports Claude Code, Cursor, Gemini CLI, VS Code Copilot, and 30+ other AI coding assistants.\n\n\u003e **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.\n\n## Compiler-Validated\n\nAll 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.\n\n| Example | Circuits | Tests | Status |\n|---------|----------|-------|--------|\n| [Counter](examples/counter.md) | 3 | 5/5 | Validated |\n| [Bulletin Board](examples/bulletin-board.md) | 3 | 8/8 | Validated |\n| [Fungible Token](examples/fungible-token.md) | 7 | 6/6 | Validated (OZ modules) |\n| [NFT](examples/nft.md) | 7 | 6/6 | Validated |\n| [Rock-Paper-Scissors](examples/rock-paper-scissors.md) | 3 | 6/6 | Validated |\n| [Shielded Voting](examples/shielded-voting.md) | 6 | 9/9 | Validated |\n| [Sealed-Bid Auction](examples/sealed-bid-auction.md) | 6 | 8/8 | Validated |\n| [Identity Proof](examples/identity-proof.md) | 4 | 6/6 | Validated |\n| [Credential Registry](examples/credential-registry.md) | 5 | 6/6 | Validated |\n| [Prescription](examples/prescription.md) | 5 | 6/6 | Validated |\n| [Escrow](examples/escrow.md) | 5 | 8/8 | Validated |\n| [Time Lock](examples/time-lock.md) | 3 | 7/7 | Validated |\n| [Multi-Sig](examples/multi-sig.md) | 6 | 6/6 | Validated |\n| [Staking](examples/staking.md) | 5 | 6/6 | Validated |\n| [Crowdfunding](examples/crowdfunding.md) | 5 | 6/6 | Validated |\n| [Lending](examples/lending.md) | 6 | 6/6 | Validated |\n| [Prediction Market](examples/prediction-market.md) | 5 | 7/7 | Validated |\n| [Oracle Feed](examples/oracle-feed.md) | 5 | 6/6 | Validated |\n| [Access Control](examples/access-control.md) | 8 | 6/6 | Validated |\n| [DID Registry](examples/did-registry.md) | 5 | 6/6 | Validated |\n| [Micro-DAO](examples/micro-dao.md) | 7 | 7/7 | Validated |\n| [Contract Upgradability](examples/contract-upgradability.md) | V1: 3, V2: 7 | 8/8 | Validated |\n| [Token Swap](examples/token-swap.md) | 6 | — | Preprod deployed |\n| [Token Minting](examples/token-minting.md) | 3 | — | Preprod deployed |\n| [Privacy Mixer](examples/privacy-mixer.md) | 3 | 7/7 | Validated |\n| [Lottery](examples/lottery.md) | 4 | 8/8 | Validated |\n| [Vesting](examples/vesting.md) | 4 | 8/8 | Validated |\n| [Revenue Sharing](examples/revenue-sharing.md) | 3 | 7/7 | Validated |\n| [Supply Chain](examples/supply-chain.md) | 4 | 7/7 | Validated |\n\n**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.**\n\nToken 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.\n\n## Preprod Deployment\n\n### v8 (Ledger 8.0.3, March 2026)\n\n6 contracts deployed to Midnight **preprod** on Ledger v8 (protocol v22000). Representative sample validating all major patterns.\n\n| Contract | Pattern | Circuits | DUST Fee | Deploy Time | Block |\n|----------|---------|----------|---------|-------------|-------|\n| Counter | simplest | 3 | 252B | 17.8s | 114208 |\n| Bulletin Board | auth | 2 | 267B | 19.1s | 114211 |\n| Sealed-Bid Auction | commit-reveal + state machine | 5 | 554B | 16.9s | 114214 |\n| Oracle Feed | time-based | 5 | 504B | 19.0s | 114217 |\n| Multi-Sig | multi-party | 6 | 574B | 17.5s | 114220 |\n| LOK | token ops (receiveUnshielded) | 4 | 423B | 17.4s | 114223 |\n\n`receiveUnshielded` (wallet→contract token transfer) confirmed working on v8 — Issue #151 resolved.\n\n### v7 (historical, chain wiped)\n\n30 contracts were previously deployed on Ledger v7 (protocol v21000). Chain state was reset with the v8 upgrade on March 25, 2026.\n\n### DUST Fee Economics\n\nDUST is Midnight's fee token — generated continuously from tNight. Must register NIGHT UTxOs for dust generation before any deployment (gotcha #75).\n\n- **Generation rate**: 5 DUST per NIGHT, ~1 week to cap\n- **Deploy time**: 16-22s per contract on preprod\n- **Practical cost**: 1000 tNight from faucet generates ample DUST for dozens of deployments\n\n## What's Covered\n\n- **Compact language** — types, syntax, circuits, witnesses, disclosure, module system\n- **Privacy model** — shielded vs unshielded state, ZK proof flow, witness security\n- **Security** — 10 ZK-specific attack categories with mitigations\n- **Testing** — simulator, standalone network, testnet (3-level testing approach)\n- **Design patterns** — authentication, OZ composition, off-chain computation, circuit optimization\n- **Off-chain integration** — TypeScript SDK, wallet connectivity, provider pattern, deployment\n- **Gotchas** — compiler bugs, SDK pitfalls, proof server issues, design traps (sourced from Discord + real compilation)\n- **29 worked examples** — core patterns through DeFi, governance, identity, contract upgradability, and supply chain\n\n## Installation\n\n### Project-level (recommended)\n\n```bash\nmkdir -p .claude/skills\ngit clone https://github.com/adavault/midnight-skill.git .claude/skills/midnight-compact\n```\n\n### Personal (all projects)\n\n```bash\ngit clone https://github.com/adavault/midnight-skill.git ~/.claude/skills/midnight-compact\n```\n\n## Usage\n\nThe skill auto-activates on keywords: `Midnight`, `Compact`, `circuit`, `witness`, `ledger`, `disclose`, `proof server`, `DUST`, `NIGHT`, `Zswap`, `shielded`.\n\nOr invoke explicitly: `/midnight-compact`\n\n## Structure\n\n```\nmidnight-skill/\n├── SKILL.md                    # Core skill — workflow, syntax, patterns\n├── README.md                   # This file\n├── LICENSE                     # MIT\n├── reference/                  # Deep-dive reference documents\n│   ├── language.md            # Compact types, syntax, modules, operators\n│   ├── privacy-model.md       # Shielded/unshielded state, ZK proof flow\n│   ├── security.md            # 10 ZK attack categories and mitigations\n│   ├── testing.md             # Simulator, standalone, testnet testing\n│   ├── patterns.md            # Design patterns and circuit optimization\n│   ├── stdlib.md              # CompactStandardLibrary reference\n│   ├── gotchas.md             # 79 real-world issues from Discord + compilation\n│   ├── offchain.md            # TypeScript SDK, wallet, deployment\n│   └── auditing.md            # ZK contract audit methodology\n└── examples/                   # Working examples with tests\n    ├── counter.md             # Simplest contract — state + increment\n    ├── bulletin-board.md      # Witness auth, CRUD, multi-user\n    ├── fungible-token.md      # OZ module composition (FT + Ownable + Pausable)\n    ├── nft.md                 # Commitment-based NFT ownership\n    ├── rock-paper-scissors.md # Commit-reveal 2-player game\n    ├── shielded-voting.md     # Commit-reveal private ballot\n    ├── sealed-bid-auction.md  # Commit-reveal with state machine\n    ├── identity-proof.md      # Selective disclosure, parameterized witnesses\n    ├── credential-registry.md # Nullifier-based double-use prevention\n    ├── prescription.md        # Batch registration, nullifier for healthcare\n    ├── escrow.md              # Two-party exchange with deadline\n    ├── time-lock.md           # Time-based LOK/RELEASE pattern\n    ├── multi-sig.md           # M-of-N authorization, composite keys\n    ├── staking.md             # Lock period + ZK reward calculation\n    ├── crowdfunding.md        # Anonymous backing, ZK refund proofs\n    ├── lending.md             # Collateral, health factor, liquidation\n    ├── prediction-market.md   # Commitment-based bets, ZK payout\n    ├── oracle-feed.md         # External data, freshness checks\n    ├── token-swap.md          # Atomic swap (coin operations)\n    ├── access-control.md      # Role hierarchy, internal guards\n    ├── did-registry.md        # DID document lifecycle management\n    ├── micro-dao.md           # Token-gated voting, treasury\n    ├── contract-upgradability.md # V1/V2 migration pattern\n    ├── token-minting.md       # Zswap coin creation (mintShieldedToken)\n    ├── privacy-mixer.md       # Nullifier-based deposit/withdraw mixer\n    ├── lottery.md             # Commit-reveal multi-party randomness\n    ├── vesting.md             # Time-based tranche release schedule\n    ├── revenue-sharing.md     # Private share allocations, ZK withdrawal\n    └── supply-chain.md        # Selective disclosure provenance tracking\n```\n\n## Key Findings from Validation\n\nCompiling all examples against the real compiler uncovered several patterns not documented elsewhere:\n\n- **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.\n- **`Uint\u003cN\u003e + literal` type widening** — `Uint\u003c32\u003e + 1` produces `Uint\u003c0..4294967297\u003e`. Fix: `(expr + 1) as Uint\u003c32\u003e`.\n- **Parameterized witnesses work** — `witness fn(param: T): U` passes circuit arguments to TypeScript witnesses as additional function parameters.\n- **Internal circuits can access ledger** — non-exported `circuit` (not `pure circuit`) can read/write `export ledger` state, enabling reusable guard patterns.\n- **Boolean/literal assignments skip `disclose()`** — compile-time constants written to `export ledger` don't need disclosure wrapping.\n\nAll findings are documented in [gotchas.md](reference/gotchas.md) (#49-#52) and in each example's Key Concepts section.\n\n### v8 Migration Findings\n\nThe Ledger v8 release (March 2026) introduced significant SDK changes discovered during validation:\n\n- **Witness tuple return** — witnesses now return `[nextPrivateState, value]` instead of just `value` (gotcha #79)\n- **Simulator API** — `contract.initialState(ctx, ...args)` replaces `contract.constructor(ctx)` (gotcha #79)\n- **Dust registration required** — must call `registerNightUtxosForDustGeneration()` before any deployment (gotcha #75)\n- **`signRecipe` bug fixed** — wallet-sdk-facade 3.0.0 handles proof markers correctly (gotcha #76)\n- **`nativeToken()` trap** — use `unshieldedToken().raw` from ledger-v7 for balance lookups (gotcha #77)\n- **Private state encryption** — `levelPrivateStateProvider` now requires encryption config (gotcha #78)\n\n## Sources\n\nBuilt from:\n- **Midnight Discord dev-chat** (Feb 2024 — Mar 2026)\n- **OpenZeppelin/compact-contracts** — canonical Compact library\n- **Official Midnight examples** — counter, bulletin board, counter-cli migration guide\n- **Brick Towers** projects — seabattle, local-network, proof-server, RWA\n- **Existing community skills** — UvRoxx, FractionEstate, OverGuild, mzf11125\n- **Compiler validation** — every example compiled against Compact 0.29.0 and 0.30.0\n- **Simulator validation** — 29/29 examples pass on compact-runtime 0.15.0\n- **Preprod deployment** — 6 contracts deployed on v8 preprod (Ledger 8.0.3, protocol v22000)\n- **[midnight-mcp](https://github.com/Olanetsoft/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.\n- **[docs.midnight.network/relnotes/overview](https://docs.midnight.network/relnotes/overview)** — official v8 compatibility matrix\n\n## Contributing\n\nPRs welcome — especially from Midnight developers, ZK researchers, and privacy protocol builders. Areas of interest:\n\n- New contract patterns or examples\n- Security findings or additional ZK attack vectors\n- Corrections to existing reference material\n- Off-chain integration patterns for new SDK versions\n\n## Companion Skills\n\n- [cardano-skill](https://github.com/ADAvault/cardano-skill) — Aiken smart contracts on Cardano (eUTxO, multi-validator, CIP-113)\n- [cardano-offchain-skill](https://github.com/ADAvault/cardano-offchain-skill) — CIP-30 wallets, MeshJS transactions, Ogmios/Kupo, Playwright testing\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\nBuilt by [ADAvault](https://github.com/adavault)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadavault%2Fmidnight-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadavault%2Fmidnight-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadavault%2Fmidnight-skill/lists"}