README.md 5.1 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 42 43 44 45 46
### 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.

### Testing

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

47 48
## Example

Hero Bird's avatar
Hero Bird committed
49
Below is an example using ink! demonstrating a simple Flipper smart contract
50 51 52 53
that has a boolean state that can be flipped or returned.

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

57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
    /// 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) {
73
            *self.value = !*self.value;
74 75 76 77 78 79 80 81 82 83
        }

        /// Returns the current state.
        pub(external) fn get(&self) -> bool {
            *self.value
        }
    }
}
```

84 85 86 87 88 89 90 91 92 93 94 95 96 97
## 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
98 99
## Goals

100 101 102
### Core Goals

| | |
Hero Bird's avatar
Hero Bird committed
103
|:-:|:-|
104 105 106 107
| **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
108

109 110 111
### Key Attributes

| | |
Hero Bird's avatar
Hero Bird committed
112 113 114 115 116
|:-:|:-|
| **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
117 118 119

## Structure

Hero Bird's avatar
Hero Bird committed
120 121
| Module | Description |
|:-------|:------------|
122
| `cli` | A minimalist tool to setup a smart contract project easily. |
123 124
| `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). |
125
| `lang` | The actual eDSL based on `ink_core` and `ink_model` to provide a user friendly interface to writing smart contract code. |
126
| `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
127

Hero Bird's avatar
Hero Bird committed
128
## Contribution
Hero Bird's avatar
Hero Bird committed
129

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

## License

134
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.
135
 of our products.