# Testing zkApps with Lightnet

> Use lightweight Mina blockchain network (Lightnet) for testing on a local blockchain before you test with a live network.

Canonical URL: https://docs.minaprotocol.com/zkapps/writing-a-zkapp/introduction-to-zkapps/testing-zkapps-lightnet

:::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](/node-operators/archive-node), `PostgreSQL RDBMS`, [Archive-Node-API](/zkapps/writing-a-zkapp/feature-overview/fetch-events-and-actions)
(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](https://github.com/o1-labs/o1js/blob/23cdfa3e17a8e8132b70895d34aab711cebd676f/src/lib/mina/fetch.ts#L804).
- Simplifies zkApps and network state monitoring by
  - providing convenient access to detailed services logs
  - launching the [lightweight Mina explorer](#lightweight-mina-explorer) web application

## Prerequisites

`Docker Engine` is required to be installed, see [Install Docker Engine](https://docs.docker.com/engine/install/) official documentation.

Lightnet requires minimum hardware resources to operate properly.

- Default `single-node` mode

  - `4.5 GB` of RAM to start up
  - `1.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](#start-the-network-without-the-archive-data-tools).

- Closer-to-real `multi-node` mode

  - More than `16 GB` of RAM

  See [start the multi node network](#start-the-multi-node-network).

When you use Lightnet via the [`zkapp-cli`](/zkapps/writing-a-zkapp/introduction-to-zkapps/install-zkapp-cli) application, the mentioned resources availability is checked automatically.

## High-level workflow for Lightnet

1. [Write tests for your smart contract](https://docs.o1labs.org/o1js/zkapps/local-development) and test locally on a simulated local blockchain
1. Start the `Docker Engine`
1. [Start the Lightnet](#start-the-single-node-network)
1. [Configure and deploy your zkApp to Lightnet](#configure-your-zkapp)
1. Explore the Docker container processes [log files](#log-files)
1. Use [lightweight Mina explorer](#lightweight-mina-explorer) to visualize the network state
1. Develop, iterate, celebrate, [monitor and troubleshoot](#monitor-and-troubleshoot-the-network-state)
1. [Stop the Lightnet](#stop-the-network)

The best way to experience Lightnet is by using it via the [`zkapp CLI`](/zkapps/writing-a-zkapp/introduction-to-zkapps/install-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:

```sh
$ zk lightnet start
```

This command performs the following operations:

- Pulls the latest Docker image for your environment from the [Docker Hub](https://hub.docker.com/r/o1labs/mina-local-network) repository
- Prepares the file system
- Uses the artifacts built from the `berkeley` branch of the Mina GitHub [repository](https://github.com/MinaProtocol/mina)
- 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](https://github.com/o1-labs/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:

```sh
$ 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:

```sh
$ 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:

```sh
$ 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:

```sh
$ zk lightnet start --no-archive
```

### Keep the current product versions

New `Docker` images are built and published to the [`Docker Hub`](https://hub.docker.com/r/o1labs/mina-local-network) 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:

```sh
$ 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:

```sh
$ 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:

```sh
$ 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:

```sh
$ 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:

```sh
$ 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](/zkapps/tutorials/deploying-to-a-network#deploy-alias) 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:

```sh
$ 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:

```sh
$ zk lightnet explorer
```

By default, this command downloads (if needed) and launches the latest version of [lightweight Mina explorer](https://github.com/o1-labs/mina-lightweight-explorer) web application.

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

```sh
$ zk lightnet explorer --list
```

To use a specific version of the lightweight Mina explorer:

```sh
$ 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:

```sh
$ zk lightnet logs save
```

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

```sh
$ 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:

```sh
$ 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`](https://github.com/shimkiv/mina-accounts-manager) helper tool provides the random key pair from the genesis ledger.
By default it is available at the [http://localhost:8181/](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:

```text
   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:"" }
```
```text
   HTTP PUT:
   http://localhost:8181/release-account
   Accepts JSON account key-pair as request payload:
   { pk:"", sk:"" }
   Returns JSON status message
```
```text
   HTTP GET:
   http://localhost:8181/list-acquired-accounts
   Returns JSON list of acquired accounts key-pairs:
   [ { pk:"", sk:"" }, ... ]
```
```text
   HTTP PUT:
   http://localhost:8181/lock-account
   Accepts JSON account key-pair as request payload:
   { pk:"", sk:"" }
   Returns JSON status message
```
```text
   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](https://github.com/o1-labs/o1js/blob/23cdfa3e17a8e8132b70895d34aab711cebd676f/src/lib/mina/fetch.ts#L804) methods.

For the real-world example of using Lightnet and o1js API, see [run-live.ts](https://github.com/o1-labs/o1js/blob/main/src/examples/zkapps/hello-world/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](https://github.com/o1-labs/zkapp-cli).
Remember to use the `lightnet` label.