Skip to main content
caution

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

Testing zkApps with Lightnet

What is Lightnet?​

It is a fast, resource-efficient solution to launch a lightweight Mina network and associated tools in a single Docker container. It lets you test zkApps locally on an accurate representation of Mina blockchain before you test same zkApps against the public testnet.

Lightnet provides the following benefits:

  • Reduces the time from ideation to launch by letting you test zkApps against the close-to-real Mina network locally.
  • Provides the resource-efficient blockchain network with fast startup and syncing times.
  • Supports multi-mode networks. (single-node network managed by multi-purpose Mina Daemon or multi-node network with diverse participant types)
  • Creates and funds accounts so that you can deploy and interact with your zkApps. The genesis ledger is configured with 1000 pre-funded accounts with the 1550 MINA balance on each.
  • Runs the archive data tools like Mina archive process, PostgreSQL RDBMS, Archive-Node-API (can be disabled if there is no need)
  • Provides the Mina accounts manager helper tool so you can automate accounts retrieval using, for example, the Lightnet o1js API namespace.
  • Simplifies zkApps and network state monitoring by

Prerequisites​

Docker Engine is required to be installed, see Install Docker Engine official documentation.

Lightnet requires minimum hardware resources to operate properly.

When you use Lightnet via the zkapp-cli application, the mentioned resources availability is checked automatically.

High-level workflow for Lightnet​

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

The best way to experience Lightnet is by using it via the zkapp CLI.

Start the Lightnet​

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

Start the single node network​

To start a single node network with default configuration:

$ zk lightnet start

This command performs the following operations:

  • Pulls the latest Docker image for your environment from the Docker Hub repository
  • Prepares the file system
  • Uses the artifacts built from the berkeley branch of the Mina GitHub repository
  • Configures the network properties to achieve fast startup, syncing and operation times
  • Disables the blockchain SNARK proofs
  • Sets the Mina processes logging level to Trace
  • Properly configures the CORS settings of the Nginx reverse proxy that will serve communications with the Mina Daemon's GraphQL endpoint
  • Forms the network using multi-purpose single Mina Daemon
  • Starts the PostgreSQL RDBMS, Mina archive process and the Archive-Node-API application
  • Waits for the network to reach the synchronized state

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

To see the options for a sub-commands, 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 the synchronized state, use:

$ zk lightnet start --no-sync

Start the network with other settings​

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

$ zk lightnet start --help

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

Start the network without the archive data tools​

By default, the Lightnet blockchian network starting up also launches the archive data tools such as the Mina archive process, the PostgreSQL RDBMS and the Archive-Node-API application.

To use fewer resources when your testing does not require the archive data tools, you can start the network without them.

To disable the archive data tools use the --no-archive option:

$ zk lightnet start --no-archive

Keep the current product versions​

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

To keep your current working versions of tools provided by the Lightnet, use the --no-pull option:

$ zk lightnet start --no-pull

Start the multi node network​

You can start the network with multiple participants. Please keep in mind that such the network uses more resources.

To start the network in multi-node mode with closer-to-real-world properties use the following command:

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

Restart the network for a clean slate​

To reinstantiate Lightnet to a clean state, stop the network and start it again:

$ zk lightnet stop
$ zk lightnet start

Stop the network​

To stop the network, remove the Docker container, and clean up the environment use the following command:

$ zk lightnet stop

When the Lightnet is being 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 you can use the --no-save-logs option:

$ zk lightnet stop --no-save-logs

Configure your zkApp​

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

Now that you have Lightnet running, you can execute a single command to configure your zkApp deploy alias in non-interactive mode:

$ zk config --lightnet

No extra steps are required.

Monitor and troubleshoot the network state​

Tools that help you monitor and troubleshoot the network state.

Lightweight Mina explorer​

To visualize the network state, launch the lightweight Mina explorer with the following command:

$ zk lightnet explorer

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

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 use the following command:

$ zk lightnet logs save

You can stream the Docker container processes logs in real time for debugging and monitoring purposes. Try the following command:

$ zk lightnet logs follow

Then select the Docker container process to follow logs for. Press Ctrl+C to stop streaming.

Lightnet status​

To get the network status use the following command:

$ zk lightnet status

The network status is returned, including HTTP endpoints, network propertis and state, code snippet of a zkApp using o1js API, and more.

Blockchain accounts​

Each Docker image is packaged with the genesis ledger that is configured with 1000 pre-funded accounts with the 1550 MINA balance on each.

The Mina accounts manager helper tool provides the random key pair from the genesis ledger. By default it is available at the http://localhost:8181/. This endpoint is the same for all users and is available when the Lightnet is up and running.

Use HTTP endpoints to manage accounts:

   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

Pro tip: the genesis ledger configuration file is named daemon.json. You can manually access the Docker container file system to manage this file. In default Lightnet configuration it can be found at /root/.mina-network/mina-local-network-2-1-1/daemon.json path.

Lightnet o1js API namespace​

The acquireKeyPair(), releaseKeyPair(), and listAcquiredKeyPairs() methods in the Lightnet o1js API namespace handle the communication with the running Mina accounts manager helper tool. For details, see the source code comments of the correspointing namespace methods.

For the real-world example of using Lightnet and o1js API, see run-live.ts example file.

Feedback and contributions​

Share your feedback, submit feature requests, and report issues with Lightnet at the zkapp-cli GitHub repository. Remember to use the lightnet label.