From 5084671d7b072644978692a0d7301041bb7f639e Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Mon, 16 Oct 2023 19:24:44 +0300 Subject: [PATCH 1/5] zkapp-cli enhancements for local lightnet management. --- 0010-zkapp-cli-lightnet-management.md | 100 ++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 0010-zkapp-cli-lightnet-management.md diff --git a/0010-zkapp-cli-lightnet-management.md b/0010-zkapp-cli-lightnet-management.md new file mode 100644 index 0000000..ba5799e --- /dev/null +++ b/0010-zkapp-cli-lightnet-management.md @@ -0,0 +1,100 @@ +# 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](https://hub.docker.com/r/o1labs/mina-local-network) 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 ` +- **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](https://hub.docker.com/r/o1labs/mina-local-network)); + - Mina Daemon GraphQL endpoint for communication: [http://localhost:8080/graphql](http://localhost:8080/graphql) + - PostgreSQL connection string: `postgresql://postgres:postgres@localhost:5432/archive`; + - Mina Daemon and Archive Node logs path; + - [o1js configuration](https://github.com/o1-labs/o1js/blob/ccf50e0b58190d9700c6dda4fafee3e62e270131/src/examples/zkapps/hello_world/run_live.ts#L18) code snippet. + +#### 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 lifecycle. +- **Function**: Destroys the running container. 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. + +#### Handle logs + +- **Command**: `zk lightnet logs ` +- **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-commands**: + - **fetch**: Fetches available account from the container's pool. + - **release**: Releases "used" account back to the pool. +- **Note**: Corresponding [o1js API](https://github.com/o1-labs/o1js/pull/1167) 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](https://github.com/o1-labs/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. From 264ed7f1f4521e055cb74dd8e2fb19634e8efc68 Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Fri, 20 Oct 2023 11:42:09 +0300 Subject: [PATCH 2/5] Couple updates based on review items. --- 0010-zkapp-cli-lightnet-management.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/0010-zkapp-cli-lightnet-management.md b/0010-zkapp-cli-lightnet-management.md index ba5799e..a09490c 100644 --- a/0010-zkapp-cli-lightnet-management.md +++ b/0010-zkapp-cli-lightnet-management.md @@ -41,13 +41,13 @@ Under the primary command `zk`, the new `lightnet` sub-commands will be introduc - Mina Daemon GraphQL endpoint for communication: [http://localhost:8080/graphql](http://localhost:8080/graphql) - PostgreSQL connection string: `postgresql://postgres:postgres@localhost:5432/archive`; - Mina Daemon and Archive Node logs path; - - [o1js configuration](https://github.com/o1-labs/o1js/blob/ccf50e0b58190d9700c6dda4fafee3e62e270131/src/examples/zkapps/hello_world/run_live.ts#L18) code snippet. + - [o1js configuration](https://github.com/o1-labs/o1js/blob/ccf50e0b58190d9700c6dda4fafee3e62e270131/src/examples/zkapps/hello_world/run_live.ts#L18) 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 lifecycle. -- **Function**: Destroys the running container. Repeating the command while network is down should not throw an error but rather output a message that the network is already down. + - 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. #### Handle logs From e8ac796080be6ce83b3d8e68a2076c53bc92f3e8 Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Sat, 21 Oct 2023 11:01:02 +0300 Subject: [PATCH 3/5] zk lightnet status. --- 0010-zkapp-cli-lightnet-management.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/0010-zkapp-cli-lightnet-management.md b/0010-zkapp-cli-lightnet-management.md index a09490c..9815121 100644 --- a/0010-zkapp-cli-lightnet-management.md +++ b/0010-zkapp-cli-lightnet-management.md @@ -50,6 +50,12 @@ Under the primary command `zk`, the new `lightnet` sub-commands will be introduc - **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 ` From 522f295075068522f12cadbca46b7788e986f4bf Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Mon, 30 Oct 2023 18:06:28 +0200 Subject: [PATCH 4/5] Update 0010-zkapp-cli-lightnet-management.md Co-authored-by: Barrie Byron --- 0010-zkapp-cli-lightnet-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/0010-zkapp-cli-lightnet-management.md b/0010-zkapp-cli-lightnet-management.md index 9815121..6de6635 100644 --- a/0010-zkapp-cli-lightnet-management.md +++ b/0010-zkapp-cli-lightnet-management.md @@ -1,4 +1,4 @@ -# RFC for zkapp-cli enhancements to provide the local lightnet networks management +# 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. From a1d2ad88f1158d94c8ef8b1e4e7a71c657d30fa5 Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Mon, 11 Dec 2023 15:51:32 +0200 Subject: [PATCH 5/5] Rename 0010-zkapp-cli-lightnet-management.md to 0011-zkapp-cli-lightnet-management.md --- ...ightnet-management.md => 0011-zkapp-cli-lightnet-management.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename 0010-zkapp-cli-lightnet-management.md => 0011-zkapp-cli-lightnet-management.md (100%) diff --git a/0010-zkapp-cli-lightnet-management.md b/0011-zkapp-cli-lightnet-management.md similarity index 100% rename from 0010-zkapp-cli-lightnet-management.md rename to 0011-zkapp-cli-lightnet-management.md