From 50b4dfbf4e77ae21f88894beb7d2b84b6bf2e1ae Mon Sep 17 00:00:00 2001 From: Michael Mueller Date: Wed, 21 Apr 2021 06:31:28 +0200 Subject: [PATCH 1/4] Polish readme --- .images/cargo-contract.svg | 103 +++++++++++++++++++++++++++ .images/ink-squid.svg | 1 + README.md | 142 ++++++++++++++++++++++++------------- 3 files changed, 195 insertions(+), 51 deletions(-) create mode 100644 .images/cargo-contract.svg create mode 100644 .images/ink-squid.svg diff --git a/.images/cargo-contract.svg b/.images/cargo-contract.svg new file mode 100644 index 00000000..61f1acde --- /dev/null +++ b/.images/cargo-contract.svg @@ -0,0 +1,103 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + diff --git a/.images/ink-squid.svg b/.images/ink-squid.svg new file mode 100644 index 00000000..3058c423 --- /dev/null +++ b/.images/ink-squid.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/README.md b/README.md index 5869c4f6..7ee96889 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,116 @@ -# Cargo plugin for [`ink!`](https://github.com/paritytech/ink) contracts +
+ cargo-contract -[![GitHub license](https://img.shields.io/github/license/paritytech/cargo-contract)](LICENSE) -[![GitLab Status](https://gitlab.parity.io/parity/cargo-contract/badges/master/pipeline.svg)](https://gitlab.parity.io/parity/cargo-contract/pipelines) -[![Latest Version](https://img.shields.io/crates/v/cargo-contract.svg)](https://crates.io/crates/cargo-contract) +[![CI Status][a1]][a2] +[![Matrix Chat][b1]][b2] +[![Discord Chat][c1]][c2] +[![Latest Release][d1]][d2] -A CLI tool for helping setting up and managing WebAssembly smart contracts written with ink!. +[a1]: https://gitlab.parity.io/parity/cargo-contract/badges/master/pipeline.svg +[a2]: https://gitlab.parity.io/parity/cargo-contract/pipelines +[b1]: https://img.shields.io/badge/matrix-chat-brightgreen.svg?style=flat +[b2]: https://riot.im/app/#/room/#ink:matrix.parity.io +[c1]: https://img.shields.io/discord/722223075629727774?style=flat-square&label=discord +[c2]: https://discord.gg/ztCASQE +[d1]: https://img.shields.io/crates/v/cargo-contract.svg +[d2]: https://crates.io/crates/cargo-contract -## Installation +

+ +> squink, the ink! mascot`cargo-contract` is a CLI tool which helps you develop smart contracts in Parity's ink!.
ink! is a Rust [eDSL](https://wiki.haskell.org/Embedded_domain_specific_language) which allows you to write smart contracts for blockchains built on the [Substrate](https://github.com/paritytech/substrate) framework. +

+ +
+ +[Guided Tutorial for Beginners](https://substrate.dev/substrate-contracts-workshop/#/0/building-your-contract)  •   +[ink! Documentation Portal](https://paritytech.github.io/ink-docs) + +
+
+ +More relevant links: +* Talk to us on [Element][b2] or [Discord][c2] +* [`ink!`](https://github.com/paritytech/ink) ‒ The main ink! repository with smart contract examples +* [Canvas UI](https://paritytech.github.io/canvas-ui/#/upload) ‒ Frontend for contract deployment and interaction +* [Canvas Node](https://github.com/paritytech/canvas-node) ‒ Simple Substrate blockchain which includes smart contract functionality -`rust-src` is a prerequisite: `rustup component add rust-src`. -`binaryen` is a prerequisite as well, we use it for optimizing the contract Wasm. -Install [`binaryen`](https://github.com/WebAssembly/binaryen#tools) with a version >= 99. -Many package managers have it available nowadays: +## Installation + +* Step 1: `rustup component add rust-src`. + +* Step 2: Install `binaryen` in a version >= 99: -* [Debian/Ubuntu](https://tracker.debian.org/pkg/binaryen): `apt-get install binaryen` -* [Homebrew](https://formulae.brew.sh/formula/binaryen): `brew install binaryen` -* [Arch Linux](https://archlinux.org/packages/community/x86_64/binaryen/): `pacman -S binaryen` -* Windows: [binary releases are available](https://github.com/WebAssembly/binaryen/releases) + * [Debian/Ubuntu](https://tracker.debian.org/pkg/binaryen): `apt-get install binaryen` + * [Homebrew](https://formulae.brew.sh/formula/binaryen): `brew install binaryen` + * [Arch Linux](https://archlinux.org/packages/community/x86_64/binaryen/): `pacman -S binaryen` + * Windows: [binary releases are available](https://github.com/WebAssembly/binaryen/releases) + + There's only an old version in your distributions package manager? Just use a + [binary release](https://github.com/WebAssembly/binaryen/releases). -After you've installed the package execute `cargo install --force cargo-contract`. +* Step 3: `cargo install --force cargo-contract` + ## Usage -``` -cargo-contract 0.11.0 -Utilities to develop Wasm smart contracts - -USAGE: - cargo contract - -OPTIONS: - -h, --help Prints help information - -V, --version Prints version information - -SUBCOMMANDS: - new Setup and create a new smart contract project - build Compiles the contract, generates metadata, bundles - both together in a `.contract` file - generate-metadata Command has been deprecated, use `cargo contract build` instead - check Check that the code builds as Wasm; does not output any - `.contract` artifact to the `target/` directory - test Test the smart contract off-chain - deploy Upload the smart contract code to the chain - instantiate Instantiate a deployed smart contract - help Prints this message or the help of the given subcommand(s) -``` +You can always use `cargo contract help` to print information on available +commands and their usage. -## `build` requires the `nightly` toolchain +For each command there is also a `--help` flag with info on additional parameters, +e.g. `cargo contract new --help`. -`cargo contract build` must be run using the `nightly` toolchain. If you have -[`rustup`](https://github.com/rust-lang/rustup) installed, the simplest way to do so is `cargo +nightly contract build`. -To avoid having to add `+nightly` you can also create a `rust-toolchain` file in your local directory containing -`nightly`. Read more about how to [specify the rustup toolchain](https://github.com/rust-lang/rustup#override-precedence). +##### `cargo contract new my_contract` -### Note +Creates an initial smart contract with some scaffolding code into a new +folder `my_contract` . -The latest version of `cargo-contract` supports all nightlies after `2020-07-30`, because of a change in the directory -structure of the `rust-src` component. +The contract contains the source code for the [`Flipper`](https://github.com/paritytech/ink/blob/master/examples/flipper/lib.rs) +contract, which is about the simplest "smart" contract you can build ‒ a `bool` which gets flipped +from `true` to `false` through the `flip()` function. -## Features +##### `cargo +nightly contract build` -The `deploy` and `instantiate` subcommands are **disabled by default**, since they are not fully stable yet and increase the build time. +Compiles the contract into optimized WebAssembly bytecode, generates metadata for it, +and bundles both together in a `.contract` file, which you can use for +deploying the contract on-chain. + +`cargo contract build` must be run using the `nightly` toolchain. If you have +[`rustup`](https://github.com/rust-lang/rustup) installed, the simplest way to +do so is `cargo +nightly contract build`. + +To avoid having to add `+nightly` you can also create a `rust-toolchain` file in your local +directory containing `nightly`. Read more about how to [specify the rustup toolchain](https://github.com/rust-lang/rustup#override-precedence). + +##### `cargo contract check` + +Checks that the code builds as WebAssembly. This command does not output any `.contract` +artifact to the `target/` directory. + + +#### Deploy and Instantiate + +The `deploy` and `instantiate` subcommands are **disabled by default**, since they +are not fully stable yet and increase the build time. If you want to try them, you need to enable the `extrinsics` feature: -`cargo install --git https://github.com/paritytech/cargo-contract cargo-contract --features extrinsics --force` +``` +cargo install + --git https://github.com/paritytech/cargo-contract + --features extrinsics + --force +``` + +Once they are stable and the compilation time is acceptable, we will consider +removing the `extrinsics` feature. -Once they are stable and the compilation time is acceptable, we will consider removing the `extrinsics` feature. ## License -The entire code within this repository is licensed under the [GPLv3](LICENSE). Please [contact us](https://www.parity.io/contact/) if you have questions about the licensing of our products. +The entire code within this repository is licensed under the [GPLv3](LICENSE). + +Please [contact us](https://www.parity.io/contact/) if you have questions about +the licensing of our products. -- GitLab From 045fb8c1449502315728005610de8903d5010aa6 Mon Sep 17 00:00:00 2001 From: Michael Mueller Date: Wed, 21 Apr 2021 07:57:05 +0200 Subject: [PATCH 2/4] Remove superfluous line --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 7ee96889..4f52aaaf 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,6 @@ More relevant links: * [Canvas Node](https://github.com/paritytech/canvas-node) ‒ Simple Substrate blockchain which includes smart contract functionality - ## Installation * Step 1: `rustup component add rust-src`. -- GitLab From 6bfe4566824c18e3deacc10e56cf173b49078070 Mon Sep 17 00:00:00 2001 From: Michael Mueller Date: Wed, 21 Apr 2021 11:28:38 +0200 Subject: [PATCH 3/4] Implement comments --- README.md | 22 ++-------------------- 1 file changed, 2 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 4f52aaaf..cafbc056 100644 --- a/README.md +++ b/README.md @@ -79,8 +79,8 @@ deploying the contract on-chain. [`rustup`](https://github.com/rust-lang/rustup) installed, the simplest way to do so is `cargo +nightly contract build`. -To avoid having to add `+nightly` you can also create a `rust-toolchain` file in your local -directory containing `nightly`. Read more about how to [specify the rustup toolchain](https://github.com/rust-lang/rustup#override-precedence). +To avoid having to add `+nightly` you can also set `nightly` as the default toolchain +of a directory by executing `rustup override set nightly` in it. ##### `cargo contract check` @@ -88,24 +88,6 @@ Checks that the code builds as WebAssembly. This command does not output any ` Date: Wed, 21 Apr 2021 11:29:57 +0200 Subject: [PATCH 4/4] Improve text --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cafbc056..c57dc5a3 100644 --- a/README.md +++ b/README.md @@ -79,8 +79,8 @@ deploying the contract on-chain. [`rustup`](https://github.com/rust-lang/rustup) installed, the simplest way to do so is `cargo +nightly contract build`. -To avoid having to add `+nightly` you can also set `nightly` as the default toolchain -of a directory by executing `rustup override set nightly` in it. +To avoid having to always add `+nightly` you can also set `nightly` as the default +toolchain of a directory by executing `rustup override set nightly` in it. ##### `cargo contract check` -- GitLab