Merge pull request #540 from o1-labs/300-tuto5

Verify Tutorial 5: Common Types and Functions

Author: barriebyron

docs/zkapps/tutorials/05-common-types-and-functions.mdx

@@ -2,7 +2,7 @@
 title: 'Tutorial 5: Common Types and Functions'
 hide_title: true
 sidebar_label: 'Tutorial 5: Common Types and Functions'
-description: Higher-order types are built from Fields and are useful for your development. Learn how to create custom types.
+description: Higher-order types are built from Fields. Create custom types to build your own strings. Create compound data types with the Struct.
 keywords:
   - smart contracts
   - zkapps
@@ -14,6 +14,10 @@ keywords:
   - zk
   - blockchain
   - mina
+  - custom types
+  - basic types
+  - circuits
+  - struct
 ---
 
 import ResponsiveVideo from '@site/src/components/common/ResponsiveVideo';
@@ -24,35 +28,36 @@ zkApp programmability is not yet available on the Mina Mainnet. You can get star
 
 :::
 
-:::note
 
-This tutorial was last tested with [SnarkyJS](https://www.npmjs.com/package/snarkyjs) 0.8.0.
+# Tutorial 5: Common Types and Functions
 
-:::
+In previous tutorials, you learned how to deploy smart contracts to the network interact with them from a React UI and NodeJS.
 
-# Tutorial 5: Common Types and Functions
+In this tutorial, you learn about types you can use when building with SnarkyJS. Earlier tutorials mostly use the `Field` type. SnarkyJS provides other higher-order types built from Fields that are useful for zkApp development and expand the possibilities for more applications.
 
-In previous tutorials, we've seen how to deploy smart contracts to the network, and we've interacted with them from both a React UI and NodeJS.
+All types are defined in the [SnarkyJS / Modules / Types](/zkapps/snarkyjs-reference/modules/Types) API reference documentation.
 
-In this tutorial, we will talk about more types that are useful when building with SnarkyJS, so you can build more applications. So far, we've mostly been using the `Field` type. SnarkyJS provides other higher-order types built from Fields, that will be useful for your development.
+The [example project](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/05-common-types-and-functions/src) includes a [main.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/05-common-types-and-functions/src/main.ts) file that shows all of the concepts presented in this tutorial, along with smart contracts showing more advanced usage of some of the concepts, particularly Merkle Trees.
 
-You can find all of these on the [SnarkyJS Reference page](../snarkyjs-reference), for their full API documentation.
+## Prerequisites
 
-There is also a project [here](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/05-common-types-and-functions/src), with a [main.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/05-common-types-and-functions/src/main.ts) demoing the concepts presented in this tutorial, along with smart contracts showing more advanced usage of some of the concepts, particularly Merkle Trees.
+This tutorial has been verified with [Mina zkApp CLI](https://github.com/o1-labs/zkapp-cli) version `0.11.0` and [SnarkyJS](https://www.npmjs.com/package/snarkyjs) `0.12.1`.
+
+Ensure your environment meets the [Prerequisites](/zkapps/tutorials#prerequisites) for zkApp Developer Tutorials.
 
 ## Basic Types
 
-To start, we'll discuss 5 basic types derived from the Fields:
+Five basic types are derived from Fields:
 
 - [Bool](../snarkyjs-reference/classes/Bool)
 - [UInt32](../snarkyjs-reference/classes/UInt32)
 - [UInt64](../snarkyjs-reference/classes/UInt64)
 - [Int64](../snarkyjs-reference/classes/Int64)
 - [Character](../snarkyjs-reference/classes/Character)
 
-These each have their usual programming language semantics.
+Each type has the usual programming language semantics.
 
-For example, we can have the following code:
+For example, the following code:
 
 ```ts
 const num1 = UInt32.from(40);
@@ -84,7 +89,7 @@ console.log(`char1 === char2: ${char1EqualsChar2.toString()}`);
 console.log(`Fields in char1: ${char1.toFields().length}`);
 ```
 
-And when run it'll print to the console:
+This result prints to the console when the code is run:
 
 ```
 num1 === num2: true
@@ -98,20 +103,20 @@ Fields in char1: 1
 
 ## More Advanced Types
 
-4 more advanced types are:
+Four advanced types are:
 
 - [CircuitString](../snarkyjs-reference/classes/CircuitString)
 - [PrivateKey](../snarkyjs-reference/classes/PrivateKey)
 - [PublicKey](../snarkyjs-reference/classes/Types.PublicKey)
 - [Signature](../snarkyjs-reference/classes/Signature)
 
-All arguments passed into smart contracts need to be arguments SnarkyJS can understand. This means that we can't just pass normal strings - we need to pass in strings that have been wrapped to be compatible with circuits, which is what `Struct` accomplishes.
+All arguments passed into smart contracts must be arguments SnarkyJS can consume. You cannot pass normal strings. Instead, you must pass in strings that are wrapped to be compatible with circuits. This is accomplished with `Struct`.
 
-One special thing to note, is that the default `CircuitString` has a max length of 128 characters. This is because, under the hood, SnarkyJS types have to be fixed length. However, the `CircuitString` API abstracts this away and can be used like a dynamic length string, with the only caveat being the max length.
+The default `CircuitString` has a maximum length of 128 characters because SnarkyJS types must be fixed length. However, the `CircuitString` API abstracts this restriction away and can be used like a dynamic length string with the maximum length caveat.
 
-We'll see in the following section how to create custom types, where you could for example build your own strings, modified to whatever length you would like.
+You can create custom types to build your own strings, modified to whatever length you want.
 
-A brief example of using these:
+A brief example of custom types:
 
 ```ts
 const str1 = CircuitString.fromString('abc..xyz');
@@ -156,19 +161,21 @@ signature verified for data2: true
 Fields in signature: 256
 ```
 
-Small but important note: Make sure that you never use the private key above (or any private key that's publicly accessible) in a real application!
+Observe and follow best practices for your key security. Make sure that you never use the private key in this example output, or any private key that's publicly accessible, in a real application.
 
-If you're curious why there are 255 Fields in a private key and 256 in a signature - the reason for this is cryptographic in nature: Elliptic curve scalars are most efficiently represented in a SNARK as an array of bits, and the bit length of these scalars happens to be 255.
+There are 255 Fields in a private key and 256 Fields in a signature. If you are curious about the reason for this, the answer is cryptographic in nature: Elliptic curve scalars are most efficiently represented in a SNARK as an array of bits, and the bit length of these scalars is 255.
 
 ## Struct
 
-A special type is [Struct](../snarkyjs-reference#struct), which lets you create your own compound data types.
+You can create your own compound data types with the special [Struct](../snarkyjs-reference#struct) type.
+
+Define a Struct as one or more data types that SnarkyJS understands. For example, Field, higher-order types built into SnarkyJS based on Field, or other Struct types defined by you. You can also define methods on your Struct to act upon this data type.
 
-Your Struct can be defined as one or more data types that SnarkyJS understands, i.e. Field, higher-order types built into SnarkyJS based on Field, or other Struct types defined by you. You can also define methods on your Struct to act upon this data type, if desired, but doing so is optional.
+The following example demonstrates how to use `Struct` to implement a `Point` structure and an array of points of length 8 structure.
 
-See the following for an example of how to use `Struct`, implementing a `Point` structure, and an array of points of length 8 structure.
+In SnarkyJS, programs are compiled into fixed-sized circuits. This means that data structures it consumes must also be a fixed size. 
 
-SnarkyJS compiles programs into fixed sized circuits. This means that data structures it consumes must also be a fixed size, and is why we declare the array in `Points8` structure to be a static size of 8 in the example below.
+To meet the fixed-size requirement, this code declares the array in `Points8` structure to be a static size of 8.
 
 ```ts
 class Point extends Struct({ x: Field, y: Field }) {
@@ -196,23 +203,24 @@ const points8: Points8 = { points };
 console.log(`points8 JSON: ${JSON.stringify(points8)}`);
 ```
 
-Which prints the following to the console:
+The console output:
 
 ```
 pointSum Fields: 11,6
 points8 Fields: {"points":[{"x":"0","y":"0"},{"x":"1","y":"10"},{"x":"2","y":"20"},{"x":"3","y":"30"},{"x":"4","y":"40"},{"x":"5","y":"50"},{"x":"6","y":"60"},{"x":"7","y":"70"}]}
 ```
 
-## Control flow
+## Control Flow
 
-There are two functions which help do control flow within SnarkyJS:
+Two functions help do control flow in SnarkyJS:
 
 - [Provable.if](../snarkyjs-reference/classes/Circuit#if)
-- [Provable.switch](../snarkyjs-reference/classes/Circuit#switch)
+  Similar to a ternary in JavaScript
 
-`Provable.if` is similar to a ternary in JavaScript. `Provable.switch` is similar to a switch case statement in JavaScript.
+- [Provable.switch](../snarkyjs-reference/classes/Circuit#switch)
+  Similar to a switch case statement in JavaScript
 
-With these, you can write conditionals inside SnarkyJS.
+You can write conditionals inside SnarkyJS with these functions.
 
 For example:
 
@@ -263,30 +271,30 @@ inputSumAbs: 5
 largest: 22
 ```
 
-Note that when using `Provable.if`, like in a JS ternary, both branches are executed. Unlike normal programming, because SnarkyJS under the hood is creating a zk circuit, there is no primitive for if statements where only one branch is executed.
+Both branches are executed when using `Provable.if`, like in a JavaScript ternary. Because SnarkyJS is creating a zk circuit, there is no primitive for `if` statements where only one branch is executed.
 
 ## Assertions and Constraints
 
 SnarkyJS functions are compiled to generate circuits.
 
-When a transaction is proven in SnarkyJS, SnarkyJS is proving that the program logic is computed according to the written program, and all assertions are holding true.
+When a transaction is proven in SnarkyJS, the proof is that the program logic is computed according to the written program, and all assertions are holding true.
 
-We've seen assertions already, with `a.assertEquals(b)`, which we've often used. There is also `.assertTrue()` available on the Bool class.
+In previous tutorials, you learned `a.assertEquals(b)`. The `.assertTrue()` is available on the Bool class.
 
-Circuits in SnarkyJS currently have a fixed maximum size. Each operation performed in a function counts towards this maximum size. This maximum size is currently equivalent to the following:
+Circuits in SnarkyJS have a fixed maximum size. Each operation performed in a function counts towards this maximum size. This maximum size is equivalent to:
 
 - about 5,200 hashes on two fields
 - about 2,600 hashes on four fields
 - about `2^17` field multiplies
 - about `2^17` field additions
 
-If a program is too large to fit into these constraints, it can be broken up into multiple recursive proof verifications. See more on how to do this in the section [here](../snarkyjs/recursion).
+If a program is too large to fit into these constraints, it can be broken up into multiple recursive proof verifications. See [Recursion](../snarkyjs/recursion).
 
 ## Merkle Trees
 
-Lastly, let's go over an example using [merkle trees](../snarkyjs-reference/classes/MerkleTree). Merkle trees are very powerful, since they let us manage large amounts of data within a circuit. In the [project corresponding to this tutorial](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/05-common-types-and-functions/src), you can find a full reference for the example here. The contract can be found in [BasicMerkleTreeContract.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/05-common-types-and-functions/src/BasicMerkleTreeContract.ts), and the example can be found in a section of [main.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/05-common-types-and-functions/src/main.ts).
+You can use [Merkle trees](../snarkyjs-reference/classes/MerkleTree) to manage large amounts of data within a circuit. The power of Merkle trees is demonstrated in the [05-common-types-and-functions/src](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/05-common-types-and-functions/src) reference project for this tutorial. See the [BasicMerkleTreeContract.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/05-common-types-and-functions/src/BasicMerkleTreeContract.ts) contract and [main.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/05-common-types-and-functions/src/main.ts) that demonstrates how contracts interact with Merkle trees and how to construct them.
 
-Start off by importing `MerkleTree`:
+The first step is to import `MerkleTree`:
 
 ```ts
 import {
@@ -296,18 +304,20 @@ import {
 } from 'snarkyjs'
 ```
 
-Merkle Trees can be created in your application like so:
+To create Merkle trees in your application:
 
 ```ts
 const height = 20;
 const tree = new MerkleTree(height);
 ```
 
-The height variable determines how many leaves are available to your application. A height of 20 for example will lead to a tree with `2^(20-1)`, or 524,288 leaves.
+The height variable determines how many leaves are available to the application. For example, a height of 20 leads to a tree with `2^(20-1)`, or 524,288 leaves.
 
-Merkle trees in smart contracts are stored as the hash of the merkle tree's root. Smart contract methods which update the merkle root can take a "witness" of the change as an argument, which represents the merkle path to the data for which inclusion is being proved.
+Merkle trees in smart contracts are stored as the hash of the Merkle tree's root. Smart contract methods that update the Merkle root can take a _witness_ of the change as an argument. The [MerkleMapWitness](/zkapps/snarkyjs-reference/classes/MerkleMapWitness) represents the Merkle path to the data for which inclusion is being proved.
 
-Here is a simple example of a contract that stores the root of a merkle tree, where each leaf stores a number, and the smart contract has an `update` function that adds a number to the leaf. As an example of putting a condition on a leaf update, the `update` function checks that the number added was less than 10.
+A contract stores the root of a Merkle tree, where each leaf stores a number, and the smart contract has an `update` function that adds a number to the leaf. 
+
+For example, to put a condition on a leaf update, the `update` function checks that the number added was less than 10:
 
 ```ts
 ...
@@ -341,7 +351,7 @@ Here is a simple example of a contract that stores the root of a merkle tree, wh
   }
 ```
 
-And code to interact with it:
+The code to interact with the smart contract:
 
 ```ts
 // initialize the zkapp
@@ -401,13 +411,15 @@ console.log(
 );
 ```
 
-While in this example leaves are fields, you can put more variables in a leaf by instead hashing an array of fields, and setting a leaf to that.
+In this example, leaves are fields. However, you can put more variables in a leaf by hashing an array of fields and setting a leaf to that hash.
+
+This complete example is in the [project directory](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/05-common-types-and-functions/src).
 
-You can find this complete example in the [project directory](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/05-common-types-and-functions/src), as well as a more advanced example `LedgerContract`, which implements a basic ledger of tokens, including checks that the sender has signed their transaction and that the amount the sender has sent matches the amount the receiver receives.
+A more advanced example `LedgerContract` implements a basic ledger of tokens, including checks that the sender has signed their transaction and that the amount the sender has sent matches the amount the receiver receives.
 
 ## Merkle Map
 
-Lastly, let's go over an example using [merkle maps](../snarkyjs-reference/classes/MerkleMap). These allow us to implement key value stores.
+See the API reference documentation for the [MerkleMap](../snarkyjs-reference/classes/MerkleMap) class you can use to implement key-value stores.
 
 The API for Merkle Maps is similar to Merkle Trees, just instead of using an index to set a leaf, one uses a key:
 
@@ -462,7 +474,7 @@ It can be used inside smart contracts with a witness, similar to merkle trees
   }
 ```
 
-With (abbreviated) code to interact with it, similar to the merkle tree example above:
+With (abbreviated) code to interact with it, similar to the Merkle tree example above:
 
 ```ts
 const map = new MerkleMap();
@@ -487,16 +499,16 @@ const txn1 = await Mina.transaction(deployerAccount, () => {
 ...
 ```
 
-MerkleMaps can be used to implement many useful patterns. For example:
+You use [MerkleMaps](/zkapps/snarkyjs-reference/classes/MerkleMap) to implement many useful patterns. For example:
 
 - A key value store from public keys to booleans, of token accounts to whether they've participated in a voted yet.
 - A nullifier that privately tracks if an input was used, without revealing it.
 
 ## Conclusion
 
-Congrats! We have finished reviewing more common types and functions in SnarkyJS. With this, you should now be capable of writing many advanced smart contracts and zkApps.
+Congratulations! You have finished reviewing more common types and functions in SnarkyJS. With this, you should now be capable of writing many advanced smart contracts and zkApps.
 
-Checkout [Tutorial 6](offchain-storage) to learn how to use off-chain storage, to use more data from your zkApp.
+To use more data from your zkApp, check out [Tutorial 6](offchain-storage) to learn how to use off-chain storage.
 
 ## Other Resources