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 create 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 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) and the example test files in the project's
src
directory.View the files that were created:
- Change to the
sudoku
directory. - Run the
ls
command
Or open the directory in a code editor, such as VS Code.
- Change to the
This example zkApp includes the
sudoku.test.ts
test file. To run tests and see the tests pass:npm run test
To rerun tests automatically after you save changes to your code, you can run the tests in watch mode:
npm run testw
Now that you have confirmed that tests run correctly, you can compile your TypeScript into JavaScript in the project
/build
directory.To build the example:
npm run build
- The
npm run build
command builds the TypeScript files insudoku/src
that contain the code for the smart contract. - This build command compiles the TypeScript code into JavaScript in the
sudoku/build
directory.
- The
Configure your zkApp:
zk config
The command prompts guide you to add a deploy alias to your project
config.json
file.Define a name for the deploy alias.
For this example, use:
devnet
The deploy alias name does not have to match the network name.
Choose the target network kind:
Testnet
Set the Mina GraphQL API URL to deploy to:
https://api.minascan.io/node/devnet/v1/graphql
Set the transaction fee to use when deploying:
0.1
When prompted to choose an account to pay transaction fees, select:
Use a different account (select to see options)
If this is the first time you are running the
zk config
command, you see these options:> Recover fee payer account from an existing base58 private key
Create a new fee payer key pairThe option to choose another account is shown only if you have a cached fee payer account.
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.A fee payer account is a developer account that can always pay fees immediately for local testing. Do not use an account that holds a substantial amount of MINA.
When prompted to create an alias for this account, give an alias to your new fee payer key pair:
testnet-fees
Your key pairs and deploy alias are created.
Fund the fee payer account. After you fund the fee payer account, you can use to to pay fees across multiple zkApps.
Follow the prompts to request tMINA to fund your fee payer account. 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 to select the
devnet
deploy alias and confirm that you want to send the transaction.Your smart contract transaction is pending until the transaction is included in a block.
To view your transaction, click the block explorer link.
For example:
https://minascan.io/devnet/tx/<txn-hash>?type=zk-tx
For details, see How to Deploy a zkApp.
Option B: Start your own project
Instead of using a provided example, you can follow these steps to create your own project.
Create your own project:
zk project <myproj>
The created project includes the smart contract files 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.When you use the zkApp CLI to create a project, the default
Add
smart contract is included along with theAdd.test.ts
test files.npm run test
To rerun tests automatically after you save changes to your code, you can run the tests in watch mode:
npm run testw
To compile your TypeScript into JavaScript in the project
/build
directory, build the example:npm run build
The
npm run build
command builds the TypeScript files inyourproject/src
that contain the code for the smart contract. This build command compiles the TypeScript code into JavaScript in theyourproject/build
directory.Configure your zkApp:
zk config
The command prompts guide you to add a deploy alias to your project
config.json
file.To configure your deploy alias, follow the prompts:
- Create a (deploy alias) name: yourprojecttestnet
- Choose the target network:
Testnet
- Set the Mina GraphQL API URL:
https://api.minascan.io/node/devnet/v1/graphql
- Set transaction fee to use when deploying (in MINA):
0.1
- Choose an account to pay transaction fees:
Create a new fee payer key pair
- Create an alias for this account: yourdeployalias
Your key pair and deploy alias are created.
Fund your fee payer account. Follow the prompts to request tMina.
Deploy to Testnet:
zk deploy yourprojecttestnet
Follow the prompts.
To learn more about deploying, 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. o1js is automatically included when you create a project using the zkApp CLI.
To get started writing zkApps, begin with these o1js docs:
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 about Testing zkApps Locally.