Need help with ink?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

paritytech
282 Stars 85 Forks Apache License 2.0 919 Commits 45 Opened issues

Description

Parity's ink to write smart contracts

Services available

!
?

Need anything else?

Contributors list

ink!

Parity's ink! for writing smart contracts

[![linux][a1]][a2] [![codecov][c1]][c2] [![coveralls][d1]][d2] [![loc][e1]][e2] [![matrix][k1]][k2] [![discord][l1]][l2]

> squid, the ink! mascotink! is an eDSL to write WebAssembly based smart contracts using the Rust programming language. The compilation target are blockchains built on the Substrate framework.


Guided Tutorial for Beginnerscargo-contract cli tool for ink! contracts • Canvas UI for contract deployment/interaction • Talk to us on Matrix or Discord

Table of Contents

Play with It

We have a demonstration testnet running. You can request some tokens to play with from our Faucet and deploy your contracts via the Canvas UI.

The Canvas UI 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 project ‒ a simple Substrate blockchain which is configured to include the

contracts
pallet (see How it Works for more).

Usage

A prerequisite for compiling smart contracts is to have Rust and Cargo installed. Here's an installation guide.

We recommend installing

cargo-contract
, a CLI tool for helping setting up and managing WebAssembly smart contracts written with ink!:

cargo install cargo-contract --force

Use the

--force
to ensure you are updated to the most recent
cargo-contract
version.

In order to initialize a new ink! project you can use:

cargo contract new flipper

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 build && cargo contract generate-metadata

As a result you'll get a file

target/flipper.wasm
and
target/metadata.json
. Those need to be used when deploying the contract.

Hello, World! ‒ The Flipper

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.

Below you can see the code using the

ink_lang
version of ink!.
use ink_lang as ink;

#[ink::contract] mod flipper { /// The storage of the flipper contract. #[ink(storage)] pub struct Flipper { /// The single bool value. value: bool, }

impl Flipper {
    /// Instantiates a new Flipper contract and initializes `value` to `init_value`.
    #[ink(constructor)]
    pub fn new(init_value: bool) -> Self {
        Self {
            value: init_value,
        }
    }

    /// Flips `value` from `true` to `false` or vice versa.
    #[ink(message)]
    pub fn flip(&mut self) {
        self.value = !self.value;
    }

    /// Returns the current state of `value`.
    #[ink(message)]
    pub fn get(&self) -> bool {
        self.value
    }
}

/// Simply execute `cargo test` in order to test your contract using the below unit tests.
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let mut flipper = Flipper::new(false);
        assert_eq!(flipper.get(), false);
        flipper.flip();
        assert_eq!(flipper.get(), true);
    }
}

}

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.

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

.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 section or our smart contracts workshop.

How it Works

  • Substrate's Framework for Runtime Aggregation of Modularised Entities (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 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
contract on how to utilize it or the documentation for details.

Off-chain Testing

The

#[ink::test]
proc. macro enables off-chain testing. See e.g. the
examples/erc20
contract on how to utilize those or the documentation for details.

Developer Documentation

| Crate | Docs | Description | |:--|:--|:--|

ink_lang
| | Language features expose by ink!. See here for a detailed description of attributes which you can use in an
#[ink::contract]
. |
ink_storage
| | Data structures available in ink!. |
ink_env
| | Low-level interface for interacting with the smart contract Wasm executor. |
ink_prelude
| | Common API for no_std and std to access alloc crate types. |

Contributing

Visit our contribution guidelines 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. Please contact us if you have questions about the licensing of our products.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.