README.md 4.33 KB
Newer Older
Hero Bird's avatar
Hero Bird committed
1 2
# pDSL - Parity's DSL for Smart Contracts

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/Robbepop/pdsl.svg?branch=master
[A2]: https://travis-ci.org/Robbepop/pdsl
9

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

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

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

19 20
[F1]: https://img.shields.io/badge/docs-nightly-black.svg
[F2]: https://robbepop.github.io/pdsl/pdsl_core/index.html
21

22 23 24
[G1]: https://img.shields.io/badge/docs-nightly-purple.svg
[G2]: https://robbepop.github.io/pdsl/pdsl_model/index.html

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

Hero Bird's avatar
Hero Bird committed
27
An [eDSL](https://wiki.haskell.org/Embedded_domain_specific_language) to write WebAssembly based smart contracts in 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 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
## 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) {
            if *self.value {
                *self.value = false
            } else {
                *self.value = true
            }
        }

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

Hero Bird's avatar
Hero Bird committed
67 68
## Goals

69 70 71
### Core Goals

| | |
Hero Bird's avatar
Hero Bird committed
72 73 74 75 76 77
|:-:|:-|
| **Ecosystem** | Allow for easy integration with the current Rust library ecosystem. |
| **Tooling** | Make the great Rust tooling work 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. These should all work without any custom configuration. |
| **Testing** | Make smart contract code as easy to test as using `cargo test`, and make most testing be possible without a blockchain environment at all. |
| **Building** | Make building of smart contract code as easy as using `cargo build`. This does not necessarily mean that you will be able to just type `cargo build`. It might need a separate subcommand. |

78 79 80
### Key Attributes

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

## Structure

Hero Bird's avatar
Hero Bird committed
89 90
| Module | Description |
|:-------|:------------|
91 92
| `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). |
93 94
| `lang` | The actual eDSL based on `pdsl_core` and `pdsl_model` to provide a user friendly interface to writing smart contract code. |
| `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
95

Hero Bird's avatar
Hero Bird committed
96
## Contribution
Hero Bird's avatar
Hero Bird committed
97

98
Visit our [contribution guidelines](CONTRIBUTING.md) for more information.
Hero Bird's avatar
Hero Bird committed
99 100 101 102

## 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.