https://github.com/o1-labs/zkapp-cli

CLI to create a zkApp (zero-knowledge app) for Mina Protocol
https://github.com/o1-labs/zkapp-cli

blockchain cryptocurrency mina web3 zero-knowledge

Last synced: 6 days ago
JSON representation

CLI to create a zkApp (zero-knowledge app) for Mina Protocol

• Host: GitHub
• URL: https://github.com/o1-labs/zkapp-cli
• Owner: o1-labs
• License: apache-2.0
• Created: 2021-07-06T21:28:48.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2025-01-21T00:03:31.000Z (16 days ago)
• Last Synced: 2025-01-23T20:05:53.245Z (13 days ago)
• Topics: blockchain, cryptocurrency, mina, web3, zero-knowledge
• Language: JavaScript
• Homepage: https://docs.minaprotocol.com/zkapps/how-to-write-a-zkapp
• Size: 5.28 MB
• Stars: 121
• Watchers: 22
• Forks: 48
• Open Issues: 70
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-mina-security - zkApp Cli
• awesome-mina-security - zkApp Cli

README

        
# zkApp CLI

[![codecov](https://codecov.io/gh/o1-labs/zkapp-cli/graph/badge.svg?token=3ZKW76ISDB)](https://codecov.io/gh/o1-labs/zkapp-cli)

The zkApp CLI allows you to scaffold, write, test, and deploy zkApps (zero knowledge apps) for [Mina Protocol](https://minaprotocol.com/) using recommended best practices.

Apps are written using [o1js](https://docs.minaprotocol.com/en/zkapps/o1js-reference), a TypeScript framework for writing zero knowledge proof-based smart contracts. o1js is automatically included when you create a project using the zkApp CLI.

## Getting Started

Read through this README file and the Mina Protocol [zkApp Developer](https://docs.minaprotocol.com/zkapps) docs.

Build foundational knowledge by completing the guided steps in the [zkApp Developer Tutorials](https://docs.minaprotocol.com/zkapps/tutorials).

## Get Involved

To learn about ways to participate and interact with community members, see the Mina [Online Communities](https://docs.minaprotocol.com/participate/online-communities) docs.

Contributions are always appreciated. See the zkApp CLI [CONTRIBUTING](https://github.com/o1-labs/zkapp-cli/blob/main/README.md) guidelines.

## Install the zkApp CLI

To install the zkApp CLI:

```sh

$ npm install -g zkapp-cli

```

To confirm successful installation:

```sh

$ zk --version

```

### Update the zkApp CLI

You are prompted to install the new version if you are running an earlier zkApp CLI minor version. For example, if you are running version 0.9.8, but the current version is 0.10.2, you are prompted to update.

You are not prompted to update if you are using an earlier patch version. For example, you are not notified to upgrade when you are running 0.10.1, and the current version is 0.10.2.

To update to the latest version of the zkApp CLI:

```sh

$ npm update -g zkapp-cli

```

### Dependencies

To use the zkApp CLI and o1js, your environment requires:

- NodeJS v18 and later

- NPM v10 and later

- git v2 and later

Use a package manager to install the required versions and upgrade older versions if needed. Package managers for the supported environments are:

- MacOS [Homebrew](https://brew.sh/)

- Windows [Chocolatey](https://chocolatey.org/)

- Linux

  - apt, yum, and others

  On Linux, you might need to install a recent Node.js version by using NodeSource. Use [deb](https://github.com/nodesource/distributions#debinstall) or [rpm](https://github.com/nodesource/distributions#rpminstall) as recommended by the Node.js project.

To verify your installed versions, use `npm -v`, `node -v`, and `git -v`.

## Usage

To see all of the zkApp CLI commands:

```sh

zk --help

```

### Create a project

```sh

zk project my-proj  # or path/to/my-proj

✔ Fetch project template

✔ Initialize Git repo

✔ NPM install

✔ Set project name

✔ Git init commit

Success!

Next steps:

  cd my-proj

  git remote add origin 

  git push -u origin main

```

This command creates a directory containing a new project template, fully set up and ready for local development.

- See the included [README](templates/project-ts/README.md) for usage instructions.

  All of the usual commands are available: `npm run build`, `npm run test`, `npm run coverage`, and so on.

- A GitHub repo is automatically initialized in the project directory. For consistency and by convention, we use `main` as the default development branch.

- A [GitHub Actions CI workflow](templates/project-ts/.github/workflows/ci.yml) is

  also included. If you push your project to GitHub, GitHub Actions run your tests (named as `*.test.js`) automatically whenever you push a commit or open a pull request.

- Code style consistency (using Prettier) and linting (using ES Lint) is automatically enforced using Git pre-commit hooks. This requires no configuration and occurs automatically when you commit a change, for example, `git commit -m 'feat: add awesome feature'`.

## Create an example project

```sh

zk example 

```

where `name` is one of the names found in the [zkApps examples](https://github.com/o1-labs/docs2/tree/main/examples/zkapps) directory.

All examples are based on the standard project template created by the zkApp CLI and contain only changes within the `src` directory, so feel free to use one of these examples as your project base.

When inside an example folder in your terminal, you can run the example:

```sh

npm run build && node ./build/src/index.js

```

### Create a new file

```sh

zk file   # or path/to/name

```

This command creates `name.js` and `name.test.js`.

For convenience, when you run this command in your project's _root_ directory creates the files inside your project's `src` dir automatically, even if you don't specify `src/` as part of your file path.

When you run this command when you are _not_ in your project's

root dir, files are created at the path you specify relative to your terminal's current working directory.

### Show system info

```sh

zk system

```

This command outputs system info such as your NodeJS version, NPM version, `zkapp-cli` version, and so on. For easier troubleshooting, be sure to include this information if submitting a bug report for `zkapp-cli`. See the [CONTRIBUTING](https://github.com/o1-labs/zkapp-cli/blob/main/README.md) guidelines.

### Update your config.json

```sh

zk config

```

The auto-generated `config.json` file contains your deployment-related configurations.

Run the `zk config` command to add a new deployment configuration to this file.

Respond to the interactive command prompts to build or update a deploy alias.

A deploy alias consists of:

- A self-describing name. This tutorial uses `devnet`. The deploy alias name can be anything and does not have to match the network name.

- The Mina GraphQL API URL that defines the network that receives your deploy transaction and broadcasts it to the appropriate Mina network (Devnet, Mainnet, and so on)

- The transaction fee (in MINA) to use when deploying

- Two key pairs:

  - A key pair for the zkApp account. Public and private keys to use in your application are automatically generated in `keys/devnet.json`.

  - A key pair to use as a fee payer account for updates and deployments. Public and private keys are stored on your local computer and can be used across multiple projects.

- Fee payer account alias

  A fee payer account is required. If you don't have a fee payer account, you are prompted to select one of these options:

  - Recover a fee payer account from an existing base58 private key

  - Create a new fee payer key pair

### Deploy your smart contract

```sh

zk deploy 

// OR

zk deploy // shows a list of aliases in your project to choose from

```

After you run `zk config`, the `zk deploy` command allows you to deploy a smart contract to a specified deploy alias.

Note: When you deploy to an alias for the first time, you are prompted to choose which smart contract you want to deploy from those that exist as _named_ exports in your project. The name of the smart contract that you choose is remembered by being saved into your `config.json` for this alias. For safety, the next time you run `zk deploy ` this _same_ smart contract automatically deploys to this alias. See [Tutorial 3: Deploy to a Live Network](https://docs.minaprotocol.com/zkapps/tutorials/deploying-to-a-network).

## Testing your zkApp

To test your zkApps, you first create automated tests for your smart contract and test with a simulated local blockchain. See [Testing zkApps Locally](https://docs.minaprotocol.com/zkapps/testing-zkapps-locally).

Before you test with a live network, use Lightnet to test your zkApp locally on an accurate representation of a Mina blockchain.

```sh

zk lightnet --help

```

See [Testing zkApps with Lightnet](https://docs.minaprotocol.com/zkapps/testing-zkapps-lightnet).

### Block explorer

To launch a lightweight Mina explorer to monitor transactions in a web browser:

```sh

zk lightnet explorer

```

## Community Support and Participation

[Mina Protocol Discord](https://discord.gg/minaprotocol) is the most popular place where Mina enthusiasts and technical contributors gather to share knowledge.

Join us in these zkApps channels:

- [#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) to meet other developers building zkApps with o1js

- [#zkapps-general](https://discord.com/channels/484437221055922177/910549624413102100) to ask general questions about zkApps, how to use a zkApp, and so on

- [#zkapps-questions](https://discord.com/channels/484437221055922177/1047214314349658172) to ask zkApps-related questions and see Q&A history

## Feedback

To provide feedback, first review existing issues. You can create [issues](https://github.com/o1-labs/zkapp-cli/issues) with feature requests for zkApp CLI and Lightnet in this repository.

zkApp CLI is an open source project, see the [CONTRIBUTING](https://github.com/o1-labs/zkapp-cli/blob/main/CONTRIBUTING.md) guidelines.

## License

[Apache-2.0](https://github.com/o1-labs/zkapp-cli/blob/main/LICENSE)