docs: traits docs

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

@@ -0,0 +1,177 @@
+# AccessControl Trait
+
+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.
+
+#### Properties
+
+- **_roles**: `map<Int, RoleData>`
+  - A mapping from role identifiers to their corresponding `RoleData`.
+- **ADMIN_ROLE**: `Int`
+  - A constant representing the administrator role. This is used as the default admin role for all roles.
+
+#### Structs
+
+- **RoleData**
+  - **hasRole**: `map<Address, Bool>`
+    - A mapping indicating which accounts have this role.
+  - **adminRole**: `Int`
+    - The role that has administrative privileges over this role.
+
+#### Messages
+
+- **GrantRoleMessage**
+  - **role**: `Int`
+  - **account**: `Address`
+
+- **RevokeRoleMessage**
+  - **role**: `Int`
+  - **account**: `Address`
+
+- **RenounceRoleMessage**
+  - **role**: `Int`
+  - **account**: `Address`
+
+- **GrantRoleEvent**
+  - **role**: `Int`
+  - **account**: `Address`
+
+- **RevokeRoleEvent**
+  - **role**: `Int`
+  - **account**: `Address`
+
+- **RenounceRoleEvent**
+  - **role**: `Int`
+  - **account**: `Address`
+
+#### Methods
+
+- **_initRole(role: Int) -> Bool**
+  - Initializes a role with an empty set of members and sets the admin role to `ADMIN_ROLE` if the role does not already exist.
+  - **Parameters**: 
+    - `role`: The identifier of the role to initialize.
+  - **Returns**: `Bool` indicating if the role was initialized.
+
+- **_setRoleAdmin(role: Int, adminRole: Int)**
+  - Sets the admin role for a specific role.
+  - **Parameters**: 
+    - `role`: The identifier of the role.
+    - `adminRole`: The identifier of the admin role.
+
+- **_grantRole(role: Int, account: Address)**
+  - Grants a role to an account if the account does not already have it.
+  - **Parameters**: 
+    - `role`: The identifier of the role to grant.
+    - `account`: The account to which the role is granted.
+
+- **_revokeRole(role: Int, account: Address)**
+  - Revokes a role from an account if the account has the role.
+  - **Parameters**: 
+    - `role`: The identifier of the role to revoke.
+    - `account`: The account from which the role is revoked.
+
+- **_checkRole(role: Int, account: Address)**
+  - Checks if an account has a specific role and throws an error if it does not.
+  - **Parameters**: 
+    - `role`: The identifier of the role.
+    - `account`: The account to check.
+
+- **_checkSenderRole(role: Int)**
+  - Checks if the sender has a specific role and throws an error if they do not.
+  - **Parameters**: 
+    - `role`: The identifier of the role.
+
+- **renounceRole(role: Int, account: Address)**
+  - Allows an account to renounce a role it has.
+  - **Parameters**: 
+    - `role`: The identifier of the role to renounce.
+    - `account`: The account renouncing the role.
+
+- **revokeRole(role: Int, account: Address)**
+  - Revokes a role from an account. Only callable by accounts with the admin role for the specified role.
+  - **Parameters**: 
+    - `role`: The identifier of the role to revoke.
+    - `account`: The account from which the role is revoked.
+
+- **grantRole(role: Int, account: Address)**
+  - Grants a role to an account. Only callable by accounts with the admin role for the specified role.
+  - **Parameters**: 
+    - `role`: The identifier of the role to grant.
+    - `account`: The account to which the role is granted.
+
+- **hasRole(role: Int, account: Address) -> Bool**
+  - Checks if an account has a specific role.
+  - **Parameters**: 
+    - `role`: The identifier of the role to check.
+    - `account`: The account to check.
+  - **Returns**: `Bool` indicating if the account has the role.
+
+- **getRoleAdmin(role: Int) -> Int**
+  - Retrieves the admin role for a specific role.
+  - **Parameters**: 
+    - `role`: The identifier of the role to check.
+  - **Returns**: `Int` representing the admin role.
+
+#### Receive Handlers
+
+- **receive(msg: GrantRoleMessage)**
+  - Handles messages to grant a role.
+  - **Parameters**: 
+    - `msg`: The `GrantRoleMessage` containing the role and account.
+
+- **receive(msg: RevokeRoleMessage)**
+  - Handles messages to revoke a role.
+  - **Parameters**: 
+    - `msg`: The `RevokeRoleMessage` containing the role and account.
+
+- **receive(msg: RenounceRoleMessage)**
+  - Handles messages to renounce a role.
+  - **Parameters**: 
+    - `msg`: The `RenounceRoleMessage` containing the role and account.
+
+### Usage Example
+
+To use the `AccessControl` trait in your smart contract, follow these steps:
+
+1. **Import the AccessControl Trait**:
+   Ensure that the `AccessControl` trait is imported into your contract file.
+
+   ```ts showLineNumbers
+   import "../imports/tonion/access/AccessControl.tact";
+   ```
+
+2. **Create Your Contract**:
+   Extend your contract with the `AccessControl` trait. Implement the required methods and initialize the variables as needed.
+
+   ```ts showLineNumbers
+    import "../imports/tonion/access/AccessControl.tact";
+   contract MyAccessControlContract with AccessControl {
+       init() {
+           // Initialize roles as needed
+           self._initRole(self.ADMIN_ROLE);
+           self._grantRole(self.ADMIN_ROLE, context().sender);
+       }
+
+       receive("GrantRoleMessage") {
+           let msg: GrantRoleMessage = context().getMessage();
+           self.grantRole(msg.role, msg.account);
+       }
+
+       receive("RevokeRoleMessage") {
+           let msg: RevokeRoleMessage = context().getMessage();
+           self.revokeRole(msg.role, msg.account);
+       }
+
+       receive("RenounceRoleMessage") {
+           let msg: RenounceRoleMessage = context().getMessage();
+           self.renounceRole(msg.role, msg.account);
+       }
+   }
+   ```
+
+In this example:
+
+- The `MyAccessControlContract` contract uses the `AccessControl` trait to manage role-based access control.
+- The `init` method initializes the `ADMIN_ROLE` and grants it to the contract deployer.
+- The `receive` methods handle messages to grant, revoke, and renounce roles.
+
+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

@@ -0,0 +1,95 @@
+# OwnableTransferable2Step Trait
+
+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.
+
+#### Messages
+
+- **ChangeOwner2Step**
+  - **pendingOwner**: `Address`
+  - Used to initiate the ownership transfer process by setting the pending owner.
+
+- **ChangeOwner2StepOk**
+  - **pendingOwner**: `Address`
+  - Emitted as a response when the ownership transfer process is initiated.
+
+- **AcceptOwnership2StepOk**
+  - **newOwner**: `Address`
+  - Emitted as a response when the new owner accepts the ownership transfer.
+
+- **AcceptOwnership2Step**
+  - Used by the pending owner to accept the ownership transfer.
+
+#### Properties
+
+- **owner**: `Address`
+  - The current owner of the contract.
+
+- **_pendingOwner**: `Address?`
+  - The address of the pending owner who is set to accept ownership.
+
+#### Methods
+
+- **receive(msg: ChangeOwner2Step)**
+  - Initiates the transfer of ownership to a new account.
+  - **Parameters**: 
+    - `msg`: The `ChangeOwner2Step` message containing the `pendingOwner` address.
+  - **Logic**: 
+    - Verifies that the sender is the current owner.
+    - Sets the `_pendingOwner` to the new address.
+    - Emits the `ChangeOwner2StepOk` event.
+
+- **receive(msg: AcceptOwnership2Step)**
+  - The new owner accepts the ownership transfer.
+  - **Parameters**: 
+    - `msg`: The `AcceptOwnership2Step` message.
+  - **Logic**: 
+    - Verifies that the sender is the `_pendingOwner`.
+    - Transfers ownership to the sender.
+    - Emits the `AcceptOwnership2StepOk` event.
+
+- **_requirePendingOwner()**
+  - Checks if the sender is the `_pendingOwner`.
+  - **Logic**: 
+    - Throws an error if the sender is not the `_pendingOwner`.
+
+- **_transferOwnership(newOwner: Address)**
+  - Transfers ownership of the contract to a new account.
+  - **Parameters**: 
+    - `newOwner`: The address of the new owner.
+  - **Logic**: 
+    - Sets the `owner` to the new address.
+    - Clears the `_pendingOwner`.
+
+- **pendingOwner() -> Address?**
+  - Returns the address of the pending owner.
+  - **Returns**: `Address?` representing the pending owner.
+
+#### Usage Example
+
+To use the `OwnableTransferable2Step` trait in your smart contract, follow these steps:
+
+1. **Import the OwnableTransferable2Step Trait**:
+   Ensure that the `OwnableTransferable2Step` trait is imported into your contract file.
+
+   ```ts showLineNumbers
+   import "../imports/tonion/access/OwnableTransferable2Step.tact";
+   ```
+
+2. **Create Your Contract**:
+   Extend your contract with the `OwnableTransferable2Step` trait and implement the required methods.
+
+   ```ts showLineNumbers
+   import "../imports/tonion/access/OwnableTransferable2Step.tact";
+   contract MyTransferableContract with OwnableTransferable2Step {
+       init(owner: Address) {
+           self.owner = owner;
+       }
+   }
+   ```
+
+In this example:
+
+- The `MyTransferableContract` contract uses the `OwnableTransferable2Step` trait to manage ownership transfer.
+- The `init` method sets the initial owner.
+
+By following these steps, you can integrate and use the `OwnableTransferable2Step` trait in your smart contracts to manage ownership transfers effectively.

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

@@ -0,0 +1,87 @@
+---
+sidebar_position: 1
+---
+
+# Counter Trait
+
+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.
+
+#### Properties
+
+- **Counter**: `Int`
+  - 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.
+  - **Default Value**: `0`
+
+#### Methods
+
+- **current() -> Int**
+  - A getter function that returns the current value of the counter.
+  - **Returns**: `Int`
+  - **Example**:
+    ```ts
+    let currentValue = self.current();
+    ```
+
+- **increment()**
+  - Increments the counter value by one.
+  - **Example**:
+    ```ts
+    self.increment();
+    ```
+
+- **decrement()**
+  - Decrements the counter value by one.
+  - **Example**:
+    ```ts
+    self.decrement();
+    ```
+
+### Usage Example
+
+To use the `Counter` trait in your smart contract, follow these steps:
+
+1. **Import the Counter Trait**:
+   Ensure that the `Counter` trait is imported into your contract file.
+
+   ```tact
+   import "../imports/tonion/utils/Counter.tact";
+   ```
+
+2. **Create Your Contract**:
+   Extend your contract with the `Counter` trait. Implement the required methods and initialize the variables as needed.
+
+   ```ts showLineNumbers
+   import "../imports/tonion/utils/Counter.tact";
+   contract MyCounterContract with Counter {
+       // Initialize the Counter
+       init() {
+           self.Counter = 0;
+       }
+
+       // Use the increment method
+       receive("IncrementCounter") {
+           self.increment();
+       }
+
+       // Use the decrement method
+       receive("DecrementCounter") {
+           self.decrement();
+       }
+
+       // Get the current counter value
+       receive("GetCounter") {
+           let currentValue: Int = self.current();
+           // Send the current value back to the caller
+       }
+   }
+   ```
+
+In this example:
+
+- The `MyCounterContract` contract uses the `Counter` trait to manage a counter.
+- The `init` method initializes the counter to `0`.
+- The `receive` methods allow for incrementing, decrementing, and getting the current counter value through specific messages.
+- The `increment` and `decrement` methods are used to modify the counter value.
+- The `current` method is used to retrieve the current value of the counter.
+
+By following these steps, you can integrate and use the `Counter` trait in your smart contracts to efficiently manage and track a simple counter.