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

3 4 5
| Linux              | Codecov              | Coveralls              | LoC              | Docs (Core)       | Docs (Model)      |
|:------------------:|:--------------------:|:----------------------:|:----------------:|:-----------------:|:-----------------:|
| [![linux][A1]][A2] | [![codecov][C1]][C2] | [![coveralls][D1]][D2] | [![loc][E1]][E2] | [![docs][F1]][F2] | [![docs][G1]][G2] |
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

19
[F1]: https://img.shields.io/badge/docs-nightly-black.svg
20
[F2]: https://paritytech.github.io/ink/ink_core/index.html
21

22
[G1]: https://img.shields.io/badge/docs-nightly-purple.svg
23
[G2]: https://paritytech.github.io/ink/ink_model/index.html
24

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

27
ink is an [eDSL](https://wiki.haskell.org/Embedded_domain_specific_language) to write WebAssembly based smart contracts using the Rust programming language.
Hero Bird's avatar
Hero Bird committed
28

29 30 31 32 33 34 35
## Example

Below is an example using the eDSL demonstrating a simple Flipper smart contract
that has a boolean state that can be flipped or returned.

```rust
contract! {
Andrew Jones's avatar
Andrew Jones committed
36 37 38
    /// Specify concrete implementation of contract environment types
    #![env = ink_core::env::DefaultSrmlTypes]
 
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
    /// 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) {
55
            *self.value = !*self.value;
56 57 58 59 60 61 62 63 64 65
        }

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

66 67 68 69 70 71 72 73 74 75 76 77 78 79
## 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
80 81
## Goals

82 83 84
### Core Goals

| | |
Hero Bird's avatar
Hero Bird committed
85
|:-:|:-|
86 87 88 89
| **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
90

91 92 93
### Key Attributes

| | |
Hero Bird's avatar
Hero Bird committed
94 95 96 97 98
|:-:|:-|
| **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
99 100 101

## Structure

Hero Bird's avatar
Hero Bird committed
102 103
| Module | Description |
|:-------|:------------|
104
| `cli` | A minimalist tool to setup a smart contract project easily. |
105 106
| `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). |
107
| `lang` | The actual eDSL based on `ink_core` and `ink_model` to provide a user friendly interface to writing smart contract code. |
108
| `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
109

Hero Bird's avatar
Hero Bird committed
110
## Contribution
Hero Bird's avatar
Hero Bird committed
111

112
Visit our [contribution guidelines](CONTRIBUTING.md) for more information.
Hero Bird's avatar
Hero Bird committed
113 114 115

## License

116
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.
117
 of our products.