[Tutorial] Managing Private State (#232)

[richard202605]

Bounty Submission: Issue #232

This tutorial covers private state management in Midnight Compact:

• Ledger vs. Transient State — Understanding persistent and temporary state types
• Private State Declaration — Using ledger for hidden data with cryptographic commitments
• The disclose() Function — Selective disclosure and its privacy implications
• Best Practices — Nonces, minimal disclosure, separation of concerns
• Design Patterns — State machines, commitment-reveal, encrypted off-chain storage
• Testing Guidance — Unit testing private state with the Compact simulator

Deliverables

Deliverable	Status
Written tutorial (2,500+ words)	✅ ~2,600 words
TUTORIAL.md with full content	✅
Working Compact code examples	✅
State machine pattern example	✅
Commitment-reveal pattern example	✅
Testing guidance with simulator	✅

Files

• TUTORIAL.md — Complete tutorial covering private state management in Compact
• private-voting.compact — Full-featured private voting contract (commitment-reveal, nullifiers, Merkle trees, selective disclosure, nonce protection)
• private-vault.compact — Private balance vault (deposit/withdraw/transfer, state machine, conditional disclosure, off-chain metadata)
• README.md — Submission summary and file descriptions

Key Takeaways for Developers

1. Private state uses cryptographic commitments, not encryption
2. Use circuit functions to prove properties without revealing values
3. Always include nonces to prevent replay attacks
4. Prefer proving over disclosing — reveal only what's strictly necessary
5. Test privacy guarantees with the Compact simulator before deploying

Ready for review.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}