zkApp programmability is not yet available on the Mina Mainnet. You can get started now by deploying zkApps to the Berkeley Testnet.
How to Write a zkApp
A zkApp consists of a smart contract and a UI to interact with it.
Write your smart contract using the zkApp CLI.
First, install the zkApp CLI:
npm install -g zkapp-cli
Start a project
Now that you have the zkApp CLI installed, you can start with an example or start your own project.
Example projects do not create an accompanying UI.
Option A: Start with an example (recommended)
Examples are based on the standard project structure and provide additional files in the /src
directory.
Create the example project:
zk example
The
zk example
command prompts you to select an example project:? Choose an example …
❯ sudoku
tictactoeSelect the
sudoku
example project.The created project includes the example files (the smart contract) in the project's
src/
directory.To see the files that were created, change to the
sudoku
directory and run thels
command or open the directory in a code editor, such as VS Code.Run tests and see the tests pass:
npm run test
To rerun tests automatically when you save changes to your code, run the tests in watch mode with
npm run testw
.Build the example:
npm run build
Compile your TypeScript into JavaScript in the project
/build
directory.Configure your zkApp:
zk config
The command prompts guide you to add a deploy alias to your project
config.json
file.The deploy alias can be anything you want. For more details, see Deploy alias in Tutorial 3: Deploy to a Live Network.
For this example on Berkeley Testnet, use:
Deploy alias name:
berkeley
This example uses
berkeley
, but the deploy alias name can be anything and does not have to match the network name.Mina GraphQL API URL:
https://proxy.berkeley.minaexplorer.com/graphql
Transaction fee to use when deploying:
0.1
Account to pay transaction fees: Create a new fee payer pair
When prompted to choose an account to pay transaction fees, select to use a different account:
Use a different account (select to see options)
If this is the first time you run the
zk config
command, you see these options:❯ Recover fee payer account from an existing base58 private key
Create a new fee payer key pair
The option to choose another account is shown only if the user has a cached fee payer account.
Next, select to create a new fee payer key pair:
Create a new fee payer key pair
NOTE: the private key will be stored in plain text on this computer.When prompted, give an alias to your new fee payer key pair. For this example, use
sudoku
:Create an alias for this account: sudoku
Your key pairs and deploy alias are created.
Fund your fee payer account.
Follow the prompts to request tMINA. For this example, your MINA address is populated on the Testnet Faucet. tMINA arrives at your address when the next block is produced (~3 minutes).
Deploy to Testnet:
zk deploy
Follow the prompts and select the
sudoku
deploy alias. For details, see how to deploy a zkApp.
Option B: Start your own project
Create your own project:
zk project <myproj>
The created project includes the files (the smart contract) in the project's
src/
directory.Select an accompanying UI framework, if any:
? Create an accompanying UI project too? …
❯ next
svelte
nuxt
empty
noneFor your selected UI framework, follow the prompts. See How to Write a zkApp UI.
To see the files that were created, change to the project (whatever you called
<myproj>
) directory and run thels
command or open the directory in a code editor, such as VS Code.Run tests and see the tests pass:
npm run test
To rerun tests automatically when you save changes to your code, run the tests in watch mode with
npm run testw
.Build the example:
npm run build
Compile your TypeScript into JavaScript in the project
/build
directory.Configure your zkApp:
zk config
The command prompts guide you to add a deploy alias to your project
config.json
file.The deploy alias can be anything you want. For more details, see Deploy alias in Tutorial 3: Deploy to a Live Network.
For this example on Berkeley Testnet, use:
Deploy alias name:
berkeley
This example uses
berkeley
, but the deploy alias name can be anything and does not have to match the network name.Mina GraphQL API URL:
https://proxy.berkeley.minaexplorer.com/graphql
Transaction fee to use when deploying:
0.1
Account to pay transaction fees: Create a new fee payer pair
When prompted to choose an account to pay transaction fees, select to use a different account:
Use a different account (select to see options)
If this is the first time you run the
zk config
command, you see these options:❯ Recover fee payer account from an existing base58 private key
Create a new fee payer key pair
The option to choose another account is shown only if the user has a cached fee payer account.
Next, select to create a new fee payer key pair:
Create a new fee payer key pair
NOTE: the private key will be stored in plain text on this computer.When prompted, give an alias to your new fee payer key pair. For this example, use
sudoku
:Create an alias for this account: sudoku
Your key pairs and deploy alias are created.
Fund your fee payer account.
Follow the prompts to request tMina.
Deploy to Testnet:
zk deploy
Follow the prompts. For details, see how to deploy a zkApp.
Writing your smart contract
zkApps are written in TypeScript using o1js. o1js 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 get started writing zkApps, begin with these o1js docs:
Add the smart contract code to your zkApp project using the o1js TypeScript library that was included automatically when you created your project using the zkApp CLI.
A basic smart contract example is generated when you created a zk project. The high-level smart contract code workflow is:
Import
o1js
.See the
import
statement in the Add.ts file.Extend the
SmartContract
class.See the exported
class
in the Add.ts file.
For guided steps to create your first zkApp, start with Tutorial 1: Hello World.
For comprehensive details about the o1js API, see the o1js reference.
Next Steps
Now that you've learned how to write and operate a basic smart contract, you can learn how to test your zkApp.