diff --git a/.github/workflows/test-tutorials.yml b/.github/workflows/test-tutorials.yml index fa2b6302f..a12b325dc 100644 --- a/.github/workflows/test-tutorials.yml +++ b/.github/workflows/test-tutorials.yml @@ -17,3 +17,17 @@ jobs: git config --global user.email "test@example.com" git config --global user.name "Test" npx ts-node scripts/tutorial-runner.ts docs/zkapps/tutorials/01-hello-world.mdx + + private-inputs-and-hash-functions: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v3 + with: + # In case of version change, update README.md accordingly + node-version: 16 + - run: | + npm ci + git config --global user.email "test@example.com" + git config --global user.name "Test" + npx ts-node scripts/tutorial-runner.ts docs/zkapps/tutorials/02-private-inputs-hash-functions.mdx diff --git a/docs/zkapps/tutorials/02-private-inputs-hash-functions.mdx b/docs/zkapps/tutorials/02-private-inputs-hash-functions.mdx index d2c20efb7..c5826389d 100644 --- a/docs/zkapps/tutorials/02-private-inputs-hash-functions.mdx +++ b/docs/zkapps/tutorials/02-private-inputs-hash-functions.mdx @@ -24,7 +24,6 @@ zkApp programmability is not yet available on the Mina Mainnet. You can get star ::: - # Tutorial 2: Private Inputs and Hash Functions In the [Hello World](hello-world) tutorial, you built a basic zkApp smart contract with SnarkyJS with a single state variable that could be updated if you knew the square of that number. @@ -49,68 +48,75 @@ Ensure your environment meets the [Prerequisites](/zkapps/tutorials#prerequisite 2. Create a project by using the `zk project` command: - ```sh - $ zk project 02-private-inputs-and-hash-functions - ``` - - The `zk project` command has the ability to scaffold the UI for your project. For this tutorial, select `none`: - - ``` - ? Create an accompanying UI project too? … - next - svelte - nuxt - empty - ❯ none - ``` - The expected output is: - - ```sh - ✔ Create an accompanying UI project too? · none - ✔ UI: Set up project - ✔ Initialize Git repo - ✔ Set up project - ✔ NPM install - ✔ NPM build contract - ✔ Set project name - ✔ Git init commit - - Success! - - Next steps: - cd 02-private-inputs-and-hash-functions - git remote add origin - git push -u origin main - ``` - - The `zk project` command creates the `02-private-inputs-and-hash-functions` directory that contains the scaffolding for your project, including tools such as the Prettier code formatting tool, the ESLint static code analysis tool, and the Jest JavaScript testing framework. + + +```sh +$ zk project 02-private-inputs-and-hash-functions +``` + +The `zk project` command has the ability to scaffold the UI for your project. For this tutorial, select `none`: + +```sh +? Create an accompanying UI project too? … + next + svelte + nuxt + empty +❯ none +``` + +The expected output is: + +```sh +✔ Create an accompanying UI project too? · none +✔ UI: Set up project +✔ Initialize Git repo +✔ Set up project +✔ NPM install +✔ NPM build contract +✔ Set project name +✔ Git init commit + +Success! + +Next steps: + cd 02-private-inputs-and-hash-functions + git remote add origin + git push -u origin main +``` + +The `zk project` command creates the `02-private-inputs-and-hash-functions` directory that contains the scaffolding for your project, including tools such as the Prettier code formatting tool, the ESLint static code analysis tool, and the Jest JavaScript testing framework. 1. Change into the `02-private-inputs-and-hash-functions` directory and list the contents: - ```sh - $ cd 02-private-inputs-and-hash-functions - $ ls - ``` - - The output shows these results: - - ```sh - LICENSE - README.md - babel.config.cjs - build - config.json - jest-resolver.cjs - jest.config.js - keys - node_modules - package-lock.json - package.json - src - tsconfig.json - ``` - -For this tutorial, you run commands from the root of the `02-private-inputs-and-hash-functions` directory as you work in the `src` directory on files that contain the TypeScript code for the smart contract. +```sh +$ cd 02-private-inputs-and-hash-functions +$ ls +``` + +The output shows these results: + +```sh +LICENSE +README.md +babel.config.cjs +build +config.json +jest-resolver.cjs +jest.config.js +keys +node_modules +package-lock.json +package.json +src +tsconfig.json +``` + +For this tutorial, you run commands from the root of the `02-private-inputs-and-hash-functions` directory as you work in the `src` directory on files that contain the TypeScript code for the smart contract. Each time you make updates, then build or deploy, the TypeScript code is compiled into JavaScript in the `build` directory. @@ -120,35 +126,35 @@ Start by deleting the default files that come with the new project. 1. To delete the default generated files: - ```sh - $ rm src/Add.ts - $ rm src/Add.test.ts - $ rm src/interact.ts - ``` +```sh +$ rm src/Add.ts +$ rm src/Add.test.ts +$ rm src/interact.ts +``` 1. Now, create the new files for your project: - ```sh - $ zk file src/IncrementSecret - $ touch src/main.ts - ``` +```sh +$ zk file src/IncrementSecret +$ touch src/main.ts +``` - The `zk file` command created the `src/IncrementSecret` file and the `src/IncrementSecret.test.ts` test file. - - However, this tutorial does not include writing tests, so you just use the `main.ts` file as a script to interact with the smart contract and observe how it works. + - However, this tutorial does not include writing tests, so you just use the `main.ts` file as a script to interact with the smart contract and observe how it works. 1. Now, open `src/index.ts` in a text editor and change it to look like: - ```ts - import { IncrementSecret } from './IncrementSecret.js'; - - export { IncrementSecret }; - ``` +```ts src/index.ts +1 import { IncrementSecret } from './IncrementSecret.js'; +2 +3 export { IncrementSecret }; +``` - The `src/index.ts` file contains all of the exports you want to make available for consumption from outside your smart contract project, such as from a UI. +The `src/index.ts` file contains all of the exports you want to make available for consumption from outside your smart contract project, such as from a UI. ### Copy the example files -This tutorial relies on the completed code in the [02-private-inputs-and-hash-functions/src/](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/02-private-inputs-and-hash-functions/src/) example files. +This tutorial relies on the completed code in the [02-private-inputs-and-hash-functions/src/](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/02-private-inputs-and-hash-functions/src/) example files. 1. First, open the [IncrementSecret.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/02-private-inputs-and-hash-functions/src/IncrementSecret.ts) example file. @@ -158,7 +164,7 @@ This tutorial relies on the completed code in the [02-private-inputs-and-hash-fu 1. Copy the entire contents of the file into your smart contract in the `main.ts` file. -Now you are ready to review the imports in the smart contract. +Now you are ready to review the imports in the smart contract. ## Write the smart contract @@ -166,27 +172,27 @@ Now we'll build the smart contract for our application. ### Imports -The `import` statement in the `IncrementSecret.ts` file brings in other packages and dependencies to use in your smart contract. +The `import` statement in the `IncrementSecret.ts` file brings in other packages and dependencies to use in your smart contract. :::info -All functions used inside a smart contract must operate on SnarkyJS compatible data types: `Field` types and other types built on top of `Field` types. +All functions used inside a smart contract must operate on SnarkyJS compatible data types: `Field` types and other types built on top of `Field` types. :::info -```ts ignore +```ts src/IncrementSecret.ts 1 import { Field, SmartContract, state, State, method, Poseidon } from 'snarkyjs'; +2 ``` ### Exports The smart contract called `IncrementSecret` has one element of on-chain state named `x` of type `Field` as defined by following code: -```ts ignore -... +```ts src/IncrementSecret.ts 3 export class IncrementSecret extends SmartContract { - @state(Field) x = State(); -} +4 @state(Field) x = State(); +5 } ``` This code adds the basic structure for the smart contract. You are familiar with the import and export code from [Tutorial 01: Hello World](hello-world). @@ -195,12 +201,14 @@ This code adds the basic structure for the smart contract. You are familiar with The `initState()` method is intended to run once to set up the initial state on the zkApp account. -```ts ignore -... - 5 - 6 @method initState(salt: Field, firstSecret: Field) { - 7 this.x.set(Poseidon.hash([ salt, firstSecret ])); - 8 } +```ts src/IncrementSecret.ts +3 export class IncrementSecret extends SmartContract { +4 @state(Field) x = State(); +5 +6 @method initState(salt: Field, firstSecret: Field) { +7 this.x.set(Poseidon.hash([ salt, firstSecret ])); +8 } +9 } ``` The `initState()` method accepts your secret and adds a `salt` value. @@ -211,8 +219,7 @@ These inputs to the `initState()` method are private to whoever initializes the This method updates the state: -```ts ignore -... +```ts src/IncrementSecret.ts 9 10 @method incrementSecret(salt: Field, secret: Field) { 11 const x = this.x.get(); @@ -230,11 +237,11 @@ This smart contract uses a secret number and the second Field, `salt`. The `incrementSecret()` method checks that the hash of the salt and the secret is equal to the current state `x`: -- If this is the case, add `1` to the secret and set `x` to the hash of the salt and this new secret. +- If this is the case, add `1` to the secret and set `x` to the hash of the salt and this new secret. - SnarkyJS creates a proof of this fact and a JSON description of the state updates to be made on the zkApp account, such as to store the new hash value. - Together, this forms a transaction that can be sent to the Mina network to update the zkApp account. -Because zkApp smart contracts are run off chain, your salt and secret remain private and are never transmitted anywhere. +Because zkApp smart contracts are run off chain, your salt and secret remain private and are never transmitted anywhere. Only the result, updating `x` on-chain state to `hash([ salt, secret + 1])` is revealed. Because the salt and secret can't be deduced from their hash, they remain private. @@ -242,16 +249,81 @@ Only the result, updating `x` on-chain state to `hash([ salt, secret + 1])` is r Cryptographic salt adds an additional layer of security to a smart contract. The extra `salt` argument prevents a possible attack on the smart contract. If you just use `secret`, the contract is vulnerable to discovery by an attacker. An attacker could try hashing likely secrets and then check if the hash matches the hash stored in the smart contract. If the hash were to match, then the attacker knows they have discovered the secret. This scenario is particularly concerning if the secret is likely to be within a particular subset of possible values, say between 1 and 10,000. In that case, with just 10,000 hashes, the attacker could discover the secret. -Adding salt as a second input to the contract code makes it harder for an attacker to reverse engineer the code and gain access to the contract. Salt makes the contract more secure and helps protect the data stored within it. For optimal security, the salt is known only to you and is typically random. +Adding salt as a second input to the contract code makes it harder for an attacker to reverse engineer the code and gain access to the contract. Salt makes the contract more secure and helps protect the data stored within it. For optimal security, the salt is known only to you and is typically random. ## Main -The `src/main.ts` file is similar to the Hello World tutorial. For a full version, see [main.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/02-private-inputs-and-hash-functions/src/main.ts). +The `src/main.ts` file is similar to the Hello World tutorial. For a full version, see [main.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/02-private-inputs-and-hash-functions/src/main.ts). For this tutorial, the key parts to discuss are initializing our contract and using the poseidon hash. The smart contract initialization this time is: + + ```ts ignore ... 24 const salt = Field.random(); @@ -268,7 +340,7 @@ Note that the `initState()` method accepts the salt and the secret. In this case This code creates a user transaction to update the on-chain state: -```ts +```ts ignore ... 47 const txn1 = await Mina.transaction(senderAccount, () => { 48 zkAppInstance.incrementSecret(salt, Field(750)); @@ -290,7 +362,7 @@ $ npm run build && node build/src/main.js The output looks something like this: -```text +```sh ignore SnarkyJS loaded state after init: 3116464240601550031577632290308565252747064306168758166756574536757280262269 state after txn1: 15333363135506653312218020664441564145350761288169575380089681962972642150348 @@ -303,4 +375,4 @@ The `state` strings are different because `Field.random()` generates the salt. Congratulations! You built a smart contract that uses privacy and hash functions. -To deploy zkApps to a live network, see [Tutorial 3: Deploy to a Live Network](deploying-to-a-network). +To deploy zkApps to a live network, see [Tutorial 3: Deploy to a Live Network](deploying-to-a-network).