README.md 4.55 KB
Newer Older
1
# ink! - Parity's ink to write smart contracts
Hero Bird's avatar
Hero Bird committed
2

Hero Bird's avatar
Hero Bird committed
3 4 5
| Linux              | Codecov              | Coveralls              | LoC              |
|:------------------:|:--------------------:|:----------------------:|:----------------:|
| [![linux][A1]][A2] | [![codecov][C1]][C2] | [![coveralls][D1]][D2] | [![loc][E1]][E2] |
6

7 8
[A1]: https://travis-ci.org/paritytech/ink.svg?branch=master
[A2]: https://travis-ci.org/paritytech/ink
9

10 11
[C1]: https://codecov.io/gh/paritytech/ink/branch/master/graph/badge.svg
[C2]: https://codecov.io/gh/paritytech/ink/branch/master
12

13 14
[D1]: https://coveralls.io/repos/github/paritytech/ink/badge.svg?branch=master
[D2]: https://coveralls.io/github/paritytech/ink?branch=master
15

16
[E1]: https://tokei.rs/b1/github/paritytech/ink?category=code
17
[E2]: https://github.com/Aaronepower/tokei#badges
18

Hero Bird's avatar
Hero Bird committed
19 20
[F1]: https://img.shields.io/badge/docs-core-blue.svg
[F2]: https://paritytech.github.io/ink/ink_core
21

Hero Bird's avatar
Hero Bird committed
22 23 24 25 26
[G1]: https://img.shields.io/badge/docs-model-blue.svg
[G2]: https://paritytech.github.io/ink/ink_model

[H1]: https://img.shields.io/badge/docs-abi-blue.svg
[H2]: https://paritytech.github.io/ink/ink_abi
27

Hero Bird's avatar
Hero Bird committed
28
**IMPORTANT NOTE:** WORK IN PROGRESS! Do not expect this to be working.
Hero Bird's avatar
Hero Bird committed
29

Hero Bird's avatar
Hero Bird committed
30 31
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.

32 33
For more information please visit [the ink! tutorial](https://substrate.dev/substrate-contracts-workshop/#/0/building-your-contract).

Hero Bird's avatar
Hero Bird committed
34 35 36 37 38
## Developer Documentation

| `ink_abi` | `ink_core` | `ink_model` |
|-----------|------------|-------------|
| [![][H1]][H2] | [![][F1]][F2] | [![][G1]][G2] |
Hero Bird's avatar
Hero Bird committed
39

Hero Bird's avatar
Hero Bird committed
40 41 42 43
### Scripts

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.

44
## Examples
45

46
For building the example smart contracts found under `examples` you will need to have `cargo-contract` installed.
47

48
```
49
cargo install --git https://github.com/paritytech/ink cargo-contract
50
```
51

52
Add `--force` option to update to the most recent `cargo-contract` version.
53

54 55
Please visit [the documentation](https://substrate.dev/substrate-contracts-workshop/#/0/building-your-contract)
about building contracts and generating metadata.
Hero Bird's avatar
Hero Bird committed
56

57
### Hello, World! - The Flipper
Hero Bird's avatar
Hero Bird committed
58

59 60
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.
61

62
Below you can see the code using the `ink_lang2` frontend to ink!.
63 64

```rust
65 66
use ink_core::storage;
use ink_lang2 as ink;
Hero Bird's avatar
Hero Bird committed
67

68 69 70 71
#[ink::contract(version = "0.1.0")]
mod flipper {
    /// The storage of the flipper contract.
    #[ink(storage)]
72
    struct Flipper {
73
        /// The single `bool` value.
74 75 76
        value: storage::Value<bool>,
    }

77 78 79 80 81
    impl Flipper {
        /// Instantiates a new Flipper contract and initializes `value` to `init_value`.
        #[ink(constructor)]
        fn new(&mut self, init_value: bool) {
            self.value.set(init_value);
82 83
        }

84 85 86 87
        /// Instantiates a new Flipper contract and initializes `value` to `false` by default.
        #[ink(constructor)]
        fn default(&mut self) {
            self.new(false)
88 89
        }

90 91 92 93 94 95 96 97 98
        /// Flips `value` from `true` to `false` or vice versa.
        #[ink(message)]
        fn flip(&mut self) {
            *self.value = !self.get();
        }

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

103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
    /// As in normal Rust code we are able to define tests like below.
    ///
    /// Simply execute `cargo test` in order to test your contract.
    #[cfg(test)]
    mod tests {
        use super::*;

        #[test]
        fn default_works() {
            // Note that `#[ink(constructor)]` functions that above have been
            // defined as `&mut self` can be used as normal Rust constructors
            // in test mode.
            let flipper = Flipper::default();
            assert_eq!(flipper.get(), false);
        }

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

Hero Bird's avatar
Hero Bird committed
130
## Contribution
Hero Bird's avatar
Hero Bird committed
131

132
Visit our [contribution guidelines](CONTRIBUTING.md) for more information.
Hero Bird's avatar
Hero Bird committed
133 134 135

## License

136
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.
137
 of our products.