Adds Docs on Foundations + More (#351)

* quick fixes

* add foundation and other items

* more provider and info

* additions

* add run tests

* updates

* Update docs/guide/intro/foundations.md

Co-authored-by: albertov19 <[email protected]>

* Update docs/guide/test/quick-start.md

Co-authored-by: albertov19 <[email protected]>

* Update docs/guide/test/quick-start.md

Co-authored-by: albertov19 <[email protected]>

* Update docs/guide/write/quick-start.md

Co-authored-by: albertov19 <[email protected]>

* Update docs/guide/troubleshooting/errors.md

Co-authored-by: albertov19 <[email protected]>

* Update docs/guide/util/common.md

Co-authored-by: albertov19 <[email protected]>

* formatting

* revisions

* additions

* nonce handling

* more advanced test case

* revisions

* foundation updates

* foundation updates

* add config section back in and details

* config and more updates

* spec updates

* links

* revisions

* quick start stuff

* additions

* revisions

* add init

* updates

* refresh demo test case and more

* add cli page

* debugging and more info

* revisions

* vaporize vitepress examples

* feedback rev

* feedback rev

* feedback rev design

* revisions

* add info on Moonwall utils

* add connection info

* additions

---------

Co-authored-by: albertov19 <[email protected]>

docs/.vitepress/config.ts

@@ -60,7 +60,7 @@ export default defineConfig({
     // sidebar: sidebar,
     sidebar: {
       "/guide/": { base: "/guide/", items: sidebarGuide() },
-      "/config/": { base: "/config/", items: sidebarConfig() },
+      "/config/": { base: "/config/", items: sidebarGuide() },
     },
 
     lastUpdated: {

docs/.vitepress/sidebar.ts

@@ -14,7 +14,15 @@ export function sidebarGuide(): DefaultTheme.SidebarItem[] {
         { text: "Networks Supported", link: "networks" },
       ],
     },
-
+    {
+      text: "Writing Tests",
+      collapsed: false,
+      base: "/guide/write/",
+      items: [
+        { text: "Quick Start", link: "quick-start" },
+        { text: "Context Functions", link: "context-functions" },
+      ],
+    },
     {
       text: "Running Tests",
       collapsed: false,
@@ -27,12 +35,13 @@ export function sidebarGuide(): DefaultTheme.SidebarItem[] {
       ],
     },
     {
-      text: "Writing Tests",
-      collapsed: false,
-      base: "/guide/write/",
+      text: "Config",
+      collapsed: true,
+      base: "/config/",
       items: [
-        { text: "Quick Start", link: "quick-start" },
-        { text: "Context Functions", link: "context-functions" },
+        { text: "Environment", link: "environment" },
+        { text: "Foundation", link: "foundation" },
+        { text: "moonwall-config", link: "moonwall-config" },
       ],
     },
     {
@@ -66,14 +75,6 @@ export function sidebarGuide(): DefaultTheme.SidebarItem[] {
         { text: "FAQ", link: "faq" },
       ],
     },
-    {
-      text: "Guide Examples",
-      collapsed: false,
-      base: "/guide/",
-      items: [
-        { text: "Markdown Examples", link: "markdown-examples" },
-      ],
-    },
   ];
 }
 

docs/config/environment.md

@@ -1,9 +1,37 @@
-# Coming Soon
+# Environment Configuration
 
-::: info
-This page is Under Construction 🏗️, whilst Moonwall has been built - the docs have not.
+## Environment Overview
 
-Please Stay tuned for more details of this feature!
+In Moonwall, an environment refers to a specific configuration and setup for running blockchain networks that you intend to run your tests against. In other words, what network are you going to run, how is it configured, and what parameters do you need to provide for it to be started successfully?
+
+You'll specify the foundation that you're using within your environment. Within the context of the foundation you'll also specify the path to the binary you're running. 
+
+You can also specify configuration details like the directory of test files, and additional parameters such as the default test timeout and the specific foundation configuration. 
+
+You'll need to set up your environment configuration while getting your Moonwall Config file sorted. Let's dive into each of the parameters you can use when setting up your environment.
+
+## Environment Params
+
+- **reporters** *string[]*:  an optional array of reporter names from the list of [Vitest Built ins](https://vitest.dev/guide/reporters#built-in-reporters){target=blank}. In most cases, you'll want to use the [Basic Reporter](https://vitest.dev/guide/reporters#basic-reporter){target=blank}. Other reporters are possible, but come with the following strings attached:
+
+::: tip
+In most cases, you'll want to use the [Basic Reporter](https://vitest.dev/guide/reporters#basic-reporter){target=blank}. Other reporters are possible, but come with the following strings attached: **verbose** has a bug in the upstream library where the values are crossed out when you have too many tests. **default** - this has custom animations which break when you have too many tests. **html** - this is great but requires a bit more explanation as you not only have to import another library to support this feature, but then you need to serve that html page (which is a simple one line command, but requires a separate terminal window). **json** - output file needs to be specified otherwise it just prints it to console uselessly.
 :::
 
-![underconstruction](/under-construction.png)
+- **reportFile** *string* or *{ [reporterName: string]: string }*: Writes test results to a file when using the HTLM or JSON reporter. You can provide an object instead of a string to define individual outputs when using multiple reporters. 
+- **name** *string*: string name of your environment
+- **description** *string*:  description of the environment to display in menus
+- **timeout** *number*: The default timeout for tests and hooks
+- **testFileDir** *string[]*: Array of directories where your test files are held
+- **envVars** *string[]*:  An optional array of environment variable names.
+- **foundation**: The foundation configuration for the environment.
+- **include?** *string[]*:  An optional array included files or directories.
+- **connections?** * ProviderConfig[]*: An optional array of ProviderConfig objects.
+- **multiThreads?** *boolean* or *number* An optional boolean to indicate if multi-threading is enabled. 
+::: tip
+Optionally, rather than providing a boolean or a number for *multiThreads* you can specify your own threadPool spec using a PoolOptions config object. See [poolOptions](https://vitest.dev/config/#pooloptions){target=blank} for more info. 
+:::
+- **contracts?** *string*: Path to directory containing smart contracts for testing against.
+- **defaultSigner?** *{Substrate keyring type, privateKey}* Allows you to specify the kind of signer and the private key with which to sign and send transactions during the createBlock() function. The default signer can be of type *ethereum*, *sr25519*, or *ed25519* For more info about each, see [Polkadot Keyring docs](https://polkadot.js.org/docs/keyring/start/sign-verify/){target=blank}
+- **defaultAllowFailures?** *boolean*: Toggle whether createBlock() will throw when extrinsic errors inside.
+- **defaultFinalization?** *boolean*:Toggle whether createBlock() will finalize blocks by default or not.

docs/config/foundation.md

@@ -0,0 +1,54 @@
+# Foundation Parameters by Type
+
+Here are the parameters that you can configure in your Moonwall Config file when setting up your Foundations.
+
+## Common Foundation Parameters
+
+*The following parameters are applicable to all foundation types:*
+- **name** *string*: The name of the launch spec.
+- **running** *boolean*: Optional. This is currently UNUSED.
+- **options** *string[]*: Optional. An array of options for the launch spec.
+
+## Foundation-Specific Parameters
+
+*The following parameters are specific to each foundation type:*
+
+### Dev
+
+- **binPath** *string*: The path to the node bin that gets executed to run a network locally.
+- **disableDefaultEthProviders** *boolean*: Optional. Determines if the default Ethereum provider connections should be disabled. When set to true, the framework will not automatically connect the Ethereum providers. Default behavior is to connect with Ethers, Viem & Web3 frameworks. Note: This also acts as a feature gate for context methods like createTxn and readPrecompile.
+- **newRpcBehaviour** *boolean*: Optional. Launch node using rpc-port parameter instead of ws-port. Any node built on [polkadot-SDK v1+](https://github.com/paritytech/polkadot-sdk){target=blank} will need to set this value to true.
+- **ports** *object*: Optional. An object with p2pPort, rpcPort, and wsPort. In most cases, you can omit this. In fact, if your environment is multithreaded, you will have to omit this so that Moonwall can automatically assign multiple concurrent ports.
+	- **p2pPort** *number*: The port for peer-to-peer (P2P) communication.
+	- **rpcPort** *number*: The port for remote procedure call (RPC).
+	- **wsPort** *number*: The port for WebSocket communication (soon deprecated).
+
+
+- **retainAllLogs** *boolean*: Optional. An optional flag to retain node logs from previous runs. The default behavior is to keep only the last run's logs. (e.g. default behavior is that logs are overwritten unless otherwise specified)
+
+### Read Only 
+
+- **rateLimiter** *boolean* or Bottleneck. ConstructorOptions: Optional. Rate limiter options, on by default. Can be set to false to disable.
+- **disableRuntimeVersionCheck** *boolean*: Optional. When set to true, Moonwall will read the runtime name and version from the chain metadata for purposes of test filtering. E.g. You want a particular subset of tests to only run for specific runtimes or runtime versions. If the option is omitted, runtime check is enabled. 
+
+### Zombie
+
+- **additionalZombieConfig** *OrcOptionsInterface*: Optional. Additional configuration for the zombie network.
+- **disableDefaultEthProviders** *boolean*: Optional. Determines if the default Ethereum provider connections should be disabled. When set to true, the framework will not automatically connect the Ethereum providers. Default behavior is to connect with Ethers, Viem & Web3 frameworks.
+- **disableLogEavesdropping** *boolean*: Optional. Specifies whether the framework should eavesdrop and log WARN, ERROR from the node logs. If set to true, the eavesdropping on node logs is disabled. Default behavior is to listen to the logs.
+- **configPath** *string*: The path to the Zombienet config file. See the [Zombienet network definition](https://paritytech.github.io/zombienet/network-definition-spec.html){target=blank} spec for more information.
+- **skipBlockCheck** *string[]*: Optional. An array of blocks to skip checking.
+
+
+### Chopsticks
+
+- **configPath** *string*: The path to the [Chopsticks](https://github.com/AcalaNetwork/chopsticks){target=blank} config file.
+- **wsPort** *number*: An optional WebSocket port. Note that this port option is only for single mode, not xcm, in Chopsticks.
+- **type** *relaychain* or *parachain*:  An optional type of either "relaychain" or "parachain".
+- **wasmOverride** *string*: Optionally override the runtime of a chain with a path to a local instance of another runtime.
+- **allowUnresolvedImports** *boolean*: An optional flag to NOT throw when the host fails to export a function expected by the runtime.
+::: tip
+In most cases you'll want **allowUnresolvedImports** to be set to true. Otherwise, Chopsticks may throw strange errors due to upstream bugs with [Smoldot](https://github.com/smol-dot/smoldot){target=blank}
+:::
+- **buildBlockMode** *batch*, *manual*, or *instant*: An optional block building mode, can be "batch", "manual" or "instant". This is only supported for single mode chopsticks.
+- **retainAllLogs** *boolean*: An optional flag to retain node logs from previous runs.

docs/guide/cmd/cli.md

@@ -1,9 +1,27 @@
-# Coming Soon
+# Moonwall CLI
 
-::: info
-This page is Under Construction 🏗️, whilst Moonwall has been built - the docs have not.
+## Initial Setup
 
-Please Stay tuned for more details of this feature!
-:::
+You can interact with the Moonwall CLI by running `moonwall` if you've installed it globally. Otherwise, you can run `pnpm moonwall`. 
 
-![underconstruction](/under-construction.png)
+If you're running moonwall for the first time in a directory setting up a project, you'll see 3 options, namely: 
+
+1. **Initialise**
+2. **Artifact Downloader**
+3. **Quit Application** 
+
+The instructions in the [`init` guide](/guide/cmd/init) will help you get started with the initial setup of your `Moonwall.config`. For more details about configuring your `Moonwall.config` see the [Quick Start Guide](/guide/test/quick-start). You can also utilize the [artifact downloader](/guide/util/common) to download binaries and more.
+
+![Config File Setup](/cli-setup.png)
+
+## Running Tests
+
+If Moonwall detects a valid `Moonwall.config` file in your directory at launch, it will offer you the following 5 options: 
+
+1. **Execute Script**: Run scripts placed in your config defined script directory
+2. **Network Launcher & Toolbox**: Launch network, access tools: tail logs, interactive tests
+3. **Test Suite Execution**: Run automated tests, start network if needed
+4. **Artifact Downloader**: Fetch artifacts (x86) from GitHub repos
+5. **Quit Application**: Gracefully exit Moonwall
+
+![Moonwall normal interface](/cli-normal.png)

docs/guide/cmd/download.md

@@ -1,9 +1,29 @@
-# Coming Soon
+# Download
 
-::: info
-This page is Under Construction 🏗️, whilst Moonwall has been built - the docs have not.
+The download CLI command allows you to quick download any necessary artifacts. 
 
-Please Stay tuned for more details of this feature!
+## Parameters
+
+- **name** - name of the artifact to download
+- **version** - artifact version to download, e.g. latest. 
+- **path** *string* - path to save artifacts. The default is the current directory. 
+- **overwrite** *boolean* - if the file exists, should it be overwritten? Default is to override. Alias: "d"
+- **output-name** *string* - Rename downloaded file to this name. Alias "o"
+
+## Example Usage
+
+### Downloading the Polkadot Client
+
+```sh [moonwall]
+pnpm moonwall download polkadot v1.5.0
+```
+
+::: tip
+If you have moonwall globally installed, you can omit pnpm from the command and simply use `moonwall download...`
 :::
 
-![underconstruction](/under-construction.png)
+### Downloading the Latest Moonbeam Client
+
+```sh [moonwall]
+pnpm moonwall download moonbeam latest
+```

docs/guide/cmd/init.md

@@ -1,9 +1,16 @@
-# Coming Soon
+# Init
 
-::: info
-This page is Under Construction 🏗️, whilst Moonwall has been built - the docs have not.
+The moonwall `init` command walks you through a step-by-step process to setting up your `moonwall.config.json` file. 
 
-Please Stay tuned for more details of this feature!
-:::
+The command takes no parameters but you'll be asked for the following to complete the setup of your `moonwall.config.json` file. Press `enter` at each step to accept the default parameters or enter your own at each step. These parameters and their default values are listed below: 
 
-![underconstruction](/under-construction.png)
+- Label: *moonwall_config*
+- Global timeout value: *30000*
+- Environment Name: *default_env*
+- Path for where tests for this environment are kept: *tests/*
+- Network Foundation: *dev*
+- Would you like to generate this config? (no to restart from beginning) (Y/n) *Y*
+
+For more details about configuring your `Moonwall.config` see the [Quick Start Guide](/guide/test/quick-start).
+
+![Moonwall init terminal screenshot](/init.png)

docs/guide/intro/foundations.md

@@ -1,9 +1,56 @@
-# Coming Soon
+# All About Foundations
 
-::: info
-This page is Under Construction 🏗️, whilst Moonwall has been built - the docs have not.
+## What are Foundations?
 
-Please Stay tuned for more details of this feature!
+Foundations are bundlings of configurations and presets that will (hopefully) make your life easier by allowing you to quickly execute tests under different assumptions. For more information about each Foundation, continue reading below. 
+
+## Foundations Offered
+
+Moonwall offers five different Foundations as follows:
+
+### Dev
+
+- The Dev Foundation is for running tests on a local development node.
+- Assumes manual seal (a block will be produced only when you specifically direct the node to produce one).
+- Moonwall will check to see if you already have a dev node running before trying to start its own. 
+
+::: tip
+Dev is great for repeated lightweight testing, e.g. debugging
 :::
 
-![underconstruction](/under-construction.png)
+### Chopsticks:
+
+- Uses [Chopsticks](https://github.com/AcalaNetwork/chopsticks){target=_blank} to start a lazily-forked network. Lazily-forking a network refers to loading the runtime of the live chain but only retrieving state when needed. The major advantage is that spares you from downloading the entire blockchain (hundreds of GBs).
+- Imports a Chopsticks config file, such as the following [example Chopsticks config](https://github.com/AcalaNetwork/chopsticks/tree/master/configs){target=_blank}. 
+- You can launch a single blockchain or multiple blockchains.
+- Performs state transitions locally and updates local state.
+- No client RPCs, no MetaMask support. 
+
+::: tip
+Chopsticks is ideal for testing runtime upgrades and substrate extrinsics. It's not suited for EVM calls.
+:::
+
+### Read only: 
+
+- This option does not start any networks but relies on networks that are already running. This applies to all networks, including local dev nodes, live testnets, and more.
+- You *can* submit transactions to live networks but it is not recommended as automated tests will quickly drain wallets (even testnet wallets).
+- Also used for smoke tests.
+
+::: tip
+Use Read Only if Moonwall doesn't need to start any networks - you've already got it covered.
+:::
+
+### Zombie
+
+- Uses [ParityTech's ZombieNet framework](https://github.com/paritytech/zombienet){target=_blank} to start a fresh multi-node network on your local machine.
+- Import a zombienet config file, such as this [ZombieNet example config file](https://paritytech.github.io/zombienet/cli/spawn.html){target=_blank}.
+- Can launch multiple blockchains, for example, a relaychain with several parachains or multiple ContainerChains with Tanssi.
+
+::: tip
+Zombie is the ideal Foundation for testing cross chain interactions including XCM.
+:::
+
+
+### Fork:
+
+- 🚧 Not yet implemented! Will be part of a new way of forking the network with a real client.