ManaToken.abi.json

Обзор

Файл ManaToken.abi.json содержит ABI (Application Binary Interface) для смарт-контракта ERC-20 токена с расширенными возможностями управления ролями и функционалом паузы. Данный контракт реализует стандартные функции ERC-20 (балансы, переводы, утверждения), а также расширяет их с помощью ролей доступа (администратор, менеджер игры, паузер, менеджер стейкинга) и механизмов паузы и разморозки токена. Кроме того, контракт поддерживает функции сжигания (burn) и выпуска новых токенов (mint), с контролем доступа и проверками ошибок.

Контракт предназначен для использования в игровой или финансовой экосистеме, где требуется гибкое управление токенами, их эмиссия и уничтожение, а также контроль за правами на выполнение определенных действий.

Подробное описание функций и методов

Конструктор

• constructor(initialOwner: address)

  • Инициализация контракта с указанием начального владельца (initialOwner), который получает административные права.

  • initialOwner — адрес владельца, которому будут назначены роли по умолчанию.

Публичные константы и геттеры ролей

• DEFAULT_ADMIN_ROLE() → bytes32

  • Возвращает значение роли администратора по умолчанию.

  • Используется для управления ролями в контракте.

• GAME_MANAGER_ROLE() → bytes32

  • Возвращает значение роли менеджера игры.

  • Роль для управления игровыми функциями, например, выпуска и сжигания токенов.

• PAUSER_ROLE() → bytes32

  • Возвращает значение роли, разрешающей приостанавливать (пауза) и возобновлять контракт.

• STAKING_MANAGER_ROLE() → bytes32

  • Роль для управления стейкингом токенов.

• INITIAL_SUPPLY() → uint256

  • Количество токенов, выпущенных при развертывании контракта.

Стандартные функции ERC-20

• name() → string

  • Имя токена (например, "Mana Token").

• symbol() → string

  • Символ токена (например, "MANA").

• decimals() → uint8

  • Количество десятичных знаков для токена (обычно 18).

• totalSupply() → uint256

  • Общее количество выпущенных токенов.

• balanceOf(account: address) → uint256

  • Баланс токенов у указанного адреса.

• allowance(owner: address, spender: address) → uint256

  • Количество токенов, которое spender может потратить от имени owner.

• approve(spender: address, value: uint256) → bool

  • Разрешить spender расходовать указанное количество токенов от имени вызывающего.

• transfer(to: address, value: uint256) → bool

  • Перевод value токенов на адрес to от вызывающего.

• transferFrom(from: address, to: address, value: uint256) → bool

  • Перевод value токенов с адреса from на адрес to, используя утвержденный лимит.

Управление ролями (AccessControl)

• getRoleAdmin(role: bytes32) → bytes32

  • Возвращает роль администратора для указанной роли.

• grantRole(role: bytes32, account: address)

  • Назначить указанную роль role аккаунту account.

  • Требует прав администратора для данной роли.

• revokeRole(role: bytes32, account: address)

  • Отозвать роль role у аккаунта account.

• renounceRole(role: bytes32, callerConfirmation: address)

  • Аккаунт отказывается от роли role.

  • Требуется подтверждение вызова вызывающего адреса.

• hasRole(role: bytes32, account: address) → bool

  • Проверяет, принадлежит ли аккаунту account роль role.

Функции паузы и безопасности

• pause()

  • Активирует паузу, приостанавливая трансферы и другие действия.

  • Доступно для роли PAUSER_ROLE.

• unpause()

  • Снимает паузу и возобновляет работу контракта.

• paused() → bool

  • Проверяет, находится ли контракт в состоянии паузы.

Эмиссия и сжигание токенов

• mint(to: address, amount: uint256)

  • Выпускает новые токены в количестве amount на адрес to.

  • Доступно для роли с возможностью минтинга (например, GAME_MANAGER_ROLE или STAKING_MANAGER_ROLE).

  • Генерирует событие TokensMinted.

• burn(from: address, amount: uint256)

  • Сжигает amount токенов с адреса from.

  • Требует соответствующих прав.

  • Генерирует событие TokensBurned.

• burnSelf(amount: uint256)

  • Сжигает токены с баланса вызывающего.

Поддержка интерфейсов

• supportsInterface(interfaceId: bytes4) → bool

  • Проверяет, поддерживается ли интерфейс с данным идентификатором.

События

• Approval(owner, spender, value)

  • Уведомляет об утверждении spender расходовать value токенов от имени owner.

• Transfer(from, to, value)

  • Уведомляет о переводе токенов.

• Paused(account)

  • Контракт был приостановлен пользователем account.

• Unpaused(account)

  • Контракт был возобновлен пользователем account.

• RoleAdminChanged(role, previousAdminRole, newAdminRole)

  • Смена администратора роли.

• RoleGranted(role, account, sender)

  • Назначение роли.

• RoleRevoked(role, account, sender)

  • Отзыв роли.

• TokensMinted(to, amount, minter)

  • Выпуск новых токенов.

• TokensBurned(from, amount, burner)

  • Сжигание токенов.

Ошибки (Errors)

Контракт определяет набор ошибок для обработки различных исключений и ошибок доступа:

• AccessControlBadConfirmation — подтверждение вызова некорректно.

• AccessControlUnauthorizedAccount(account, neededRole) — аккаунт не обладает необходимой ролью.

• ERC20InsufficientAllowance(spender, allowance, needed) — недостаточно разрешенных токенов.

• ERC20InsufficientBalance(sender, balance, needed) — недостаточно токенов на балансе.

• ERC20InvalidApprover(approver) — неверный адрес утверждающего.

• ERC20InvalidReceiver(receiver) — неверный адрес получателя.

• ERC20InvalidSender(sender) — неверный адрес отправителя.

• ERC20InvalidSpender(spender) — неверный адрес расходующего.

• EnforcedPause — операция невозможна при активной паузе.

• ExpectedPause — операция требует нахождения в паузе.

• InsufficientBalance — недостаточный баланс для операции.

• UnauthorizedBurner — отсутствие прав на сжигание токенов.

• UnauthorizedMinter — отсутствие прав на выпуск токенов.

• ZeroAddress — использование нулевого адреса запрещено.

• ZeroAmount — использование нулевого количества токенов запрещено.

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

• Контракт ManaToken взаимодействует с другими смарт-контрактами и системами, реализующими игровые механики или стейкинг, через назначение ролей GAME_MANAGER_ROLE и STAKING_MANAGER_ROLE.

• Использование ролей безопасности обеспечивает распределение прав и предотвращает несанкционированные операции.

• Функции паузы позволяют временно приостанавливать работу токена в случае выявления уязвимостей или необходимости проведения обновлений.

• События обеспечивают прозрачность транзакций и позволяют отслеживать изменения состояния токена внешними сервисами.

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

// Получение баланса пользователя
const balance = await manaToken.methods.balanceOf(userAddress).call();

// Передача токенов другому пользователю
const tx = await manaToken.methods.transfer(recipientAddress, amount).send({from: senderAddress});

// Назначение роли менеджера игры новому аккаунту (только для администратора)
await manaToken.methods.grantRole(manaToken.methods.GAME_MANAGER_ROLE().call(), newManager).send({from: adminAddress});

// Приостановка работы токена (только для паузера)
await manaToken.methods.pause().send({from: pauserAddress});

Визуальное представление структуры (Mermaid диаграмма)

classDiagram
    class ManaToken {
        <<contract>>
        +constructor(initialOwner: address)
        +DEFAULT_ADMIN_ROLE(): bytes32
        +GAME_MANAGER_ROLE(): bytes32
        +PAUSER_ROLE(): bytes32
        +STAKING_MANAGER_ROLE(): bytes32
        +INITIAL_SUPPLY(): uint256
        +name(): string
        +symbol(): string
        +decimals(): uint8
        +totalSupply(): uint256
        +balanceOf(account: address): uint256
        +allowance(owner: address, spender: address): uint256
        +approve(spender: address, value: uint256): bool
        +transfer(to: address, value: uint256): bool
        +transferFrom(from: address, to: address, value: uint256): bool
        +mint(to: address, amount: uint256)
        +burn(from: address, amount: uint256)
        +burnSelf(amount: uint256)
        +pause()
        +unpause()
        +paused(): bool
        +getRoleAdmin(role: bytes32): bytes32
        +grantRole(role: bytes32, account: address)
        +revokeRole(role: bytes32, account: address)
        +renounceRole(role: bytes32, callerConfirmation: address)
        +hasRole(role: bytes32, account: address): bool
        +supportsInterface(interfaceId: bytes4): bool
    }

Заключение

Файл ManaToken.abi.json описывает полнофункциональный смарт-контракт ERC-20 токена с расширенными возможностями управления ролями, контроля доступа, паузы и управления эмиссией токенов. Данный контракт подходит для использования в игровых и финансовых приложениях, требующих гибкой и безопасной работы с токенами на блокчейне.