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 the1550 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
- providing convenient access to detailed services logs
- launching the lightweight Mina explorer web application
Prerequisites
Docker Engine
is required to be installed, see Install Docker Engine official documentation.
Lightnet requires minimum hardware resources to operate properly.
Default
single-node
mode4.5 GB
of RAM to start up1.5-2 GB
of RAM to operate
Fewer resources are required if you start the Lightnet without the archive data tools. See start the network without the archive data tools.
Closer-to-real
multi-node
mode- More than
16 GB
of RAM
- More than
When you use Lightnet via the zkapp-cli
application, the mentioned resources availability is checked automatically.
High-level workflow for Lightnet
- Write tests for your smart contract and test locally on a simulated local blockchain
- Start the
Docker Engine
- Start the Lightnet
- Configure and deploy your zkApp to Lightnet
- Explore the Docker container processes log files
- Use lightweight Mina explorer to visualize the network state
- Develop, iterate, celebrate, monitor and troubleshoot
- 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 theNginx 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.