mazzaroth_rs/
lib.rs

1//! # Mazzaroth Rust Library
2//!
3//! The Mazzaroth Rust Library is a rust library that includes host bindings
4//! and everything needed to compile rust contracts to Web Assembly, compatible
5//! with the Mazzaroth VM.  Here you will find the necessary abi encoders and
6//! decoders used to pass and return arguments to contract functions as well as
7//! the external host functions available to use.
8//!
9//! ## How to use
10//!
11//! The first step to using this library is to include the necessary dependencies.
12//! The following 3 dependencies should be included in your Cargo.toml:
13//!
14//! mazzaroth-rs
15//! mazzaroth-rs-derive
16//! mazzaroth-xdr
17//!
18//! Every contract will have a similar base layout for the main function and the contract trait definition.
19//! `main()` is used as the entry point and has several important features.  It will instantiate the contract,
20//! call a host function to retrieve function input, execute the function, and return a response.
21//!
22//! Here is a basic Hello World contract example:
23//! ```ignore
24//! // must include the ContractInterface and mazzaroth_abi for compiling the macro
25//! extern crate mazzaroth_rs;
26//! extern crate mazzaroth_rs_derive;
27//! use mazzaroth_rs::ContractInterface;
28//! use mazzaroth_rs_derive::mazzaroth_abi;
29//!
30//! // using specific external host modules
31//! use mazzaroth_rs::external::{transaction, log};
32//!
33//! #[no_mangle]
34//! pub fn main() {
35//!     // panic hook is set to call the host error log function when a panic occurs
36//!     std::panic::set_hook(Box::new(mazzaroth_rs::external::errors::hook));
37//!
38//!     // Creates a new instance of the ABI generated around the Contract
39//!     let mut contract = HelloWorld::new(Hello {});
40//!
41//!     // Use a host function to get arguments
42//!     let args = transaction::arguments();
43//!
44//!     // Execute calls one of the functions defined in the contract
45//!     // Input for the function to call and it's params comes from the Runtime
46//!     let response = contract.execute(&args);
47//!
48//!     // Provide return value through host call
49//!     transaction::ret(response);
50//! }
51//!
52//! // mazzaroth_abi used to generate the contract from the trait during compilation
53//! #[mazzaroth_abi(HelloWorld)]
54//! pub trait HelloWorldContract {
55//!     // hello() defined as a readonly function
56//!     #[readonly]
57//!     fn hello(&mut self) -> u32;
58//! }
59//!
60//! // Struct used to implement the contract trait
61//! pub struct Hello {}
62//!
63//! // Actual contract implementation
64//! impl HelloWorldContract for Hello {
65//!     fn hello(&mut self) -> u32 {
66//!         log("Hello World!".to_string());
67//!         14
68//!     }
69//! }
70//! ```
71
72/// Defines the Encoder and Decoder used to transmit XDR objects to and from the host VM.
73pub mod abi;
74pub use abi::decoder::{Decoder, InputDecoder};
75pub use abi::encoder::Encoder;
76
77// Contract trait definition
78mod contract;
79pub use contract::{ContractError, ContractInterface};
80
81#[macro_use]
82extern crate cfg_if;
83
84extern crate mazzaroth_xdr;
85extern crate xdr_rs_serialize;
86
87pub mod external;
mazzaroth_rs/lib.rs

mazzaroth_rs/
lib.rs
