Skip to main content

Testing zkApps with Lightnet

The most efficient way to deploy and run a lightweight Mina blockchain network for testing purposes is to spin up a lightweight Mina network (Lightnet) in a single Docker container. Lightnet is a resource-efficient solution with fast startup and syncing times.

Lightnet lets you test your zkApp locally on an accurate representation of Mina blockchain before you test with a live network.

Lightnet provides the following benefits:

  • Reduces the time from ideation to launch by letting you test your applications and changes against a close-to-real Mina network.
  • Starts a single-node network or a multi-node network with diverse types of participants.
  • Creates and funds accounts so that you can deploy and interact with your zkApp. The genesis ledger is configured with 1000 pre-funded accounts with a 1550 MINA balance on each account.
  • Optionally runs a Mina archive node.
  • Provides the Mina accounts manager helper tool so you can automate account retrieval.
  • Launches a lightweight Mina explorer in a web browser so you can monitor transactions.
  • Simplifies zkApp troubleshooting by providing convenient access to detailed logs.
info

Use of Lightnet is appropriate for local development and testing only. It is not intended to replicate all aspects of the full network.

Prerequisites​

Docker Engine is required for your environment, see Install Docker Engine.

Minimum hardware resources are required for Lightnet to operate properly.

High-level workflow for Lightnet​

  1. Write tests for your smart contract and test locally on a simulated local blockchain
  2. Start Docker Engine
  3. Start Lightnet
  4. Configure and deploy your zkApp to Lightnet
  5. Manage the log files of the local network
  6. Use Lightweight Mina Explorer to visualize the local network state
  7. Develop, iterate, celebrate, and troubleshoot
  8. Stop the local network

The best way to experience Lightnet is by using it from the zkApp CLI.

Start a local network​

Most of your zkApp testing can be done on a single node network. Docker Engine must be running before you can start the Lightnet Docker container.

Start a single node network​

To start a single node network with default behavior:

zk lightnet start

This command performs the following operations that successfully serve the majority of testing requirements:

  • Pulls the latest Docker image for your environment from the Docker Hub repository
  • Prepares the file system
  • Forms the network with a single node
  • Configures the network to be fast
  • Disables the blockchain SNARK proofs
  • Uses the o1js-main branch of the Mina repository
  • Starts the Mina archive process and the Archive-Node-API application.
  • Waits for the network to reach a synchronized state
  • Sets the Mina process logging level to trace

Use --no- prefix for boolean sub-commands​

To see the options for a sub-command, use the --help (or -h) parameter. For example:

zk lightnet start --help

Some of the zk lightnet sub-commands have boolean values that default to true.

For these sub-commands, the option is active when present. For example, the default value for --sync is true, so using zk lightnet start is the same as zk lightnet start --sync.

For sub-commands that show the option as ([boolean] [default: true]), negation happens by adding the --no- prefix to the option.

For example, to start Lightnet without waiting for the network to reach a synchronized state, use:

zk lightnet start --no-sync

Start a local network with other settings​

To see the options to start a local blockchain network with other-than-default settings:

zk lightnet start --help

You can configure different network properties as appropriate to your testing requirements.

The default when starting Lightnet is to start the PostgreSQL (RDBMS and database) service, the Mina archive process, and the Archive-Node-API application.

To use fewer resources when your testing does not require an Archive-Node-API application, you can start a local network without the archive data-related service.

To disable the archive data-related services:

zk lightnet start --no-archive

Keep current product versions​

New Docker images are built and published to the Docker Hub every night. You might not always want to get the latest product versions. For example, when your zkApp relies on well-defined APIs and you want to continue developing in your current environment.

To keep your current working versions of o1js and Mina:

zk lightnet start --no-pull

Start a multi-node local network​

You can start a local network with multiple network participants. This network uses more resources.

To start a multi-node local network with closer-to-real-world properties:

zk lightnet start --mode multi-node --type real --proof-level full

Restart for a clean slate​

To reinstantiate Lightnet so you can redeploy and retest:

zk lightnet stop
zk lightnet start

Stop the local network​

To stop the local network, remove the Docker container, and clean up the environment:

zk lightnet stop

When Lightnet is stopped, the log files for Docker container services are saved to the host file system at ${HOME}/.cache/zkapp-cli/lightnet/logs/.

To disable saving of log files:

zk lightnet stop --no-save-logs

Configure your zkApp​

When you first build your zkApp, you test it locally and create a deploy alias as described in Tutorial 3: Deploy to a Live Network. With Lightnet, the complexities are removed and the deploy alias is automatically configured to be compatible with the lightweight Mina blockchain network.

Now that you have Lightnet running, you can run a single command to configure your zkApp deploy alias:

zk config --lightnet

Troubleshoot transactions​

Tools are provided for troubleshooting.

Lightweight Mina Explorer​

To monitor transactions and visualize the network progress, launch the lightweight Mina Explorer:

zk lightnet explorer

By default, this command downloads (if needed) and launches the latest version of lightweight Mina explorer.

To list versions, their published dates, and show the version in use:

zk lightnet explorer --list

To use a specific version of the lightweight Mina Explorer:

zk lightnet explorer use <version>

Log files​

Log files for various processes are saved inside the Docker container as:

  • /root/logs/*.log
  • /root/.mina-network/mina-local-network-2-1-1/nodes/**/logs/*.log

To save the log files that are produced by Docker container processes to the host machine file system:

zk lightnet logs save

To debug your zkApp, you can monitor the Docker container process logs in real time.

In a different terminal window, to stream the process logs:

zk lightnet logs follow

Select the Docker container process to follow. Press Ctrl+C to stop streaming.

Lightnet status​

To get the network status:

zk lightnet status

The network status is returned, including HTTP endpoints. For example, the default single node network status returns these endpoints:

- Mina Daemon GraphQL endpoint │ http://localhost:8080/graphql
- Accounts Manager endpoint    │ http://localhost:8181
- Archive-Node-API endpoint    │ http://localhost:8282
- PostgreSQL connection string │ postgresql://postgres:postgres@localhost:5432/archive

These URLs are used when you configure your zkApp with zk config --lightnet.

Lightnet status includes blockchain network properties, the Docker container state, and a code snippet of a zkApp using o1js API.

Blockchain network properties include:

  • Sync status
  • Commit ID
  • Chain ID
  • Consensus mechanism
  • Consensus configuration
    • Transaction finality ("k" blocks)
    • Slot duration (new block every ~)
    • Slots per Epoch
  • SNARK work fee
  • Known accounts
  • Uptime

Accounts​

Each Docker image is packaged with a genesis ledger that is configured with more than 1000 prefunded accounts. Each account has a balance of 1550 MINA.

The Mina Accounts-Manager helper tool provides a random public/private key pair that operates with accounts already configured in the genesis ledger. On Lightnet, the Mina Accounts-Manager is deployed to http://localhost:8181/. This endpoint is the same for all users and is available when Lightnet is up and running.

Use HTTP endpoints to acquire, release, list, lock, and unlock accounts:

.:: Mina Accounts-Manager ::.
-----------------------------

Application initialized and is running at: http://localhost:8181
Available endpoints:

   HTTP GET:
   http://localhost:8181/acquire-account
   Supported Query params: 
                           isRegularAccount=<boolean>, default: true
                           Useful if you need to get non-zkApp account.
                           
                           unlockAccount=<boolean>, default: false
                           Useful if you need to get unlocked account.
   Returns JSON account key-pair:
   { pk:"", sk:"" }
   
   HTTP PUT:
   http://localhost:8181/release-account
   Accepts JSON account key-pair as request payload:
   { pk:"", sk:"" }
   Returns JSON status message
   
   HTTP GET:
   http://localhost:8181/list-acquired-accounts
   Returns JSON list of acquired accounts key-pairs:
   [ { pk:"", sk:"" }, ... ]
   
   HTTP PUT:
   http://localhost:8181/lock-account
   Accepts JSON account key-pair as request payload:
   { pk:"", sk:"" }
   Returns JSON status message
   
   HTTP PUT:
   http://localhost:8181/unlock-account
   Accepts JSON account key-pair as request payload:
   { pk:"", sk:"" }
   Returns JSON status message
   
Operating with:
   Mina Genesis ledger:   /root/.mina-network/mina-local-network-2-1-1/daemon.json
   Mina GraphQL endpoint: http://localhost:8080/graphql

Advanced The genesis ledger configuration file is daemon.json. You can manually access the Docker container file system to view and download the file.

zkApp account interactions​

The acquireKeyPair(), releaseKeyPair(), and listAcquiredKeyPairs() methods in the Lightnet o1js API namespace handle zkApp access to account information, including public keys, private keys, and secret keys.

For details, see the doc comments in the code.

For a real-world example of using Lightnet accounts, see run-live.ts example file used in Tutorial 1: Hello World.

Feedback and contributions​

You can add contributions, submit feature requests, and create issues to let us know about problems with Lightnet in the https://github.com/o1-labs/zkapp-cli repository. Be sure to add the lightnet label.