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

See zkApp CLI Installation.

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
tictactoe
```
Select 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.
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 in sudoku/src that contain the code for the smart contract.
- This build command compiles the TypeScript code into JavaScript in the sudoku/build directory.
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 pair
```
The 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
none
```
For 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 the ls 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 the Add.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 in yourproject/src that contain the code for the smart contract. This build command compiles the TypeScript code into JavaScript in the yourproject/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.

How to Write a zkApp

Start a project​

Option A: Start with an example (recommended)​

Option B: Start your own project​

Writing your smart contract​

Next Steps​

Start a project

Option A: Start with an example (recommended)

Option B: Start your own project

Writing your smart contract

Next Steps