Skip to main content
For the complete documentation index, see llms.txt

Edda Midnight starter template

Edda Midnight Starter Template은 Midnight Network에서 DApp을 만들기 위한 풀스택 모노레포입니다. Compact 스마트 컨트랙트, React(Vite) 프론트엔드, CLI를 갖춘 동작하는 카운터 애플리케이션을 제공하며, 클론하고 빌드해 Vercel에 바로 배포할 수 있습니다. 라이브 데모는 counter.nebula.builders에서 확인할 수 있습니다.

이 프로젝트에는 영어, 스페인어, 포르투갈어 영상 가이드가 담긴 학습 자료가 포함되어 있어, Midnight을 처음 접하는 개발자에게 실용적인 출발점이 됩니다.

Edda Labs 유지보수자들은 MeshJS/midnight-starter-template을 포크해 이 템플릿을 만들었고, 여기에 Apache-2.0 라이선스, 배포 자동화, 학습 자료 디렉터리를 더했습니다.

Community-maintained - not audited

이 템플릿은 Midnight Foundation이 아니라 Edda Labs가 유지보수합니다. 감사를 거치지 않았습니다. 스마트 컨트랙트는 학습용으로 만든 최소한의 카운터 예제이므로, 프로덕션에 사용할 때는 별도로 직접 검증하세요.

Prerequisites​

템플릿을 사용하기 전에 다음을 갖췄는지 확인하세요.

Compatibility​

이 템플릿은 특정 Compact 컴파일러, 런타임, 도구 버전을 대상으로 합니다. 빌드하기 전에 로컬 환경과 대조해 확인하세요.

ComponentVersionNotes
Compact compiler0.31.0compact update +0.31.0로 설정
Compact language>= 0.23컨트랙트 소스의 pragma 기준
Node.js22+.node-version과 engines.node에 고정
pnpm10.14.0package.json의 packageManager로 고정
Build orchestratorTurborepo최상위 스크립트가 turbo run을 통해 실행
Networksundeployed, Preview, Preprod, Mainnetstandalone undeployed 네트워크는 Docker로 실행
LicenseApache-2.0(상위 Mesh 템플릿에는 라이선스가 없으며, Edda의 포크가 Apache-2.0을 추가함)

Monorepo structure​

이 템플릿은 코드를 세 개의 워크스페이스 패키지로 나눕니다.

PackagePurpose
counter-contract공개 round 카운터를 증가시키는 단일 increment circuit을 가진 Compact 스마트 컨트랙트. TypeScript 바인딩과 ZK proof 아티팩트로 컴파일됩니다.
counter-cli터미널에서 컨트랙트를 배포하고 상호작용하는 CLI 도구. 세 네트워크를 모두 지원합니다.
frontend-vite-reactLace wallet 연동, TailwindCSS 스타일, TanStack Router를 갖춘 React 19 + Vite 프론트엔드. 배포된 컨트랙트에 연결해 카운터 상태를 표시합니다.

Installation​

저장소를 클론합니다.

git clone https://github.com/eddalabs/midnight-starter-template.git
cd midnight-starter-template

Git Large File Storage(LFS)로 영지식 증명 아티팩트를 내려받습니다.

git lfs install
git lfs pull

Compact Toolchain을 템플릿이 대상으로 하는 버전으로 업데이트합니다.

compact update +0.31.0

의존성을 설치하고 모든 워크스페이스 패키지를 빌드합니다.

pnpm install
pnpm build

counter-cli/와 frontend-vite-react/에는 모두 .env_template 파일이 들어 있습니다. 로컬에서 실행하기 전에 각각 .env로 복사하고 값을 채워 넣으세요.

Git LFS required

저장소는 영지식 증명 아티팩트(prover key, verifier key, ZKIR 파일)를 Git LFS로 저장합니다. git lfs install과 git lfs pull을 거치지 않으면 이 파일들이 바이너리 데이터가 아니라 텍스트 포인터로 나타나, 컨트랙트 배포가 "mismatched verifier keys" 오류로 실패합니다.

Run locally​

Preview 네트워크를 대상으로 프론트엔드를 실행합니다.

pnpm dev:frontend

외부 네트워크에 의존하지 않는 완전한 로컬 환경을 원하면, standalone 네트워크를 먼저 실행하세요.

pnpm setup-standalone
pnpm dev:frontend

standalone 네트워크는 Midnight node, indexer, proof server 컨테이너를 Docker에서 실행합니다.

Testing​

CLI에는 각 네트워크에서 컨트랙트를 엔드투엔드로 실행하는 Vitest 기반 테스트 스위트가 들어 있습니다.

pnpm --filter @eddalabs/counter-cli test-undeployed
pnpm --filter @eddalabs/counter-cli test-preview
pnpm --filter @eddalabs/counter-cli test-preprod

이 스크립트들은 필요한 인프라(undeployed용 컨테이너, preview·preprod용 faucet 호출)를 띄우고, 컨트랙트를 배포한 뒤 circuit 동작을 검증합니다. 직접 컨트랙트 테스트 하네스를 구성할 때 유용한 참고 자료가 됩니다.

The smart contract​

컨트랙트는 export된 circuit 하나만 가진 최소한의 카운터입니다.

pragma language_version >= 0.23;

import CompactStandardLibrary;

export ledger round: Counter;

export circuit increment(): [] {
  round.increment(1);
}

컨트랙트는 의도적으로 최소한으로 만들어졌습니다. 이 템플릿의 가치는 컨트랙트 로직이 아니라 그 주변을 둘러싼 풀스택 스캐폴딩(지갑 연결, provider 연동, 배포 파이프라인)에 있습니다. 컨트랙트를 직접 만든 것으로 교체하면 주변 인프라가 그에 맞춰 동작합니다.

Deploy to Vercel​

Edda Labs 팀은 전체 배포 절차를 DEPLOYMENT_PROCEDURE.md에 정리해 두었습니다. 핵심 단계는 다음과 같습니다.

  1. 첫 빌드 전에 Vercel 프로젝트 설정에서 Git LFS를 활성화하세요.
  2. 빌드 명령을 npm run build-production으로 설정하세요(이 스크립트는 워크스페이스를 인식하며, 빌드 전에 LFS 아티팩트를 가져옵니다).
  3. 출력 디렉터리를 frontend-vite-react/dist로 설정하세요.
  4. 배포한 컨트랙트 주소를 담아 VITE_CONTRACT_ADDRESS 환경 변수를 추가하세요.
Git LFS in Vercel

Vercel 설정에서 Git LFS를 활성화하지 않고 배포하면 빌드는 끝나지만 DApp이 런타임에 실패합니다. 증명 아티팩트가 바이너리 파일이 아니라 LFS 포인터이기 때문입니다. 먼저 LFS를 활성화한 뒤, 캐시 없이 다시 배포하세요.

Educational materials​

저장소에는 다음 내용을 다루는 체계적인 세션 가이드가 담긴 educational-material/ 디렉터리가 들어 있습니다.

  • 영지식 증명과 프라이버시를 강화한 DApp
  • devnet, Preview, Testnet 환경
  • Edda Labs YouTube 채널의 영상 가이드
  • 영어, 스페인어, 포르투갈어로 제공

Resources​

Report issues​

템플릿 관련 문제는 Edda Labs 트래커에 제보하세요.

이 문서 페이지 관련 문제는 Midnight docs 저장소에 제보하세요.