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
/*
Date: 2023
Author: Fred Kyung-jin Rezeau <fred@litemint.com>
Copyright (c) 2023 Litemint LLC
MIT License
*/
//! A collection of procedural macros designed to streamline development for Soroban
//! smart contracts.
//!
//! ##State Machine
//!
//! The `state-machine` attribute macro can be used to implement versatile state machines
//! in Soroban smart contracts. It features state concurrency through regions, runtime behavior
//! modeling via extended state variables, transition control with guards and effects,
//! and state persistence with Soroban storage.
//!
//! ### Background
//!
//! While state machines are a prevalent behavioral pattern in Solidity smart contracts, their
//! implementation is often limited due to Solidity rigid architecture leading to complexities,
//! and sometimes impossibilities, in implementing concurrency and runtime behaviors.
//!
//! Leveraging Rust advanced type system, soroban-kit `state-machine` can handle more complex interactions
//! and concurrent state executions, enabling a flexible, yet straightforward state machine solution
//! for Soroban smart contracts.
//!
//! ### Usage
//!
//! Check out the `game lobby` and `coffee machine` examples for detailed usage:
//! soroban-kit/crates/soroban-macros/tests/state-machine-tests.rs
//! soroban-kit/crates/hello-soroban-kit/src/tests.rs
//!
//! ##Storage
//!
//! The `storage` and `key_constraint` macros can be used to implement type safety
//! for storage operations while also enforcing type rules at compile time to bind
//! the Soroban storage, data types and keys.
//!
//! For performance, the code generates a minimal wrapper that handles key and data operations
//! without duplication, leveraging Rust lifetimes for safe borrowing.
//!
//! ### Background
//!
//! When dealing with the Soroban storage, repetitive boilerplate code is typically required
//! for encapsulation and type safety over generic storage functions.
//! e.g.
//! fn set_user_data(key: &userKey, data: &UserData) // Persists user data in storage.
//! fn get_user_data(key: &userKey) -> UserData // Retrieves user data from storage.
//!
//! These macros streamline this process by automatically generating the boilerplate
//! code, enforcing type rules at compile time, binding the storage with custom data types and
//! optionally, applying Trait constraints to storage keys with `key_constraint`.
//!
//! ### Usage
//!
//! Check out the integration tests for detailed usage:
//! soroban-kit/crates/soroban-macros/tests/storage-tests.rs