Skip to content

Commit d2556de

Browse files
debansh001debansh001
committed
add README.md
1 parent d047c03 commit d2556de

1 file changed

Lines changed: 189 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
<div align="center">
2+
<img src="public/logo.png" alt="Midnight Pass Logo" width="200" height="200">
3+
4+
# Midnight Pass
5+
6+
**The privacy-first party and event management DApp on the Midnight Network**
7+
8+
<p>
9+
<img src="https://img.shields.io/badge/Midnight-Network-purple?style=for-the-badge" alt="Midnight Network">
10+
<img src="https://img.shields.io/badge/Compact-Language-blue?style=for-the-badge" alt="Compact">
11+
<img src="https://img.shields.io/badge/Next.js-Black?style=for-the-badge&logo=next.js&logoColor=white" alt="Next.js">
12+
<img src="https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript">
13+
<img src="https://img.shields.io/badge/TailwindCSS-38B2AC?style=for-the-badge&logo=tailwind-css&logoColor=white" alt="TailwindCSS">
14+
</p>
15+
16+
### [🔗 Live Demo](https://midnightpass.vercel.app) | [📺 Demo Video](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
17+
</div>
18+
19+
---
20+
21+
## 💡 About The Product
22+
23+
### The Problem
24+
Traditional event ticketing and RSVP systems are entirely public or highly centralized. When users RSVP to an event on Web2 platforms or transparent Web3 blockchains, their attendance, identity, and connections are exposed to the public or data brokers. For private parties, exclusive events, or discreet gatherings, this lack of privacy is a significant issue.
25+
26+
### The Solution
27+
**Midnight Pass** leverages the Midnight Network to solve this problem by introducing a **privacy-first RSVP and check-in system**.
28+
- **Private RSVPs:** Guests can RSVP without revealing their identity or address to the public ledger.
29+
- **Secure Verification:** The organizer can verify the number of attendees, and guests can securely check in at the door using Zero-Knowledge proofs.
30+
- **Controlled Disclosure:** Only at the moment of physical check-in and fee payment (the privacy boundary) does the guest's identity become public, ensuring that only verified attendees are known, while the initial guest list remains entirely hidden.
31+
32+
---
33+
34+
## 🔒 Privacy-First Model
35+
36+
Midnight Pass is built fundamentally around a privacy-first model, giving users absolute control over what data is public and what remains private.
37+
38+
### Public State vs Private Witness
39+
In the Midnight Network, smart contracts (written in Compact) separate data into two categories:
40+
- **Public State:** Data stored openly on the ledger. In Midnight Pass, this includes the organizer's public key, the entry fee, the maximum list size, the current state of the party (e.g., `READY`, `STARTED`), and the *count* of RSVPs (stored as a hashed commitment set).
41+
- **Private Witness (Local State):** Data stored only on the user's local device. In Midnight Pass, this is the attendee's secret (`_secret`). When an attendee RSVPs, the application uses their private secret to generate a **Zero-Knowledge Proof (ZKP)** locally. The network validates this proof without ever seeing the actual secret.
42+
43+
This separation ensures that the blockchain only stores cryptographic commitments, while sensitive user data never leaves the user's browser.
44+
45+
---
46+
47+
## 📸 Product Screenshots
48+
49+
<div align="center">
50+
<p><i>[ Space for product screenshots ]</i></p>
51+
<!-- <img src="screenshot1.png" alt="Screenshot 1" width="400"> -->
52+
<!-- <img src="screenshot2.png" alt="Screenshot 2" width="400"> -->
53+
</div>
54+
55+
---
56+
57+
## 📜 Smart Contracts
58+
59+
The core of Midnight Pass is the `private-party.compact` contract, written in Midnight's Compact language.
60+
61+
### Key Circuits
62+
- `constructor`: Deploys the contract, setting the max capacity, entry fee, and binding the organizer's identity.
63+
- `rsvp`: Allows an attendee to privately add their commitment hash to the guest list (`hashedPartyGoers`) using a ZK proof.
64+
- `startParty`: The organizer officially starts the event, allowing check-ins to begin.
65+
- `checkIn`: An attendee crosses the privacy boundary, proving they were on the RSVP list, paying the unshielded entry fee, and revealing their address on-chain.
66+
- `closeEntry` / `claimFees`: The organizer closes the doors and claims the accumulated entry fees via an unshielded token transfer.
67+
68+
<div align="center">
69+
<p><i>[ Space for contract deployment and execution images ]</i></p>
70+
<!-- <img src="deployment1.png" alt="Deployment 1" width="400"> -->
71+
</div>
72+
73+
---
74+
75+
## 🏗️ Project Architecture
76+
77+
```mermaid
78+
graph TD
79+
A[Next.js Client UI] -->|User Actions| B(Wallet Context / Provider)
80+
B -->|Request ZK Proof| C{1AM Wallet}
81+
B -->|Fetch Contract State| D[Midnight Indexer]
82+
C -->|Generate Proof| E[WASM Prover]
83+
E -.->|Verify Keys| F[Local ZK Config Provider]
84+
E -->|Unbound Tx| C
85+
C -->|Balance & Sign| G((Midnight Network))
86+
G -.->|Update Ledger| D
87+
```
88+
89+
---
90+
91+
## 🔄 User Workflow
92+
93+
```mermaid
94+
sequenceDiagram
95+
participant O as Organizer
96+
participant C as Smart Contract
97+
participant G as Guest
98+
99+
O->>C: 1. Deploy Contract (Fee, Max Guests)
100+
G->>C: 2. RSVP (Private ZK Commitment)
101+
O->>C: 3. Start Party
102+
G->>C: 4. Check In (Prove RSVP + Pay Fee)
103+
O->>C: 5. Close Doors
104+
O->>C: 6. Claim Fees
105+
```
106+
107+
---
108+
109+
## 📂 File Structure
110+
111+
```text
112+
MidnightPass/
113+
├── app/
114+
│ ├── app/ # DApp routes
115+
│ │ ├── dashboard/ # Main entry point
116+
│ │ ├── organize/ # Organizer UI (Deploy, Start, Close, Claim)
117+
│ │ └── join/ # Attendee UI (RSVP, Check In)
118+
│ ├── layout.tsx & globals.css # Global styles and layouts
119+
├── components/ # Reusable React components (TxCard, Navigation)
120+
├── contract/
121+
│ ├── src/private-party.compact # The core smart contract
122+
│ └── src/index.ts # Contract artifact exports
123+
├── lib/ # Core application logic
124+
│ ├── midnight.ts # Wallet connection, SDK providers, and ZK config
125+
│ ├── party.ts # Contract interaction wrappers (deployParty, rsvp, etc)
126+
│ └── secret.ts # LocalStorage secret management
127+
└── public/zk/private-party/ # Compiled ZK proving keys and IR
128+
```
129+
130+
---
131+
132+
## 🧪 Testing
133+
134+
### How to Test
135+
Midnight Pass uses the Midnight Network's recommended testing approach. The contract logic can be tested using the `@midnight-ntwrk/compact-runtime` to simulate local network states.
136+
137+
To run the local test harness (if set up via Docker devnet):
138+
```bash
139+
npm run test:local
140+
```
141+
142+
<div align="center">
143+
<p><i>[ Space for screenshot of passed test cases ]</i></p>
144+
<!-- <img src="tests.png" alt="Test Cases" width="600"> -->
145+
</div>
146+
147+
---
148+
149+
## 🚀 How to Run Locally
150+
151+
### 1. Set up the 1AM Wallet
152+
1. Download and install the **1AM Wallet** extension for your browser.
153+
2. Create a new wallet or import an existing one.
154+
3. Switch the wallet network to **Preview** (or Preprod, matching the application).
155+
4. Fund your wallet with `tNIGHT` tokens from the [Midnight Faucet](https://faucet.preview.midnight.network/).
156+
157+
### 2. Install Dependencies
158+
Ensure you have Node.js 20+ installed.
159+
```bash
160+
npm install
161+
npm run postinstall
162+
```
163+
164+
### 3. Compile the Contract and Sync Assets
165+
Compile the Compact contract and sync the generated ZK assets to the public folder:
166+
```bash
167+
npm run compact
168+
npm run sync:assets
169+
```
170+
171+
### 4. Start the Development Server
172+
```bash
173+
npm run dev
174+
```
175+
Open `http://localhost:3000` in your browser. Connect your 1AM wallet and start organizing or joining private parties!
176+
177+
---
178+
179+
## 🔮 Future Implementation & Real World Application
180+
181+
### Future Implementations
182+
- **Dynamic Pricing:** Implement tiers for early-bird RSVPs versus late check-ins.
183+
- **Token-Gated Perks:** Issue soulbound tokens (SBTs) upon successful check-in for attendees to claim exclusive physical or digital merchandise.
184+
- **Event Discovery:** A privacy-preserving event discovery feed where organizers can broadcast public metadata while keeping the RSVP list hidden.
185+
186+
### Real World Applications
187+
- **Exclusive VIP Events:** High-profile events where attendee privacy and security are paramount, preventing paparazzi or unwanted attention from knowing the guest list.
188+
- **Corporate Seminars & Offsites:** Internal corporate events that require absolute confidentiality regarding who is attending from which departments or rival companies.
189+
- **Underground Music & Art Shows:** Secret pop-up events that rely on word-of-mouth and private registries to maintain exclusivity and avoid gate-crashers.

0 commit comments

Comments
 (0)