Added Simple Anonymous Message Board Tutorial page to zkApps section

Author: jackryanservia

pages/en/zkapps/simple-anonymous-message-board-tutorial.mdx

@@ -0,0 +1,333 @@
+import Page from "@reason/pages/Docs";
+import DocLink from "@reason/components/DocLink";
+export default Page({ title: "Simple Anonymous Message Board Tutorial" });
+
+<Alert kind="info">
+
+Please note that zkApp programmability is not yet available on Mina, but zkApps
+can now be deployed to Berkeley QANet. These docs are a preview of work that is
+currently in progress.
+
+</Alert>
+
+# Simple Anonymous Message Board Tutorial
+<DocLink copy="How to write a zkApp" url="/zkapps/how-to-write-a-zkapp" /> provides a high-level overview of everything you need to know to build applications on Mina. This tutorial will put these ideas into practice as we walk through the design and implementation of a semi-anonymous messaging protocol.
+
+## Overview
+
+We’ll build a smart contract that allows users to publish messages semi-anonymously. Our contract will allow a specific set of users to create new messages but will not disclose which user within the set has done so. This way, people can leverage one aspect of their identity without revealing exactly who they are. So, for example, a DAO member could make credible statements on behalf of their DAO without revealing their specific individual identity.
+
+## Setup
+
+First, install the [Mina zkApp CLI](https://github.com/o1-labs/zkapp-cli) if you haven’t already done so
+
+#### Dependencies
+
+You'll need the following installed to use the zkApp CLI:
+
+- NodeJS 16+ (or 14 using `--experimental-wasm-threads`)
+- NPM 6+
+- Git 2+
+
+If you have an older version installed, we suggest installing a newer version
+using the package manager for your system: [Homebrew](https://brew.sh/) (Mac),
+[Chocolatey](https://chocolatey.org/) (Windows), or apt/yum/etc (Linux). On
+Linux, you may need to install a recent NodeJS version via NodeSource
+([deb](https://github.com/nodesource/distributions#debinstall) or
+[rpm](https://github.com/nodesource/distributions#rpminstall)), as recommended
+by the NodeJS Project.
+
+#### Installation
+
+```sh
+npm install -g zkapp-cli
+```
+
+#### Usage
+
+```sh
+zk --help
+```
+
+##### Create a new project
+
+```sh
+zk project my-proj  # or path/to/my-proj
+
+✔ Fetch project template
+✔ Initialize Git repo
+✔ NPM install
+✔ Set project name
+✔ Git init commit
+
+Success!
+
+Next steps:
+  cd my-proj
+  git remote add origin <your-repo-url>
+  git push -u origin main
+```
+
+This command creates a directory containing a new project template, fully set up
+& ready for local development.
+
+- See the included [README](templates/project-ts/README.md) for usage instructions.
+  All usual commands will be available: `npm run build`, `npm run test`,
+  `npm run coverage`, etc.
+- A Git repo will be initialized in the project directory automatically. For
+  consistency, we use `main` as the default Git branch, by convention.
+- A [Github Actions CI workflow](templates/project-ts/.github/workflows/ci.yml) is
+  also included. If you push your project to Github, Github Actions will run
+  your tests (named as `*.test.js`) automatically, whenever you push a commit or
+  open a pull request.
+- Code style consistency (via Prettier) and linting (via ES Lint) are
+  automatically enforced using Git pre-commit hooks. This requires no
+  configuration and occurs automatically when you commit to Git--e.g. `git commit -m 'feat: add awesome feature'`.
+- To skip all checks in the Git pre-commit hook (not recommended), you can pass
+  the `-n` flag to Git--e.g. `git commit -m 'a bad commit' -n`. But we'd
+  recommend avoiding this and resolving any errors which exist in your project
+  until the pre-commit hook passes.
+
+### Scaffolding
+
+Now that your project is set up, you can open it in your IDE or `cd zk-message` if you work from the command line.
+
+There should be an example smart contract in `./src` called `Add.ts` and test for it in `Add.test.ts`. Let’s create a new contract by running:
+
+```sh
+zk file Message
+```
+
+Now open it up and paste in the following:
+
+```ts
+import {
+  Field,
+  SmartContract,
+  state,
+  State,
+  method,
+  DeployArgs,
+  Permissions,
+  PrivateKey,
+  PublicKey,
+  isReady,
+  Poseidon,
+  Encoding,
+} from 'snarkyjs';
+
+export { isReady, Field, Encoding };
+
+// Wait till our SnarkyJS instance is ready
+await isReady;
+
+// These private keys are exported so that experimenting with the contract is
+// easy. Three of them (the Bobs) are used when the contract is deployed to
+// generate the public keys that are allowed to post new messages. Jack's key
+// is never added to the contract. So he won't be able to add new messages. In
+// real life, we would only use the Bobs' public keys to configure the contract,
+// and only they would know their private keys.
+
+export const users = {
+  Bob: PrivateKey.fromBase58(
+    'EKFAdBGSSXrBbaCVqy4YjwWHoGEnsqYRQTqz227Eb5bzMx2bWu3F'
+  ),
+  SuperBob: PrivateKey.fromBase58(
+    'EKEitxmNYYMCyumtKr8xi1yPpY3Bq6RZTEQsozu2gGf44cNxowmg'
+  ),
+  MegaBob: PrivateKey.fromBase58(
+    'EKE9qUDcfqf6Gx9z6CNuuDYPe4XQQPzFBCfduck2X4PeFQJkhXtt'
+  ), // This one says duck in it :)
+  Jack: PrivateKey.fromBase58(
+    'EKFS9v8wxyrrEGfec4HXycCC2nH7xf79PtQorLXXsut9WUrav4Nw'
+  ),
+};
+
+export class Add extends SmartContract {
+  // On-chain variable definitions
+
+  @method init() {
+    // Define initial values of on-chain variables
+  }
+
+  @method publishMessage(message: Field, signerPrivateKey: PrivateKey) {
+    // Compute signerPublicKey from signerPrivateKey argument
+    // Get approved public keys
+    // Assert that signerPublicKey is one of the approved public keys
+    // Update on-chain message variable
+    // Computer new messageHistoryHash
+    // Update on-chain messageHistoryHash
+  }
+}
+```
+
+This will serve as the scaffolding for the rest of the tutorial and contains a smart contract called `Message` with two methods: `init()` and `publishMessage()`. The `init()` method is similar to the `constructor` in Solidity. It’s a place for you to define any setup that needs to happen before users begin interacting with the contract. `publishMessage()` is the method that users will invoke when they want to create a new message. The `@method` decorator tells SnarkyJS that users should be allowed to call this method and that it should generate a zero-knowledge proof of its execution.
+
+## Wrting the Smart Contract
+
+### Defining On-Chain Storage
+
+Every Mina smart contract includes eight on-chain state variables that each store almost 256 bits of information. In more complex smart contracts, these can store commitments (i.e., the hash of a file, the root of a Merkle tree, etc.) to off-chain storage, but in this case, we’ll store everything on-chain for the sake of simplicity. 
+
+<Alert kind="note">
+General purpose off-chain storage libraries are planned, but you can always roll your own solution if desired.
+</Alert>
+
+In this smart contract, one state variable will store the last message. Another will store the hash of all the previous messages (so a frontend can validate message history), and three more will store user public keys (we could store even more by Merkelizing them, but we’ll keep it to three here for the sake of brevity).
+
+```ts
+export class Add extends SmartContract {
+  // On-chain variable definitions
+  @state(Field) message = State<Field>();
+  @state(Field) messageHistoryHash = State<Field>();
+  @state(PublicKey) user1 = State<PublicKey>();
+  @state(PublicKey) user2 = State<PublicKey>();
+  @state(PublicKey) user3 = State<PublicKey>();
+  ```
+
+  The `@state(Field)` decorator tells SnarkyJS that the variable should be stored on-chain as a `Field` type.
+
+  For practical purposes, the `Field` type is similar to the `uint256` type in Solidity. It can store large integers, and addition, subtraction, and multiplication all work as expected. The only caveats are division and what happens in the event of an overflow. You can learn a little more about them [here](https://en.wikipedia.org/wiki/Finite_field_arithmetic), but it’s not necessary to understand exactly how field arithmetic works for this tutorial. SnarkyJS also provides `UInt32`, `UInt64`, and `Int64` types, but under the hood, all SnarkyJS types are composed of the Field type (including `PublicKey`, as you see above).
+
+### Defining the `init()` method
+
+  The `init` method is similar to the `constructor` in Solidity. It’s a place for you to define any setup that needs to happen before users begin interacting with the contract. In this case, we’ll set the public keys of users who can post, and initialize `message` and `messageHistoryHash` as zero (our front end will interpret the zero value to mean that no messages have been posted yet).
+
+  ```ts
+    @method init() {
+    // Define initial values of on-chain variables
+    this.user1.set(users['Bob'].toPublicKey());
+    this.user2.set(users['SuperBob'].toPublicKey());
+    this.user3.set(users['MegaBob'].toPublicKey());
+    this.message.set(Field.zero);
+    this.messageHistoryHash.set(Field.zero);
+  }
+  ```
+
+  ### Defining `publishMessage()`
+
+The `publishMessage` method will allow an approved user to publish a message. Note the `@method` decorator mentioned earlier. It makes this method callable by users so that they can interact with the smart contract.
+
+For our example, we’ll pass in `message` and `signerPrivateKey` arguments to check that the user holds a private key associated with one of the three on-chain public keys before allowing them to update the message.
+
+```ts
+  @method publishMessage(message: Field, signerPrivateKey: PrivateKey) {
+```
+
+Note that all inputs are private by default and will only exist on the user’s local machine when the smart contract runs; the Mina network will never see them. Our smart contract will only send values that are stored as state to the Mina blockchain. This means that even though the value of the `message` argument will eventually be public, the value of `signerPrivateKey` will never leave the user's machine (as a result of interacting with the smart contract).
+
+### Computing `signerPublicKey` from `signerPrivateKey`
+
+Now that we have the user’s private key, we’ll need to derive the associated public key to check it against the list of approved publishers. Luckily the `PrivateKey` type in SnarkyJS includes a `toPublicKey()` method.
+
+```ts
+    // Compute signerPublicKey from signerPrivateKey argument
+    const signerPublicKey = signerPrivateKey.toPublicKey();
+```
+
+We’ll have to check if this public key matches one of the ones stored on-chain. So let’s grab those as well.
+
+
+```ts
+    // Get approved public keys
+    const user1 = this.user1.get();
+    const user2 = this.user2.get();
+    const user3 = this.user3.get();
+```
+
+Calling the `get()` method tells SnarkyJS to retrieve these values from the zkApp account’s on-chain state. (Note that SnarkyJS uses a single network request to retrieve all on-chain state values simultaneously.)
+
+Finally, we check if `signerPublicKey` is equal to one of the allowed public keys contained in our `user` variables.
+
+```ts
+    // Assert that signerPublicKey is one of the approved public keys
+    signerPublicKey
+      .equals(user1)
+      .or(signerPublicKey.equals(user2))
+      .or(signerPublicKey.equals(user3))
+      .assertEquals(true);
+```
+
+Notice that we call the SnarkyJS `equals()` and `or()` methods instead of using the JavaScript operators (`===`, and `||`). The built-in SnarkyJS methods have the same effect, but they work with SnarkyJS types, and their execution can be verified using a zero-knowledge proof.
+
+`assertEquals(true)` at the end means that it will be impossible to generate a valid proof unless `signerPublicKey` is equal to one of the pre-approved users. The Mina network will reject any transaction sent to a zkApp account that doesn’t include a valid zero-knowledge proof for that account. So it will be impossible for users to post new messages unless they have a private key associated with one of the three pre-approved public keys.
+
+### Updating `message`
+
+Until now, we have worked to ensure that only approved users can call `publishMessage()`. When they do, the contract should update the on-chain message variable to their new message.
+
+```ts
+    // Update on-chain message variable
+    this.message.set(message);
+```
+
+The `set()` method will ask the Mina nodes to update the values of their on-chain message variables, but only if the associated proof is valid.
+
+### Updating `messageHistoryHash`
+
+There’s one more thing we should do. If we want users to be able to keep track of what has been said, then we need to store a commitment to the message history on-chain. There are a few ways to do this, but the simplest is to store a hash of our new `message` and our old `messageHistoryHash` every time we call `publishMessage`.
+
+```ts
+    // Computer new messageHistoryHash
+    const oldHash = this.messageHistoryHash.get();
+    const newHash = Poseidon.hash([oldHash, message]);
+
+    // Update on-chain messageHistoryHash
+    this.messageHistoryHash.set(newHash);
+```
+
+That’s it! Save the file, and let’s make sure everything compiles.
+
+
+```sh
+npm run build
+```
+
+If everything is correct, you should see a new `./build` directory. This is where the compiled version of your project lives that you can import into a user interface.
+
+## Integrating with a User Interface
+
+One of the benefits of writing smart contracts in TypeScript is that they are usually straightforward to <DocLink copy="integrate with UI components" url="/zkapps/how-to-write-a-zkapp" />.
+
+We won’t make you write a UI for this tutorial, but we have created a simple command-line interface so you can interact with your smart contract as a user, get a sense of how it works, and experiment with what you have just built. You can clone it from [this](https://github.com/) repository.
+
+```sh
+git clone https://placeholder.com
+cd ./placeholder
+```
+
+Now install your smart contract:
+
+```sh
+npm install ../zk-message
+```
+
+And start the front end:
+
+```sh
+npm run start
+
+Who are you? (Bob, SuperBob, MegaBob, Jack): Bob
+
+What would you like to say? (should only work if you are one of the Bobs): Snarky is a nice sharky.
+
+Message history:
+Snarky is a nice sharky.
+
+Who are you? (Bob, SuperBob, MegaBob, Jack): Jack
+
+What would you like to say? (should only work if you are one of the Bobs): Hello World!
+
+** GNARLY ERROR **
+```
+
+## Wrapping up
+
+Hopefully you enjoyed this tutorial, and it gave you a sense of what's possible with SnarkyJS. The messaging protocol we built is quite simple but also very powerful. This basic pattern could be used to create a whistleblower system, an anonymous NFT project, or even anonymous DAO voting. SnarkyJS makes it easy for developers to build things that don’t intuitively seem possible, and this is really the point. Zero-knowledge proofs open the door to an entirely different way of thinking about the internet, and we are so excited to see what people like you will build. Make sure to join the [#zkapps-developers](https://placeholder.com) channel on our Discord, and apply for the [zkApp Builders Program](https://placeholder.com) if you are interested in building something more complex with the help of our team at O(1) Labs. More tutorials are on the way ([suggest ideas](https://placeholder.com)), but these are some logical next steps if you are interested in extending this project.
+
+1. Allow users to pass signers into the publishMessage method directly so that many different organizations can use a single contract. (Hint: You’ll have to store a commitment to the signers on-chain.)
+2. Allow users to pass an arbitrarily large number of signers into the publishMessage method.
+3. Store the message history in a Merkle tree so a user interface can check a subset of the messages quickly without evaluating the entire history.
+4. Build a shiny front end!
+
+

src/components/DocsNavs.re

@@ -125,6 +125,10 @@ module DocsNavsTranslations = {
   let zkAppsForEthereumDevelopers= {
     id: "sidenav.zkapps-for-ethereum-developers",
     defaultMessage: "zkApps for Ethereum Developers",
+  };
+    let simpleAnonymousMessageBoardTutorial= {
+    id: "sidenav.simple-anonymous-message-board-tutorial",
+    defaultMessage: "Simple Anonymous Message Board Tutorial",
   };
   let howZkAppsWork = {
     id: "sidenav.how-zkapps-work",
@@ -385,6 +389,10 @@ module SideNav = {
           <Item
             title={intl->Intl.formatMessage(zkAppsForEthereumDevelopers)}
             slug="zkapps-for-ethereum-developers"
+          />
+          <Item
+            title={intl->Intl.formatMessage(simpleAnonymousMessageBoardTutorial)}
+            slug="simple-anonymous-message-board-tutorial"
           />
            <Item
             title={intl->Intl.formatMessage(zkAppsAPIReference)}
@@ -635,6 +643,10 @@ module Dropdown = {
             title={intl->Intl.formatMessage(zkAppsForEthereumDevelopers)}
             slug="zkapps-for-ethereum-developers"
           />
+          <Item
+            title={intl->Intl.formatMessage(simpleAnonymousMessageBoardTutorial)}
+            slug="simple-anonymous-message-board-tutorial"
+          />
         <Item
         title={intl->Intl.formatMessage(zkAppsAPIReference)}
         slug="snarkyjs-reference"