Skip to content

Commit 58c94be

Browse files
ZigBalthazarZigBalthazar
committed
docs: traits docs
1 parent 5407cf8 commit 58c94be

File tree

8 files changed

+468
-20
lines changed

8 files changed

+468
-20
lines changed

‎docs/3-Traits/1-Tokens/index.md

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎docs/3-Traits/2-AccessControl/1-AccessControl/index.md

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# AccessControl Trait
2+
3+
The `AccessControl` trait provides a flexible and extensible role-based access control mechanism. It allows you to manage different roles and their respective permissions within a smart contract. Roles can be granted, revoked, or renounced by accounts, and specific functions can be restricted to certain roles.
4+
5+
#### Properties
6+
7+
- **_roles**: `map<Int, RoleData>`
8+
- A mapping from role identifiers to their corresponding `RoleData`.
9+
- **ADMIN_ROLE**: `Int`
10+
- A constant representing the administrator role. This is used as the default admin role for all roles.
11+
12+
#### Structs
13+
14+
- **RoleData**
15+
- **hasRole**: `map<Address, Bool>`
16+
- A mapping indicating which accounts have this role.
17+
- **adminRole**: `Int`
18+
- The role that has administrative privileges over this role.
19+
20+
#### Messages
21+
22+
- **GrantRoleMessage**
23+
- **role**: `Int`
24+
- **account**: `Address`
25+
26+
- **RevokeRoleMessage**
27+
- **role**: `Int`
28+
- **account**: `Address`
29+
30+
- **RenounceRoleMessage**
31+
- **role**: `Int`
32+
- **account**: `Address`
33+
34+
- **GrantRoleEvent**
35+
- **role**: `Int`
36+
- **account**: `Address`
37+
38+
- **RevokeRoleEvent**
39+
- **role**: `Int`
40+
- **account**: `Address`
41+
42+
- **RenounceRoleEvent**
43+
- **role**: `Int`
44+
- **account**: `Address`
45+
46+
#### Methods
47+
48+
- **_initRole(role: Int) -> Bool**
49+
- Initializes a role with an empty set of members and sets the admin role to `ADMIN_ROLE` if the role does not already exist.
50+
- **Parameters**:
51+
- `role`: The identifier of the role to initialize.
52+
- **Returns**: `Bool` indicating if the role was initialized.
53+
54+
- **_setRoleAdmin(role: Int, adminRole: Int)**
55+
- Sets the admin role for a specific role.
56+
- **Parameters**:
57+
- `role`: The identifier of the role.
58+
- `adminRole`: The identifier of the admin role.
59+
60+
- **_grantRole(role: Int, account: Address)**
61+
- Grants a role to an account if the account does not already have it.
62+
- **Parameters**:
63+
- `role`: The identifier of the role to grant.
64+
- `account`: The account to which the role is granted.
65+
66+
- **_revokeRole(role: Int, account: Address)**
67+
- Revokes a role from an account if the account has the role.
68+
- **Parameters**:
69+
- `role`: The identifier of the role to revoke.
70+
- `account`: The account from which the role is revoked.
71+
72+
- **_checkRole(role: Int, account: Address)**
73+
- Checks if an account has a specific role and throws an error if it does not.
74+
- **Parameters**:
75+
- `role`: The identifier of the role.
76+
- `account`: The account to check.
77+
78+
- **_checkSenderRole(role: Int)**
79+
- Checks if the sender has a specific role and throws an error if they do not.
80+
- **Parameters**:
81+
- `role`: The identifier of the role.
82+
83+
- **renounceRole(role: Int, account: Address)**
84+
- Allows an account to renounce a role it has.
85+
- **Parameters**:
86+
- `role`: The identifier of the role to renounce.
87+
- `account`: The account renouncing the role.
88+
89+
- **revokeRole(role: Int, account: Address)**
90+
- Revokes a role from an account. Only callable by accounts with the admin role for the specified role.
91+
- **Parameters**:
92+
- `role`: The identifier of the role to revoke.
93+
- `account`: The account from which the role is revoked.
94+
95+
- **grantRole(role: Int, account: Address)**
96+
- Grants a role to an account. Only callable by accounts with the admin role for the specified role.
97+
- **Parameters**:
98+
- `role`: The identifier of the role to grant.
99+
- `account`: The account to which the role is granted.
100+
101+
- **hasRole(role: Int, account: Address) -> Bool**
102+
- Checks if an account has a specific role.
103+
- **Parameters**:
104+
- `role`: The identifier of the role to check.
105+
- `account`: The account to check.
106+
- **Returns**: `Bool` indicating if the account has the role.
107+
108+
- **getRoleAdmin(role: Int) -> Int**
109+
- Retrieves the admin role for a specific role.
110+
- **Parameters**:
111+
- `role`: The identifier of the role to check.
112+
- **Returns**: `Int` representing the admin role.
113+
114+
#### Receive Handlers
115+
116+
- **receive(msg: GrantRoleMessage)**
117+
- Handles messages to grant a role.
118+
- **Parameters**:
119+
- `msg`: The `GrantRoleMessage` containing the role and account.
120+
121+
- **receive(msg: RevokeRoleMessage)**
122+
- Handles messages to revoke a role.
123+
- **Parameters**:
124+
- `msg`: The `RevokeRoleMessage` containing the role and account.
125+
126+
- **receive(msg: RenounceRoleMessage)**
127+
- Handles messages to renounce a role.
128+
- **Parameters**:
129+
- `msg`: The `RenounceRoleMessage` containing the role and account.
130+
131+
### Usage Example
132+
133+
To use the `AccessControl` trait in your smart contract, follow these steps:
134+
135+
1. **Import the AccessControl Trait**:
136+
Ensure that the `AccessControl` trait is imported into your contract file.
137+
138+
```ts showLineNumbers
139+
import "../imports/tonion/access/AccessControl.tact";
140+
```
141+
142+
2. **Create Your Contract**:
143+
Extend your contract with the `AccessControl` trait. Implement the required methods and initialize the variables as needed.
144+
145+
```ts showLineNumbers
146+
import "../imports/tonion/access/AccessControl.tact";
147+
contract MyAccessControlContract with AccessControl {
148+
init() {
149+
// Initialize roles as needed
150+
self._initRole(self.ADMIN_ROLE);
151+
self._grantRole(self.ADMIN_ROLE, context().sender);
152+
}
153+
154+
receive("GrantRoleMessage") {
155+
let msg: GrantRoleMessage = context().getMessage();
156+
self.grantRole(msg.role, msg.account);
157+
}
158+
159+
receive("RevokeRoleMessage") {
160+
let msg: RevokeRoleMessage = context().getMessage();
161+
self.revokeRole(msg.role, msg.account);
162+
}
163+
164+
receive("RenounceRoleMessage") {
165+
let msg: RenounceRoleMessage = context().getMessage();
166+
self.renounceRole(msg.role, msg.account);
167+
}
168+
}
169+
```
170+
171+
In this example:
172+
173+
- The `MyAccessControlContract` contract uses the `AccessControl` trait to manage role-based access control.
174+
- The `init` method initializes the `ADMIN_ROLE` and grants it to the contract deployer.
175+
- The `receive` methods handle messages to grant, revoke, and renounce roles.
176+
177+
By following these steps, you can integrate and use the `AccessControl` trait in your smart contracts to manage roles and permissions effectively.

‎docs/3-Traits/2-AccessControl/2-OwnableTransferable2Step/index.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# OwnableTransferable2Step Trait
2+
3+
The `OwnableTransferable2Step` trait extends the `Ownable` contract by adding a two-step mechanism for transferring ownership. This process ensures that the new owner explicitly accepts the ownership transfer, reducing the risk of accidental ownership transfers.
4+
5+
#### Messages
6+
7+
- **ChangeOwner2Step**
8+
- **pendingOwner**: `Address`
9+
- Used to initiate the ownership transfer process by setting the pending owner.
10+
11+
- **ChangeOwner2StepOk**
12+
- **pendingOwner**: `Address`
13+
- Emitted as a response when the ownership transfer process is initiated.
14+
15+
- **AcceptOwnership2StepOk**
16+
- **newOwner**: `Address`
17+
- Emitted as a response when the new owner accepts the ownership transfer.
18+
19+
- **AcceptOwnership2Step**
20+
- Used by the pending owner to accept the ownership transfer.
21+
22+
#### Properties
23+
24+
- **owner**: `Address`
25+
- The current owner of the contract.
26+
27+
- **_pendingOwner**: `Address?`
28+
- The address of the pending owner who is set to accept ownership.
29+
30+
#### Methods
31+
32+
- **receive(msg: ChangeOwner2Step)**
33+
- Initiates the transfer of ownership to a new account.
34+
- **Parameters**:
35+
- `msg`: The `ChangeOwner2Step` message containing the `pendingOwner` address.
36+
- **Logic**:
37+
- Verifies that the sender is the current owner.
38+
- Sets the `_pendingOwner` to the new address.
39+
- Emits the `ChangeOwner2StepOk` event.
40+
41+
- **receive(msg: AcceptOwnership2Step)**
42+
- The new owner accepts the ownership transfer.
43+
- **Parameters**:
44+
- `msg`: The `AcceptOwnership2Step` message.
45+
- **Logic**:
46+
- Verifies that the sender is the `_pendingOwner`.
47+
- Transfers ownership to the sender.
48+
- Emits the `AcceptOwnership2StepOk` event.
49+
50+
- **_requirePendingOwner()**
51+
- Checks if the sender is the `_pendingOwner`.
52+
- **Logic**:
53+
- Throws an error if the sender is not the `_pendingOwner`.
54+
55+
- **_transferOwnership(newOwner: Address)**
56+
- Transfers ownership of the contract to a new account.
57+
- **Parameters**:
58+
- `newOwner`: The address of the new owner.
59+
- **Logic**:
60+
- Sets the `owner` to the new address.
61+
- Clears the `_pendingOwner`.
62+
63+
- **pendingOwner() -> Address?**
64+
- Returns the address of the pending owner.
65+
- **Returns**: `Address?` representing the pending owner.
66+
67+
#### Usage Example
68+
69+
To use the `OwnableTransferable2Step` trait in your smart contract, follow these steps:
70+
71+
1. **Import the OwnableTransferable2Step Trait**:
72+
Ensure that the `OwnableTransferable2Step` trait is imported into your contract file.
73+
74+
```ts showLineNumbers
75+
import "../imports/tonion/access/OwnableTransferable2Step.tact";
76+
```
77+
78+
2. **Create Your Contract**:
79+
Extend your contract with the `OwnableTransferable2Step` trait and implement the required methods.
80+
81+
```ts showLineNumbers
82+
import "../imports/tonion/access/OwnableTransferable2Step.tact";
83+
contract MyTransferableContract with OwnableTransferable2Step {
84+
init(owner: Address) {
85+
self.owner = owner;
86+
}
87+
}
88+
```
89+
90+
In this example:
91+
92+
- The `MyTransferableContract` contract uses the `OwnableTransferable2Step` trait to manage ownership transfer.
93+
- The `init` method sets the initial owner.
94+
95+
By following these steps, you can integrate and use the `OwnableTransferable2Step` trait in your smart contracts to manage ownership transfers effectively.

‎docs/3-Traits/2-AccessControl/index.md

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎docs/3-Traits/3-Utils/1-Counter/index.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Counter Trait
6+
7+
The `Counter` trait provides a simple counter mechanism that can only be incremented or decremented by one. This can be useful for tracking the number of elements in a mapping, issuing NFT IDs, counting request IDs, and more.
8+
9+
#### Properties
10+
11+
- **Counter**: `Int`
12+
- Represents the current count. This variable should not be accessed directly by users of the library; interactions should be restricted to the library's functions.
13+
- **Default Value**: `0`
14+
15+
#### Methods
16+
17+
- **current() -> Int**
18+
- A getter function that returns the current value of the counter.
19+
- **Returns**: `Int`
20+
- **Example**:
21+
```ts
22+
let currentValue = self.current();
23+
```
24+
25+
- **increment()**
26+
- Increments the counter value by one.
27+
- **Example**:
28+
```ts
29+
self.increment();
30+
```
31+
32+
- **decrement()**
33+
- Decrements the counter value by one.
34+
- **Example**:
35+
```ts
36+
self.decrement();
37+
```
38+
39+
### Usage Example
40+
41+
To use the `Counter` trait in your smart contract, follow these steps:
42+
43+
1. **Import the Counter Trait**:
44+
Ensure that the `Counter` trait is imported into your contract file.
45+
46+
```tact
47+
import "../imports/tonion/utils/Counter.tact";
48+
```
49+
50+
2. **Create Your Contract**:
51+
Extend your contract with the `Counter` trait. Implement the required methods and initialize the variables as needed.
52+
53+
```ts showLineNumbers
54+
import "../imports/tonion/utils/Counter.tact";
55+
contract MyCounterContract with Counter {
56+
// Initialize the Counter
57+
init() {
58+
self.Counter = 0;
59+
}
60+
61+
// Use the increment method
62+
receive("IncrementCounter") {
63+
self.increment();
64+
}
65+
66+
// Use the decrement method
67+
receive("DecrementCounter") {
68+
self.decrement();
69+
}
70+
71+
// Get the current counter value
72+
receive("GetCounter") {
73+
let currentValue: Int = self.current();
74+
// Send the current value back to the caller
75+
}
76+
}
77+
```
78+
79+
In this example:
80+
81+
- The `MyCounterContract` contract uses the `Counter` trait to manage a counter.
82+
- The `init` method initializes the counter to `0`.
83+
- The `receive` methods allow for incrementing, decrementing, and getting the current counter value through specific messages.
84+
- The `increment` and `decrement` methods are used to modify the counter value.
85+
- The `current` method is used to retrieve the current value of the counter.
86+
87+
By following these steps, you can integrate and use the `Counter` trait in your smart contracts to efficiently manage and track a simple counter.

‎docs/3-Traits/3-Utils/index.md

Lines changed: 0 additions & 5 deletions
This file was deleted.

0 commit comments

Comments
 (0)