DLE/docs/SMART_CONTRACTS.md

Смарт Контракты Digital Legal Entity (DLE)

Основной смарт контракт DLE

DLE v2: ключевые изменения и API (актуально)

• Безопасность: удалены уязвимые Merkle‑механизмы cross‑chain; нет внешних мостов/оракулов.
• Голосующая сила: OpenZeppelin ERC20Votes (снимки getPastVotes, getPastTotalSupply).
• Делегирование: жестко ограничено «только на себя»; третьим лицам делегировать нельзя (1 токен = 1 голос).
• Переводы токенов: ЗАБЛОКИРОВАНЫ прямые переводы (transfer, transferFrom, approve); переводы возможны ТОЛЬКО через governance предложения.
• Single‑Chain Governance: голосование происходит в одной выбранной сети (governanceChainId), время снапшота фиксируется на создании предложения и используется во всех сетях.
• Multi‑Chain исполнение: выполнение в целевых сетях по EIP‑712 подписям холдеров, проверяется суммарная голосующая сила на зафиксированном timepoint (без доверия к мостам).
• «100% или ничего»: операции считаются успешными только при готовности/успешности всех целевых сетей.
• Модули вынесены отдельно: Treasury, Timelock, Deactivation, Communication и др. Управление только через предложения.
• Детерминированные адреса: CREATE с выровненным nonce. Единый адрес DLE и модулей во всех выбранных сетях.
• Аналитика: добавлены view‑функции для агрегирования и пагинации.

Пример основных функций DLE v2 (интерфейс):

// Создание предложения с фиксацией сети голосования, целевых сетей и таймлока
function createProposal(
    string calldata description,
    uint256 governanceChainId,
    uint256[] calldata targetChains,
    uint64 timelockHours,
    bytes calldata operationCalldata
) external returns (uint256 proposalId);

// Голосование с использованием снапшотов ERC20Votes (учет силы на момент создания)
function vote(uint256 proposalId, bool support) external;

// Отмена инициатором при наличии достаточной голосующей силы (мягкая отмена)
function cancelProposal(uint256 proposalId) external;

// Исполнение в целевой сети по EIP-712 подписям холдеров (без мостов)
function executeProposalBySignatures(
    uint256 proposalId,
    bytes[] calldata signatures
) external;

// Просмотровые функции (аналитика)
function getProposalState(uint256 proposalId) external view returns (uint8);
function getProposalVotes(uint256 proposalId) external view returns (uint256 forVotes, uint256 againstVotes);
function getQuorumAt(uint256 timepoint) external view returns (uint256);
function getVotingPowerAt(address account, uint256 timepoint) external view returns (uint256);
function getProposalSummary(uint256 proposalId) external view returns (/* агрегированные поля */);
function getGovernanceParams() external view returns (/* кворум, снапшоты, chainIds */);
function listSupportedChains() external view returns (uint256[] memory);

События (ключевые):

• ProposalCreated, ProposalCancelled, ProposalExecuted
• OffchainAction (триггер оффчейн‑действий через события)
• ModuleAdded, ModuleRemoved

Замечания по безопасности:

• Снапшоты голосующей силы через ERC20Votes исключают перелив голосов.
• Верификация EIP‑712 подписей исключает зависимость от внешних мостов.
• Отсутствуют админ‑роли: все изменения только предложением и кворумом.
• Защита от повторов: nonces и EIP‑712 схемы подписи используются по стандарту OZ.

### Концепция
**Один смарт-контракт** с ERC-20 токенами, настраиваемым кворумом и модулями. Адрес контракта одновременно выполняет функции банковского счета и контактных данных.

### Архитектура

DLE.sol (Один контракт) ├── ERC-20 токены (голосующая сила) ├── Настраиваемый кворум (% от общего количества токенов) ├── Система голосования (проверка баланса токенов) ├── Голосование токен‑холдеров ├── Модули (добавляемые через голосование) ├── Мультичейн синхронизация └── Полное управление данными DLE через кворум

### Требования

#### 1. Токен управления (ERC-20)
- **Описание**: Стандартный ERC-20 токен для управления DLE
- **Функции**:
  - Минтинг токенов при создании DLE
  - Распределение токенов между участниками
  - **Голосующая сила = количество токенов**
  - Проверка баланса токенов при каждой операции
  - **Прямые переводы ЗАБЛОКИРОВАНЫ** - токены служат только для голосования
  - **Переводы возможны ТОЛЬКО через governance предложения**

#### 2. Настраиваемый кворум
- **Описание**: Процент от общего количества токенов для принятия решений
- **Функции**:
  - Настройка кворума при создании DLE
  - **Изменение кворума через голосование** ✅
  - Расчет кворума: `(totalSupply * quorumPercentage) / 100`
  - Проверка достижения кворума для каждого решения

#### 3. Система голосования через токен-холдеров
- **Описание**: Только владельцы токенов участвуют в управлении
- **Функции**:
  - Создание предложений (любым токен-холдером)
  - Голосование пропорционально балансу токенов
  - Проверка баланса токенов при каждой подписи
  - Выполнение предложений после достижения кворума
  - **НЕТ админских ролей - только коллективное управление**

#### 4. Полное управление данными DLE через кворум ✅
- **Описание**: Все данные DLE можно изменить через систему голосования
- **Функции**:
  - **Изменение названия DLE** через кворум
  - **Изменение символа токена** через кворум
  - **Изменение местонахождения** через кворум
  - **Изменение координат** через кворум
  - **Изменение юрисдикции** через кворум
  - **Изменение ОКТМО** через кворум
  - **Изменение КПП** через кворум
  - **Изменение кодов ОКВЭД** через кворум
  - **Изменение процента кворума** через кворум
  - **Изменение текущей цепочки** через кворум

#### 5. Голосование токен‑холдеров
- **Описание**: Критические операции подтверждаются голосованием держателей токенов
- **Функции**:
  - Подача голосов за/против с учетом голосующей силы
  - Подсчет голосов по снапшотам `ERC20Votes`
  - Исполнение операций после достижения кворума

#### 6. Казначейские функции
- **Описание**: Управление финансами DLE через голосование
- **Функции**:
  - Внесение токенов в казну
  - Вывод токенов из казны через голосование
  - Распределение дивидендов
  - Бюджетирование через предложения

#### 7. Модульная система
- **Описание**: Добавление новых функций через модули
- **Функции**:
  - Добавление модулей через голосование
  - Управление модулями через голосование
  - Изоляция модулей от основного контракта
  - Обновление модулей через голосование

#### 8. Коммуникационные функции
- **Описание**: Прием сообщений и звонков
- **Функции**:
  - Прием текстовых сообщений
  - Прием аудио/видео звонков
  - Кворум для коммуникационных действий
  - Хранение истории коммуникаций

### Иерархическая система голосования DLE

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

#### Механизм работы
1. **DLE A** владеет токенами **DLE B**
2. **Голос DLE A** в **DLE B** прямо пропорционален количеству токенов **DLE B** на балансе **DLE A**
3. Для участия в голосовании **DLE B** холдеры **DLE A** должны собрать **кворум голосов** внутри **DLE A**
4. После достижения кворума подписей **DLE A** может голосовать в **DLE B** как единое целое

### Новые возможности изменения данных DLE ✅

#### 1. Обновление основной информации DLE
```solidity
function _updateDLEInfo(
    string memory _name,
    string memory _symbol,
    string memory _location,
    string memory _coordinates,
    uint256 _jurisdiction,
    uint256 _oktmo,
    string[] memory _okvedCodes,
    uint256 _kpp
) internal

2. Изменение процента кворума

function _updateQuorumPercentage(uint256 _newQuorumPercentage) internal

3. События для отслеживания изменений

event DLEInfoUpdated(string name, string symbol, string location, string coordinates, uint256 jurisdiction, uint256 oktmo, string[] okvedCodes, uint256 kpp);
event QuorumPercentageUpdated(uint256 oldQuorumPercentage, uint256 newQuorumPercentage);

Процесс изменения данных DLE

1. Создание предложения

• Любой токен-холдер создает предложение об изменении данных
• Выбирает цепочку для сбора голосов
• Указывает новые значения для изменения

2. Голосование

• Токен-холдеры голосуют за/против изменения
• Голосующая сила = количество токенов
• Проверка баланса при каждом голосе

3. Исполнение

• При достижении кворума предложение исполняется
• Данные DLE обновляются
• Событие эмитится для отслеживания

4. Синхронизация

• Изменения синхронизируются во все поддерживаемые цепочки
• EIP‑712 подписи холдеров обеспечивают безопасность cross-chain исполнения (без мостов)

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

Изменение названия DLE

1. Создание предложения: "Изменить название на 'Новое DLE'"
2. Голосование в выбранной цепочке
3. При кворуме: обновление названия
4. Синхронизация во все цепочки

Изменение кворума

1. Создание предложения: "Изменить кворум с 51% на 60%"
2. Голосование в выбранной цепочке
3. При кворуме: обновление процента кворума
4. Синхронизация во все цепочки

Изменение текущей цепочки

1. Создание предложения: "Изменить текущую цепочку на Polygon"
2. Голосование в выбранной цепочке
3. При кворуме: обновление currentChainId
4. Синхронизация во все цепочки

Безопасность

Валидация данных

• Проверка корректности всех входящих данных
• Валидация адресов и числовых значений
• Проверка поддержки цепочек перед изменением

Защита от злоупотреблений

• Все изменения только через кворум
• Проверка баланса токенов при голосовании
• EIP‑712 подписи и проверка снапшотов для cross-chain безопасности

Аудит изменений

• Все изменения логируются в событиях
• Возможность отслеживания истории изменений
• Прозрачность всех операций

Иерархическая система голосования DLE

Концепция

DLE может владеть токенами других DLE и участвовать в их голосовании через систему кворума подписей.

Механизм работы

1. DLE A владеет токенами DLE B
2. Голос DLE A в DLE B прямо пропорционален количеству токенов DLE B на балансе DLE A
3. Для участия в голосовании DLE B холдеры DLE A должны собрать кворум голосов внутри DLE A
4. После достижения кворума подписей DLE A может голосовать в DLE B как единое целое

Пример

• DLE A владеет 10% токенов DLE B
• Кворум в DLE B = 51%
• Холдеры DLE A голосуют за подпись в DLE B
• DLE B получает от DLE A подпись на 10% голосов

Технические требования

• Система сбора голосов внутри DLE для внешнего голосования
• Проверка прав через голосование
• Прямо пропорциональный подсчет голосов по количеству токенов
• Интерфейсы для взаимодействия между DLE

Межприложное взаимодействие DLE

Концепция

Каждое DLE имеет свое веб3 приложение с интерфейсом управления. DLE могут взаимодействовать через встраивание интерфейсов.

Архитектура взаимодействия

• DLE A (домен 1) + Веб3 приложение A с интерфейсом
• DLE B (домен 2) + Веб3 приложение B с интерфейсом
• Голосование происходит через блокчейн между доменами

Вариант реализации (рекомендуемый)

Встраивание интерфейса DLE B в приложение DLE A

Преимущества:

• Безопасность: Холдеры DLE A не покидают свое приложение
• Защита от фишинга: Пользователи всегда в знакомой среде
• Контроль: DLE A контролирует безопасность интерфейса
• Удобство: Единый интерфейс для управления всеми DLE
• Аудит: Все действия отслеживаются в одном месте

Техническая реализация:

// В приложении DLE A
function DLEBManagementInterface({ dleBAddress }) {
    return (
        <div className="dle-b-management">
            <h3>Управление DLE B</h3>
            <VotingInterface targetDLE={dleBAddress} />
            <ProposalInterface targetDLE={dleBAddress} />
            <TreasuryInterface targetDLE={dleBAddress} />
        </div>
    );
}

Пример интерфейса:

• URL: http://localhost:5173/dle-management
• Встраивание компонентов управления DLE B
• Безопасное подписание транзакций для DLE B
• Проверка прав через голосование

Технические требования

• Один адрес = универсальная точка входа
• Безопасность коллективного голосования токен‑холдеров по снапшотам
• Масштабируемость через модули
• Поддержка аудио/видео коммуникации
• Совместимость с существующими стандартами (ERC-20, ERC-721)
• Иерархическая система голосования между DLE
• Межприложное взаимодействие через встраивание интерфейсов

Мульти-чейн архитектура DLE

Концепция

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

Требования

1. CREATE2 детерминистический деплой

• Использование CREATE2 opcode для предсказуемых адресов
• Одинаковый адрес смарт-контракта во всех EVM-совместимых сетях
• Factory контракт с одинаковым адресом во всех целевых сетях
• Детерминистический salt на основе пользовательских данных

2. Синхронные токены управления

• Одинаковое количество токенов для каждого партнера во всех сетях
• Синхронизация операций с токенами между всеми развернутыми сетями
• Все операции с токенами только через кворум голосов
• Защита от double-spending и рассинхронизации

3. Single-Chain Governance система

• Инициатор предложения выбирает ОДНУ сеть для голосования
• Все токен-холдеры участвуют в голосовании только в выбранной сети
• Инициатор устанавливает таймлок для предложения
• Проверка балансов токен-холдеров при подписании
• Исполнение решения происходит во всех целевых сетях

4. Упрощенная cross-chain архитектура

• Голосование и кворум ТОЛЬКО в одной governance сети
• Проверка балансов токен-холдеров при подписании
• Настраиваемый таймлок для каждого предложения
• Исполнение во всех выбранных целевых сетях

5. Мульти-сетевой деплой

• Выбор множественных сетей для деплоя из интерфейса
• Автоматический расчет стоимости деплоя по всем сетям
• Поддержка различных EVM-совместимых сетей
• Возможность добавления новых сетей после первоначального деплоя

Поддерживаемые сети

• Динамическое добавление сетей через таблицу RPC провайдеров

Архитектура синхронизации

Single-Chain Governance операции

contract DLE_SingleChainGovernance {
    struct Proposal {
        bytes operation;            // Операция для выполнения
        uint256[] targetChains;     // Целевые сети для исполнения
        uint256 timelock;           // Время исполнения (timestamp)
        uint256 governanceChain;    // Сеть где проходит голосование
        address initiator;          // Инициатор предложения
        bytes[] signatures;         // Подписи токен-холдеров
        bool executed;              // Статус исполнения
    }
    
    function createProposal(
        bytes calldata operation,
        uint256[] calldata targetChains,
        uint256 timelockDelay
    ) external onlyTokenHolder returns (uint256 proposalId);
    
    function signProposal(uint256 proposalId) external onlyTokenHolder;
    
    function executeProposal(uint256 proposalId) external;
}

Типы операций

• Управление токенами - перевод, минтинг, сжигание
• Финансовые операции - выплата дивидендов, инвестиции
• Emergency действия - пауза, разморозка, восстановление
• Модульные операции - добавление/удаление функциональности

Безопасность Single-Chain Governance

Требования к безопасности

• Участие только верифицированных токен-холдеров
• Проверка балансов токенов на момент подписания
• Настраиваемый кворум подписей (минимум 51%)
• Настраиваемый таймлок для всех операций (кроме emergency)

Механизмы защиты

• Token-holder verification - только владельцы токенов участвуют
• Balance verification - проверка баланса при каждой подписи
• Flexible timelock - инициатор устанавливает задержку
• Governance chain selection - инициатор устанавливает сеть для голосования
• Atomic execution - операция выполняется во всех сетях или не выполняется
• Fallback mechanisms - исполнение в доступных сетях при сбоях

Пользовательский интерфейс

Форма мульти-чейн деплоя

• Выбор целевых сетей из выпадающего списка
• Предварительный расчет стоимости деплоя
• Настройки single-chain governance

Создание предложений

• Выбор governance сети для голосования
• Установка таймлока инициатором
• Выбор целевых сетей для исполнения
• Описание операции и параметров

Участие в голосовании

• Подписание предложений в governance сети
• Проверка баланса токенов при подписи
• Отображение прогресса сбора подписей
• Статус исполнения в целевых сетях

Технические требования упрощенной архитектуры

• Детерминистический деплой через CREATE2
• Single-chain governance для безопасности
• Token-holder verification при каждой подписи
• Настраиваемые таймлоки для разных типов операций
• Атомарное исполнение во всех целевых сетях
• Fallback механизмы при недоступности сетей

Технические решения

ERC-4337 (Account Abstraction) как основа

Концепция

ERC-4337 предоставляет стандартную инфраструктуру для смарт-контракт кошельков с универсальностью (один адрес во всех цепочках) и готовыми решениями для оптимизации газа.

Компоненты ERC-4337

• Smart Contract Wallets — инфраструктура аккаунтов (опционально для UX)
• Bundlers - оптимизация газа через агрегацию транзакций
• Paymasters - гибкая оплата транзакций
• Account Abstraction - универсальность и стандартизация

Преимущества использования ERC-4337

• ✅ Универсальность - один адрес во всех блокчейнах
• ✅ Готовые решения - проверенная экосистема
• ✅ Безопасность - прошедший аудит стандарт
• ✅ Оптимизация - встроенная экономия газа
• ✅ Совместимость - стандартные интерфейсы

Варианты технической реализации

Вариант 1: Собственный контракт + ERC-4337

Создание собственного DLE контракта с использованием компонентов ERC-4337

Архитектура:

Собственный DLE контракт
├── ERC-4337 компоненты (импорт/наследование)
│   ├── Account Abstraction логика
│   ├── Bundler совместимость
│   └── Paymaster поддержка
└── DLE Logic (ваша уникальная логика)
    ├── Governance Token
    ├── Single-Chain Voting System
    ├── Communication
    ├── Treasury
    └── Multi-Chain Execution

Лицензия ERC-4337

ERC-4337 распространяется под лицензией CC0 (Public Domain), что означает полную свободу использования.

Готовые компоненты с аудитом

1. OpenZeppelin (аудит: ConsenSys Diligence)

• ✅ ERC-20 - токены управления
• ✅ Governance - система голосования
• ✅ Access Control - роли и разрешения (устарело) Multisig — используем голосование токен‑холдеров (ERC20Votes)
• ✅ Timelock - задержки выполнения

2. ERC-4337 (аудит: Trail of Bits)

• ✅ Account Abstraction - универсальность
• ✅ Smart Contract Wallets - кошельки
• ✅ Bundlers - оптимизация газа

3. Проверенные паттерны

• ✅ Diamond Pattern (EIP-2535) - модульность
• ✅ Proxy Pattern - обновляемость
• ✅ Factory Pattern - создание контрактов

Архитектура безопасного контракта DLE

Сборка в один безопасный контракт:

contract DLE is ERC20, Governor, TimelockController {
    // Single-chain governance логика
    // + готовые компоненты с аудитом
    // + проверенные паттерны
}

Компоненты для интеграции:

• ERC-20 - токен управления DLE
• Governor - система голосования
• TimelockController - настраиваемые таймлоки
• Account Abstraction - универсальность адреса

Преимущества упрощенного подхода:

✅ Безопасность

• Все компоненты протестированы и проаудированы
• Устранены риски cross-chain мостов
• Single-chain governance снижает сложность

✅ Эффективность

• Использование готовых решений OpenZeppelin
• Быстрая разработка с проверенными компонентами
• Меньше ошибок благодаря упрощенной архитектуре

✅ Надежность

• Временем проверенные решения
• Простая логика коллективного голосования токен‑холдеров
• Понятные механизмы таймлоков

✅ Совместимость

• Стандартные интерфейсы Ethereum
• Совместимость с существующими кошельками
• Легкая интеграция с DeFi протоколами

Примечание про ERC-4337 (опционально)

• Может использоваться в кошельках/окружении для UX (userOps), но не является частью ядра DLE v2.