For the complete documentation index, see llms.txt

Build a privacy-preserving leaderboard DApp

이 튜토리얼에서는 Midnight Network에서 풀스택 DApp을 처음부터 끝까지 만듭니다. Compact 스마트 컨트랙트를 작성하고, TypeScript로 연동하고, Lace 지갑을 지원하는 브라우저 프론트엔드를 만든 다음, 완성된 애플리케이션을 프로덕션에 배포합니다.

완료하면 플레이어가 프라이버시 제어와 함께 점수를 제출하고 영지식 증명으로 자신의 기록임을 증명하는, 아케이드 스타일의 리더보드가 동작하게 됩니다.

What you learn

이 튜토리얼은 Midnight DApp 개발의 네 가지 영역을 다룹니다.

Smart contract (Compact)

• Map, Counter, 커스텀 struct로 구조화된 온체인 데이터를 정의합니다.
• disclose()로 어떤 데이터를 온체인에 올릴지 제어합니다.
• witness로 필요할 때마다 비공개 데이터를 ZK circuit에 전달합니다.
• assert로 소유권 검사를 강제합니다.
• persistentHash로 해시해 익명 신원을 만듭니다.

TypeScript integration

• Compact 컨트랙트를 컴파일하고 생성된 TypeScript 바인딩을 다룹니다.
• midnight-js-contracts로 플랫폼에 독립적인 API 레이어를 만듭니다.
• 비공개 데이터를 circuit으로 연결하는 witness provider를 만듭니다.

Browser DApp

• DApp Connector API를 통해 Lace 지갑에 연결합니다.
• 증명 생성, indexer 접근, 지갑 작업, ZK config를 위한 provider를 초기화합니다.
• 지갑 없이 indexer에서 온체인 상태를 직접 읽습니다.
• ZK proof를 생성하며 브라우저에서 트랜잭션을 제출합니다.

Production deployment

• 프론트엔드를 Vercel에 배포합니다.
• 네트워크별 환경 변수를 설정합니다.

Prerequisites

시작하기 전에 다음 도구를 설치해야 합니다.

• Node.js v22+ (필요하면 nvm install 22을 사용하세요).
• Compact 툴체인.
• Docker (로컬 proof server용).
• Lace 지갑 브라우저 확장.

Wallet setup

1. Lace 확장을 설치하고 새 지갑을 만드세요.
2. 네트워크를 Preprod로 설정하세요.
3. proof server를 http://localhost:6300으로 설정하세요.
4. Preprod faucet에서 tNIGHT을 받아 지갑에 충전하세요.
5. 토큰으로 이동해 Generate tDUST를 클릭하고 트랜잭션을 확인하세요.

Note: Preprod에서 트랜잭션 수수료를 내려면 tDUST이 필요합니다. tDUST은 보유한 tNIGHT 잔액에서 생성됩니다.

Project structure

완성된 프로젝트는 세 개의 워크스페이스 패키지와 proof server용 Docker 설정으로 구성됩니다.

midnight-leaderboard/
├── contract/              # Compact 스마트 컨트랙트 + TypeScript 바인딩
│   ├── leaderboard.compact
│   ├── src/
│   │   ├── index.ts       # 컴파일된 컨트랙트 export + witness 연결
│   │   └── witnesses.ts   # Witness provider
│   └── managed/           # 컴파일러 출력
├── api/                   # 공용 비즈니스 로직 (플랫폼 독립적)
│   └── src/
│       ├── index.ts       # LeaderboardAPI 클래스
│       ├── common-types.ts
│       └── utils/index.ts
├── leaderboard-ui/        # React + Vite 브라우저 DApp
│   └── src/
│       ├── App.tsx         # 게임 UI + 리더보드 + 지갑 연결
│       ├── main.tsx        # Buffer polyfill이 포함된 진입점
│       ├── contexts/       # Lace 지갑 provider 브리지
│       └── hooks/          # Indexer 읽기 hook
├── proof-server/           # 로컬 proof server용 Docker 설정
│   └── Dockerfile
├── vercel.json             # 프론트엔드 배포 설정
└── package.json            # 워크스페이스 루트

Tutorial sections

각 파트는 앞 파트를 토대로 이어집니다. 순서대로 진행하세요.

Section	What you build
Part 1: Smart contract	프라이버시 모드와 소유권 검증을 갖춘 Compact 컨트랙트를 작성합니다.
Part 2: TypeScript integration	컨트랙트 패키지, witness, 공용 API 레이어를 구성합니다.
Part 3: Browser DApp	Lace 지갑 연결과 indexer 읽기를 갖춘 React 프론트엔드를 만듭니다.
Part 4: Production deployment	프론트엔드를 Vercel에 배포합니다.