Skip to main content
info

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

See zkApp CLI Installation.

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.

Examples are based on the standard project structure and provide additional files in the /src directory.

  1. Create the example project: zk example

    The zk example 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) in the project's src/ directory.

    To see the files that were created, change to the sudoku directory and run the ls command or open the directory in a code editor, such as VS Code.

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

  3. Build the example: npm run build

    Compile your TypeScript into JavaScript in the project /build directory.

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

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

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

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

  3. 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).

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

  1. Create your own project: zk project <myproj>

    The created project includes the files (the smart contract) in the project's src/ directory.

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

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

  4. Build the example: npm run build

    Compile your TypeScript into JavaScript in the project /build directory.

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

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

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

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

  3. Fund your fee payer account.

    Follow the prompts to request tMina.

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

  1. Import o1js.

    See the import statement in the Add.ts file.

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