From 6024ba360eaa9e978a958f6df47affa7b266c644 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C5=A1a=20Pul?= <4625220+codespool@users.noreply.github.com> Date: Tue, 3 Jan 2023 12:58:55 +0200 Subject: [PATCH] Update/swanky version 1 (#216) * update installation info * use Figure component from shared folder * Reversed order of installation options to put recommended on top Co-authored-by: andabakus --- docs/wasm/sc-dev/figure.jsx | 13 --- docs/wasm/sc-dev/swanky.md | 156 +++++++++++++++++++----------------- 2 files changed, 82 insertions(+), 87 deletions(-) delete mode 100644 docs/wasm/sc-dev/figure.jsx diff --git a/docs/wasm/sc-dev/figure.jsx b/docs/wasm/sc-dev/figure.jsx deleted file mode 100644 index f697e2c7819..00000000000 --- a/docs/wasm/sc-dev/figure.jsx +++ /dev/null @@ -1,13 +0,0 @@ -import React from "react"; -import useBaseUrl from "@docusaurus/useBaseUrl"; - -export default function Figure({src, caption}) { - return ( -
-
- {caption} -
{caption}
-
-
- ) -} \ No newline at end of file diff --git a/docs/wasm/sc-dev/swanky.md b/docs/wasm/sc-dev/swanky.md index 4ddd962c7a8..b49c44476de 100644 --- a/docs/wasm/sc-dev/swanky.md +++ b/docs/wasm/sc-dev/swanky.md @@ -2,7 +2,7 @@ sidebar_position: 2 --- -import Figure from './figure' +import Figure from '/src/components/figure' # Swanky Suite @@ -18,62 +18,60 @@ Features of Swanky Suite: - Deploying smart contracts to networks within the Dotsama ecosystem that support pallet-contracts - Making arbitrary calls to the deployed smart contracts -Below is the user documentation for Swanky CLI which is meant to be used hand-in-hand with Swanky Node. +## Architecture overview -## Installation -### Prerequisites -Swanky CLI requires Rust and WebAssembly environment, also `cargo-contract` being installed to work. -If you haven't done environment setup, please follow [instructions](/docs/wasm/sc-dev/env-setup.md) and make sure everything installed correctly. +The Swanky Suite consists of two main parts, Swanky CLI and the Swanky Node. -Node.js version `>= 18.0.0` is supported. Please check node version to use beforehand. -``` -node -v -``` +Source code for both Swanky CLI nad Swanky Node is hosted on GitHub: -### CLI Installation +- [Swanky CLI](https://github.com/AstarNetwork/swanky-cli) +- [Swanky Node](https://github.com/AstarNetwork/swanky-node). -Swanky CLI can be either installed globally via [NPM](https://www.npmjs.com/package/@astar-network/swanky-cli): +The envisioned architecture of Swanky CLI and Swanky Node (Local developer node) -``` -npm i -g @astar-network/swanky-cli -``` +![Project Diagram Canvas](img/SwankySuiteAstar.png) -or used with `npx` command: +## Swanky CLI -``` -npx @astar-network/swanky-cli [command] -``` +Swanky CLI is a Node.js CLI app that uses the Polkadot.js API as its backend alongside many existing tools like the cargo contract CLI. There will be many features that will support the developer such as bootstrapping WASM dApps via smart contract and UI scaffolding, running integration tests, starting local nodes, account management, connecting and deploying contracts to both local and remote networks, compiling for various languages from a single CLI app, compatibility check from contract pallet to the compiler, and much more. -Source code for both Swanky CLI nad Swanky Node is hosted on GitHub: +### Installing -- [Swanky CLI](https://github.com/AstarNetwork/swanky-cli) -- [Swanky Node](https://github.com/AstarNetwork/swanky-node) +CLI can be installed in two ways: -## Architecture overview +#### Recommended Way: Downloading the precompiled binaries -The Swanky Suite consists of two main parts, Swanky CLI and the Swanky Node. +This is the recommended way - it comes with all the dependencies (even NodeJs) included and will support auto-updates in the future. -The envisioned architecture of Swanky CLI and Swanky Node (Local developer node) +1. Download the correct archive for your platform from the [releases section of swanky-cli github page](https://github.com/AstarNetwork/swanky-cli/releases). -![Project Diagram Canvas](img/SwankySuiteAstar.png) +2. Extract the archive to appropriate location, for example `software` directory. -## Swanky CLI +3. Add the `swanky` executable to your path variable by creating a symbolic link to it from a common `bin` directory or similar. + +> Example on MacOS: +> +> `ln -s /Users/my_name/software/swanky-cli/bin/swanky /usr/local/bin` -Swanky CLI is a Node.js CLI app that uses the Polkadot.js API as its backend alongside many existing tools like the cargo contract CLI. There will be many features that will support the developer such as bootstrapping WASM dApps via smart contract and UI scaffolding, running integration tests, starting local nodes, account management, connecting and deploying contracts to both local and remote networks, compiling for various languages from a single CLI app, compatibility check from contract pallet to the compiler, and much more. + +#### Globally with npm + +This approach is arguably simpler, but due to the nature of NodeJs dependency management, could lead to dependency and compatibility errors. ```sh-session $ npm install -g @astar-network/swanky-cli -$ swanky COMMAND -running command... -$ swanky (--version|-V|-v) -@astar-network/swanky-cli/0.2.0 darwin-x64 node-v18.2.0 -$ swanky --help [COMMAND] -USAGE - $ swanky COMMAND -... ``` -### `swanky help` +or + +```sh-session +$ npx @astar-network/swanky-cli [command] +``` + + +### Commands + +#### `swanky help` Display help and usage examples for swanky commands and subcommands. @@ -91,7 +89,7 @@ DESCRIPTION Display help for swanky. ``` -### `swanky init` +#### `swanky init` Scaffold a WASM project. @@ -118,7 +116,7 @@ The resulting folder structure should look like this:
-### `swanky check` +#### `swanky check` Verify the dependencies needed to run the swanky project. @@ -136,7 +134,7 @@ DESCRIPTION Currently you have to be be in a project folder to run this command. ::: -### `swanky account` +#### `swanky account` Create and manage accounts to be used in contract interaction. @@ -158,9 +156,9 @@ To generate a new mnemonic, use `-g` or `--generate` flag.
-### `swanky contract` +#### `swanky contract` -Compile the given contract. +Compile, deploy, call a command on a given contract, or scaffold a new contract inside the project. ``` USAGE @@ -173,7 +171,7 @@ COMMANDS contract new Generate a new smart contract template inside a project ``` -#### `compile` +#### `swanky contract compile` ``` Compile the smart contract(s) in your contracts directory @@ -193,7 +191,7 @@ DESCRIPTION
-#### `deploy` +#### `swanky contract deploy` Deploy a compiled contract to a running node. @@ -216,7 +214,7 @@ DESCRIPTION
-#### `new` +#### `swanky contract new` Generate a new smart contract template inside a project @@ -235,7 +233,7 @@ DESCRIPTION Generate a new smart contract template inside a project ``` -#### `call` +#### `swanky contract call` Call a method on a smart contract @@ -255,13 +253,14 @@ DESCRIPTION Call a method on a smart contract ``` -### `swanky node` +#### `swanky node` Manage a local node. ``` USAGE $ swanky node COMMAND + COMMANDS node purge Purge local chain state node start Start a local node @@ -273,30 +272,34 @@ COMMANDS Swanky node is a Substrate based blockchain configured to enable `pallet-contracts` (a smart contract module) and more features to help WASM smart contract development locally. -### Features -- [pallet-contracts](https://github.com/paritytech/substrate/tree/master/frame/contracts) (polkadot-0.9.30) and its unstable-feature are enabled by default. +## Features + +- [pallet-contracts](https://github.com/paritytech/substrate/tree/master/frame/contracts) (polkadot-0.9.27) and its unstable-feature are enabled by default. - `grandpa` & `aura` consensus were removed. Instead, `instant-seal` & `manual-seal` are used. - Blocks are authored & finalized (1) as soon as a transaction get in the pool (2) when `engine_createBlock` `engine_finalizeBlock` RPC called respectively. -- [pallet-dapps-staking](https://github.com/AstarNetwork/astar-frame/tree/polkadot-v0.9.30/frame/dapps-staking) and ChainExtension to interact with it. -- [pallet-assets](https://github.com/paritytech/substrate/tree/polkadot-v0.9.30/frame/assets). -- [pallet-rmrk](https://github.com/AstarNetwork/rmrk-substrate/tree/polkadot-v0.9.30) (core, equip, market) and chain extensions for pallet-rmrk-core. -- RMRK chain-extension -- Pallet-assets chain-extension -- dApps-staking chain-extension + Blocks are authored (1) as soon as a transaction get in the pool (2) when `engine_createBlock` RPC called. + Blocks are finalized when `engine_finalizeBlock` RPC called. +- [pallet-dapps-staking](https://github.com/AstarNetwork/astar-frame/tree/polkadot-v0.9.27/frame/dapps-staking) and ChainExtension to interact with it. +- [pallet-assets](https://github.com/paritytech/substrate/tree/master/frame/assets). +- [pallet-rmrk](https://github.com/AstarNetwork/rmrk-substrate/tree/polkadot-v0.9.27) (core, equip, market) and chain extensions for pallet-rmrk-core. It is optimized to local development purpose while removing unnecessary components such as P2P. More features and pallets to interact with (Contract <-> Runtime) will be added. -### Compatible ink! version -ink! version `3.4.0` or lower is supported by pallet-contract polkadot-0.9.30 branch. +## Compatible ink! version + +ink! version `3.3.1` or lower is supported by pallet-contract polkadot-0.9.27 branch. + +## Installation + +### Download Binary -### Installation -#### Download Binary The easiest way is to download a binary release from [Release Page](https://github.com/AstarNetwork/swanky-node/releases) ### Build Locally -First, complete the [basic Rust setup instructions](/docs/wasm/sc-dev/env-setup.md). + +First, complete the [basic Rust setup instructions](https://github.com/AstarNetwork/swanky-node/blob/main/docs/rust-setup.md). After that, you can build node via + ```bash cargo build --release ``` @@ -310,12 +313,16 @@ subcommands: ./target/release/swanky-node -h ``` -### Usage +## Usage + This command will start the single-node development chain with persistent state. + ```bash ./target/release/swanky-node ``` + If you want to run the node with non-persist mode, use tmp option. + ``` ./target/release/swanky-node --tmp # or @@ -323,6 +330,7 @@ If you want to run the node with non-persist mode, use tmp option. ``` Purge the development chain's state. + ```bash ./target/release/swanky-node purge-chain ``` @@ -330,6 +338,7 @@ Purge the development chain's state. > Development **alice** account will be authority and sudo account as declared in the > [genesis state](https://github.com/AstarNetwork/swanky-node/blob/main/node/src/chain_spec.rs#L44). > At the same time the following accounts will be pre-funded: +> > - Alice > - Bob > - Charlie @@ -344,11 +353,8 @@ Purge the development chain's state. > - Ferdie//stash ### Show only Errors and Contract Debug Output -To have only errors and contract debug output show up on the console you can supply -``` --lerror,runtime::contracts=debug -``` -when starting the node. + +To have only errors and contract debug output show up on the console you can supply `-lerror,runtime::contracts=debug` when starting the node. Important: Debug output is only printed for RPC calls or off-chain tests ‒ not for transactions. @@ -389,7 +395,8 @@ by appending your own. A few useful ones are as follow. ./scripts/docker_run.sh cargo check ``` -### Consensus (Manual Seal & Instant Seal) +## Consensus (Manual Seal & Instant Seal) + Unlike other blockchains, Swanky node adopts block authioring and finalized gadget called Manual Seal and Instant Seal, consensus which is suitable for contracts development and testing. Manual seal - Blocks are authored whenever RPC called. @@ -397,7 +404,8 @@ Instant seal - Block are authored as soon as transactions get inside the pool, m Swanky node enables both Manual seal and Instant seal. -#### Manual Seal RPC calls +### Manual Seal RPC calls + We can tell the node to author a block by calling the `engine_createBlock` RPC. ```bash @@ -410,16 +418,18 @@ $ curl http://localhost:9933 -H "Content-Type:application/json;charset=utf-8" -d ``` #### Params + - **Create Empty** -`create_empty` is a Boolean value indicating whether empty blocks may be created. Setting `create-empty` to true does not mean that an empty block will necessarily be created. Rather it means that the engine should go ahead creating a block even if no transaction are present. If transactions are present in the queue, they will be included regardless of `create_empty`'s value.' + `create_empty` is a Boolean value indicating whether empty blocks may be created. Setting `create-empty` to true does not mean that an empty block will necessarily be created. Rather it means that the engine should go ahead creating a block even if no transaction are present. If transactions are present in the queue, they will be included regardless of `create_empty`'s value.' - **Finalize** -`finalize` is a Boolean indicating whether the block (and its ancestors, recursively) should be finalized after creation. + `finalize` is a Boolean indicating whether the block (and its ancestors, recursively) should be finalized after creation. - **Parent Hash** -`parent_hash` is an optional hash of a block to use as a parent. To set the parent, use the format `"0x0e0626477621754200486f323e3858cd5f28fcbe52c69b2581aecb622e384764"`. To omit the parent, use `null`. When the parent is omitted the block is built on the current best block. Manually specifying the parent is useful for constructing fork scenarios and demonstrating chain reorganizations. + `parent_hash` is an optional hash of a block to use as a parent. To set the parent, use the format `"0x0e0626477621754200486f323e3858cd5f28fcbe52c69b2581aecb622e384764"`. To omit the parent, use `null`. When the parent is omitted the block is built on the current best block. Manually specifying the parent is useful for constructing fork scenarios and demonstrating chain reorganizations. #### Manually Finalizing Blocks + In addition to finalizing blocks while creating them, they can be finalized later by using the second provided RPC call, `engine_finalizeBlock`. ```bash @@ -435,8 +445,6 @@ $ curl http://localhost:9933 -H "Content-Type:application/json;charset=utf-8" -d For more detailed documentation please visit the [`swanky-node` GitHub repo]. ---- - ## Documentation [`swanky` CLI Github repo] with the latest documentation