stellar-macros 0.7.0

Macros for Stellar contracts.
Documentation 
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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

# Stellar Macros

Macros for Stellar contracts.

## Modules

### Default Implementation

The `#[contractimpl(contracttrait)]` macro generates missing default implementations for traits provided by this library.

#### Usage Examples

```rust
use soroban_sdk::{contract, contractimpl, Address, Env};
use stellar_tokens::fungible::{Base, FungibleToken};

#[contract]
pub struct MyContract;

#[contractimpl(contracttrait)]
impl FungibleToken for MyContract {
    type ContractType = Base;

    // Only provide overrides here, default implementations are auto-generated
}
```

#### Supported Traits

- `FungibleToken`
- `FungibleBurnable`
- `NonFungibleToken`
- `NonFungibleBurnable`
- `NonFungibleEnumerable`
- `AccessControl`
- `Ownable`

### Access Control Macros

Macros for role-based and ownership-based access control.

#### Usage Examples

```rust
use soroban_sdk::{contract, contractimpl, Address, Env};
use stellar_macros::{only_admin, only_role, has_role, only_owner};

#[contract]
pub struct MyContract;

#[contractimpl]
impl MyContract {
    #[only_admin]
    pub fn admin_function(e: &Env) {
        // Only admin can call this
    }

    #[only_role(caller, "minter")]
    pub fn mint(e: &Env, amount: i128, caller: Address) {
        // Only accounts with "minter" role can call this
        // Includes both role check AND authorization
    }

    #[has_role(caller, "minter")]
    pub fn mint_with_auth(e: &Env, amount: i128, caller: Address) {
        caller.require_auth(); // Manual authorization required
        // Only role check, no automatic authorization
    }

    #[only_owner]
    pub fn owner_function(e: &Env) {
        // Only contract owner can call this
    }
}
```

#### Available Macros

- `#[only_admin]`: Restricts access to admin only
- `#[only_role(account, "role")]`: Role check with authorization
- `#[has_role(account, "role")]`: Role check without authorization
- `#[has_any_role(account, ["role1", "role2"])]`: Multiple role check without authorization
- `#[only_any_role(account, ["role1", "role2"])]`: Multiple role check with authorization
- `#[only_owner]`: Restricts access to owner only

**Important**: Some macros perform role checking without authorization, while others include both:

- **Role Check Only** (`#[has_role]`, `#[has_any_role]`): Verify role membership but don't call `require_auth()`
- **Role Check + Auth** (`#[only_role]`, `#[only_any_role]`): Verify role membership AND call `require_auth()`

Use role-only macros when your function already contains `require_auth()` calls to avoid duplicate authorization panics.

### Pausable Macros

Macros for implementing pausable functionality in contracts.

#### Usage Examples

```rust
use soroban_sdk::{contract, contractimpl, Env};
use stellar_macros::{when_not_paused, when_paused};

#[contract]
pub struct MyContract;

#[contractimpl]
impl MyContract {
    #[when_not_paused]
    pub fn normal_operation(e: &Env) {
        // This function only works when contract is not paused
    }

    #[when_paused]
    pub fn emergency_function(e: &Env) {
        // This function only works when contract is paused
    }
}
```

#### Available Macros

- `#[when_not_paused]`: Function executes only when contract is not paused
- `#[when_paused]`: Function executes only when contract is paused

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
# We recommend pinning to a specific version, because rapid iterations are expected as the library is in an active development phase.
stellar-macros = "=0.7.0"
```

## Examples

See the following examples in the repository:
- [`examples/fungible-pausable/`](https://github.com/OpenZeppelin/stellar-contracts/tree/main/examples/fungible-pausable) - Pausable macros usage
- [`examples/nft-access-control/`](https://github.com/OpenZeppelin/stellar-contracts/tree/main/examples/nft-access-control) - Access control macros

## License

This package is part of the Stellar Contracts library and follows the same licensing terms.