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

Private tip jar tutorial

Prerequisites: work through the Battleship tutorial first. This tutorial assumes you can compile a contract, run a local devnet, and read a MidnightJS test. You should also know what disclose() marks, why a secret should only reach the ledger as a hash, and that every exported circuit is a public entry point the contract has to defend.

Private Party moved NIGHT, an unshielded token, so every payment was public. This tutorial introduces shielded tokens. A tip jar takes a tip from anyone, and the contract never learns who tipped. Only the jar's owner can take the tips out. Tip values stay public, so an observer can see that someone tipped 40, but not who.

The example is still small, but it is the first one on the learning path with two contracts. Along the way you will see:

  • Two contracts. private-tip-jar.compact is the jar. tip-token.compact is a tiny demo token that exists only because a fresh devnet has no shielded tokens to tip with. The test suite deploys both and connects them by the token's color.
  • receiveShielded and a fresh coin. The coin a tipper passes to tip is not one of their wallet's coins. It describes a new coin the transaction creates for the contract, and the wallet pays for it from whatever coins it holds, making change. Because the tipper gives that coin a fresh random nonce, the contract can store it in the public pot as it is, and the pot's nonces don't lead back to anyone's wallet.
  • An owner-only withdraw. The owner is a hash of a secret key, and withdraw proves knowledge of that secret through a witness before it pays a coin to the caller's wallet.
  • A privacy test over the public ledger. The tests collect every byte the contract makes public and assert that no tipper key, nonce of a tipper's wallet coin, or owner secret is among them.

The source for this tutorial is examples/private-tip-jar in midnight-examples. Its SPEC.md is the design card the contract was built from.

Set up​

Clone midnight-examples, install the workspace, and compile every contract:

git clone https://github.com/midnightntwrk/midnight-examples.git
cd midnight-examples
yarn install && yarn compile

Then move into the example:

cd examples/private-tip-jar

You'll start the local network in the second part, when you run the tests.

Private tip jar contracts

Read both contracts: the jar's anonymous tip, the fresh coin it stores, and the owner-only withdrawal, then the demo token that mints coins to tip with.

Read the contracts

Private tip jar tests

Run the jar in memory, then on a local devnet with MidnightJS: mint, tip, check that nothing about the tipper is public, and withdraw.

Run the tests