Skip to main content

zkApp programmability is not yet available on the Mina Mainnet. You can get started now by deploying zkApps to the Berkeley Testnet.

zkApps Getting Started

You can start writing zkApps with just a few steps. You can write zkApps for your project in other ways, this Getting Started Guide provides a high-level workflow to build and deploy quickly.

High-Level Workflow

  1. Install or update the zkApp CLI
  2. Create a project
  3. Add testing code
  4. Add functionality
  5. Create an integration test
  6. Test with a live network

1. Install or update the zkApp CLI

npm install -g zkapp-cli

The zkApp CLI provides project scaffolding, including dependencies such as o1js, a test framework, code auto-formatting, linting, and more.

See zkApp CLI Installation.

2. Create a project

zk project <project-name>

o1js is automatically installed when you generate a project using the zkApp CLI.

A zkApp consists of a smart contract and a UI to interact with it.

3. Add testing code

When you use the zkApp CLI to create a project, tests and examples are included.

  1. See the import statements in the Add.test.ts example file.

  2. A LocalBlockchain instance to interact with is included in the Add.test.ts example file.

  3. In o1js, an array of 10 test accounts to pay fees and sign transactions are provided for the LocalBlockchain instance. These can be accessed with Local.testAccounts as shown in the Add.test.ts example file. The example uses the public/private key pairs of two of these accounts. The example uses these names, but the names can be anything:

    • deployerAccount deploys the smart contract
    • senderAccount pays transaction fees
  4. Deploy the smart contract to the LocalBlockchain instance that simulates a network for testing purposes.

    See the localDeploy function in the Add.test.ts example file.

4. Add functionality

Add the logic for your smart contract.

  1. Start experimenting with iterative development to build and test one method at a time. Add functionality to the smart contract by implementing a @method.

    See @method update() in the Add.ts example file.

  2. Build the smart contract:

    npm run build
  3. Invoke the @method you added or use new functionality in the test file.

    See the transaction code that invokes the update() method in the Add.test.ts file.

    • If it works as expected with no errors, add more functionality.
    • If there are errors, look through the stack traces to find the source of the errors and update the contract to resolve them.

5. Create an integration test.

  • Create a Node.js script to run the smart contract and test it's functionality, similar to step 3. Add testing code.

    For an example, see the Node.js script that runs the Tic Tac Toe smart contract in the run.ts file.

6. Test with a live network

To deploy the smart contract to the Testnet, run the zk commands from the directory that contains your smart contract.

  1. Configure your zkApp.

    zk config

    Follow the prompts to specify a deploy alias name (can be anything), URL to deploy to, fee (in MINA) to be used when sending your deploy transaction, and the fee payer account.

    For the Berkeley Testnet, use:

    • Deploy alias name: berkeley

    • Mina GraphQL API URL:

    • Transaction fee to use when deploying: 0.1

    • Account to pay transaction fees: Create a new fee payer pair

    See Add a deploy alias to config.json.

    For other Testnets, use the details provided.

  2. Choose a fee payer alias. A fee payer account is a developer account that is funded and can always pay fees immediately. When you configure a zkApp, you can choose to use a stored account or create a new fee payer account.

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

    • Next, select 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.

  3. Fund your fee payer account.

    Follow the prompts to request tMina.

  4. Deploy to the Testnet.

    zk deploy

    Follow the prompts.

    See How to deploy a zkApp.

  5. Create a script to interact with a live network.

    See the example files:

  6. Run your script.

    For example:

    node build/src/interact.js
  7. Keep building and experimenting! After you add features to your contract, repeat 7. Test with a live network to test with a live network.

Learn more

To learn more about developing zkApps, see how zkApps work, how to write a zkApp, and zkApps for Ethereum Developers.

Try the zkApp Developer Tutorials for use cases that guide you to achieve a defined goal.

Get help and join the community

Join the #zkapps-developers channel on Mina Protocol Discord.