info

zkApp programmability is not yet available on the Mina Mainnet. You can get started now by deploying zkApps to the Berkeley Testnet.

Tutorial 2: Private Inputs and Hash Functions

In the Hello World tutorial, you built a basic zkApp smart contract with o1js with a single state variable that could be updated if you knew the square of that number.

In this tutorial, you learn about private inputs and hash functions.

With a zkApp, a smart contract user's local device generates one or more zero knowledge proofs, which are then verified by the Mina network. Each method in a o1js smart contract corresponds to constructing a proof.

All inputs to a smart contract are private by default. Inputs are never seen by the blockchain unless you store those values as on-chain state in the zkApp account.

In this tutorial, you build a smart contract with a piece of private state that can be modified if a user knows the private state.

Prerequisites

This tutorial has been tested with Mina zkApp CLI version 0.9.0 and SnarkyJS 0.11.0.

Ensure your environment meets the Prerequisites for zkApp Developer Tutorials.

Create a project

1. Create or change to a directory where you have write privileges.

2. Create a project by using the zk project command:

   $ 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:

   ✔ 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 <your-repo-url>
     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.

3. Change into the 02-private-inputs-and-hash-functions directory and list the contents:

   $ cd 02-private-inputs-and-hash-functions
   $ ls

   The output shows these results:

   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.

Prepare the project

Start by deleting the default files that come with the new project.

1. To delete the default generated files:

   $ rm src/Add.ts
   $ rm src/Add.test.ts
   $ rm src/interact.ts

2. Now, create the new files for your project:

   $ 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.

3. Now, open src/index.ts in a text editor and change it to look like:

   import { IncrementSecret } from './IncrementSecret.js';
   
   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.

Copy the example files

This tutorial relies on the completed code in the 02-private-inputs-and-hash-functions/src/ example files.

1. First, open the IncrementSecret.ts example file.

2. Copy the entire contents of the file into your smart contract in the IncrementSecret.ts file.

3. Next, open the main.ts example file.

4. 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.

Write the smart contract

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.

info

All functions used inside a smart contract must operate on o1js compatible data types: Field types and other types built on top of Field types.

1 import { Field, SmartContract, state, State, method, Poseidon } from 'o1js';

Exports

The smart contract called IncrementSecret has one element of on-chain state named x of type Field as defined by following code:

...
3 export class IncrementSecret extends SmartContract {
  @state(Field) x = State<Field>();
}

This code adds the basic structure for the smart contract. You are familiar with the import and export code from Tutorial 01: Hello World.

Initial State

The initState() method is intended to run once to set up the initial state on the zkApp account.

...
  5
  6   @method initState(salt: Field, firstSecret: Field) {
  7     this.x.set(Poseidon.hash([ salt, firstSecret ]));
  8   }

The initState() method accepts your secret and adds a salt value.

These inputs to the initState() method are private to whoever initializes the contract. The zkApp account on the chain does not reveal what the values firstSecret or salt actually are.

Update the State

This method updates the state:

...
  9
 10   @method incrementSecret(salt: Field, secret: Field) {
 11     const x = this.x.get();
 12     this.x.assertEquals(x);
 13
 14     Poseidon.hash([ salt, secret ]).assertEquals(x);
 15     this.x.set(Poseidon.hash([ salt, secret.add(1) ]));
 16   }
 17 }

Mina uses the Poseidon hash function that is optimized for fast performance inside zero knowledge proof systems. The Poseidon hash function takes in an array of Fields and returns a single Field as output.

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.
• o1js 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.

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.

About the salt argument

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.

Main

The src/main.ts file is similar to the Hello World tutorial. For a full version, see 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:

...
 24 const salt = Field.random();
...
 33 const deployTxn = await Mina.transaction(deployerAccount, () => {
 34   AccountUpdate.fundNewAccount(deployerAccount);
 35   zkAppInstance.deploy();
 36   zkAppInstance.initState(salt, Field(750));
 37 });
 38
 39 await deployTxn.prove();
...

Note that the initState() method accepts the salt and the secret. In this case, the secret is the number 750.

This code creates a user transaction to update the on-chain state:

...
 47 const txn1 = await Mina.transaction(senderAccount, () => {
 48   zkAppInstance.incrementSecret(salt, Field(750));
 49 });
...

Call the zkApp smart contract with both the salt and the secret (the number 750).

Because zkApp smart contracts are executed locally, neither the secret nor the salt are part of the transaction.

Instead, the transaction includes only the proof that the update was called in such a way that all assertions passed and an update to the on-chain state x where the hash value is stored. After the transaction is processed by the Mina network, x is the value of Poseidon.hash([ salt, Field(750).add(1) ]). The underlying salt and secret are not revealed.

Try running main:

$ npm run build && node build/src/main.js

The output looks something like this:

o1js loaded
state after init: 3116464240601550031577632290308565252747064306168758166756574536757280262269
state after txn1: 15333363135506653312218020664441564145350761288169575380089681962972642150348
Shutting down

The state strings are different because Field.random() generates the salt.

Conclusion

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.