Please note that zkApp programmability is not yet available on Mina Mainnet, but zkApps can now be deployed to Berkeley Testnet.
Tutorial 1: Hello World
Overview
In this tutorial, we will code a zkApp step by step, from start to finish.
We will write a basic smart contract that stores a number as on-chain state and contains logic to only allow this number to be replaced by its square (e.g. 2 -> 4 -> 16...). We will create this project using the Mina zkApp CLI, write our smart contract code, and then use a local Mina blockchain to interact with it.
Future tutorials will introduce further concepts and patterns. But we hope this helps you get started with SnarkyJS, zkApps, and programming with zero knowledge proofs. Then you can go further by reading the zkApps docs and additional tutorials.
You can find the full source code for this example here.
Setup
First, install the Mina zkApp CLI, if you haven’t already.
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 (Mac), Chocolatey (Windows), or apt/yum/etc (Linux). On Linux, you may need to install a recent NodeJS version via NodeSource (deb or rpm), as recommended by the NodeJS Project.
Installation
npm install -g zkapp-cli
To confirm it is installed, run:
zk --version
This tutorial has been tested as of Mina zkApp CLI version 0.4.17 and SnarkyJS 0.6.0.
Create a new project
Now that you have the tooling installed, we can start building our application.
First, create a new project using:
zk project 01-hello-world
This will create a directory named 01-hello-world containing scaffolding for our project, including tools such as Prettier, ESLint, & Jest.
Let's change into this directory and list the contents to see what it created:
$ cd 01-hello-world
$ ls
LICENSE build jest.config.js package-lock.json tsconfig.json
README.md config.json keys package.json
babel.config.cjs jest-resolver.cjs node_modules src
We will be working mostly within the src directory, which will contain the TypeScript code for our smart contract. When we build or deploy (which automatically builds for us), our TypeScript will be compiled into JavaScript inside the build directory.
Preparing the project
We will start by creating files for our project and deleting the default files that come with the new project.
First, delete the old files. Run:
rm src/Add.ts
rm src/Add.test.ts
And generate the new files for our project. Enter:
zk file src/Square
touch src/main.ts
The zk file <name> command created both src/Square.ts and src/Square.test.ts for us, but we won't worry about writing tests in this tutorial. We'll use main.ts as a script to interact with the smart contract and observe how it works. In future tutorials, we will see how to interact with a smart contract from the browser, like a typical end user, but for now we'll just use our main.ts script to do this.
Now, let's open src/index.ts in a text editor and change it to look like below. This file contains all exports we want to make available for consumption from outside our smart contract project, such as from a UI.
import { Square } from './Square.js';
export { Square };
Building and running
The following commands are included for reference, and will fail if you run them at this point. This is because we haven't written the Square smart contract yet.
To compile the TypeScript code into JavaScript, and run the JavaScript code, you'll type:
npm run build
node build/src/main.js
The first line creates JavaScript code in the build directory, while the second line runs the code in src/main.ts.
You can also combine these together into one line, such as:
npm run build && node build/src/main.js
This will run main if the build is successful.
Write the zkApp Smart Contract
Now, the fun part! Let's write our smart contract: src/Square.ts. Line numbers are provided for convenience. A final version of what we're writing can be found here.
To avoid inserting the line numbers into your smart contract, copy these code snippets using the button provided. It will appear at the top right of the snippet box when you mouseover it.
Imports
First, open src/Square.ts in your editor, then add the following at the top of the file:
1 import {
2 Field,
3 SmartContract,
4 state,
5 State,
6 method,
7 DeployArgs,
8 Permissions,
9 } from 'snarkyjs';
What each of these are:
Field: The native "number" type in SnarkyJS. You can think of these as unsigned integers. These are the most basic type in SnarkyJS and are what all other SnarkyJS-compatible types are built on top of.SmartContract: The class that creates zkApp smart contracts.state: a convenience decorator used within zkApp smart contracts to create references to state stored on chain in a zkApp account.State: a class used within zkApp smart contracts to create state stored on chain in a zkApp account.method: a convenience decorator used within zkApp smart contracts to create new smart contract methods (i.e. functions). Methods that uses this decorator are the end user's entry points to interacting with our smart contract.DeployArgs: The type for arguments submitted to a newly deployed smart contract.Permissions: An collection of methods for manipulating zkApp smart contract permissions.
Smart contract class
Now, we will write the smart contract. Write the following in your file:
10
11 export class Square extends SmartContract {
12 @state(Field) num = State<Field>();
13
14 }
This creates a new smart contract called Square with one element of on-chain state named num of type Field. zkApps can have up to 8 fields worth of on-chain state, each storing up to 32 bytes of arbitrary data. A later tutorial will discuss options for off-chain state.
Now, let's add our deploy method:
11 export class Square extends SmartContract {
12 @state(Field) num = State<Field>();
13
14 deploy(args: DeployArgs) {
15 super.deploy(args);
16 this.setPermissions({
17 ...Permissions.default(),
18 editState: Permissions.proofOrSignature(),
19 });
20 }
21
22 }
This method describes how we want to deploy our smart contract. This will be the same for many smart contracts. It is also where we specify the permissions for how we want to allow others to interact with our smart contract.
In this case, we will allow our zkApp on-chain state to be altered by transactions containing account updates with either proof or signature authorization. Proof authorization allows end users to alter the zkApp account state if their transaction was generated from your smart contract code. Signature authorization allows whomever deployed the smart contract to edit it.
Next, we will add an init() method:
18 editState: Permissions.proofOrSignature(),
19 });
20 }
21
22 @method init() {
23 this.num.set(Field(3));
24 }
25
26 }
This method is used to set initial values of our zkApp account's on-chain state. In this case, we will initialize our on-chain state named num to a value of 3.
Lastly, we will add our update function:
23 this.num.set(Field(3));
24 }
25
26 @method update(square: Field) {
27 const currentState = this.num.get();
28 this.num.assertEquals(currentState);
29 square.assertEquals(currentState.mul(currentState));
30 this.num.set(square);
31 }
32
33 }
The name update is arbitrary, but makes sense for our example. Notice that we use the @method decorator because we intend for this method to be invoked by end users, such as via a zkApp UI or our main.ts script in this case.
This method will contain our logic by which end users are allowed to update our zkApp's account state on chain. In this example, we are saying that if the user provides a number (e.g. 9) to the update() method that is the square of the existing on-chain state referred to as num (e.g. 3), then we'll update the num value stored on chain to the provided value (e.g. 9). If the user provides a number that does not meet these conditions, they will not be able to generate a proof or update the on-chain state.
This is accomplished through using "assertions" within our method. When a user invokes a method on a smart contract, all assertions must be true in order to generate the zero knowledge proof from that smart contract; the Mina network will only accept the transaction and update the on-chain state if the attached proof is valid. This is how we can achieve predictable behavior in an off-chain execution model.
Notice that we have get() and set() methods for retrieving and setting on-chain state. A smart contract retrieves the on-chain account state when it is first invoked if at least one get() exists within it. Similarly, using set() will change the transaction to indicate we want to change this particular on-chain state, but it will only be updated when the transaction is received by the Mina network if it contains a valid authorization (i.e. a proof usually).
Our logic also uses the .mul() method for multiplication of our values stored in fields. You can view all available methods in the SnarkyJS reference. Keep in mind that all functions used inside your smart contract must operate on SnarkyJS compatible data types (e.g. Fields and other types built on top of Fields). This is to say, functions from random NPM packages won't work inside our smart contract, because it's really a zero-knowledge circuit, unless the functions it provides operate on SnarkyJS-compatible data types.
Importantly, data passed as an input to smart contract method in SnarkyJS is private and never seen by the network. But you can also store data publicly on-chain when needed, such as we do with our num in this example. A future tutorial will cover an example leveraging privacy.
This completes the smart contract!
Interacting with our smart contract
Next, we will write a script that interacts with our smart contract, so we can easily test it out, for purposes of this tutorial.
Open up src/main.ts in your editor. A complete version of this file can be found here.
Imports
Add the following:
1 import { Square } from './Square.js';
2 import {
3 isReady,
4 shutdown,
5 Field,
6 Mina,
7 PrivateKey,
9 AccountUpdate,
10 } from 'snarkyjs';
11
...
What each of these imports are:
isReady: an asynchronous promise that tells us when SnarkyJS is loaded and ready. This is necessary because SnarkyJS contains WASM.shutdown: a function that closes our program.Field: SnarkyJS' unsigned integer type, that we've seen above.Mina: A local Mina blockchain. We will deploy our smart contract to this in order to interact with it as a user would.PrivateKey: a class with functions for manipulating private keys.AccountUpdate: a class that generates a data structure referred to as an AccountUpdate that can update zkApp accounts.
Local Blockchain
Now add the following code to your src/main.ts:
...
11
12 (async function main() {
13 await isReady;
14
15 console.log('SnarkyJS loaded')
16
17 const Local = Mina.LocalBlockchain();
18 Mina.setActiveInstance(Local);
19 const deployerAccount = Local.testAccounts[0].privateKey;
20
21 console.log('Shutting down')
22
23 await shutdown();
24 })();
...
Now when you run npm run build && node build/src/main.js, your main function should run!
In production, you'll deploy your zkApp to Mina network. But this "local blockchain" allows us to speed up development and test the behavior of our smart contract locally. This local blockchain also provides pre-funded accounts (e.g. the deployerAccount above). Later tutorials will discuss how to deploy your zkApp to live Mina networks, such as Berkeley Testnet.
zkApp programmability is currently available on Berkeley Testnet, Mina's public testnet, which is in its final stages of testing before Mainnet.
Initializing our smart contract
Now, let's initalize our smart contract. Comments are provided to break down each stage.
...
19 const deployerAccount = Local.testAccounts[0].privateKey;
20
21 // ----------------------------------------------------
22
23 // Create a public/private key pair. The public key is our address and where we will deploy to
24 const zkAppPrivateKey = PrivateKey.random();
25 const zkAppAddress = zkAppPrivateKey.toPublicKey();
26
27 // Create an instance of our Square smart contract and deploy it to zkAppAddress
28 const contract = new Square(zkAppAddress);
29 const deployTxn = await Mina.transaction(deployerAccount, () => {
30 AccountUpdate.fundNewAccount(deployerAccount);
31 contract.deploy({ zkappKey: zkAppPrivateKey });
32 contract.init();
33 contract.sign(zkAppPrivateKey);
34 });
35 await deployTxn.send().wait();
36
37 // Get the initial state of our zkApp account after deployment
38 const num0 = contract.num.get();
39 console.log('state after init:', num0.toString());
40
41 // ----------------------------------------------------
42
43 console.log('Shutting down')
...
The above code will be similar for any smart contract that you create.
Try running this now with: npm run build && node build/src/main.js. The output should be:
$ npm run build && node build/src/main.js
...
SnarkyJS loaded
state after init: 3
Shutting down
Updating our zkApp account with a transaction
Now let's try updating our local zkApp account with a transaction! Add the following:
...
39 console.log('state after init:', num0.toString());
40
41 // ----------------------------------------------------
42
43 const txn1 = await Mina.transaction(deployerAccount, () => {
44 contract.update(Field(9));
45 contract.sign(zkAppPrivateKey);
46 });
47 await txn1.send().wait();
48
49 const num1 = contract.num.get();
50 console.log('state after txn1:', num1.toString());
51
52 // ----------------------------------------------------
53
54 console.log('Shutting down')
...
This code creates a new transaction that attempts to update the field to the value 9. Because this follows the rules in the update() function that we are calling on the smart contract, this should pass. And if you run it, it should!
Use npm run build && node build/src/main.js again to run it:
...
SnarkyJS loaded
state after init: 3
state after txn1: 9
Shutting down
Now let's try adding a transaction that should fail - updating the state to 75. Now that num is in state 9, updating should only be possible with 81.
...
50 console.log('state after txn1:', num1.toString());
51
52 // ----------------------------------------------------
53
54 try {
55 const txn2 = await Mina.transaction(deployerAccount, () => {
56 contract.update(Field(75));
57 contract.sign(zkAppPrivateKey);
58 });
59 await txn2.send().wait();
60 } catch (err: any) {
61 console.log(err.message);
62 }
63 const num2 = contract.num.get();
64 console.log('state after txn2:', num2.toString());
65
66 // ----------------------------------------------------
67
68 console.log('Shutting down')...
...
Run this again with npm run build && node build/src/main.js. The output should be:
...
SnarkyJS loaded
state after init: 3
state after txn1: 9
assert_equal: 75 != 81
state after txn2: 9
Shutting down
And lastly, to show the correct update:
...
64 console.log('state after txn2:', num2.toString());
65
66 // ----------------------------------------------------
67
68 const txn3 = await Mina.transaction(deployerAccount, () => {
69 contract.update(Field(81));
70 contract.sign(zkAppPrivateKey);
71 });
72 await txn3.send().wait();
73
74 const num3 = contract.num.get();
75 console.log('state after txn3:', num3.toString());
76
77 // ---------------------------------------
78
79 console.log('Shutting down')
...
Run this again with npm run build && node build/src/main.js. The output should be:
...
SnarkyJS loaded
state after init: 3
state after txn1: 9
assert_equal: 75 != 81
state after txn2: 9
state after txn3: 81
Shutting down
Conclusion
Congrats! We have finished building our first zkApp with SnarkyJS.
Checkout Tutorial 2 to learn how to use private inputs and hash functions with SnarkyJS.