Unverified Commit c85cb782 authored by Michael Müller's avatar Michael Müller Committed by GitHub
Browse files

Readme makeover (#560)

* Fix typo: anonmyous ➜ anonymous

* Readme makeover

* Improve titles

* Migrate to table

* Remove default() impl

* Remove default() impl

* Fix id

* Update table

* Update title

* Shorten example instructions

* Link examples

* Link to lines

* Link to lines

* Link to lines
parent a35f76ac
Pipeline #113101 failed with stages
in 22 minutes and 51 seconds
<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg width="100%" height="100%" viewBox="0 0 2011 928" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:1.41421;"><g><path id="inc" d="M1811.78,748.385c-50.595,18.311 -78.758,71.865 -62.852,119.517c15.906,47.653 69.897,71.474 120.492,53.164c50.595,-18.311 78.758,-71.865 62.852,-119.518c-15.906,-47.652 -69.897,-71.474 -120.492,-53.163Zm-1651.2,-484.206c13.209,0.001 19.813,6.605 19.813,19.814l0,620.821c0,13.209 -6.604,19.813 -19.813,19.814l-130.769,0c-13.209,0 -19.814,-6.605 -19.814,-19.814l0,-620.821c0,-13.209 6.605,-19.813 19.814,-19.814l130.769,0Zm537.605,-5.283c143.978,0 194.171,97.746 194.171,232.478l0,413.44c0,13.209 -6.604,19.813 -19.813,19.814l-130.769,0c-13.209,0 -19.813,-6.605 -19.813,-19.814l0,-433.254c0,-44.91 -33.022,-60.761 -71.329,-60.761l-15.85,0c-56.799,0 -97.747,23.776 -112.277,47.552l0,446.463c0,13.209 -6.604,19.813 -19.813,19.814l-130.769,0c-13.209,0 -19.813,-6.605 -19.813,-19.814l0,-620.821c0,-13.209 6.604,-19.813 19.813,-19.814l130.769,0c13.209,0.001 19.813,6.605 19.813,19.814l0,58.119c19.814,-33.022 70.008,-83.216 167.754,-83.216l7.926,0Zm503.261,-258.896c13.21,0 19.814,6.605 19.814,19.813l0,458.352l187.567,-198.135c7.925,-9.246 19.813,-15.85 30.381,-15.851l136.052,0c17.173,0.001 33.022,19.814 9.246,44.911l-196.813,211.343l229.836,368.53c7.925,14.53 6.604,35.664 -15.851,35.665l-124.164,0c-17.172,0 -33.023,-5.284 -43.59,-23.776l-161.149,-266.822l-51.515,51.515l0,219.269c0,13.209 -6.604,19.813 -19.814,19.814l-130.768,0c-13.209,0 -19.814,-6.605 -19.814,-19.814l0,-885.001c0,-13.208 6.604,-19.813 19.814,-19.813l130.768,0Zm-1131.88,31.383c-49.584,14.992 -79.423,65.023 -66.591,111.655c12.833,46.631 63.507,72.319 113.092,57.326c49.585,-14.992 79.423,-65.023 66.591,-111.654c-12.832,-46.632 -63.507,-72.319 -113.092,-57.327Z" style="fill:#0e0e0e;"/><path d="M1795.61,594.617l-28.783,-0.213c-13.209,0 -19.813,-6.605 -19.813,-19.814l0,-554.777c0,-13.208 6.604,-19.813 19.813,-19.813l134.732,0c13.209,0 19.813,6.605 19.813,19.813l-0.081,18.721c-51.238,12.482 -91.137,64.695 -94.329,129.8c-2.564,52.29 19.2,99.658 53.607,126.46c-25.633,17.438 -44.472,46.887 -49.193,82.159c-5.141,38.403 7.648,74.783 31.364,98.837c-23.939,10.508 -45.741,31.983 -58.147,60.301c-8.77,20.019 -11.509,40.408 -8.983,58.526Z" style="fill:#0e0e0e;"/><path d="M1837.23,549.753c-9.822,22.417 -2.309,46.088 16.766,52.827c19.074,6.738 42.534,-5.992 52.356,-28.41c9.821,-22.418 2.308,-46.089 -16.766,-52.827c-19.075,-6.739 -42.535,5.992 -52.356,28.41Zm35.572,-164.125c-6.558,34.707 11.744,67.29 40.844,72.716c29.1,5.426 58.05,-18.347 64.607,-53.054c6.558,-34.707 -11.744,-67.29 -40.844,-72.716c-29.1,-5.425 -58.05,18.347 -64.607,53.054Zm-7.312,-204.559c-2.328,47.49 28.18,88.336 68.085,91.158c39.905,2.821 74.194,-33.443 76.522,-80.933c2.329,-47.49 -28.179,-88.336 -68.084,-91.158c-39.906,-2.821 -74.194,33.444 -76.523,80.933Z" style="fill:#0e0e0e;"/></g></svg>
\ No newline at end of file
<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg width="100%" height="100%" viewBox="0 0 585 1776" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:1.5;"><g id="ink-_just-squid" serif:id="ink!_just-squid"><g id="head"><path d="M61.588,492.612c0,0 -7.787,-35.339 -17.042,-77.338c-15.38,-69.798 16.47,-141.479 78.578,-176.847c40.366,-23.045 83.92,-59.209 115.553,-115.363" style="fill:#bc83fb;stroke:#000;stroke-width:38.83px;"/><path d="M544.14,492.612c0,0 4.848,-21.725 11.014,-49.353c12.986,-58.202 -14.727,-117.872 -67.575,-145.499c-52.995,-27.815 -109.76,-79.723 -114.748,-174.696l-0.854,319.551l172.163,49.997Z" style="fill:#bc83fb;stroke:#000;stroke-width:38.83px;"/><path d="M271.404,61.098c0.001,-0.002 8.026,-36.942 49.417,-37.199c22.92,-0.142 43.073,15.169 49.416,37.194c0.001,0.001 18.468,136.346 28.237,208.471c3.615,26.687 15.518,51.566 34.03,71.125c64.995,68.641 209.497,254.328 67.775,427.883c0,0 -11.16,-146.803 -188.333,-146.803c-31.161,0 25.086,0 -6.074,0c-177.173,0 -200.355,146.803 -200.355,146.803c-178.127,-218.137 111.546,-582.703 165.887,-707.474Z" style="fill:#bc83fb;stroke:#000;stroke-width:47.8px;"/></g><path id="body_bg" d="M485.165,826.25c59.883,25.856 80.376,99.619 64.177,160.974c-0.006,0.022 -0.011,0.044 -0.015,0.066c-76.121,391.969 -273.048,737.581 -353.108,764.548c0,0 14.566,-96.568 21.806,-144.572c3.182,-21.093 2.061,-42.611 -3.296,-63.259c-21.189,-80.793 -71.186,-148.893 -91.258,-226.697c-30.168,-116.941 -38.327,-243.9 -77.662,-386.562c-11.653,-41.965 7.464,-86.386 45.952,-106.773c-0.039,-0.076 -0.039,-0.076 -0.039,-0.076c54.691,-10.513 8.172,-71.692 5.561,-116.782c42.402,-127.461 76.691,-171.199 189.145,-172.715c121.934,-11.058 190.547,83.668 222.079,170.506c-10.38,109.706 -29.437,100.192 -23.342,121.342Z" style="fill:#bc83fb;"/><g id="flippers"><path d="M505.519,1167.22c-111.845,446.167 -51.515,489.313 -51.515,489.313l-80.526,-75.666" style="fill:#5a007e;stroke:#000;stroke-width:47.8px;"/><path d="M114.632,1280.12c7.085,192.97 44.58,303.81 -22.91,337.857c0,0 71.031,-2.088 107.259,-60.746" style="fill:#5a007e;stroke:#000;stroke-width:47.8px;"/></g><g id="light"><path d="M455.392,845.552l53.236,32.453c15.547,9.478 23.268,27.853 19.155,45.59c-23.426,100.128 -101.538,423.999 -152.836,516.733l-1.498,5.541l-5.115,19.169c-4.31,20.485 -9.004,45.187 -8.722,32.685l8.722,-32.685c2.245,-10.959 4.41,-20.72 5.615,-22.841l0.998,-1.869c67.527,-250.121 123.383,-436.843 -7.457,-539.047c45.508,-7.88 74.756,-25.832 87.902,-55.729Z" style="fill:#d8b6ff;"/><path d="M298.366,80.959c0.859,-19.666 -33.441,70.938 -35.595,77.779c-60.307,191.603 -222.861,305.457 -155.678,529.851c0.599,2.001 7.039,-11.202 19.882,-33.997c36.458,-64.714 135.245,-82.878 135.245,-82.878c-187.957,-146.439 29.662,-342.272 36.146,-490.755Z" style="fill:#5a007e;"/><path d="M334.482,92.912c4.751,-19.103 13.025,40.858 11.696,47.906c-34.982,185.571 247.214,345.882 149.704,559.724c-0.425,0.933 -7.418,-32.56 -26.602,-57.787c-19.908,-26.181 -52.026,-44.151 -52.026,-44.151c104.517,-117.24 -144.544,-257.319 -82.772,-505.692Z" style="fill:#d8b6ff;"/><path d="M213.77,895.126c-125.926,104.11 17.82,544.184 32.353,724.18c0.159,1.97 -0.512,3.869 -0.819,5.72c-3.224,19.418 -3.006,-33.561 -3.849,-40.684c-7.219,-60.975 -39.367,-151.175 -74.873,-226.186c-36.848,-77.846 -42.666,-198.965 -51.182,-282.213c-13.834,-135.245 -60.477,-169.659 27.876,-237.628c0.248,-0.191 2.731,0.897 6.684,2.883c9.77,26.173 30.992,43.776 63.81,53.928Z" style="fill:#5a007e;"/><path d="M221.199,897.32l3.017,0.727c-27.171,39.278 -62.221,177.976 1.925,557.989c-15.66,-92.769 -101.049,-443.859 -6.891,-559.278l1.949,0.562Z" style="fill:#d8b6ff;"/><path d="M229.538,899.33c19.853,4.357 43.194,6.542 70.031,6.689c-73.29,35.322 -111.4,86.451 -42.925,437.052c19.978,102.293 -11.207,202.261 -10.521,276.235c0.019,1.977 -0.512,3.869 -0.819,5.72c-3.224,19.418 -3.006,-33.561 -3.849,-40.684c-23.438,-278.138 -61.397,-522.872 -11.917,-685.012Z" style="fill:#5a007e;"/></g><path id="body_line" d="M485.165,826.25c59.883,25.856 80.376,99.619 64.177,160.974c-0.006,0.022 -0.011,0.044 -0.015,0.066c-76.121,391.969 -273.048,737.581 -353.108,764.548c0,0 14.566,-96.568 21.806,-144.572c3.182,-21.093 2.061,-42.611 -3.296,-63.259c-21.189,-80.793 -71.186,-148.893 -91.258,-226.697c-28.861,-111.876 -37.579,-232.92 -72.722,-368.112c-13.613,-52.308 12.668,-106.778 62.085,-128.675c-0.039,-0.089 -0.039,-0.089 -0.039,-0.089" style="fill:none;stroke:#000;stroke-width:47.8px;"/><g id="tenticles"><path d="M330.94,1487.71c-7.247,28.951 4.705,57.396 26.674,63.481c21.969,6.085 45.689,-12.478 52.936,-41.429c7.247,-28.951 -4.706,-57.395 -26.675,-63.481c-21.969,-6.085 -45.688,12.479 -52.935,41.429Z" style="fill:#d8b6ff;stroke:#000;stroke-width:47.8px;"/><path d="M375.149,1349.05c-9.986,36.514 4.39,72.917 32.083,81.243c27.693,8.325 58.284,-14.56 68.27,-51.074c9.986,-36.514 -4.39,-72.918 -32.083,-81.243c-27.693,-8.326 -58.284,14.56 -68.27,51.074Z" style="fill:#d8b6ff;stroke:#000;stroke-width:47.8px;"/><path d="M294.861,1587.31c-13.531,22.432 -10.45,48.869 6.875,58.999c17.326,10.13 42.378,0.142 55.909,-22.29c13.531,-22.433 10.451,-48.869 -6.875,-58.999c-17.326,-10.13 -42.377,-0.142 -55.909,22.29Z" style="fill:#d8b6ff;stroke:#000;stroke-width:47.8px;"/><path d="M236.999,1669.42c-17.263,15.764 -21.137,38.383 -8.646,50.48c12.491,12.097 36.648,9.12 53.91,-6.644c17.263,-15.764 21.137,-38.383 8.646,-50.48c-12.491,-12.097 -36.648,-9.12 -53.91,6.644Z" style="fill:#d8b6ff;stroke:#000;stroke-width:47.8px;"/></g><g id="face"><path d="M289.677,785.548c0,0 0,0.002 0.001,0.004c3.201,8.634 11.431,14.367 20.638,14.376c9.208,0.01 17.45,-5.706 20.668,-14.333c0.063,-0.168 0.095,-0.255 0.095,-0.255" style="fill:none;stroke:#000;stroke-width:17.41px;"/><path d="M369.563,730.226c0,0 1.993,-1.381 5.108,-3.539c20.62,-14.29 48.782,-10.196 64.48,9.374c1.325,1.652 2.116,2.638 2.116,2.638" style="fill:none;stroke:#000;stroke-width:29.87px;"/><path d="M253.404,731.668c0,0 -6.294,-3.257 -14.187,-7.343c-18.502,-9.576 -41.076,-6.06 -55.789,8.691c-4.511,4.523 -7.824,7.845 -7.824,7.845" style="fill:none;stroke:#000;stroke-width:29.87px;"/></g></g></svg>
\ No newline at end of file
......@@ -105,6 +105,6 @@ For a nice list of hints visit this [link][GitHub Perfect Pull Reqest].
For questions about the ink! project, about Parity Technologies or general technical related questions you are welcome to contact us via [Riot][Riot-Smart-Contracts-ink]. For technical questions specifically about the ink! and its sub-projects you may also file an issue. For more information about filing issues go [here](#Issues-&-pull-requests).
[Riot-Smart-Contracts-ink]: https://riot.im/app/#/room/!tYUCYdSvSYPMjWNDDD:matrix.parity.io
[Riot-Smart-Contracts-ink]: https://riot.im/app/#/room/#ink:matrix.parity.io
[GitHub Perfect Pull Reqest]: https://github.blog/2015-01-21-how-to-write-the-perfect-pull-request/
# ink! - Parity's ink to write smart contracts
<div align="center">
<img src="./.images/ink-logo.svg" alt="ink!" height="120" />
<h1 align="center">
Parity's ink! for writing smart contracts
</h1>
| Linux | Codecov | Coveralls | LoC |
| :----------------: | :------------------: | :--------------------: | :--------------: |
| [![linux][a1]][a2] | [![codecov][c1]][c2] | [![coveralls][d1]][d2] | [![loc][e1]][e2] |
[![linux][a1]][a2] [![codecov][c1]][c2] [![coveralls][d1]][d2] [![loc][e1]][e2] [![matrix][k1]][k2] [![discord][l1]][l2]
[a1]: https://gitlab.parity.io/parity/ink/badges/master/pipeline.svg
[a2]: https://gitlab.parity.io/parity/ink/pipelines?ref=master
......@@ -12,41 +14,58 @@
[d2]: https://coveralls.io/github/paritytech/ink?branch=master
[e1]: https://tokei.rs/b1/github/paritytech/ink?category=code
[e2]: https://github.com/Aaronepower/tokei#badges
[f1]: https://img.shields.io/badge/docs-storage-blue.svg
[f1]: https://img.shields.io/badge/click-blue.svg
[f2]: https://paritytech.github.io/ink/ink_storage
[g1]: https://img.shields.io/badge/docs-env-blue.svg
[g1]: https://img.shields.io/badge/click-blue.svg
[g2]: https://paritytech.github.io/ink/ink_env
[h1]: https://img.shields.io/badge/docs-metadata-blue.svg
[h2]: https://paritytech.github.io/ink/ink_metadata
[i1]: https://img.shields.io/badge/docs-prelude-blue.svg
[i1]: https://img.shields.io/badge/click-blue.svg
[i2]: https://paritytech.github.io/ink/ink_prelude
[j1]: https://img.shields.io/badge/docs-lang-blue.svg
[j1]: https://img.shields.io/badge/click-blue.svg
[j2]: https://paritytech.github.io/ink/ink_lang
[k1]: https://img.shields.io/badge/chat%20on-matrix-brightgreen.svg?style=flat
[k2]: https://riot.im/app/#/room/#ink:matrix.parity.io
[l1]: https://img.shields.io/badge/chat%20on-discord-brightgreen.svg?style=flat
[l2]: https://discord.gg/ztCASQE
ink! is an [eDSL](https://wiki.haskell.org/Embedded_domain_specific_language) to write WebAssembly based smart contracts using the Rust programming language targeting Substrate blockchains.
> <img src="./.images/ink-squid.svg" alt="squid, the ink! mascot" style="vertical-align: middle" align="left" height="60" />ink! is an [eDSL](https://wiki.haskell.org/Embedded_domain_specific_language) to write WebAssembly based smart contracts using the Rust programming language. The compilation target are blockchains built on the [Substrate](https://github.com/paritytech/substrate) framework.
For a guided workshop targeting beginners please visit [the ink! tutorial](https://substrate.dev/substrate-contracts-workshop/#/0/building-your-contract).
<br/>
## Developer Documentation
[Guided Tutorial for Beginners](https://substrate.dev/substrate-contracts-workshop/#/0/building-your-contract)
[`cargo-contract`](https://github.com/paritytech/cargo-contract) cli tool for ink! contracts •
[Canvas UI](https://paritytech.github.io/canvas-ui/#/upload) for contract deployment/interaction •
Talk to us on [Matrix]([k3]) or [Discord]([l1])
</div>
| `ink_metadata` | `ink_env` | `ink_storage` | `ink_lang` | `ink_prelude` |
| ------------- | ------------- | ------------- | ------------- | ------------- |
| [![][h1]][h2] | [![][g1]][g2] | [![][f1]][f2] | [![][j1]][j2] | [![][i1]][i2] |
## Table of Contents
### Interaction with Substrate
* [Play with It](#play-with-it)
* [Usage](#usage)
* [Hello, World! ‒ The Flipper](#hello-world--the-flipper)
* [Examples](#examples)
* [How it Works](#how-it-works)
* [ink! Macros & Attributes Overview](#ink-macros--attributes-overview)
* [Entry Point](#entry-point)
* [Trait Definitions](#trait-definitions)
* [Off-chain Testing](#off-chain-testing)
* [Developer Documentation](#developer-documentation)
* [Contributing](#contributing)
* [License](#license)
Substrate's [Framework for Runtime Aggregation of Modularised Entities (FRAME)](https://substrate.dev/docs/en/next/conceptual/runtime/frame) contains the `contracts` pallet, which provides a generic smart contract interface for Wasm blobs. It takes care of e.g. state rent, storage, costs, etc..
ink! is a smart contract language which targets the interface exposed by
`contracts`. As such, ink! smart contracts are compiled to Wasm.
## Play with It
### Scripts
We have [a demonstration testnet](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fcanvas-rpc.parity.io) running.
You can request some tokens to play with from our [Faucet](https://riot.im/app/#/room/#canvas_faucet:matrix.parity.io) and deploy your contracts via the [Canvas UI](https://paritytech.github.io/canvas-ui/#/upload).
Use the scripts provided under `scripts` directory in order to run checks on either the workspace or all examples. Please do this before pushing work in a PR.
The [Canvas UI](https://paritytech.github.io/canvas-ui/#/upload) can also be used to deploy your contract to e.g. a Substrate chain which you run locally and execute calls there.
If you want a quickstart you can use our [canvas-node](https://github.com/paritytech/canvas-node#note) project ‒ a simple Substrate blockchain which is configured to include the `contracts` pallet (see [How it Works](#how-it-works) for more).
## Examples
## Usage
A prerequisite for compiling smart contracts is to have Rust and Cargo installed. Here's [an installation guide](https://doc.rust-lang.org/cargo/getting-started/installation.html).
For building the example smart contracts found under `examples` you will need to have [`cargo-contract`](https://github.com/paritytech/cargo-contract) installed.
We recommend installing [`cargo-contract`](https://github.com/paritytech/cargo-contract), a CLI tool for helping setting up and managing WebAssembly smart contracts written with ink!:
```
cargo install cargo-contract --force
......@@ -54,34 +73,32 @@ cargo install cargo-contract --force
Use the `--force` to ensure you are updated to the most recent `cargo-contract` version.
### Build example contract and generate the contracts metadata
To build a single example and generate the contracts Wasm file, navigate to the root of the example smart contract and run:
In order to initialize a new ink! project you can use:
```
cargo contract build
cargo contract new flipper
```
To generate the contract metadata (a.k.a. the contract ABI), run the following command:
This will create a folder `flipper` in your work directory.
The folder contains a scaffold `Cargo.toml` and a `lib.rs`, which both contain the necessary building blocks for using ink!.
The `lib.rs` contains our hello world contract ‒ the `Flipper`, which we explain in the next section.
In order to build the contract just execute these commmands in the `flipper` folder:
```
cargo contract generate-metadata
cargo contract build && cargo contract generate-metadata
```
You should now have an optimized `<contract-name>.wasm` file and an `metadata.json` file in the `target` folder of the contract.
As a result you'll get a file `target/flipper.wasm` and `target/metadata.json`. Those need to be used when deploying the contract.
For further information, please have a look at our [smart contracts workshop](https://substrate.dev/substrate-contracts-workshop/).
## Hello, World! - The Flipper
## Hello, World! The Flipper
The `Flipper` contract is a simple contract containing only a single `bool` value
that it can flip from `true` to `false` and vice versa and return the current state.
The `Flipper` contract is a simple contract containing only a single `bool` value.
It provides methods to
* flip its value from `true` to `false` (and vice versa) and
* return the current state.
To create your own version of the flipper contract, you first need to initialize a new ink! project in your working directory.
```
cargo contract new flipper
```
Below you can see the code using the `ink_lang` version of ink!.
......@@ -106,12 +123,6 @@ mod flipper {
}
}
/// Instantiates a new Flipper contract and initializes `value` to `false` by default.
#[ink(constructor)]
pub fn default() -> Self {
Self::new(false)
}
/// Flips `value` from `true` to `false` or vice versa.
#[ink(message)]
pub fn flip(&mut self) {
......@@ -130,12 +141,6 @@ mod flipper {
mod tests {
use super::*;
#[test]
fn default_works() {
let flipper = Flipper::default();
assert_eq!(flipper.get(), false);
}
#[test]
fn it_works() {
let mut flipper = Flipper::new(false);
......@@ -149,10 +154,84 @@ mod flipper {
Place this code in the `./lib.rs` file of your flipper contract and run `cargo contract build && cargo contract generate-metadata` to build your first ink! smart contract example.
## Contribution
## Examples
In the `examples` folder you'll find a number of examples written in ink!.
Some of the most interesting ones:
* `delegator` ‒ Implements cross-contract calling.
* `trait-erc20` ‒ Defines a trait for `Erc20` contracts and implements it.
* `erc721` ‒ An exemplary implementation of `Erc721` NFT tokens.
* `dns` ‒ A simple `DomainNameService` smart contract.
* …and more, just rummage through the folder 🙃.
To build a single example navigate to the root of the example and run:
```
cargo contract build && cargo contract generate-metadata
```
You should now have an optimized `<contract-name>.wasm` file and a `metadata.json` file in the `target` folder of the contract.
For further information, please have a look at the [Play with It](#play-with-it) section or our [smart contracts workshop](https://substrate.dev/substrate-contracts-workshop/).
## How it Works
* Substrate's [Framework for Runtime Aggregation of Modularised Entities (FRAME)](https://substrate.dev/docs/en/next/conceptual/runtime/frame) contains the `contracts` pallet,
which implements an API for typical functions smart contracts need (storage, querying information about account, …).
* The `contracts` pallet requires smart contracts to be uploaded to the blockchain as a Wasm blob.
* ink! is a smart contract language which targets the API exposed by `contracts`.
Hence ink! smart contracts are compiled to Wasm.
* When executing `cargo contract build` an additional file `metadata.json` is created.
It contains information about e.g. what methods the contract provides for others to call.
## ink! Macros & Attributes Overview
### Entry Point
In a module annotated with `#[ink::contract]` these attributes are available:
| Attribute | Where Applicable | Description |
|:--|:--|:--|
| `#[ink(storage)]` | On `struct` definitions. | Defines the ink! storage struct. There can only be one ink! storage definition per contract. |
| `#[ink(event)]` | On `struct` definitions. | Defines an ink! event. A contract can define multiple such ink! events. |
| `#[ink(anonymous)]` | Applicable to ink! events. | Tells the ink! codegen to treat the ink! event as anonymous which omits the event signature as topic upon emitting. Very similar to anonymous events in Solidity. |
| `#[ink(topic)]` | Applicate on ink! event field. | Tells the ink! codegen to provide a topic hash for the given field. Every ink! event can only have a limited number of such topic field. Similar semantics as to indexed event arguments in Solidity. |
| `#[ink(message)]` | Applicable to methods. | Flags a method for the ink! storage struct as message making it available to the API for calling the contract. |
| `#[ink(constructor)]` | Applicable to method. | Flags a method for the ink! storage struct as constructor making it available to the API for instantiating the contract. |
| `#[ink(payable)]` | Applicable to ink! messages. | Allows receiving value as part of the call of the ink! message. ink! constructors are implicitly payable. |
| `#[ink(selector = "..")]` | Applicable to ink! messages and ink! constructors. | Specifies a concrete dispatch selector for the flagged entity. This allows a contract author to precisely control the selectors of their APIs making it possible to rename their API without breakage. |
| `#[ink(namespace = "..")]` | Applicable to ink! trait implementation blocks. | Changes the resulting selectors of all the ink! messages and ink! constructors within the trait implementation. Allows to disambiguate between trait implementations with overlapping message or constructor names. Use only with great care and consideration! |
| `#[ink(implementation)]` | Applicable to ink! implementation blocks. | Tells the ink! codegen that some implementation block shall be granted access to ink! internals even without it containing any ink! messages or ink! constructors. |
See [here](https://paritytech.github.io/ink/ink_lang/attr.contract.html) for a more detailed description of those and also for details on the `#[ink::contract]` macro.
### Trait Definitions
Use`#[ink::trait_definition]` to define your very own trait definitions that are then implementable by ink! smart contracts.
See e.g. the [`examples/trait-erc20`](https://github.com/paritytech/ink/blob/master/examples/trait-erc20/lib.rs#L49-L51) contract on how to utilize it or [the documentation](https://paritytech.github.io/ink/ink_lang/attr.trait_definition.html) for details.
### Off-chain Testing
The `#[ink::test]` proc. macro enables off-chain testing. See e.g. the [`examples/erc20`](https://github.com/paritytech/ink/blob/master/examples/erc20/lib.rs#L278-L280) contract on how to utilize those or [the documentation](https://paritytech.github.io/ink/ink_lang/attr.test.html) for details.
## Developer Documentation
| Crate | Docs | Description |
|:--|:--|:--|
`ink_lang` | [![][j1]][j2] | Language features expose by ink!. See [here](https://paritytech.github.io/ink/ink_lang/attr.contract.html) for a detailed description of attributes which you can use in an `#[ink::contract]`. |
`ink_storage` | [![][f1]][f2] | Data structures available in ink!. |
`ink_env` | [![][g1]][g2] | Low-level interface for interacting with the smart contract Wasm executor. |
`ink_prelude` | [![][i1]][i2] | Common API for no_std and std to access alloc crate types. |
## Contributing
Visit our [contribution guidelines](CONTRIBUTING.md) for more information.
Use the scripts provided under `scripts/check-*` directory in order to run checks on either the workspace or all examples. Please do this before pushing work in a PR.
## License
The entire code within this repository is licensed under the [Apache License 2.0](LICENSE). Please [contact us](https://www.parity.io/contact/) if you have questions about the licensing of our products.
......@@ -353,7 +353,7 @@ We won't be going into the details for any of those but will briefly present the
|:--|:--|:--|
| `#[ink(storage)]` | On `struct` definitions. | Defines the ink! storage struct. There can only be one ink! storage definition per contract. |
| `#[ink(event)]` | On `struct` definitions. | Defines an ink! event. A contract can define multiple such ink! events. |
| `#[ink(anonymous)]` **new** | Applicable to ink! events. | Tells the ink! codegen to treat the ink! event as anonmyous which omits the event signature as topic upon emitting. Very similar to anonymous events in Solidity. |
| `#[ink(anonymous)]` **new** | Applicable to ink! events. | Tells the ink! codegen to treat the ink! event as anonymous which omits the event signature as topic upon emitting. Very similar to anonymous events in Solidity. |
| `#[ink(topic)]` | Applicate on ink! event field. | Tells the ink! codegen to provide a topic hash for the given field. Every ink! event can only have a limited number of such topic field. Similar semantics as to indexed event arguments in Solidity. |
| `#[ink(message)]` | Applicable to methods. | Flags a method for the ink! storage struct as message making it available to the API for calling the contract. |
| `#[ink(constructor)]` | Applicable to method. | Flags a method for the ink! storage struct as constructor making it available to the API for instantiating the contract. |
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment