Documentation

English
  • English
  • Russian
Welcome

info

Please note that zkApp programmability is not yet available on Mina Mainnet, but zkApps can now be deployed to Berkeley QANet.

How to write a zkApp

Learn how to write a smart contract

A zkApp consists of a smart contract and a UI to interact with it. First, we’ll install the Mina zkApp CLI and write a smart contract.

Write a smart contract

Your smart contract will be written using Mina zkApp CLI.

Mina zkApp CLI makes it easy to follow recommended best practices by providing project scaffolding including dependencies such as SnarkyJS, a test framework (Jest), code auto-formatting (Prettier), linting (ES Lint), & more.

Install Mina zkApp CLI

npm install -g zkapp-cli

Dependencies:

  • NodeJS 16+ (or 14 using node --experimental-wasm-threads)
  • NPM 6+
  • Git 2+

tip

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.

Start a project

Now that you have Mina zkApp CLI installed, you can start with an example or start your own project.

Examples are based on the standard project structure, but with additional files in the /src directory as the only difference.

  1. Install: Run zk example sudoku. This creates a new project and includes the example files (i.e. the smart contract) inside the project’s src/ directory. Type ls & hit enter to see the files that were created or open the directory in a code editor such as VS Code.
  2. Run tests: Run npm run test. Tests are written using Jest. After running this command, you should see all tests pass. You can also run npm run testw to run tests in watch mode, so it will automatically re-run tests when saving changes to your code.
  3. Build the example: Run npm run build. This will compile your TypeScript into JavaScript inside the project’s /build directory.
  4. Deploy to QANet: Run zk config, which will walk you through adding a network alias to your project’s config.json. For Berkeley QANet, we recommend using berkeley as the name, 0.1 for the fee, and https://proxy.berkeley.minaexplorer.com/graphql for the url. Then run zk deploy and follow the prompts. See the how to deploy a zkApp page for further details.

You can view a list of all available examples here.

Option B: Start your own project

  1. Install: Run zk project <myproj>. Type ls and hit enter to see the newly created project structure.
  2. Run tests: Run npm run test. Tests are written using Jest. After running this command, you should see all tests pass. You can also run npm run testw to run tests in watch mode, so it will automatically re-run tests when saving changes to your code.
  3. Build: Run npm run build. This will compile your TypeScript code into JavaScript inside the project’s /build.
  4. Deploy to QANet: Run zk config, which will walk you through adding a network alias to your project’s config.json. For Berkeley QANet, we recommend using berkeley as the name, 0.1 for the fee, and https://proxy.berkeley.minaexplorer.com/graphql for the url. Then run zk deploy and follow the prompts. See the how to deploy a zkApp page for further details.
  5. Deploy to Mainnet: (Coming soon.)

Writing your smart contract’s custom logic

The goal of this section is to explain the concepts that you will need to understand to write a zero-knowledge-based smart contract.

If you haven’t yet read the how zkApps work pages, please read it first so that this section makes sense.

SnarkyJS

zkApps are written in TypeScript using SnarkyJS. SnarkyJS is a TypeScript library for writing smart contracts based on zero-knowledge proofs for the Mina Protocol. It is included automatically when creating a new project using the Mina zkApp CLI.

To view the full SnarkyJS reference, please see here.

Concepts

Field elements are the basic unit of data in zero-knowledge proof programming. Each field element can store a number up to almost 256 bits in size. You can think of it as a uint256 in Solidity.

note

For the cryptography inclined, the exact max value that a field can store is: 28,948,022,309,329,048,855,892,746,252,171,976,963,363,056,481,941,560,715,954,676,764,349,967,630,336

For example, in typical programming, you might use:

const sum = 1 + 3.

In SnarkyJS, you would write this as:

const sum = new Field(1).add(new Field(3))

This can be simplified as:

const sum = new Field(1).add(3)

Note that the 3 is auto-promoted to a field type to make this cleaner.

Primitive data types

A couple common data types you may use are:

new Bool(x);   // accepts true or false
new Field(x);  // accepts an integer, or a numeric string if you want to represent a number greater than JavaScript can represent but within the max value that a field can store.
new UInt64(x); // accepts a Field - useful for constraining numbers to 64 bits
new UInt32(x); // accepts a Field - useful for constraining numbers to 32 bits
PrivateKey, PublicKey, Signature; // useful for accounts and signing
new Group(x, y); // a point on our elliptic curve, accepts two Fields/numbers/strings
Scalar; // the corresponding scalar field (different than Field)

In the case of Field and Bool, you can also call the constructor without new:

let x = Field(10);
let b = Bool(true);

info

Support for strings within SnarkyJS will be available soon.

Conditionals

Traditional conditional statements are not yet supported by SnarkyJS:

// this will NOT work
if (foo) {
  x.assertEquals(y);
}

Instead, use SnarkyJS’ built-in Circuit.if() method, which is a ternary operator:

const x = Circuit.if(new Bool(foo), a, b); // behaves like `foo ? a : b`
Functions

Functions work as you would expect in TypeScript. For example:

function addOneAndDouble(x: Field): Field {
  return x.add(1).mul(2);
}
Common methods

Some common methods you will use often are:

let x = new Field(4); // x = 4
x = x.add(3); // x = 7
x = x.sub(1); // x = 6
x = x.mul(3); // x = 18
x = x.div(2); // x = 9
x = x.square(); // x = 81
x = x.sqrt(); // x = 9

let b = x.equals(8); // b = Bool(false)
b = x.greaterThan(8); // b = Bool(true)
b = b.not().or(b).and(b); // b = Bool(true)
b.toBoolean(); // true

let hash = Poseidon.hash([x]); // takes array of Fields, returns Field

let privKey = PrivateKey.random(); // create a private key
let pubKey = PublicKey.fromPrivateKey(privKey); // derive public key
let msg = [hash];
let sig = Signature.create(privKey, msg); // sign a message
sig.verify(pubKey, msg); // Bool(true)

For a full list, see the SnarkyJS reference.

Smart Contract

Let’s put this all together and create a basic smart contract. This where you define your custom logic.

Smart contracts are written by extending the base class SmartContract:

class HelloWorld extends SmartContract {}

A smart contract can contain on-chain state, which is declared as a property on the class with the @state decorator:

class HelloWorld extends SmartContract {
  @state(Field) x = State<Field>();
}

Here, x is of type Field. Only types built out of Field can be used for state variables. In the current design, the state can consist of at most 8 Fields of 32 bytes each. States are initialized with the State() function.

The constructor of a SmartContract is inherited from the base class and should not be overriden. It takes the zkApp account address (a public key) as its only argument:

let zkAppKey = PrivateKey.random();
let zkAppAddress = PublicKey.fromPrivateKey(zkAppKey);

let zkApp = new SmartContract(zkAppAddress);
SnarkyJS Deployment Method

There is one method that every smart contract needs: deploy. It describes how the zkApp account will be initialized when the zkApp is deployed:

class HelloWorld extends SmartContract {
  @state(Field) x = State<Field>();

  deploy(initialBalance: UInt64, x: Field) {
    super.deploy();
    this.balance.addInPlace(initialBalance);
    this.x.set(x);
  }
}

The deploy method needs one default parameter, the initial balance of the zkApp account. The first two lines below are mandatory:

super.deploy();
this.balance.addInPlace(initialBalance);

You are free to add additional parameters, like the initial values of your state. State variables can be initialized during deployment using the .set method on State:

this.x.set(x);

Uninitialized values will be zero.

Methods and state updates

To update your zkApp state or to send MINA, your smart contract will need one or more custom methods.

You declare methods using the @method decorator:

class HelloWorld extends SmartContract {
  @state(Field) x = State<Field>();

  // ...

  @method async increment() {
    const x = await this.x.get();
    this.x.set(x.add(1));
  }
}

The increment() method in our example is async because it calls this.x.get(). This is how you can fetch the current state of the zkApp account from the chain.

The method then sets the new state to x + 1 using this.x.set().

The methods .get() and .set() are defined on every state property.

Assertions

Let's modify the increment() method to accept a parameter:

class HelloWorld extends SmartContract {
  @state(Field) x = State<Field>();

  // ...

  @method async increment(xPlus1: Field) {
    const x = await this.x.get();
    x.add(1).assertEquals(xPlus1);
    this.x.set(xPlus1);
  }
}

Here, after obtaining the current state x, we make an assertion: x.add(1).assertEquals(xPlus1);.

If the assertion fails, SnarkyJS will throw an error and not submit the transaction. On the other hand, if it succeeds, it will become a part of the proof that is sent to the chain and that is verified on-chain.

Because of this, our new version of increment() is guaranteed to behave like the previous version: It can only ever update the state x to x + 1.

Assertions can be incredibly useful to constrain state updates. Common assertions you may use are:

x.assertEquals(y); // x = y
x.assertBoolean(); // x = 0 or x = 1
x.assertLt(y);     // x < y
x.assertLte(y);    // x <= y
x.assertGt(y);     // x > y
x.assertGte(y);    // x >= y

For a full list, see the SnarkyJS reference.

Public and private inputs

While the state of a zkApp is public, method parameters are private.

When a smart contract method is called, its code will execute on the client and generate a proof, which is then sent to the network to update the chain. The proof uses zero-knowledge to hide inputs and details of the computation.

The only way method parameters can be exposed is when the computation explicitly exposes them, as in our last example where the input was directly stored in the public state: this.x.set(xPlus1);

Let's show an example where this is not the case, by defining a new method called incrementSecret():

class HelloWorld extends SmartContract {
  @state(Field) x = State<Field>();

  // ...

  @method async incrementSecret(secret: Field) {
    const x = await this.x.get();
    Poseidon.hash(secret).assertEquals(x);
    this.x.set(Poseidon.hash(secret.add(1)));
  }
}

This time, our input is called secret. We check that the hash of our secret is equal to the current state x. If this is the case, we add 1 to the secret and set x to the hash of that.

When running this successfully, it just proves that the code was run with some input secret whose hash is x, and that the new x will be set to hash(secret + 1). However, the secret itself remains private, because it can't be deduced from it's hash.

Managing State

Updating on-chain state

As we saw before, on-chain state can be managed inside smart contract methods using .get() and .set().

Updating off-chain state

info

Off-chain state is not yet available.

Next Steps

Now that you've learn how to write a smart contract, you can now learn how to test your zkApp.