Skip to main content

zkApps Getting Started

You can start writing zkApps with just a few steps. The focus of this Getting Started Guide is 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 locally
  7. Test with Lightnet
  8. 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 simulated LocalBlockchain instance you can 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 simulated 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 simulated 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 async 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 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 locally​

7. Test with Lightnet​

  • Use Lightnet to test your zkApp with an accurate representation of Mina blockchain.

  1. Start Lightnet:

    zk lightnet start

    The default settings start a single node that successfully serves the majority of testing requirements.

  2. Verify the status of the local blockchain:

    zk lightnet status

  3. Communicate with the Mina Accounts-Manager service to fetch account details.

    • Mina Accounts-Manager is deployed to http://localhost:8181/
    • Use HTTP endpoints to acquire, release, list, lock, and unlock accounts

  4. Configure your zkApp for Lightnet blockchain. Use the endpoints provided by the zk lightnet status command.

    • Deploy name
    • Set the Mina GraphQL API URL to deploy to: http://localhost:8080/graphql
    • Set transaction fee to use when deploying (in MINA): 0.1

  5. Deploy your zkApp to Lightnet:

    zk deploy

8. 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 Devnet, use:

    • Deploy alias name: devnet

    • Mina GraphQL API URL: https://api.minascan.io/node/devnet/v1/graphql

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