GameManager.abi.json

Обзор

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

Основная задача контракта — централизованное хранение и обновление состояния игроков, обработка игровых действий и распределение вознаграждений для валидаторов, участвующих в проверке и подтверждении игровых батчей.

Основные сущности и структуры

Структуры данных

• PlayerState — состояние игрока. Содержит адрес игрока, баланс маны, уровень, опыт, статистику PvP, количество созданных предметов и другие параметры.

• ValidatorInfo — информация о валидаторе: адрес, ставка, заработанные вознаграждения, активность и количество участий.

• BatchResult — результат обработки батча игровых действий, включает идентификатор батча, обновлённые состояния игроков и временную метку обработки.

• GameAction — описание игрового действия: игрок, тип действия, параметры, затраты маны, nonce и время создания.

• EconomicConfig — параметры экономики игры: комиссии, лимиты, длительность эпохи и бюджет вознаграждений.

Перечисления (enums)

• ActionType — типы игровых действий (крафтинг, PvP, трейды и др.).

• ActionStatus — статус действия (например, ожидает обработки, обработано, просрочено).

Конструктор

constructor(address _settlement, address _manaToken, address _admin)

• _settlement — адрес контракта расчётов (ISettlement).

• _manaToken — адрес токена маны (ManaToken).

• _admin — адрес администратора с правами по умолчанию.

Инициализирует контракт с ключевыми адресами и устанавливает роли доступа.

Основные функции

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

• grantRole(bytes32 role, address account) — предоставить роль аккаунту.

• revokeRole(bytes32 role, address account) — отозвать роль.

• renounceRole(bytes32 role, address callerConfirmation) — добровольно отказаться от роли с подтверждением.

• hasRole(bytes32 role, address account) returns (bool) — проверить, есть ли у аккаунта роль.

• getRoleAdmin(bytes32 role) returns (bytes32) — получить администратора роли.

Игровые действия

• submitGameAction(ActionType actionType, bytes actionParams, uint256 manaAmount) returns (bytes32 actionId)
  Отправить новое игровое действие в цепочку. Возвращает уникальный идентификатор действия.

• submitCrossChainGameAction(ActionType actionType, bytes actionParams, uint256 manaAmount, uint64 targetChain) returns (bytes32 actionId)
  Отправить действие для выполнения на другом блокчейне (кросс-чейн).

• getActionStatus(bytes32 actionId) returns (ActionStatus) — получить статус действия по его ID.

• gameActions(bytes32) returns (GameAction) — получить детали действия.

• processedActions(bytes32) returns (bool) — проверить, было ли действие уже обработано.

Обработка батчей действий

• processBatch(bytes32 batchId, BatchResult result, uint48 epoch, bytes proof)
  Обработать батч игровых действий, обновить состояние игроков, проверить достоверность подписи.

• processCrossChainBatch(bytes32 batchId, BatchResult result, uint64 sourceChain, uint48 epoch, bytes proof)
  Обработать батч с другого блокчейна.

Состояние игроков и статистика

• getPlayerState(address player) returns (PlayerState state) — получить полное состояние игрока.

• playerStates(address) returns (PlayerState) — текущее состояние игрока в карте.

• getLevelProgressInfo(address player) returns (...) — получить прогресс игрока по уровню и опыту.

• getCraftingStats(address player) returns (...) — статистика крафтинга игрока.

• getMarketplaceStats(address player) returns (...) — статистика торгов на маркетплейсе.

• getPvPStats(address player) returns (...) — PvP статистика игрока.

• getProgressionStats(address player) returns (...) — сводная статистика по прогрессу игрока.

• getPlayerManaBalance(address player) returns (uint256) — баланс маны игрока.

• getCrossChainManaBalance(address player, uint64 targetChain) returns (uint256) — баланс маны игрока на другом блокчейне.

Валидация и проверка параметров действий

• validateCraftingParams(bytes actionParams, address player) returns (bool)
  Проверка корректности параметров крафтинга.

• validateLevelUpParams(bytes actionParams, address player) returns (bool)
  Проверка параметров повышения уровня.

• validateMarketplaceTrade(bytes actionParams, address player, uint256 tradeAmount) returns (bool)
  Проверка параметров торговой сделки.

• validateMarketplaceTradeParams(bytes actionParams, address player) returns (bool)
  Проверка параметров торговой операции (без суммы).

• validatePvPBattleParams(bytes actionParams, address player) returns (bool)
  Проверка параметров PvP боя.

• validateCrossChainAction(ActionType actionType, bytes actionParams, uint64 targetChain, address player) returns (bool)
  Проверка кросс-чейн действия.

Расчёты стоимости и опыта

• calculateCraftingCost(uint256 recipeId, uint256 quantity, uint256 playerLevel) returns (uint256 cost)
  Рассчитать стоимость крафта с учётом уровня.

• calculateLevelBasedCost(uint256 baseCost, uint256 playerLevel, ActionType actionType) returns (uint256 scaledCost)
  Масштабировать стоимость действия в зависимости от уровня игрока.

• calculateLevelUpCost(uint256 currentLevel) returns (uint256 cost) — стоимость повышения уровня.

• calculateMarketplaceCost(uint256 tradeAmount, uint8 tradeType, uint256 playerLevel) returns (uint256 cost)
  Стоимость торговой сделки.

• calculatePvPCost(uint8 battleType) returns (uint256 cost) — стоимость PvP боя.

• calculateExperienceForLevel(uint256 level) returns (uint256 experience) — опыт, необходимый для данного уровня.

• calculateExpectedValidatorReward(address validator) returns (uint256 expectedReward) — ожидаемое вознаграждение валидатора.

Управление валидаторами

• registerValidator(address validator, uint256 stakeAmount) — зарегистрировать валидатора с указанной ставкой.

• deregisterValidator(address validator) — удалить валидатора.

• getValidatorInfo(address validator) returns (ValidatorInfo info) — получить информацию о валидаторе.

• getValidatorStats(address validator) returns (...) — статистика валидатора.

• getActiveValidators() returns (address[] validatorList) — получить список активных валидаторов.

• validatorIndex(address) returns (uint256) — индекс валидатора в массиве.

• activeValidators(uint256) returns (address) — валидатор по индексу.

• validators(address) returns (ValidatorInfo) — данные валидатора.

Управление экономикой и фондами

• economicConfig() returns (EconomicConfig) — текущая конфигурация экономики.

• getEconomicConfig() returns (EconomicConfig) — получить параметры экономики.

• updateEconomicConfig(EconomicConfig newConfig) — обновить экономические параметры (только для ролей с правами).

• emergencyFundRewardPool(uint256 amount) — пополнить фонд вознаграждений в экстренном режиме.

• validatorRewardPool() returns (uint256) — текущий баланс фонда для вознаграждений валидаторов.

• lastRewardDistribution() returns (uint256) — время последнего распределения вознаграждений.

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

• pause() — приостановить работу контракта (только для ролей с правами PAUSER_ROLE).

• unpause() — снять приостановку.

• paused() returns (bool) — проверить, приостановлен ли контракт.

• supportsInterface(bytes4 interfaceId) returns (bool) — поддержка интерфейсов (ERC165).

Кросс-чейн синхронизация состояния

• synchronizePlayerState(address player, PlayerState newState, uint64 sourceChain, bytes proof)
  Синхронизировать состояние игрока из другого блокчейна с проверкой доказательства.

• emergencyUpdatePlayerState(address player, PlayerState newState)
  Экстренное обновление состояния игрока (только для ролей с правами EMERGENCY_ROLE).

Взаимодействия с внешними контрактами

• settlement() returns (ISettlement) — адрес контракта расчётов.

• manaToken() returns (ManaToken) — адрес контракта токена маны.

Ошибки (Errors)

• AccessControlBadConfirmation — ошибка подтверждения роли.

• AccessControlUnauthorizedAccount(address account, bytes32 neededRole) — попытка выполнить действие без нужной роли.

• ActionExpired — действие устарело.

• ActionNotFound — действие не найдено.

• AlreadyProcessed — действие уже обработано.

• EnforcedPause — контракт приостановлен.

• ExpectedPause — ожидалась приостановка.

• InsufficientManaBalance — недостаточно маны.

• InsufficientValidatorRewards — недостаточно вознаграждений для валидатора.

• InvalidActionParams — неверные параметры действия.

• InvalidActionType — неверный тип действия.

• InvalidEconomicParameter — неверный экономический параметр.

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

• InvalidVerifyingEpoch — неверная эпоха верификации.

• ReentrancyGuardReentrantCall — повторный вызов (reentrancy).

• ValidatorNotFound — валидатор не найден.

• ZeroAddress — передан нулевой адрес.

• ZeroAmount — передано нулевое значение.

События (Events)

• GameActionSubmitted — новое игровое действие отправлено.

• CrossChainGameActionSubmitted — кросс-чейн действие отправлено.

• BatchProcessed — батч игровых действий обработан.

• CrossChainBatchProcessed — кросс-чейн батч обработан.

• PlayerStateUpdated — обновлено состояние игрока.

• CrossChainPlayerStateSynchronized — синхронизация состояния игрока с другого блокчейна.

• PvPBattleInitiated — инициировано PvP сражение.

• PvPBattleCompleted — завершено PvP сражение.

• RoleGranted — роль предоставлена.

• RoleRevoked — роль отозвана.

• RoleAdminChanged — изменён администратор роли.

• Paused / Unpaused — контракт приостановлен / возобновлён.

• ManaTokensMinted / ManaTokensBurned — манатокены созданы / сожжены.

• ValidatorRegistered / ValidatorDeregistered — валидатор зарегистрирован / удалён.

• ValidatorRewardDistributed — вознаграждение валидатору выплачено.

• ValidatorCommissionPaid — выплата комиссии валидатору.

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

• Контракт взаимодействует с контрактом токена маны (manaToken), который управляет балансами и трансферами манатокенов.

• Контракт settlement отвечает за расчёты и может использоваться для урегулирования торговых операций.

• Валидаторы — внешние участники системы, которые регистрируются, ставят залог и получают вознаграждения за проверку батчей.

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

• Ролевая система обеспечивает безопасное управление доступом к критичным функциям контракта.

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

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

• Валидация действий и параметров происходит до их обработки, что предотвращает неверные или мошеннические операции.

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

• Система уровней и опыта основана на вычислении необходимого опыта для каждого уровня (calculateExperienceForLevel) и масштабировании стоимости действий в зависимости от уровня игрока.

• Реализована система ролей и прав доступа с использованием стандартных подходов Access Control.

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

• Кросс-чейн взаимодействия используют доказательства (proof), обеспечивающие безопасность и целостность синхронизации.

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

Отправка игрового действия

bytes32 actionId = gameManager.submitGameAction(
    GameManager.ActionType.CRAFT, 
    abi.encode(recipeId, quantity), 
    manaCost
);

Получение состояния игрока

GameManager.PlayerState memory state = gameManager.getPlayerState(playerAddress);
uint256 currentLevel = state.level;
uint256 manaBalance = state.manaBalance;

Регистрация валидатора

gameManager.registerValidator(validatorAddress, stakeAmount);

Обработка батча действий (вызывается валидаторами)

gameManager.processBatch(batchId, batchResult, currentEpoch, quorumProof);

Диаграмма структуры (Mermaid classDiagram)

classDiagram
    class GameManager {
        +constructor(address _settlement, address _manaToken, address _admin)
        +submitGameAction(ActionType actionType, bytes actionParams, uint256 manaAmount) returns (bytes32)
        +submitCrossChainGameAction(ActionType actionType, bytes actionParams, uint256 manaAmount, uint64 targetChain) returns (bytes32)
        +processBatch(bytes32 batchId, BatchResult result, uint48 epoch, bytes proof)
        +processCrossChainBatch(bytes32 batchId, BatchResult result, uint64 sourceChain, uint48 epoch, bytes proof)
        +getPlayerState(address player) returns (PlayerState)
        +registerValidator(address validator, uint256 stakeAmount)
        +deregisterValidator(address validator)
        +getValidatorInfo(address validator) returns (ValidatorInfo)
        +distributeEpochRewards()
        +pause()
        +unpause()
        +updateEconomicConfig(EconomicConfig newConfig)
        +calculateCraftingCost(uint256 recipeId, uint256 quantity, uint256 playerLevel) returns (uint256)
        +calculateLevelUpCost(uint256 currentLevel) returns (uint256)
        +validateCraftingParams(bytes actionParams, address player) returns (bool)
        +validateMarketplaceTrade(bytes actionParams, address player, uint256 tradeAmount) returns (bool)
        +hasRole(bytes32 role, address account) returns (bool)
        +grantRole(bytes32 role, address account)
        +revokeRole(bytes32 role, address account)
        +paused() returns (bool)
        +manaToken() returns (address)
        +settlement() returns (address)
    }

    class PlayerState {
        +address player
        +uint256 manaBalance
        +uint256 level
        +uint256 experience
        +uint256 lastActionTimestamp
        +uint256 wins
        +uint256 losses
        +uint256 rating
        +uint256 totalManaEarned
        +uint256 totalManaSpent
        +uint256 itemsCrafted
    }

    class ValidatorInfo {
        +address validator
        +uint256 stakedAmount
        +uint256 totalRewardsEarned
        +uint256 lastRewardEpoch
        +uint256 participationCount
        +bool isActive
    }

    class BatchResult {
        +bytes32 batchId
        +PlayerState[] newStates
        +uint48 processedAt
    }

    GameManager --> PlayerState : uses
    GameManager --> ValidatorInfo : uses
    GameManager --> BatchResult : uses

Заключение

GameManager.abi.json представляет собой ABI контракта, который является ядром логики многопользовательской блокчейн-игры. Контракт управляет состоянием игроков, экономикой, игровыми действиями, а также взаимодействует с валидаторами и кросс-чейн механизмами. Он обеспечивает безопасность и масштабируемость игрового процесса, используя ролевую модель доступа, батчи для обработки действий и комплексные проверки параметров.