Skip to main content

Lightnet zkApp Testing

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.

Using 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 the Mina archive node.
  • Provides the Mina accounts manager helper tool so you can automate account retrieval.
  • Launches the lightweight Mina Explorer in a web browser so you can monitor transactions.
info

Use of Lightnet blockchain 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.

  1. Install Docker Engine.
  2. Start Docker Engine.

Docker Engine must be running before you can start the Docker container.

Start a single node network​

To start a single node network with default behavior:

zk lightnet start

This command uses default settings 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
  • Downloads and updates the lightweight Mina Explorer
  • 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
  • Waits for the network to reach a synchronized state
  • Sets the Mina process logging level to trace

Start a local network with other settings​

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

zk lightnet start --help

You can configure different network properties. For example, to start a multi-node local blockchain network with slower, close-to-real-world properties:

zk lightnet start --mode multi-node --type real

Keep current 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

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 /Users/<username>/.cache/zkapp-cli/lightnet/logs/.

To disable saving of log files:

zk lightnet stop --no-save-logs

Troubleshooting transactions​

Tools are provided for troubleshooting.

Lightweight Mina Explorer​

To monitor transactions, launch the lightweight Mina Explorer:

zk lightnet explorer

By default, the latest version is launched.

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

zk lightnet explorer list true

To use a specific version of the lightweight Mina Explorer:

zk lightnet explorer use <version>

Reinstantiate lightnet​

Log files​

Log files for different 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 follow the Docker container process logs in real time.

On 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 useful URLs. For example, the default single node network status returns these useful URLs:

- 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

Use these URLs when you configure your zkApp.

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.

Advanced To access the genesis ledger configuration file daemon.json, you must manually access the Docker container file system with docker exec -it mina-local-lightnet bash.

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.

Account Use Other Than zkApp​

To get the accounts information outside of the zkApp program, use the Accounts-Manager Docker container service at the endpoint: http://localhost:8181/. This endpoint is the same for all users and is available when the Lightnet Docker container is up and running.