docs: add leaderboard runnable example (closes #1039)#1041
Open
mzf11125 wants to merge 8 commits into
Open
Conversation
|
@mzf11125 is attempting to deploy a commit to the Midnight Foundation Team on Vercel. A member of the Team first needs to authorize it. |
nstanford5
requested changes
Jun 15, 2026
nstanford5
left a comment
nstanford5
left a comment
Contributor
There was a problem hiding this comment.
Leaderboard repo here: https://github.com/midnightntwrk/midnight-leaderboard
The leaderboard repo (midnightntwrk/midnight-leaderboard) already exists. Replace the placeholder 'follow tutorial to create from scratch' with actual clone + install commands. Remove redundant npm install from compile section.
mzf11125
commented
Jun 15, 2026
mzf11125
left a comment
mzf11125
left a comment
Contributor
Author
There was a problem hiding this comment.
Thanks for the link. The clone instructions now point directly to https://github.com/midnightntwrk/midnight-leaderboard and the redundant install step has been removed.
nstanford5
requested changes
Jun 16, 2026
- Proof server only needed for transactions not compilation - Removed Command-line familiarity prerequisite - Removed compatibility version table - Removed inline dev script commands
Contributor
Author
|
Addressed all review comments
|
nstanford5
previously requested changes
Jun 17, 2026
Co-authored-by: nstanford5 <67871053+nstanford5@users.noreply.github.com> Signed-off-by: nstanford5 <67871053+nstanford5@users.noreply.github.com>
oduameh
reviewed
Jun 22, 2026
Contributor
There was a problem hiding this comment.
Thank you for this contribution. The leaderboard example page is a great addition to the docs! I have left several inline suggestions to bring it into alignment with the existing example pages and the Midnight style guide. You can batch-commit the suggestions directly from the GitHub UI.
The main themes are:
- Frontmatter format: Align the SPDX header and sidebar position with
bboard.mdxandzkloan.mdx - Terminology: "zero-knowledge" (hyphenated, lowercase) per the style guide
- Active voice and second person: Replace passive constructions and "the user's" with "your"
- Missing sections: The page needs "Set up the example" and "Start the proof server" sections to be a complete, runnable example
- Admonition titles: Add descriptive titles using bracket syntax
Comment on lines
+1
to
+16
| {/* SPDX-License-Identifier: Apache-2.0 | ||
| copyright: This file is part of midnight-docs. Copyright (C) Midnight Foundation. Licensed | ||
| under the Apache License, Version 2.0 (the "License"); You may not use this file except in | ||
| compliance with the License. You may obtain a copy of the License at | ||
| http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to | ||
| in writing, software distributed under the License is distributed on an "AS IS" BASIS, | ||
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for | ||
| the specific language governing permissions and limitations under the License. */} | ||
|
|
||
| --- | ||
| sidebar_label: "Leaderboard DApp" | ||
| sidebar_position: 30 | ||
| title: Leaderboard DApp | ||
| description: Learn how the leaderboard DApp demonstrates privacy-preserving score submission and ownership verification with Zero Knowledge proofs on Midnight Network. | ||
| toc_max_heading_level: 2 | ||
| --- |
Contributor
There was a problem hiding this comment.
Suggested change
| {/* SPDX-License-Identifier: Apache-2.0 | |
| copyright: This file is part of midnight-docs. Copyright (C) Midnight Foundation. Licensed | |
| under the Apache License, Version 2.0 (the "License"); You may not use this file except in | |
| compliance with the License. You may obtain a copy of the License at | |
| http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to | |
| in writing, software distributed under the License is distributed on an "AS IS" BASIS, | |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for | |
| the specific language governing permissions and limitations under the License. */} | |
| --- | |
| sidebar_label: "Leaderboard DApp" | |
| sidebar_position: 30 | |
| title: Leaderboard DApp | |
| description: Learn how the leaderboard DApp demonstrates privacy-preserving score submission and ownership verification with Zero Knowledge proofs on Midnight Network. | |
| toc_max_heading_level: 2 | |
| --- | |
| --- | |
| SPDX-License-Identifier: Apache-2.0 | |
| copyright: This file is part of midnight-docs. Copyright (C) Midnight Foundation. Licensed under the Apache License, Version 2.0 (the "License"); You may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. | |
| sidebar_label: "Leaderboard DApp" | |
| sidebar_position: 25 | |
| title: Leaderboard DApp | |
| description: Learn how the leaderboard DApp demonstrates privacy-preserving score submission and ownership verification with zero-knowledge proofs on Midnight Network. | |
| toc_max_heading_level: 2 | |
| --- |
|
|
||
| # Leaderboard DApp | ||
|
|
||
| The leaderboard contract demonstrates privacy-preserving smart contracts on Midnight using the Compact language. This example shows how to create a DApp that lets players submit scores with configurable privacy modes while protecting player identity through Zero Knowledge (ZK) proofs. |
Contributor
There was a problem hiding this comment.
Suggested change
| The leaderboard contract demonstrates privacy-preserving smart contracts on Midnight using the Compact language. This example shows how to create a DApp that lets players submit scores with configurable privacy modes while protecting player identity through Zero Knowledge (ZK) proofs. | |
| The leaderboard smart contract demonstrates privacy-preserving score tracking on Midnight using the Compact language. This example shows how to create a DApp that lets players submit scores with configurable privacy modes while protecting player identity through zero-knowledge (ZK) proofs. |
|
|
||
| The leaderboard contract demonstrates privacy-preserving smart contracts on Midnight using the Compact language. This example shows how to create a DApp that lets players submit scores with configurable privacy modes while protecting player identity through Zero Knowledge (ZK) proofs. | ||
|
|
||
| The leaderboard example is a privacy-focused DApp that introduces key Midnight concepts: |
Contributor
There was a problem hiding this comment.
Suggested change
| The leaderboard example is a privacy-focused DApp that introduces key Midnight concepts: | |
| The leaderboard example introduces key Midnight concepts: |
|
|
||
| Two public fields track the leaderboard state on-chain: | ||
|
|
||
| - `scores`: A `Map<Uint<64>, ScoreEntry>` that stores all submitted entries, keyed by an auto-incrementing ID. Each `ScoreEntry` holds a score, a display name, and an ownership commitment. |
Contributor
There was a problem hiding this comment.
Suggested change
| - `scores`: A `Map<Uint<64>, ScoreEntry>` that stores all submitted entries, keyed by an auto-incrementing ID. Each `ScoreEntry` holds a score, a display name, and an ownership commitment. | |
| - `ownerCommitment(sk)`: A helper circuit that derives an on-chain identity from your secret key using `persistentHash`. It produces a deterministic commitment that you can store and verify later without revealing the secret. |
| Two public fields track the leaderboard state on-chain: | ||
|
|
||
| - `scores`: A `Map<Uint<64>, ScoreEntry>` that stores all submitted entries, keyed by an auto-incrementing ID. Each `ScoreEntry` holds a score, a display name, and an ownership commitment. | ||
| - `nextId`: A `Counter` that auto-increments to assign a unique ID to each new entry. |
Contributor
There was a problem hiding this comment.
Suggested change
| - `nextId`: A `Counter` that auto-increments to assign a unique ID to each new entry. | |
| - `submitScore(score, useCustomName)`: Creates a new leaderboard entry. It retrieves your secret key via the `localSecretKey` witness, computes the owner commitment, and inserts a new `ScoreEntry` into `scores`. The `useCustomName` flag controls whether the display name comes from the `getCustomName` witness or derives directly from the secret key hash. |
|
|
||
| Click **Verify Ownership** next to any of your entries. The UI calls `verifyOwnership(entryId)`, which generates a ZK proof that your secret key matches the `ownerHash` stored in the entry. The circuit asserts the match on-chain without writing anything to the ledger. | ||
|
|
||
| A success message confirms ownership. If your wallet does not hold the correct secret key for that entry, the assertion fails and the transaction is rejected locally before reaching the network. |
Contributor
There was a problem hiding this comment.
Suggested change
| A success message confirms ownership. If your wallet does not hold the correct secret key for that entry, the assertion fails and the transaction is rejected locally before reaching the network. | |
| A success message confirms ownership. If your wallet does not hold the correct secret key for that entry, the assertion fails and the proof server rejects the transaction locally before it reaches the network. |
Comment on lines
+258
to
+260
| :::caution | ||
| Ownership verification only works from the same browser and wallet instance that submitted the entry, because the secret key lives in the local private state store. | ||
| ::: |
Contributor
There was a problem hiding this comment.
Suggested change
| :::caution | |
| Ownership verification only works from the same browser and wallet instance that submitted the entry, because the secret key lives in the local private state store. | |
| ::: | |
| :::caution[Same browser required] | |
| Ownership verification only works from the same browser and wallet instance that submitted the entry, because the secret key lives in the local private state store. | |
| ::: |
| - Lace wallet browser extension installed | ||
|
|
||
| For more information, refer to [install the toolchain](../../getting-started/installation). | ||
|
|
Contributor
There was a problem hiding this comment.
This page would benefit from two additional sections before "Compile the contract" to match the structure of the existing bboard.mdx example page:
1. "Set up the example" section with:
- A note that no standalone
example-leaderboardrepository exists yet, directing readers to the tutorial - An "Install dependencies" subsection with
npm installfrom the project root
2. "Start the proof server" section with:
- The Docker command:
docker run -p 6300:6300 midnightntwrk/proof-server:8.0.3 -- midnight-proof-server -v - A
:::tip[Keep the proof server running]admonition
These sections are present in bboard.mdx and are essential for a "runnable example" page -- without them, readers have no way to obtain the code or start the proof server before compiling.
|
|
||
| The leaderboard example uses a monorepo structure with three workspace packages and a Docker configuration for the proof server. | ||
|
|
||
| ```text |
Contributor
There was a problem hiding this comment.
For consistency with bboard.mdx, which uses bare fenced code blocks (without a language tag) for directory trees and command output, consider removing the text language tag here. The same applies to the compiler output block further down (line 176).
| npm run compact | ||
| ``` | ||
|
|
||
|
|
Contributor
There was a problem hiding this comment.
There is an extra blank line here (two consecutive blank lines). One blank line between the code block and the following paragraph is sufficient.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
docs/examples/dapps/leaderboard.mdxas a self-contained runnable-example page for the leaderboard DApp. The page gives developers everything they need to understand the contract, build the project, and run the browser DApp against Preprod.The page follows the exact structure of the existing
bboard.mdxexample page:Type of Change
Related Links
docs/examples/dapps/leaderboard.mdx(new file)docs/examples/dapps/bboard.mdxIssue Reference
Closes #1039
Checklist
npm run start).Notes (Optional)
The leaderboard tutorial already exists at
docs/tutorials/leaderboard/across six pages. This PR adds the companion example page indocs/examples/dapps/that issue #1039 requested. The example page links to the tutorial for the full build walkthrough, since the tutorial builds the project from scratch step by step.The page targets the following component versions matching the existing tutorial:
A standalone
example-leaderboardrepository (similar toexample-bboard) does not exist yet. Once the Midnight Foundation publishes that repo, the clone instructions in this page can be updated to point directly to it.