README.md 4.56 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 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51
## 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! {
    /// 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) {
52
            *self.value = !*self.value;
53 54 55 56 57 58 59 60 61 62
        }

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

63 64 65 66 67 68 69 70 71 72 73 74 75 76
## 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
77 78
## Goals

79 80 81
### Core Goals

| | |
Hero Bird's avatar
Hero Bird committed
82
|:-:|:-|
83 84 85 86
| **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
87

88 89 90
### Key Attributes

| | |
Hero Bird's avatar
Hero Bird committed
91 92 93 94 95
|:-:|:-|
| **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
96 97 98

## Structure

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

Hero Bird's avatar
Hero Bird committed
107
## Contribution
Hero Bird's avatar
Hero Bird committed
108

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

## License

The entire code within this repository is licensed under the [GLP-v3](LICENSE). Please [contact us](https://www.parity.io/contact/) if you have questions about the licensing of our products.
114
 of our products.