README.md 5.65 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 32 33 34 35 36
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.

## Developer Documentation

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

Hero Bird's avatar
Hero Bird committed
38 39 40 41
### 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.

42 43
### Examples

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

46 47 48
```
cargo install cargo-contract
```
49

50 51 52 53 54
Execute the following command in shell while in an example's directory:

```
cargo contract build
```
55

Hero Bird's avatar
Hero Bird committed
56 57 58 59 60
### Testing

Off-chain testing is done by `cargo test`.
If you want to test all workspace crates, do `cargo test --all`.

61 62
## Example

Hero Bird's avatar
Hero Bird committed
63
Below is an example using ink! demonstrating a simple Flipper smart contract
64 65 66 67
that has a boolean state that can be flipped or returned.

```rust
contract! {
Andrew Jones's avatar
Andrew Jones committed
68 69
    /// Specify concrete implementation of contract environment types
    #![env = ink_core::env::DefaultSrmlTypes]
Hero Bird's avatar
Hero Bird committed
70

71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
    /// Flips its state between `true` and `false`.
    struct Flipper {
        /// The current state of our flag.
        value: storage::Value<bool>,
    }

    impl Deploy for Flipper {
        /// Initializes our state to `false` upon deploying our smart contract.
        fn deploy(&mut self) {
            self.value.set(false)
        }
    }

    impl Flipper {
        /// Flips the current state of our smart contract.
        pub(external) fn flip(&mut self) {
87
            *self.value = !*self.value;
88 89 90 91 92 93 94 95
        }

        /// Returns the current state.
        pub(external) fn get(&self) -> bool {
            *self.value
        }
    }
}
96 97 98 99 100 101 102 103 104 105 106 107 108 109

/// Run off-chain tests with `cargo test`.
#[cfg(tests)]
mod tests {
    use super::*;

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

112 113 114 115 116 117 118 119 120 121 122 123 124 125
## Documentation

- User
    - Wiki: [link](https://github.com/paritytech/ink/wiki)
- Developer
    - [`core`][F2]: Developer documentation for the core abstractions
        - Storage allocators, SRML environment definitions
        - Offchain test environment
        - Utilities for smart contracts like collections
    - [`model`][G2]: Developer documentation for the model abstractions
        - Virtual model of a smart contract
        - Contains smart contract ABI dispatch
        - Used to build an actual smart contract eDSL on

Hero Bird's avatar
Hero Bird committed
126 127
## Goals

128 129 130
### Core Goals

| | |
Hero Bird's avatar
Hero Bird committed
131
|:-:|:-|
132 133 134 135
| **Ecosystem** | Easy integration with the Rust ecosystem. |
| **Tooling** | Rust tooling works out-of-the-box for smart contract code. This includes auto-completion, syntax highlighting, code coverage for tests, go-to definitions and other IDE goodies. |
| **Testing** | Easy to build, test, deploy and run. |
| **Development** | Development can be done entirely off-chain to speed up the process. |
Hero Bird's avatar
Hero Bird committed
136

137 138 139
### Key Attributes

| | |
Hero Bird's avatar
Hero Bird committed
140 141 142 143 144
|:-:|:-|
| **Efficient** | Compile smart contract code to machine code that is _at least_ as efficient as if you used the low-level function calls directly. |
| **Robust** | Make it as simple as possible to write code that just does what is expected and as difficult as possible to write incorrect or exploitable code. |
| **Simple** | Smart contract code should be as easy-to-read as possible. |
| **Accessible** | Make it accessible to users by providing excellent documentation and teaching materials. |
Hero Bird's avatar
Hero Bird committed
145 146 147

## Structure

Hero Bird's avatar
Hero Bird committed
148 149
| Module | Description |
|:-------|:------------|
150
| `cli` | A minimalist tool to setup a smart contract project easily. |
151 152
| `core` | The core utilities used to write smart contracts. |
| `model` | Medium-level abstractions to write smart contracts heavily inspired by [Fleetwood](https://github.com/paritytech/fleetwood). |
153
| `lang` | The actual eDSL based on `ink_core` and `ink_model` to provide a user friendly interface to writing smart contract code. |
154
| `examples` | Features some smart contracts written for clarity with focus on teaching users how to use pDSL to write their own contracts. |
Hero Bird's avatar
Hero Bird committed
155

Hero Bird's avatar
Hero Bird committed
156
## Contribution
Hero Bird's avatar
Hero Bird committed
157

158
Visit our [contribution guidelines](CONTRIBUTING.md) for more information.
Hero Bird's avatar
Hero Bird committed
159 160 161

## License

162
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.
163
 of our products.