README.md 5.8 KB
Newer Older
Michael Müller's avatar
Michael Müller committed
1
2
<div align="center">
    <img src="./.images/cargo-contract.svg" alt="cargo-contract" height="170" />
Andrew Jones's avatar
Andrew Jones committed
3

Michael Müller's avatar
Michael Müller committed
4
5
[![CI Status][a1]][a2]
[![Latest Release][d1]][d2]
6
[![stack-exchange][s1]][s2]
Andrew Jones's avatar
Andrew Jones committed
7

8
9
[a1]: https://gitlab.parity.io/parity/mirrors/cargo-contract/badges/master/pipeline.svg
[a2]: https://gitlab.parity.io/parity/mirrors/cargo-contract/pipelines
Michael Müller's avatar
Michael Müller committed
10
11
[d1]: https://img.shields.io/crates/v/cargo-contract.svg
[d2]: https://crates.io/crates/cargo-contract
12
13
[s1]: https://img.shields.io/badge/click-white.svg?logo=StackExchange&label=ink!%20Support%20on%20StackExchange&labelColor=white&color=blue
[s2]: https://substrate.stackexchange.com/questions/tagged/ink?tab=Votes
Andrew Jones's avatar
Andrew Jones committed
14

Michael Müller's avatar
Michael Müller committed
15
16
17
18
19
20
<p align="center">

> <img src="./.images/ink-squid.svg" alt="squink, the ink! mascot" style="vertical-align: middle" align="left" height="60" />`cargo-contract` is a CLI tool which helps you develop smart contracts in Parity's <a href="https://github.com/paritytech/ink">ink!</a>.<br/>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.
</p>

<br/>
21

22
23
[Guided Tutorial for Beginners](https://docs.substrate.io/tutorials/v3/ink-workshop/pt1/)&nbsp;&nbsp;&nbsp;&nbsp;
[ink! Documentation Portal](https://ink.substrate.io)
24

Michael Müller's avatar
Michael Müller committed
25
26
<br/>
</div>
27

Michael Müller's avatar
Michael Müller committed
28
More relevant links:
29
30
* Find answers to your questions by joining our [Stack Exchange][s2] community
* [ink!](https://github.com/paritytech/ink) ‒ The main ink! repository with smart contract examples
31
* [Contracts UI](https://contracts-ui.substrate.io/) ‒ Frontend for contract deployment and interaction
32
* [Substrate Contracts Node](https://github.com/paritytech/substrate-contracts-node) ‒ Simple Substrate blockchain which includes smart contract functionality
Michael Müller's avatar
Michael Müller committed
33
34
35


## Installation
36

Michael Müller's avatar
Michael Müller committed
37
38
39
40
41
42
43
44
* 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)
45

46
  There's only an old version in your distributions package manager? Just use a
Michael Müller's avatar
Michael Müller committed
47
  [binary release](https://github.com/WebAssembly/binaryen/releases).
48

Chevdor's avatar
Chevdor committed
49
50
51
* Step 3: Install `dylint`
  * (MacOS) `brew install openssl`
  * `cargo install cargo-dylint dylint-link`.
52

Chevdor's avatar
Chevdor committed
53
* Step 4: `cargo install --force --locked cargo-contract`.
54

55
You can always update the `cargo-contract` binary to the latest version by running the Step 4.
56

57
### Installation using Docker Image
58

59
60
61
62
If you prefer to use Docker instead we have a Docker image
[available on the Docker Hub](https://hub.docker.com/r/paritytech/contracts-ci-linux):

```bash
63
64
# Pull the latest stable image.
docker pull paritytech/contracts-ci-linux:production
65
66

# Create a new contract in your current directory.
67
docker run --rm -it -v $(pwd):/sources paritytech/contracts-ci-linux:production \
68
69
70
71
  cargo +nightly contract new --target-dir /sources my_contract

# Build the contract. This will create the contract file under
# `my_contract/target/ink/my_contract.contract`.
72
docker run --rm -it -v $(pwd):/sources paritytech/contracts-ci-linux:production \
73
74
75
  cargo +nightly contract build --manifest-path=/sources/my_contract/Cargo.toml
```

76
77
If you want to reproduce other steps of CI process you can use the following
[guide](https://github.com/paritytech/scripts#reproduce-ci-locally).
78

Michael Müller's avatar
Michael Müller committed
79
## Usage
80

Michael Müller's avatar
Michael Müller committed
81
82
You can always use `cargo contract help` to print information on available
commands and their usage.
83

Michael Müller's avatar
Michael Müller committed
84
85
For each command there is also a `--help` flag with info on additional parameters,
e.g. `cargo contract new --help`.
86

Michael Müller's avatar
Michael Müller committed
87
##### `cargo contract new my_contract`
88

Michael Müller's avatar
Michael Müller committed
89
90
Creates an initial smart contract with some scaffolding code into a new
folder `my_contract` .
91

92
The contract contains the source code for the [`Flipper`](https://github.com/paritytech/ink/blob/master/examples/flipper/lib.rs)
Michael Müller's avatar
Michael Müller committed
93
94
contract, which is about the simplest "smart" contract you can build ‒ a `bool` which gets flipped
from `true` to `false` through the `flip()` function.
95

Michael Müller's avatar
Michael Müller committed
96
##### `cargo +nightly contract build`
97

Michael Müller's avatar
Michael Müller committed
98
99
100
Compiles the contract into optimized WebAssembly bytecode, generates metadata for it,
and bundles both together in a `<name>.contract` file, which you can use for
deploying the contract on-chain.
101

Michael Müller's avatar
Michael Müller committed
102
103
104
`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`.
Qinxuan Chen's avatar
Qinxuan Chen committed
105

Michael Müller's avatar
Michael Müller committed
106
107
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.
Qinxuan Chen's avatar
Qinxuan Chen committed
108

Michael Müller's avatar
Michael Müller committed
109
##### `cargo contract check`
Qinxuan Chen's avatar
Qinxuan Chen committed
110

Michael Müller's avatar
Michael Müller committed
111
112
Checks that the code builds as WebAssembly. This command does not output any `<name>.contract`
artifact to the `target/` directory.
113

114
115
116
##### `cargo contract test`

Runs test suites defined for a smart contract off-chain.
Qinxuan Chen's avatar
Qinxuan Chen committed
117

118
119
120
121
122
123
124
125
126
127
128
129
##### `cargo contract upload`

Upload a contract to a `pallet-contracts` enabled chain. See [extrinsics](docs/extrinsics.md).

##### `cargo contract instantiate`

Create an instance of a contract on chain. See [extrinsics](docs/extrinsics.md).

##### `cargo contract call`

Invoke a message on an existing contract on chain. See [extrinsics](docs/extrinsics.md).

130
131
132
133
134
135
136
137
##### `cargo contract decode`

Decodes a contracts input or output data.

This can be either an event, an invocation of a contract message, or an invocation of a contract constructor.

The argument has to be given as hex-encoding, starting with `0x`.

Andrew Jones's avatar
Andrew Jones committed
138
139
## License

Michael Müller's avatar
Michael Müller committed
140
141
142
143
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.