SymbioticDVN.sol

Обзор

Контракт SymbioticDVN реализует децентрализованную сеть верификаторов (Decentralized Verifier Network, DVN), обеспечивающую проверку сообщений для межцепочечных коммуникаций LayerZero. Основная цель — гарантировать достоверность и целостность сообщений, передаваемых между различными блокчейн-сетями, с помощью консенсуса группы валидаторов, работающих в рамках симбиотической системы.

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

Основные возможности и функции

Управление валидаторами: добавление и удаление с назначением ролей.
Поддержка списка разрешённых цепочек LayerZero.
Запросы на верификацию сообщений с последующим подтверждением валидаторами.
Автоматическое определение достижения кворума и смены статуса верификации.
Возможность экстренного подтверждения сообщения администратором.
Управление порогом кворума.
Пауза и анпаузу контракта для защиты в критических ситуациях.

Подробное описание компонентов

Роли

VALIDATOR_ROLE — роль валидатора, даёт право подписывать и подтверждать сообщения.
PAUSER_ROLE — роль, позволяющая ставить контракт на паузу и снимать с неё.
EMERGENCY_ROLE — роль для проведения экстренных операций, например, экстренного подтверждения сообщений.

Константы

Название	Описание
`VERIFICATION_TIMEOUT` (3600)	Тайм-аут на верификацию сообщения, 1 час (сек).
`MAX_VALIDATORS_PER_VERIFICATION` (100)	Максимальное количество валидаторов для проверки.

Перечисления

`VerificationStatus`

Статусы верификации сообщения:

PENDING — ожидает подтверждения.
VERIFIED — сообщение подтверждено.
FAILED — верификация не удалась.
EXPIRED — время верификации истекло.

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

`MessageVerification`

Хранит данные о конкретной верификации сообщения:

Поле	Тип	Описание
`messageHash`	bytes32	Хэш проверяемого сообщения.
`srcEid`	uint32	Идентификатор исходной цепочки LayerZero.
`dstEid`	uint32	Идентификатор целевой цепочки LayerZero.
`payloadHash`	bytes32	Хэш полезной нагрузки сообщения.
`confirmations`	uint64	Число подтверждений, требуемых для сообщения.
`timestamp`	uint256	Время инициации верификации.
`status`	enum	Текущий статус верификации (см. `VerificationStatus`).
`validatorCount`	uint256	Количество валидаторов, подтвердивших сообщение.
`validatorSigned`	mapping	Отметки, какие валидаторы подписали сообщение.

`ValidatorVerification`

Информация о подписи валидатора:

Поле	Тип	Описание
`validator`	address	Адрес валидатора.
`signature`	bytes	Подпись валидатора на сообщении.
`timestamp`	uint256	Время верификации валидатором.
`isValid`	bool	Валидность подписи.

`LayerZeroMessage`

Описание сообщения LayerZero для верификации:

Поле	Тип	Описание
`messageHash`	bytes32	Хэш сообщения.
`srcEid`	uint32	Исходный LayerZero endpoint ID.
`dstEid`	uint32	Целевой LayerZero endpoint ID.
`payloadHash`	bytes32	Хэш полезной нагрузки.
`confirmations`	uint64	Требуемое число подтверждений.
`payload`	bytes	Полезная нагрузка сообщения.

События

MessageVerificationRequested — новый запрос на верификацию сообщения.
ValidatorVerified — валидатор подтвердил сообщение.
MessageVerified — сообщение успешно верифицировано.
MessageVerificationFailed — верификация сообщения провалилась.
QuorumThresholdUpdated — изменение порога кворума.
ValidatorAdded / ValidatorRemoved — изменения в списке валидаторов.
SupportedChainUpdated — обновление списка поддерживаемых цепочек.

Методы

Конструктор

constructor(address _admin)

Инициализирует контракт, назначая адрес администратора с ролями DEFAULT_ADMIN_ROLE, PAUSER_ROLE, EMERGENCY_ROLE.
Проверка на нулевой адрес.

`requestVerification`

function requestVerification(LayerZeroMessage calldata message) external whenNotPaused returns (bytes32 messageHash)

Запрашивает создание записи верификации для нового сообщения.
Проверяет валидность messageHash и поддержку цепочек источника и приёма.
Если запись уже существует, возвращает существующий хэш.
Создаёт структуру MessageVerification, статус PENDING.
Генерирует событие MessageVerificationRequested.

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

LayerZeroMessage memory msg = LayerZeroMessage({
    messageHash: keccak256(abi.encodePacked(...)),
    srcEid: 1,
    dstEid: 2,
    payloadHash: keccak256(abi.encodePacked(...)),
    confirmations: 10,
    payload: bytes("")
});
bytes32 hash = symbioticDVN.requestVerification(msg);

`verifyMessage`

function verifyMessage(bytes32 messageHash, bytes calldata signature) external onlyRole(VALIDATOR_ROLE) whenNotPaused

Вызывается валидаторами для подтверждения сообщения.
Проверяет, что сообщение существует и статус PENDING.
Проверяет, что не истёк тайм-аут верификации.
Проверяет, что валидатор не подписывал ранее.
Проверяет корректность подписи с помощью _verifyValidatorSignature.
Записывает подтверждение, увеличивает счётчик валидаторов.
Если достигнут кворум, переводит статус в VERIFIED и вызывает событие MessageVerified.
Вызывает событие ValidatorVerified.

`getVerificationStatus`

function getVerificationStatus(bytes32 messageHash) external view returns (VerificationStatus status, uint256 validatorCount, uint256 requiredValidators)

Возвращает текущий статус верификации сообщения.
Показывает, сколько валидаторов подтвердили сообщение.
Показывает, сколько валидаторов необходимо для достижения кворума.
Если время верификации истекло, возвращает статус EXPIRED.

`isMessageVerified`

function isMessageVerified(bytes32 messageHash) external view returns (bool verified)

Быстрый чек, было ли сообщение верифицировано (статус VERIFIED).

`getValidatorVerification`

function getValidatorVerification(bytes32 messageHash, address validator) external view returns (ValidatorVerification memory verification)

Возвращает данные о конкретной подписи валидатора для сообщения.

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

addSupportedChain(uint32 eid) — добавляет цепочку в список поддерживаемых.
removeSupportedChain(uint32 eid) — удаляет цепочку из списка.

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

addValidator(address validator) — добавляет нового валидатора, проверяет лимит и адрес.
removeValidator(address validator) — удаляет валидатора из списка активных.

Кворум и пороги

updateQuorumThreshold(uint256 newThreshold) — обновляет порог кворума (в базисных пунктах).
getRequiredValidators() — возвращает необходимое число валидаторов для достижения кворума.

Проверка поддержки цепочки

isChainSupported(uint32 eid) — возвращает, поддерживается ли цепочка.

Пауза и экстренные операции

pause() и unpause() — управление состоянием паузы.
emergencyVerifyMessage(bytes32 messageHash) — принудительно переводит сообщение в статус VERIFIED (только для экстренной роли).

Внутренний метод: `_verifyValidatorSignature`

function _verifyValidatorSignature(bytes32 messageHash, bytes calldata signature, address validator) internal pure returns (bool valid)

Проверяет подпись валидатора на сообщении.
Использует Ethereum Signed Message Hash (EIP-191) для восстановления адреса.
Проверяет длину подписи, корректность параметров v, r, s.
Сравнивает адрес, полученный через ecrecover, с адресом валидатора.

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

supportsInterface(bytes4 interfaceId) — переопределение для совместимости с AccessControl.

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

Контракт интегрируется с LayerZero, используя идентификаторы цепочек (srcEid, dstEid) для фильтрации и поддержки межцепочечной коммуникации.
Использует OpenZeppelin библиотеки AccessControl для управления ролями, ReentrancyGuard для защиты от повторных вызовов и Pausable для возможности временной приостановки работы.
Валидаторы — внешние участники, которым назначена роль VALIDATOR_ROLE и которые подписывают сообщения для достижения кворума.
Администраторы управляют настройками, списком валидаторов и поддерживаемыми цепочками.

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

Использование mapping внутри структуры MessageVerification для хранения отметок подписей валидаторов оптимизирует проверку повторных подписей.
Кворум рассчитывается через умножение общего числа валидаторов на порог в базисных пунктах (например, 6700 = 67%).
Используются собственные ошибки (error) вместо require с сообщением для экономии газа.
Тайм-аут верификации (1 час) предотвращает бесконечное ожидание подтверждений.
Подписи валидаторов проверяются строго и валидаторы могут подтвердить сообщение только один раз.

Диаграмма структуры класса

classDiagram
    class SymbioticDVN {
        <<contract>>
        +bytes32 VALIDATOR_ROLE
        +bytes32 PAUSER_ROLE
        +bytes32 EMERGENCY_ROLE
        +uint256 VERIFICATION_TIMEOUT
        +uint256 MAX_VALIDATORS_PER_VERIFICATION
        +uint256 quorumThreshold
        +uint256 totalValidators
        +mapping(bytes32 => MessageVerification) verifications
        +mapping(bytes32 => mapping(address => ValidatorVerification)) validatorVerifications
        +mapping(uint32 => bool) supportedChains
        +mapping(address => bool) activeValidators
        +constructor(address _admin)
        +requestVerification(LayerZeroMessage message) returns (bytes32)
        +verifyMessage(bytes32 messageHash, bytes signature)
        +getVerificationStatus(bytes32 messageHash) returns (VerificationStatus, uint256, uint256)
        +isMessageVerified(bytes32 messageHash) returns (bool)
        +getValidatorVerification(bytes32 messageHash, address validator) returns (ValidatorVerification)
        +addSupportedChain(uint32 eid)
        +removeSupportedChain(uint32 eid)
        +addValidator(address validator)
        +removeValidator(address validator)
        +updateQuorumThreshold(uint256 newThreshold)
        +getRequiredValidators() returns (uint256)
        +isChainSupported(uint32 eid) returns (bool)
        +pause()
        +unpause()
        +emergencyVerifyMessage(bytes32 messageHash)
        -_verifyValidatorSignature(bytes32 messageHash, bytes signature, address validator) returns (bool)
        +supportsInterface(bytes4 interfaceId) returns (bool)
    }

    class MessageVerification {
        +bytes32 messageHash
        +uint32 srcEid
        +uint32 dstEid
        +bytes32 payloadHash
        +uint64 confirmations
        +uint256 timestamp
        +VerificationStatus status
        +uint256 validatorCount
        +mapping(address => bool) validatorSigned
    }

    class ValidatorVerification {
        +address validator
        +bytes signature
        +uint256 timestamp
        +bool isValid
    }

    class LayerZeroMessage {
        +bytes32 messageHash
        +uint32 srcEid
        +uint32 dstEid
        +bytes32 payloadHash
        +uint64 confirmations
        +bytes payload
    }

    SymbioticDVN --> MessageVerification : uses
    SymbioticDVN --> ValidatorVerification : uses
    SymbioticDVN --> LayerZeroMessage : input

Заключение

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

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