piecrust_uplink/lib.rs
1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at http://mozilla.org/MPL/2.0/.
4//
5// Copyright (c) DUSK NETWORK. All rights reserved.
6
7//! Piecrust Uplink is the crate for writing WASM smart contracts in Rust
8//! targeting the Piecrust virtual machine.
9//!
10//! A smart contract is a program exposing a collection of functions that
11//! operate on a shared state. These functions can perform a variety of
12//! operations, such as reading or modifying the state, or interacting with the
13//! host.
14//!
15//! # State Model and ABI
16//! Contracts targeting the Piecrust VM represent their state as a [WASM
17//! memory]. The contract is free to represent its data as it sees fit, and may
18//! allocate at will.
19//!
20//! To communicate with the host, both the contract and the host can
21//! emplace data in a special region of this memory called the argument buffer.
22//! The argument buffer is used as both the input from the host and as the
23//! output of the contract. All functions exposed by the contract must follow
24//! the convention:
25//!
26//! ```c
27//! // A function compatible with the piecrust ABI takes in the number of bytes
28//! // written by the host to the argument buffer and returns the number of
29//! // bytes written by the contract.
30//! uint32_t fname(uint32_t arg_len);
31//! ```
32//!
33//! The contract also has some functions available to it, offered by the host
34//! through WASM imports. Examples of these functions include, but are not
35//! limited to:
36//!
37//! - [`call`] to call another contract
38//! - [`emit`] to emit events
39//!
40//! The functions in this crate are wrappers around a particular way of calling
41//! the WASM imports. Take a look at the [externs] for a full view of what is
42//! available.
43//!
44//! # Examples
45//! Some of the contracts used for testing purposes function as good examples.
46//! Take a look at the [contracts/] directory.
47//!
48//! # Features
49//! By default, this crate will include no features and build only the types and
50//! functions available when the ABI is not present. To write a contract one
51//! must use the `abi` feature:
52//!
53//! - `abi` for writing contracts
54//! - `dlmalloc` to using the builtin allocator
55//! - `debug` for writing contracts with debug capabilities such as the
56//! [`debug!`] macro, and logging panics to stdout
57//!
58//! [WASM memory]: https://wasmbyexample.dev/examples/webassembly-linear-memory/webassembly-linear-memory.rust.en-us.html
59//! [contracts/]: https://github.com/dusk-network/piecrust/tree/main/contracts
60//! [externs]: https://github.com/dusk-network/piecrust/blob/c2dadaa8dec210bdbbc72619a687eb8c6f693877/piecrust-uplink/src/abi/state.rs#L42-L64
61
62// Allow unsafe_op_in_unsafe_fn from bytecheck/rkyv derive macros until
63// we can update to rkyv 0.8 / bytecheck 0.8 which have breaking API changes.
64#![allow(unsafe_op_in_unsafe_fn)]
65#![cfg_attr(docsrs, feature(doc_cfg))]
66#![no_std]
67
68extern crate alloc;
69
70#[cfg(feature = "abi")]
71#[cfg_attr(docsrs, doc(cfg(feature = "abi")))]
72mod abi;
73#[cfg(feature = "abi")]
74pub use abi::*;
75
76mod types;
77pub use types::*;
78
79mod error;
80pub use error::*;
81
82/// How many bytes to use for scratch space when serializing
83pub const SCRATCH_BUF_BYTES: usize = 1024;
84
85/// The size of the argument buffer in bytes
86pub const ARGBUF_LEN: usize = 64 * 1024;