0011-zkapp-cli-lightnet-management.md

RFC for zkApp CLI enhancements to provide the local lightnet networks management

Introduce new sub-commands to the existing zkapp CLI application to streamline the local lightnet networks management for development and testing purposes.

Summary

We aim to extend the current zkapp CLI application by introducing the lightnet sub-command suite. This suite will centralize and simplify Docker containers and provided tools management tasks for local zkApps development and testing, enhancing user and developer experience.

Motivation

The primary motivation is to simplify the local zkApps development and testing process by offering intuitive CLI commands.

Expected Outcomes:

• A streamlined workflow for managing local lightnet network Docker containers and tools provided by such containers.
• Reduced complexity and better DX, eliminating manual 3rd party tools management.

Detailed design

zkapp CLI Interface Enhancements

Under the primary command zk, the new lightnet sub-commands will be introduced:

Help

• Command: zk lightnet
• Output: Help message with description of available sub-commands and their options.

Start lightnet network

• Command: zk lightnet start <options>
• Function: Checks the env., starts the local lightnet Docker container with reasonable default configuration options and waits until the network sync. Repeating the command while network is up and running should not start a new container, but rather check the status of the existing one.
• Configuration options:
  • --mode: single-node or multi-node (default: single-node)
  • --proof-level: none or full (default: none)
  • --archive-node: true or false (default: true)
  • --mina-branch: rampup, berkeley or develop (default: rampup)
  • --dune-profile: lightnet or devnet (default: lightnet)
• Output:
  • Anticipated network properties (as per Docker image description);
  • Mina Daemon GraphQL endpoint for communication: http://localhost:8080/graphql
  • PostgreSQL connection string: postgresql://postgres:postgres@localhost:5432/archive;
  • Mina Daemon and Archive Node logs path;
  • o1js configuration code snippet and/or link to the example usage documentation.

Stop lightnet network

• Command: zk lightnet stop
  • In future we might want to extend this command with additional options to preserve the network state between containers launches. But for now, we will keep it simple and clean up any leftovers.
• Function: Destroys the running container and cleans up any leftovers. Repeating the command while network is down should not throw an error but rather output a message that the network is already down.
• Output: Maybe blockchain state (blocks height, slots, epoch, txns processed during the session, etc.) at the time of command issuing.

Get lightnet network status

• Command: zk lightnet status
• Function: Fetches the lightnet network status.
• Output: Whether the network is running and possible reasons if it is not running.

Handle logs

• Command: zk lightnet logs <sub-command>
• Sub-commands:
  • view: less or tail the log files (Mina Daemon or Archive Node). OS agnostic.
  • save: Saves the log files to default location and outputs the resulting path.

Manage accounts

• Command: zk lightnet account <sub-command>
• Sub-commands:
  • fetch: Fetches available account from the container's pool.
  • release: Releases "used" account back to the pool.
• Note: Corresponding o1js API can be used.

Launch the blockchain explorer

• Command: zk lightnet explorer
• Function: Opens the local lightweight blockchain explorer (HTML + JS + CSS application) in default browser tab.
  • Existing lightweight explorer will be refactored and ported under the zkapp-cli repository.
• Output: The URL of application.

Impact

This update enhances the existing zkapp CLI by appending more commands under the lightnet sub-command. The core operations will remain intact.

Test plan and functional requirements

• Testing goals and objectives:
  • To validate the reliability of the enhanced zkapp CLI tool.
• Testing approach:
  • Unit tests for the new lightnet subcommands.
  • Integration tests for the new lightnet subcommands.
• Testing scope:
  • Testing all lightnet commands and their possible variations.
  • Addressing potential error scenarios and recovery mechanisms.
• Testing requirements:
  • Test in various local setups to simulate different development environments.
• Testing resources:
  • Simulated environments resembling typical local development setups.

Drawbacks

Don't see any.

Rationale and alternatives

Not enhancing the zkapp CLI would force developers to use intricate Docker commands and additional tools manually, impacting DX.