Merge pull request #245 from 0xPolygon/km/tools-launchpad

Developer tools dApp launchpad

docs/tools/dApp-development/launchpad/commands.md

@@ -0,0 +1,114 @@
+## `init`
+
+Initializes a new project in a new directory which has the same name as the project. If a project name is not mentioned, a random one is chosen.
+
+```sh
+dapp-launchpad init [PROJECT-NAME]
+```
+
+### Options
+
+|         Option        |     Description                        |
+|:---------------------:|----------------------------------------|
+| -t, --template [NAME] | Name of the scaffold template to use; default: "javascript". To get list of available templates, run list scaffold-templates. (default: "javascript") |
+| -h, --help            | display help for command               |
+
+### Help
+
+```sh
+dapp-launchpad init -h
+```
+
+## `dev`
+
+Starts a local dev environment; a local blockchain (Hardhat) and a local front end (Next.js) server.
+
+```sh
+dapp-launchpad dev [options]
+```
+
+The `dev` command starts 
+
+### Options
+
+| Option                               | Description                                                                                                                                                                                                    |
+|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| -n, --fork-network-name [NAME]       | Name of the network to fork; optional. By default, it starts a new chain from genesis block. (choices: "ethereum", "goerli", "polygonPos", "polygonMumbai", "polygonZkevm", "polygonZkevmTestnet")             |
+| -b, --fork-block-num [number]        | Block number to fork at. By default, it's the latest block.                                                                                                                                                    |
+| -r, --reset-on-change                | Resets the entire local blockchain when any code is changed; for forked mode, it resets back to forked block number; NOT DEFAULT.                                                                              |
+| --only-smart-contracts               | Deploys only smart contracts (having started local test chain) and updates Smart contract configs for frontend; does not start frontend dev environment.                                                       |
+| --only-frontend                      | Deploys only frontend (having started local server); does not start local blockchain. Smart contracts data is read from pre-existing configs. To generate these manually, use generate smart-contracts-config. |
+| -e, --enable-explorer                | Sets up a chain explorer for the local test blockchain started; NOT DEFAULT; sign up at https://app.tryethernal.com/.                                                                                          |
+| --ethernal-login-email [EMAIL]       | Ethernal login email; needed only if --explorer is enabled. This overrides env variable ETHERNAL_EMAIL if present.                                                                                             |
+| --ethernal-login-password [PASSWORD] | Ethernal login password; needed only if --explorer is enabled. This overrides env variable ETHERNAL_PASSWORD if present.                                                                                       |
+| --ethernal-workspace [WORKSPACE]     | Ethernal workspace name; needed only if --explorer is enabled. This overrides env variable ETHERNAL_WORKSPACE if present.                                                                                      |
+| -h, --help                           | Display help for command                                                                                                                                                                                       |
+
+### Help
+
+```sh
+dapp-launchpad dev -h
+```
+
+## `deploy`
+
+The deploy command deploys the smart contracts and frontend app to production.
+
+```sh
+dapp-launchpad deploy -n CHAIN_NAME
+```
+
+### Options
+
+|        Option         |        Description         |
+|:----------------------:|:-------------------------------------------------------|
+| -n, --network-name     | Name of the network to deploy smart contracts to. (choices: "ethereum", "goerli", "polygonPos", "polygonMumbai", "polygonZkevm", "polygonZkevmTestnet")               |
+| --only-smart-contracts | Deploys only smart contracts and updates Smart contracts config for frontend.                                                                                         |
+| --only-frontend        | Deploys only frontend; smart contracts data is read from Smart contracts config which must pre-exist. To generate these manually, use generate smart-contracts-config |
+| -h, --help             | Display help for command                                                                                                                                              |
+
+### Help
+
+```sh
+dapp-launchpad deploy -h
+```
+
+## `list`
+
+List options.
+
+```sh
+dapp-launchpad list <WHAT TO LIST>
+```
+
+### `scaffold-templates`
+
+List the available scaffold template languages.
+
+```sh
+dapp-launchpad list scaffold-templates
+```
+
+## `generate`
+
+Generate the specified.
+
+```sh
+dapp-launchpad generate <WHAT TO GENERATE>
+```
+
+### `smart-contracts-config`
+
+Generate the smart contract configuration.
+
+```sh
+dapp-launchpad generate smart-contracts-config
+```
+
+### Options
+
+|          Option         |                         Description      |
+|:-----------------------:|:-----------------------------------------|
+| -e, --environment <ENV> | Environment where this config would be used (choices: "development", "production", default: "development")                                        |
+| -n, --network-name      | Name of the network to generate config for. (choices: "ethereum", "goerli", "polygonPos", "polygonMumbai", "polygonZkevm", "polygonZkevmTestnet") |
+| -h, --help              | Display help for command                  |

docs/tools/dApp-development/launchpad/common-pitfalls.md

@@ -0,0 +1,13 @@
+## MetaMask transactions fail with a nonce error in dev environment 
+
+Every time the dev environment starts, a new local test chain is started. Metamask maintains a cache of "latest block number" and "account transaction nonce". Since every run of `dev` creates a new chain, it never matches with this cache.
+
+To clear the cache, follow the [MetaMask documentation](https://support.metamask.io/hc/en-us/articles/360015488891-How-to-clear-your-account-activity-reset-account).
+
+## MetaMask transactions fail with a nonce error when using the **reset on change** option in dev environment
+
+The reset on change option resets the blockchain on every code change. 
+
+MetaMask maintains a cache of *latest block number* and *account transaction nonce*. After resetting the chain, the latest block number and account transaction nonce should go back to the initial state as well, but MetaMask does not update this cache on its own.
+
+To clear the cache, follow the [MetaMask documentation](https://support.metamask.io/hc/en-us/articles/360015488891-How-to-clear-your-account-activity-reset-account).

docs/tools/dApp-development/launchpad/contributing.md

@@ -0,0 +1,42 @@
+## Build from source
+
+To build from source, clone the dApp Launchpad repository.
+
+```sh
+git clone https://github.com/0xPolygon/dapp-launchpad.git
+cd dapp-launchpad
+```
+
+Then build the CLI tool.
+
+```sh
+npm run build
+```
+
+This generates `cli.js` inside the `bin` directory, which can then be installed globally with:
+
+```sh
+npm run install-global
+```
+
+Now `dapp-launchpad` is available as a global command.
+
+## Develop on local
+
+To modify this tool, start a local dev environment by running:
+
+```sh
+npm run dev
+```
+
+This running process watches the source files, bundles up the CLI app on every change, and installs it globally.
+
+This means that the app is continuously updating with changes to the code.
+
+## Report a bugs/request a feature
+
+Create an issue below on the repo:
+
+https://github.com/0xPolygon/dapp-launchpad/issues
+
+Please give as much detail about your issue or request as possible.

docs/tools/dApp-development/launchpad/frontend.md

@@ -0,0 +1,42 @@
+## Framework
+
+The frontend runs on a Next.js server. 
+
+To get started, modify the component file at `./frontend/src/pages/index`.
+
+!!! info
+    If you're new to Next.js but know React.js, getting used to Next.js is trivial. 
+    To learn more about Next.js, [read the Next.js docs](https://nextjs.org/docs).
+
+## Environment variables
+
+Make sure you have followed the [steps in the quickstart](quickstart.md#set-up-environment-variables).
+
+!!! note
+    All environment variable names exposed in client requests should be prefixed with `NEXT_PUBLIC_`.
+
+## Connecting wallets
+
+To connect a wallet, [Web3Modal v3](https://web3modal.com/) has been integrated and pre-configured for you.
+
+Use the provided [`useWallet`](https://github.com/0xPolygon/dapp-launchpad/blob/scaffold-template/javascript/frontend/src/hooks/useWallet.js) hook to interact with Web3Modal and wallets. This contains utilities to simplify anything you need related to wallets.
+
+## Sending transactions to smart contracts
+
+To send transactions to either a locally deployed smart contract or a smart contract on a prod chain, use the [`useSmartContract`](https://github.com/0xPolygon/dapp-launchpad/blob/scaffold-template/javascript/frontend/src/hooks/useSmartContract.js) hook. This contains utilities that simplify getting and interacting with a Ethers.js contract instance.
+
+When [deploying to local or production](https://0xpolygon.gitbook.io/dapp-launchpad/commands/deploy), this hook automatically uses the correct chain and contracts.
+
+## Deploying to local test server
+
+The [`dev`](https://0xpolygon.gitbook.io/dapp-launchpad/commands/dev) command automates everything needed for setting up a local Next.js test server.
+
+## Deploying to Vercel
+
+We use Vercel for deployments. Vercel offers free quotas to developers to get started.
+
+To deploy, follow the [deployment steps](quickstart.md#deploy-your-app-to-production).
+
+With the [`deploy`](https://0xpolygon.gitbook.io/dapp-launchpad/commands/deploy) command, the frontend deployment is fully automated. 
+
+No pre-configuration is necessary for running the `deploy` command. You'll be taken through all relevant steps upon running it.

docs/tools/dApp-development/launchpad/intro.md

@@ -0,0 +1,17 @@
+dApp Launchpad is an automated CLI tool for initializing, creating, and deploying a fully-integrated web3 dApp project.
+
+## Overview
+
+dApp projects are divided into two parts:
+
+- [Frontend](frontend.md): The frontend runs on Next.js. 
+- [Smart contracts](smart-contracts.md): The smart contracts use a Hardhat environment.
+
+The tool automates basic activity such as auto-updating contract artifacts, (re)deploying contracts on code changes, and Hot Module Replacement (HMR) for frontend code changes, and more.
+
+## Repo
+
+Find the code on the following git repo: https://github.com/0xPolygon/dapp-launchpad
+
+!!! warning
+    Please note the docs in the README are possibly not up-to-date.

docs/tools/dApp-development/launchpad/quickstart.md

@@ -0,0 +1,154 @@
+## Prerequisites
+
+- [Node](https://nodejs.org/en/download) version 18.x.x is recommended.
+- Anything above Node version 16.14.x is supported.
+- We recommend [https://github.com/nvm-sh/nvm](https://github.com/nvm-sh/nvm) for managing Node installations.
+
+## Install the app
+
+Open a terminal window and run the following command to install the launchpad:
+
+```sh
+npm install -g @polygonlabs/dapp-launchpad
+```
+
+## Initialize a new project
+
+```sh
+dapp-launchpad init <PROJECT-NAME>
+```
+
+This creates a new directory in your current directory, initializes a minimal dApp project, and installs the required packages.
+
+### Project templates
+
+By default, the scaffolded project uses JavaScript. For TypeScript, use the `--template` flag.
+
+```sh
+dapp-launchpad init <PROJECT-NAME> --template typescript
+```
+
+To see the available templates, run the following:
+
+```sh
+dapp-launchpad list scaffold-templates
+```
+
+## Set up environment variables
+
+There are mandatory environment variables in both the `frontend` and `smart-contracts` directories. 
+
+1. `cd` into your project directory.
+
+2. Navigate to the frontend folder and copy the example file.
+
+    ```sh
+    cd frontend
+    cp .env.example .env
+    ```
+
+3. Open the `.env` file and add the `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` to the file. 
+
+    !!! info "How to get the WalletConnect project id"
+        You can get the variable by creating an application on [WalletConnect](https://cloud.walletconnect.com/). 
+
+        1. Create an account and sign in.
+        2. Select **Create a new project**.
+        3. Give it a name and select **App**. 
+        4. The URL can be blank. 
+        5. Click the **Create** button underneath the project box.
+        6. Copy the project id and paste it into the frontend `.env` file.
+
+4. Navigate to the smart-contracts directory and copy the example file.
+
+    ```sh
+    cd proj/smart-contracts
+    cp .env.example .env
+    ```
+
+5. Open the `.env` file and add the mandatory `PRIVATE_KEY_DEPLOYER` variable. This is a private key from any wallet account. 
+
+    !!! info
+        The other variables in the smart-contracts `.env` file are optional.
+
+## Start developing
+
+1. Run the following command from the project root:
+
+    ```sh
+    dapp-launchpad dev
+    ```
+
+    You will see the local test blockchain running with deployed contracts and some pre-funded wallets you can use.
+
+    ![Local test environment running](../../../img/tools/launchpad/running-example.png)
+
+2. Open [http://localhost:3000](http://localhost:3000) in a browser.
+
+    ![Web application running](../../../img/tools/launchpad/dev-startup.png)
+
+You now have a fully integrated dev environment including a local dev blockchain and a local frontend dev server. Any changes to the code automatically updates both the frontend and the smart contracts. No manual reload is necessary.
+
+### Start developing on an existing chain fork
+
+You can start developing by forking an existing chain. To see the available options run the following:
+
+```sh
+dapp-launchpad dev -h
+```
+
+The chain name options are in this section of the help output:
+
+```sh
+-n, --fork-network-name [NAME]        Name of the network to fork; optional. 
+                                        By default, it starts a new
+                                        chain from genesis block. (choices: "ethereum", "goerli",
+                                        "polygonPos", "polygonMumbai", "polygonZkevm", "polygonZkevmTestnet")
+```
+
+To fork Polygon zkEVM, for example, run the following command:
+
+```sh
+dapp-launchpad dev -n polygonZkevm
+```
+
+To fork at a particular block number run the command including the optional flag `-b`:
+
+```sh
+dapp-launchpad dev -n polygonZkevm -b [BLOCK_NUMBER_TO_FORK_AT]
+```
+
+## Deploy your app to production
+
+To deploy your project to production, run:
+
+```sh
+dapp-launchpad deploy -n <CHAIN-NAME>
+```
+
+This does two things:
+
+1. Deploys all your smart contracts to the selected chain, and logs the deployment results.
+2. Deploys your frontend to Vercel, and logs the deployment URL.
+
+To deploy only the smart contracts, run:
+
+```sh
+dapp-launchpad deploy -n CHAIN_NAME --only-smart-contracts
+```
+
+To deploy only the frontend, run:
+
+```sh
+dapp-launchpad deploy -n CHAIN_NAME --only-frontend
+```
+
+!!! important
+    The frontend deployment requires that smart contracts to have already been deployed, so if you are only deploying the frontend, make sure that you:
+
+    1. Have already run the smart contracts deploy command successfully.
+    2. If not, run the following wizard command:
+
+            `generate smart-contracts-config -e production -n CHAIN_NAME`
+
+