piecrust-uplink 0.18.0

Build smart contracts directly on top of Dusk's `piecrust` virtual machine.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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
67
68
69
70
71

# π-crust Uplink

[![Repository](https://img.shields.io/badge/github-piecrust%20uplink-blueviolet?logo=github)](https://github.com/dusk-network/piecrust/tree/main/piecrust-uplink)
![Build Status](https://github.com/dusk-network/piecrust/workflows/build/badge.svg)
[![Documentation](https://img.shields.io/badge/docs-piecrust%20uplink-blue?logo=rust)](https://docs.rs/piecrust-uplink/)

Piecrust Uplink is the library that allows you to build smart contracts directly on top of Dusk's Piecrust virtual machine. 

## Usage

The library allows users of the contract platform to manage the interface and state with the host environment of the contracts. The example below describes a barebones contract. For more detailed examples, see the [contracts](https://github.com/dusk-network/piecrust/tree/main/contracts) folder.

Add `piecrust_uplink` as a dependency to your contract project:
```sh
cargo add piecrust_uplink
```

To make use of `uplink`, import the dependency in your project and mark it as `no_std`:
```rust
#![no_std]

use piecrust_uplink as uplink;
```

To attach state to a contract:
```rust
/// Struct that describe the state for your contract
pub struct Counter {
    value: i64,
};

/// State of the contract
static mut STATE: Counter = Counter { value: 0x1 };
```

To define logic for your contract, define an implementation:
```rust
impl Counter {
    pub fn read_value(&self) -> i64 {
        self.value
    }

    pub fn increment(&mut self) {
        let value = self.value + 1;
    }
}
```

Read and write operations need to be exposed to the host. Add the following below the implementation:
```rust
unsafe fn read_value(arg_len: u32) -> u32 {
    uplink::wrap_call(arg_len, |_: ()| STATE.read_value())
}

#[no_mangle]
unsafe fn increment(arg_len: u32) -> u32 {
    uplink::wrap_call(arg_len, |panic: bool| STATE.increment(panic))
}
```

## Release History

To see the release history for this crate, please see the [CHANGELOG](./CHANGELOG.md) file.

## License

This code is licensed under the Mozilla Public License Version 2.0 (MPL-2.0). Please see the [LICENSE](./LICENSE) for further details.

## Contribute

If you want to contribute to this project, please check the [CONTRIBUTING](https://github.com/dusk-network/.github/blob/main/.github/CONTRIBUTING.md) file.