Skip to content

Commit

Permalink
Update/swanky version 1 (#216)
Browse files Browse the repository at this point in the history 
* update installation info

* use Figure component from shared folder

* Reversed order of installation options to put recommended on top

Co-authored-by: andabakus <[email protected]>
  • Loading branch information
@codespool @andabak
codespool and andabak authored Jan 3, 2023
1 parent f197fc0 commit 6024ba3
Show file tree
Hide file tree
Showing 2 changed files with 82 additions and 87 deletions.
13 changes: 0 additions & 13 deletions docs/wasm/sc-dev/figure.jsx
View file

This file was deleted.

156 changes: 82 additions & 74 deletions docs/wasm/sc-dev/swanky.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
sidebar_position: 2
---

import Figure from './figure'
import Figure from '/src/components/figure'

# Swanky Suite

Expand All @@ -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.

Expand All @@ -91,7 +89,7 @@ DESCRIPTION
Display help for swanky.
```

### `swanky init`
#### `swanky init`

Scaffold a WASM project.

Expand All @@ -118,7 +116,7 @@ The resulting folder structure should look like this:

<Figure caption="Folder structure" src={require('./img/01a-folder_structure.png').default} />

### `swanky check`
#### `swanky check`

Verify the dependencies needed to run the swanky project.

Expand All @@ -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.

Expand All @@ -158,9 +156,9 @@ To generate a new mnemonic, use `-g` or `--generate` flag.

<Figure caption="Generate account" src={require('./img/06-account_generate.gif').default} />

### `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
Expand All @@ -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
Expand All @@ -193,7 +191,7 @@ DESCRIPTION

<Figure caption="Compile a contract" src={require('./img/03-compile.gif').default} />

#### `deploy`
#### `swanky contract deploy`

Deploy a compiled contract to a running node.

Expand All @@ -216,7 +214,7 @@ DESCRIPTION

<Figure caption="Deploy a contract" src={require('./img/08-deploy.gif').default} />

#### `new`
#### `swanky contract new`

Generate a new smart contract template inside a project

Expand All @@ -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

Expand All @@ -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
Expand All @@ -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
```
Expand All @@ -310,26 +313,32 @@ 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
./target/release/swanky-node --dev
```

Purge the development chain's state.

```bash
./target/release/swanky-node purge-chain
```

> 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
Expand All @@ -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.

Expand Down Expand Up @@ -389,15 +395,17 @@ 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.
Instant seal - Block are authored as soon as transactions get inside the pool, most often one transaction per block.

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
Expand All @@ -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
Expand All @@ -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
Expand Down

0 comments on commit 6024ba3

Please sign in to comment.