ManaToken.sol

Обзор

Файл ManaToken.sol содержит реализацию смарт-контракта MANA — ERC20 токена, используемого в качестве игровой валюты и токена для стейкинга валидаторов. Контракт базируется на стандарте ERC20 с добавлением ролевого контроля доступа (AccessControl) и возможности приостанавливать операции с токенами (Pausable). Основная функциональность включает выпуск (mint), сжигание (burn) токенов с контролем прав доступа, а также управление ролями и паузой для повышения безопасности.

Описание классов и методов

Контракт ManaToken

Наследуется от:

ERC20 — стандартный интерфейс токена ERC20.
AccessControl — управление ролями и правами доступа.
Pausable — механизм приостановки операций с токеном.

Константы

Имя	Тип	Описание
`GAME_MANAGER_ROLE`	`bytes32`	Роль менеджера игровой логики (для mint и burn)
`STAKING_MANAGER_ROLE`	`bytes32`	Роль менеджера стейкинга (для mint и burn)
`PAUSER_ROLE`	`bytes32`	Роль, позволяющая ставить контракт на паузу и снимать с паузы
`INITIAL_SUPPLY`	`uint256`	Начальное количество токенов для выпуска — 1 миллион MANA (в 18 десятичных знаках)

Пользовательские ошибки (Custom Errors)

Для оптимизации газа используются следующие кастомные ошибки:

UnauthorizedMinter() — вызывается при попытке mint без соответствующей роли.
UnauthorizedBurner() — вызывается при попытке burn без соответствующей роли.
ZeroAddress() — передан нулевой адрес.
ZeroAmount() — передано количество токенов равное 0.
InsufficientBalance() — недостаточно токенов для burn.

События

TokensMinted(address indexed to, uint256 amount, address indexed minter) — эмитируется при выпуске токенов.
TokensBurned(address indexed from, uint256 amount, address indexed burner) — эмитируется при сжигании токенов.

Конструктор

constructor(address initialOwner)

Параметры:
- initialOwner — адрес, которому будут выданы все права администратора и который получит начальный выпуск токенов.
Логика:
- Проверяет, что initialOwner не нулевой адрес.
- Выдаёт DEFAULT_ADMIN_ROLE и PAUSER_ROLE этому адресу.
- Выпускает начальный запас токенов INITIAL_SUPPLY на адрес initialOwner.

Функции

mint

function mint(address to, uint256 amount) external whenNotPaused

Назначение: Выпускает новые токены на указанный адрес.
Параметры:
- to — адрес получателя.
- amount — количество токенов для выпуска.
Требования:
- Адрес to не должен быть нулевым.
- Количество amount должно быть больше 0.
- Вызвать функцию могут только адреса с ролями GAME_MANAGER_ROLE или STAKING_MANAGER_ROLE.
- Контракт не должен быть на паузе.
Возвращаемое значение: отсутствует.

Пример использования:

manaToken.mint(playerAddress, 1000 * 10**18);

burn

function burn(address from, uint256 amount) external whenNotPaused

Назначение: Сжигает токены с указанного адреса.
Параметры:
- from — адрес, с которого списываются токены.
- amount — количество токенов для сжигания.
Требования:
- Адрес from не нулевой.
- Количество amount > 0.
- Вызвать функцию могут только с ролями GAME_MANAGER_ROLE или STAKING_MANAGER_ROLE.
- Баланс from должен быть не меньше amount.
- Контракт не на паузе.
Возвращаемое значение: отсутствует.

Пример использования:

manaToken.burn(userAddress, 500 * 10**18);

burnSelf

function burnSelf(uint256 amount) external whenNotPaused

Назначение: Позволяет вызывающему сжечь свои собственные токены.
Параметры:
- amount — количество токенов для сжигания.
Требования:
- amount > 0.
- Баланс вызывающего ≥ amount.
- Контракт не на паузе.
Возвращаемое значение: отсутствует.
Пример использования:
```
manaToken.burnSelf(100 * 10**18);
```

pause

function pause() external onlyRole(PAUSER_ROLE)

Назначение: Приостанавливает все трансферы и операции с токеном.
Требования: Вызвать функцию может только адрес с ролью PAUSER_ROLE.
Пример использования:
```
manaToken.pause();
```

unpause

function unpause() external onlyRole(PAUSER_ROLE)

Назначение: Снимает паузу, позволяя снова выполнять операции с токенами.
Требования: Вызвать функцию может только адрес с ролью PAUSER_ROLE.
Пример использования:
```
manaToken.unpause();
```

_update (переопределение)

function _update(address from, address to, uint256 value) internal override whenNotPaused

Назначение: Внутренний метод, вызываемый при трансферах токенов.
Особенности: Добавлена проверка, что контракт не на паузе.
Примечание: Переопределяет метод из ERC20 для интеграции с механизмом паузы.

decimals

function decimals() public pure override returns (uint8)

Возвращает: число десятичных знаков — 18 (стандарт для ERC20).

supportsInterface

function supportsInterface(bytes4 interfaceId) public view override returns (bool)

Назначение: Проверяет поддержку интерфейса (для AccessControl).
Возвращает: true, если интерфейс поддерживается.

Важные детали реализации

Использование кастомных ошибок вместо require с текстом для оптимизации газа.
Ролевой доступ для операций mint и burn, что обеспечивает безопасность и разграничение полномочий.
Возможность приостановки всех операций с токеном через pause/unpause для экстренной защиты.
Начальное распределение токенов осуществляется в конструкторе на адрес администратора.
Токен имеет 18 десятичных знаков, как и большинство ERC20 токенов.
Механизм сжигания реализован как через специальные роли, так и через возможность самостоятельного сжигания вызвавшим контракт лицом.

Взаимодействие с другими частями системы

Контракт предполагает наличие внешних менеджеров:
- Game Manager — контракт, управляющий игровой логикой и имеющий права mint/burn.
- Staking Manager — контракт, управляющий стейкингом валидаторов, также с правами mint/burn.
Роли назначаются через AccessControl, что позволяет гибко управлять правами в системе.
Контракт может взаимодействовать с другими компонентами, которые подписаны под соответствующие роли, для обеспечения корректного выпуска и сжигания токенов.
Использование OpenZeppelin библиотек гарантирует надежность и совместимость с Ethereum-экосистемой.

Диаграмма структуры контракта

classDiagram
    class ManaToken {
        +bytes32 GAME_MANAGER_ROLE
        +bytes32 STAKING_MANAGER_ROLE
        +bytes32 PAUSER_ROLE
        +uint256 INITIAL_SUPPLY
        +constructor(address initialOwner)
        +mint(address to, uint256 amount)
        +burn(address from, uint256 amount)
        +burnSelf(uint256 amount)
        +pause()
        +unpause()
        +decimals() uint8
        +supportsInterface(bytes4 interfaceId) bool
        -_update(address from, address to, uint256 value)
    }
    ManaToken ..|> ERC20
    ManaToken ..|> AccessControl
    ManaToken ..|> Pausable

Резюме

Контракт ManaToken.sol представляет собой надежный и расширяемый ERC20 токен с поддержкой ролевого контроля и механизмом паузы, предназначенный для использования в игровой экосистеме и системе стейкинга. Его архитектура обеспечивает безопасность операций с токеном, гибкость в управлении правами и интеграцию с другими смарт-контрактами системы.