diff --git a/docs/intro/ink-vs-cosmwasm.md b/docs/intro/ink-vs-cosmwasm.md new file mode 100644 index 0000000000..7a60aa7011 --- /dev/null +++ b/docs/intro/ink-vs-cosmwasm.md @@ -0,0 +1,146 @@ +--- +title: ink! vs. CosmWasm +slug: /ink-vs-cosmwasm +--- + +This is a short comparison between [ink!](https://github.com/paritytech/ink/) +and [CosmWasm](https://github.com/CosmWasm/cosmwasm) meant to onboard +developers coming from the Cosmos ecosystem. + +# Architecture + +CosmWasm is modular, meaning that any blockchain using the Cosmos SDK can add smart +contract support to their chain. That is similar to the [Substrate](https://substrate.io/) +approach, where chains have the option to add `pallet-contracts` to their runtime. + +Aside from that, the architecture philosophy is likely the point where CosmWasm and ink! +differ the most. CosmWasm follows the actor model design pattern, while ink! follows a +synchronous execution model. That means some fundamental differences in how the source +code is structured. + +The main entry point functions of CosmWasm contracts are: +- `instantiate` which bootstraps the initial contract state (assuming it's already been + deployed). +- `execute` which has the actor perform operations to its internal state. +- `query` which retrieves data from the actor’s internal state. + +An ink! contract can have as many public dispatchables as the developer desires, and +differently from CosmWasm, it doesn’t rely on JSON schemas for defining how the messages +are structured. + +Instead, ink! makes heavy usage of Rust macros. The main ink! macros are: +- `#[ink(constructor)]` which is called when the contract is deployed, and is responsible + for bootstrapping the initial contract state into the storage. It is analogous to the + CosmWasm `instantiate` function. +- `#[ink(storage)]` which annotates a struct that represents the contract's internal + state. +- `#[ink(message)]` which marks a function as a publicl dispatchable, meaning that it is + exposed in the contract interface to the outside world. This macro can make a function + behave analogously to CosmWasm’s `execute` and `query` functions. This depends on how it + affects the internal contract state and what the return types. +- `#[ink(event)]` and `#[ink(topic)]` which annotates a struct and its members as the + events and topics that the contract might emit. + +There are other ink! macros, for which details can be found at [Macros & Attributes](/macros-attributes). + +# Unit Testing + +Unit testing in CosmWasm is quite similar to ink!. Both use the conventional Rust +`#[cfg(test)]` macro and set up a mock on-chain environment. + +While CosmWasm unit tests have different modules for each of the three main entry-point +functions, ink! allows for a more generalised approach, where the `#[ink(test)]` macro is +used for each unit test. + +You can read more about ink! unit tests [here](https://ink.substrate.io/basics/contract-testing#unit-tests). + +# Compiler + +CosmWasm uses [cargo-wasm](https://docs.rs/crate/cargo-wasm/latest) as its main +compiler, while ink! uses [cargo-contract](https://github.com/paritytech/cargo-contract). +`cargo-contract` is developed by Parity specifically for building, testing, and deploying +ink! contracts. + +# Local Development Network + +In terms of local development networks, the [cosmos/gaia](https://github.com/cosmos/gaia) +repository acts as the basic template for a generic Cosmos node. With the addition of the +`x/wasm` module and some clean-up, this template repository becomes +[wasmd](https://github.com/CosmWasm/wasmd), the entry point for CosmWasm development. + +In terms of Substrate, `substrate-node-template` is a basic generic template of a node. +Similar to `x/wasm`, [`pallet-contracts`[(https://github.com/paritytech/substrate/tree/master/frame/contracts) +is the module that adds WebAssembly smart contract functionality to the chain. Parity +provides the [substrate-contracts-node](https://github.com/paritytech/substrate-contracts-node), +which is analogous to `wasmd` - a basic template node for smart contract development. + +# Testnets + +For CosmWasm development and on-chain testing, `wasmd` can be operated as a local setup +(single or multiple nodes), or connected to the `cliffnet` public test network. + +ink! contracts can be deployed on a few different options: +- Locally, on a single or multiple node setup of [`substrate-contracts-node`](https://github.com/paritytech/substrate-contracts-node). +- [Contracts on Rococo Parachain](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frococo-contracts-rpc.polkadot.io#/explorer), + which is connected to the [Rococo relay chain test network](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frococo-rpc.polkadot.io#/explorer). +- [Astar Network’s Shibuya testnet](https://docs.astar.network/maintain/collator/shibuya-network/). + +# Development Workflow + +## Dependencies + +The first step in CosmWasm development is to +[install dependencies](https://docs.cosmwasm.com/docs/1.0/getting-started/installation), +namely Go, Rust and `wasmd`. + +For ink! you can also find [a setup guide](/getting-started/setup) which will help you +with dependencies, namely Rust, `cargo-contract` and `substrate-contracts-node`. + +## Environment Setup + +The next step in the CosmWasm development workflow is +[setting up the environment](https://docs.cosmwasm.com/docs/1.0/getting-started/setting-env). +That consists mainly of configuring `wasmd` such that it has prefunded accounts that are able +to interact with the network. + +When `substrate-contracts-node` is started with the `--dev` flag, it already contains well +known pre-funded accounts (`alice`, `bob`, etc.) which are ready to be used for development. + +## Compile and Test + +CosmWasm provides example contracts at the +[cw-contracts](https://github.com/InterWasm/cw-contracts) repository. After the +repository is cloned, from the contract directory it can be compiled via: +``` +$ cargo wasm +``` + +and tested via: +``` +$ cargo unit-test +``` + +Similarly, ink! provides an +[`examples`](https://github.com/paritytech/ink/tree/master/examples) directory of its +main repository. + +A contract can be compiled from its directory via: +``` +$ cargo +nightly contract build +``` + +and tested via: +``` +$ cargo test +``` + +## Deploy and Interact + +CosmWasm contracts are deployed and instantiated with help of the `wasmd` executable. The +list of step is provided [here](https://docs.cosmwasm.com/docs/1.0/getting-started/interact-with-contract). + +It is possible to deploy and interact with ink! contracts using either a CLI +(`cargo-contract`), or a web UI ([`contracts-ui`](https://paritytech.github.io/contracts-ui/)). + +- [Instructions for `cargo-contract`](https://github.com/paritytech/cargo-contract/blob/master/docs/extrinsics.md) +- [Instructions for `contracts-ui`](/getting-started/deploy-your-contract) diff --git a/docs/monthly-update/overview.md b/docs/monthly-update/overview.md index 29d927e6dd..bb5baca170 100644 --- a/docs/monthly-update/overview.md +++ b/docs/monthly-update/overview.md @@ -9,7 +9,7 @@ Hey there reader 👋! This is meant to be a high-level overview of the changes that have taken place as part of Parity's Web Assembly (Wasm) smart contract efforts. These efforts include the [`ink!`](https://github.com/paritytech/ink) programming language, the [`pallet-contracts`](https://github.com/paritytech/substrate/tree/master/frame/contracts) execution environment, the [`cargo-contract`](https://github.com/paritytech/cargo-contract) -development tool, and the [Canvas parachain](https://github.com/paritytech/cumulus/tree/master/polkadot-parachains/canvas-kusama). For anything UI related go check out the +development tool, and the [Contracts parachain](https://github.com/paritytech/cumulus/tree/master/parachains/runtimes/contracts/contracts-rococo). For anything UI related go check out the [`contracts-ui` repository](https://github.com/paritytech/contracts-ui). If these updates are too high-level for you you can always check out the release notes for @@ -21,4 +21,4 @@ the various projects: If you're new here and aren't sure where to get started with ink! check out our [guided tutorial for beginners](https://docs.substrate.io/tutorials/v3/ink-workshop/pt1/). -This was inspired by the [Polkadot Staking Progress Report](https://gist.github.com/kianenigma/aa835946455b9a3f167821b9d05ba376) ❤️. \ No newline at end of file +This was inspired by the [Polkadot Staking Progress Report](https://gist.github.com/kianenigma/aa835946455b9a3f167821b9d05ba376) ❤️. diff --git a/sidebars.js b/sidebars.js index 3c0cfe7b01..2755e065c7 100644 --- a/sidebars.js +++ b/sidebars.js @@ -6,6 +6,7 @@ module.exports = { 'intro/why-webassembly', 'intro/how-it-works', 'intro/ink-vs-solidity', + 'intro/ink-vs-cosmwasm', ], 'Monthly Update': [ 'monthly-update/overview',