For the complete documentation index, see llms.txt
Create a Midnight DApp
create-mn-app CLI 도구를 사용하여 Midnight DApp을 스캐폴딩하는 방법을 설명합니다.
Prerequisites
Midnight DApp을 실행하려면 다음이 필요합니다:
- Compact compiler
0.31.0설치 완료. Toolchain 설치를 참고하세요. - Docker Desktop 설치 및 실행 중, Docker Compose v2 포함.
- Node.js v22 이상. NVM으로 설치할 수 있습니다.
Midnight CLI tool
create-mn-app CLI 도구는 Midnight DApp용 스타터 템플릿을 제공합니다. TypeScript 설정, 핫 리로딩, 지갑 연동 로직이 미리 구성되어 있습니다.
새 DApp을 스캐폴딩하세요:
npx create-mn-app [project-name]
[project-name]을 새 DApp의 이름으로 교체하세요.
CLI 도구는 먼저 생성할 프로젝트 유형을 선택하라는 프롬프트를 표시합니다:
- Contract
- Full DApp
Midnight 개발이 처음이라면 _contract_로 시작하는 것을 권장합니다. 전체 애플리케이션 스캐폴드를 다루기 전에 Compact smart contract의 컴파일과 배포에 집중할 수 있는 최소 구성을 제공합니다.
Contract
컨트랙트를 선택하면 Compact smart contract 배포에 필요한 최소 구성의 프로젝트가 생성됩니다. 이어서 컨트랙트 템플릿을 선택하라는 프롬프트가 나타납니다:
| Template | 설명 |
|---|---|
hello-world | 기본값. 메시지를 저장하는 컨트랙트로, Compact contract를 컴파일·배포하고 상호작용할 수 있도록 local devnet이 함께 번들로 제공됩니다. |
battleship | private board 상태 머신으로, example-battleship에서 복제됩니다. |
번들 devnet과 --network 플래그는 hello-world에서만 제공됩니다.
Full DApp
Full DApp을 선택하면 컨트랙트와 상호작용하는 브라우저 또는 CLI 인터페이스까지 갖춘 완전한 탈중앙화 애플리케이션이 생성됩니다. 이어서 DApp 템플릿을 선택하라는 프롬프트가 나타납니다:
| Template | 설명 |
|---|---|
bboard | 기본값. 프라이버시를 보호하는 게시판으로, example-bboard에서 복제됩니다. |
leaderboard | 브라우저에서 ZK proving을 수행하는 React + Lace 브라우저 DApp으로, midnight-leaderboard에서 복제됩니다. |
dex와 midnight-kitties는 템플릿 선택기에 _coming soon_으로 표시됩니다. Full DApp 템플릿은 아래에 설명한 번들 devnet 흐름 대신 각자의 upstream 리포지토리 README를 따릅니다.
이 가이드에서는 첫 번째 프롬프트에서 컨트랙트를 선택하고, 템플릿 선택 프롬프트에서 hello-world를 선택하세요. 나머지 프롬프트에 따라 설정을 완료하세요.
다음과 유사한 출력이 나타납니다:
Creating a new Midnight app in /path/to/my-app.
Template: hello-world
✔ Project structure created
✔ Dependencies installed
✔ Git repository initialized
✔ Docker is ready for proof server
✔ Contract compiled successfully
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 Success! Your Midnight app is ready.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
완료되면 my-app 디렉토리로 이동하세요:
cd my-app
프로젝트 구조:
my-app/
├── contracts/
│ └── hello-world.compact # Compact smart contract
├── src/
│ ├── cli.ts # Interact with deployed contract
│ ├── deploy.ts # Deploy contract
│ └── check-balance.ts # Check wallet balance
├── docker-compose.yml # Local devnet: node, indexer, proof server
├── package.json
└── .midnight-state.json # Deployment state (gitignored; contract address and network)
contracts/hello-world.compact 파일에 Compact smart contract 코드가 있습니다.
pragma language_version >= 0.23;
import CompactStandardLibrary;
export ledger message: Opaque<"string">;
export circuit storeMessage(customMessage: Opaque<"string">): [] {
message = disclose(customMessage);
}
Compact는 컨트랙트 로직을 정의하는 Midnight의 스마트 컨트랙트 언어입니다. TypeScript와 유사하지만 Midnight 런타임용으로 설계되었습니다.
docker-compose.yml 파일은 Docker에서 실행되는 local devnet, 즉 Midnight node, indexer, proof server를 정의합니다. Proof server는 Midnight 네트워크에서 스마트 컨트랙트용 ZK(영지식) 증명을 생성합니다. 컨트랙트를 배포하거나 상호작용하기 전에 devnet이 실행 중이어야 합니다.
Set up the project
설정 스크립트를 실행하세요:
npm run setup
npm run setup은 Docker에서 local devnet(노드, indexer, proof server)을 띄우고, 컨트랙트를 컴파일한 뒤 배포합니다. 지갑 확장 프로그램이나 faucet은 필요하지 않습니다. 로컬 dev preset이 genesis seed에 NIGHT을 미리 발행해 두며, 이 자금으로 배포가 자동으로 처리됩니다.
CLI는 배포 상태를 .midnight-state.json 파일에 기록합니다(Git이 이 파일을 무시합니다). 이 파일에는 컨트랙트 주소와 활성 네트워크가 담깁니다. CLI는 컨트랙트와 상호작용할 때 이 파일을 참조합니다.
Interact with the contract
컨트랙트를 배포한 뒤, 대화형 CLI를 시작하세요:
npm run cli
CLI로 배포된 컨트랙트와 상호작용할 수 있습니다:
1. Store a message
2. Read current message
3. Check wallet balance
4. Exit
메뉴에서 원하는 옵션을 선택하고 프롬프트에 따라 진행하세요. Ledger 상태를 직접 확인하려면 end-to-end 테스트를 실행하세요:
npm run test:e2e
Deploy to a public testnet
기본값은 local devnet입니다. 공개 testnet은 선택 사항이며, npm run setup에 --network를 전달하세요:
npm run setup -- --network preview
공개 네트워크를 처음 대상으로 지정하면 CLI가 지갑을 생성하고 충전에 사용할 faucet URL을 출력합니다. preview faucet 또는 preprod faucet에서 지갑에 자금을 충전하세요. 네트워크 선택은 고정으로 유지되며, 이후에는 npm run network <name>으로 네트워크를 전환할 수 있습니다.
| Network | Source | 용도 |
|---|---|---|
undeployed | Local devnet (docker-compose.yml) | 기본값. 자금 충전이나 지갑 확장 프로그램이 필요하지 않습니다. |
preview | Public preview (faucet) | 릴리스 전 공유 인프라입니다. |
preprod | Public preprod (faucet) | mainnet에 가장 가깝습니다. |
Templates
Midnight CLI 도구는 컨트랙트와 full DApp 모두를 위한 스타터 템플릿을 제공합니다. --template <name>으로 템플릿을 전달하거나, 생략하면 CLI가 선택하라는 프롬프트를 표시합니다.
Hello world
hello-world 템플릿은 blockchain에 메시지를 게시하고 조회하는 메시지 저장 contract입니다. 번들로 제공되는 local devnet과 함께 제공됩니다.
npx create-mn-app my-app
hello-world는 기본 템플릿이며 의존성이 설치된 상태로 제공됩니다. 새 hello-world 프로젝트를 만들 때 --template 플래그는 필요하지 않습니다.
Battleship
battleship 템플릿은 private board 상태 머신으로, example-battleship에서 복제됩니다.
npx create-mn-app my-app --template battleship
Bulletin board
bboard 템플릿은 메시지를 게시하고 삭제할 수 있는 프라이버시 보호 게시판 DApp으로, example-bboard에서 복제됩니다.
npx create-mn-app my-app --template bboard
ZK proof를 활용해 온체인에서 신원을 드러내지 않으면서도 게시자와 메시지 소유자를 검증합니다. 자세한 내용은 Bulletin board DApp 예제를 참고하세요.
Leaderboard
leaderboard 템플릿은 브라우저에서 직접 ZK 증명을 생성하는 React + Lace 기반 DApp으로, midnight-leaderboard를 복제해 만듭니다.
npx create-mn-app my-app --template leaderboard
create-mn-app v0.4.2는 Counter 템플릿을 제거했습니다. --from 플래그로 은퇴한 Counter 예제를 여전히 스캐폴딩할 수 있습니다:
npx create-mn-app@latest my-app --from midnightntwrk/example-counter
CLI options
create-mn-app으로 DApp을 만들 때 사용 가능한 옵션:
| 옵션 | 설명 |
|---|---|
-t, --template <name> | 템플릿 선택: hello-world, battleship, bboard, leaderboard |
--list | 사용 가능한 템플릿 목록 표시 |
--from <owner/repo> | GitHub 저장소로부터 스캐폴딩 |
--network <name> | hello-world 템플릿의 네트워크 설정 (undeployed, preview, preprod) |
-y | 프롬프트 없이 기본값 적용 |
--dry-run | 파일을 생성하지 않고 CLI가 만들 내용 미리 보기 |
--use-npm/yarn/pnpm/bun | 특정 패키지 매니저 강제 사용 |
--skip-install | 의존성 설치 건너뛰기 |
--skip-git | git 저장소 초기화 건너뛰기 |
--verbose | 프로젝트 생성 시 상세 출력 표시 |
-h, --help | 도움말 표시 |
-V, --version | CLI 도구 버전 표시 |
Next steps
Midnight CLI 도구로 DApp을 스캐폴딩하는 방법을 익혔습니다. Hello world 튜토리얼에서 Compact 언어로 첫 번째 Midnight contract를 직접 작성해 보세요.