ManaSettlement.abi.json

Обзор

Файл ManaSettlement.abi.json содержит описание интерфейса смарт-контракта на языке ABI (Application Binary Interface) для Ethereum-подобных блокчейнов. Этот контракт отвечает за управление состояниями игроков в игровой экосистеме, связанной с токеном Mana. Он предоставляет функциональность для регистрации игроков, управления их игровыми профилями, балансами токенов, достижениями, а также реализует систему ролей и управления доступом. Контракт поддерживает как индивидуальные, так и пакетные обновления состояний игроков, что повышает эффективность работы с данными.

Структура и функциональность

Основные компоненты

PlayerProfile — структура, содержащая подробную информацию о профиле игрока: уровень, опыт, статистику по заработанному и потраченному Mana, время последнего действия, количество побед/поражений, рейтинг, количество созданных предметов и список достижений.
PlayerStateUpdate — структура, содержащая адрес игрока, новый баланс Mana и обновлённый профиль игрока.

Конструктор

constructor(_manaToken: address)

Описание: Инициализирует контракт, связывая его с определённым контрактом токена Mana.
Параметры:
- _manaToken — адрес контракта токена Mana.
Возвращаемое значение: отсутствует.
Пример использования:

ManaSettlement settlement = new ManaSettlement(manaTokenAddress);

Роли

Контракт использует систему ролей для разграничения доступа.

Функции:

DEFAULT_ADMIN_ROLE() -> bytes32
Возвращает идентификатор роли администратора по умолчанию.
GAME_MANAGER_ROLE() -> bytes32
Возвращает идентификатор роли менеджера игры.
PAUSER_ROLE() -> bytes32
Возвращает идентификатор роли, которая может приостанавливать работу контракта.
grantRole(role: bytes32, account: address)
Назначает роль role аккаунту account.
revokeRole(role: bytes32, account: address)
Отзывает роль у аккаунта.
renounceRole(role: bytes32, callerConfirmation: address)
Позволяет аккаунту отказаться от роли с подтверждением.
hasRole(role: bytes32, account: address) -> bool
Проверяет, имеет ли аккаунт определённую роль.
getRoleAdmin(role: bytes32) -> bytes32
Возвращает роль администратора для заданной роли.
initialize(defaultAdmin: address, gameManager: address)
Инициализирует роли администратора и менеджера игры.

Управление игроками

Регистрация и проверка

registerPlayer(player: address)
Регистрирует нового игрока в системе.
isPlayerRegistered(player: address) -> bool
Проверяет, зарегистрирован ли игрок.
registeredPlayers(address) -> bool
Маппинг, показывающий регистрацию игрока.
totalPlayers() -> uint256
Возвращает общее количество зарегистрированных игроков.

Профиль и состояние игрока

getPlayerProfile(player: address) -> PlayerProfile
Возвращает профиль игрока.
getPlayerManaBalances(player: address) -> (settlementBalance: uint256, tokenBalance: uint256)
Возвращает баланс Mana игрока в системе и на токене.
getPlayerAchievements(player: address) -> bytes32[]
Возвращает список достижений игрока.
getPlayerState(player: address) -> (manaBalance: uint256, profile: PlayerProfile, isRegistered: bool)
Возвращает полный статус игрока и информацию о регистрации.
getMultiplePlayerStates(players: address[]) -> PlayerStateUpdate[]
Возвращает состояния нескольких игроков за один вызов.

Обновление данных игроков

updatePlayerManaBalance(player: address, newBalance: uint256)
Обновляет баланс Mana игрока.
updatePlayerState(player: address, newManaBalance: uint256, newProfile: PlayerProfile)
Обновляет баланс и профиль игрока.
batchUpdatePlayerStates(updates: PlayerStateUpdate[])
Пакетное обновление состояний нескольких игроков. Увеличивает счётчик пакетов.
addPlayerAchievement(player: address, achievement: bytes32)
Добавляет достижение игроку.

Управление состоянием контракта

pause()
Приостанавливает работу контракта (только для роли Pauser).
unpause()
Возобновляет работу контракта.
paused() -> bool
Проверяет, приостановлен ли контракт.

Дополнительные функции

manaBalances(address) -> uint256
Маппинг балансов Mana игроков.
playerProfiles(address) -> PlayerProfile
Маппинг профилей игроков.
batchCounter() -> uint256
Счётчик пакетов обновлений состояний игроков.
manaToken() -> address
Возвращает адрес контракта токена Mana.
supportsInterface(interfaceId: bytes4) -> bool
Проверяет поддержку интерфейса (стандарт ERC165).
getTotalStats() -> (totalRegisteredPlayers: uint256, totalBatches: uint256)
Возвращает общую статистику по зарегистрированным игрокам и пакетам обновлений.

События

BatchPlayerStateUpdated(batchId, playersUpdated)
Срабатывает при пакетном обновлении состояний игроков.
ManaBalanceUpdated(player, oldBalance, newBalance)
Срабатывает при изменении баланса Mana игрока.
PlayerProfileUpdated(player, newProfile)
Срабатывает при обновлении профиля игрока.
PlayerStateUpdated(player, newManaBalance, newProfile)
Срабатывает при обновлении состояния игрока.
RoleAdminChanged(role, previousAdminRole, newAdminRole)
Событие изменения администратора роли.
RoleGranted(role, account, sender)
Срабатывает при назначении роли.
RoleRevoked(role, account, sender)
Срабатывает при отзыве роли.

Ошибки (Errors)

AccessControlBadConfirmation — ошибка неправильного подтверждения при отказе от роли.
AccessControlUnauthorizedAccount(account, neededRole) — аккаунт не имеет необходимой роли.
ContractPaused — операция невозможна, контракт приостановлен.
InvalidManaAmount — указан некорректный баланс Mana.
InvalidPlayerProfile — профиль игрока невалиден.
PlayerNotFound — игрок не найден.
ReentrantCall — обнаружен повторный вызов (защита от reentrancy).
UnauthorizedGameManager — неавторизованный менеджер игры.
ZeroAddress — передан нулевой адрес.

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

Контракт связывается с токеном Mana (контракт ManaToken), что позволяет синхронизировать балансы и транзакции.
Использует систему ролей для разграничения доступа и управления функциями.
Обеспечивает интерфейс для внешних систем (например, игровых серверов или UI) для получения и обновления данных игроков.
Поддерживает пакетные обновления для оптимизации массовых операций.

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

// Получить профиль игрока
(PlayerProfile profile) = manaSettlement.getPlayerProfile(playerAddress);

// Обновить профиль и баланс игрока
manaSettlement.updatePlayerState(
    playerAddress,
    newManaBalance,
    PlayerProfile({
        level: 10,
        experience: 1500,
        totalManaEarned: 5000,
        totalManaSpent: 3000,
        lastActionTimestamp: block.timestamp,
        wins: 20,
        losses: 5,
        rating: 1200,
        itemsCrafted: 15,
        achievements: [achievement1, achievement2]
    })
);

// Добавить достижение игроку
manaSettlement.addPlayerAchievement(playerAddress, newAchievement);

Mermaid диаграмма структуры

classDiagram
    class ManaSettlement {
        +constructor(_manaToken: address)
        +DEFAULT_ADMIN_ROLE() bytes32
        +GAME_MANAGER_ROLE() bytes32
        +PAUSER_ROLE() bytes32
        +initialize(defaultAdmin: address, gameManager: address)
        +registerPlayer(player: address)
        +isPlayerRegistered(player: address) bool
        +getPlayerProfile(player: address) PlayerProfile
        +getPlayerManaBalances(player: address) (uint256, uint256)
        +getPlayerAchievements(player: address) bytes32[]
        +getPlayerState(player: address) (uint256, PlayerProfile, bool)
        +getMultiplePlayerStates(players: address[]) PlayerStateUpdate[]
        +updatePlayerManaBalance(player: address, newBalance: uint256)
        +updatePlayerState(player: address, newManaBalance: uint256, newProfile: PlayerProfile)
        +batchUpdatePlayerStates(updates: PlayerStateUpdate[])
        +addPlayerAchievement(player: address, achievement: bytes32)
        +pause()
        +unpause()
        +paused() bool
        +grantRole(role: bytes32, account: address)
        +revokeRole(role: bytes32, account: address)
        +renounceRole(role: bytes32, callerConfirmation: address)
        +hasRole(role: bytes32, account: address) bool
        +getRoleAdmin(role: bytes32) bytes32
        +supportsInterface(interfaceId: bytes4) bool
        +getTotalStats() (uint256, uint256)
    }

    class PlayerProfile {
        +level: uint256
        +experience: uint256
        +totalManaEarned: uint256
        +totalManaSpent: uint256
        +lastActionTimestamp: uint256
        +wins: uint256
        +losses: uint256
        +rating: uint256
        +itemsCrafted: uint256
        +achievements: bytes32[]
    }

    class PlayerStateUpdate {
        +player: address
        +newManaBalance: uint256
        +newProfile: PlayerProfile
    }

    ManaSettlement "1" o-- "*" PlayerStateUpdate : batchUpdatePlayerStates
    PlayerStateUpdate "1" *-- "1" PlayerProfile : contains

Итог

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