<!--
  Copyright (c) 2024-2025 Тарабанов Александр Викторович
  All rights reserved.
  
  This software is proprietary and confidential.
  Unauthorized copying, modification, or distribution is prohibited.
  
  For licensing inquiries: info@hb3-accelerator.com
  Website: https://hb3-accelerator.com
  GitHub: https://github.com/HB3-ACCELERATOR
-->

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

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

### DLE v2: ключевые изменения и API (актуально)
- Безопасность: удалены уязвимые Merkle‑механизмы cross‑chain; нет внешних мостов/оракулов.
- Голосующая сила: OpenZeppelin `ERC20Votes` (снимки `getPastVotes`, `getPastTotalSupply`).
- Делегирование: жестко ограничено «только на себя»; третьим лицам делегировать нельзя (1 токен = 1 голос).
- Single‑Chain Governance: голосование происходит в одной выбранной сети (`governanceChainId`), время снапшота фиксируется на создании предложения и используется во всех сетях.
- Multi‑Chain исполнение: выполнение в целевых сетях по EIP‑712 подписям холдеров, проверяется суммарная голосующая сила на зафиксированном `timepoint` (без доверия к мостам).
- «100% или ничего»: операции считаются успешными только при готовности/успешности всех целевых сетей.
- Модули вынесены отдельно: `Treasury`, `Timelock`, `Deactivation`, `Communication` и др. Управление только через предложения.
- Детерминированные адреса: фабрика `FactoryDeployer` + CREATE2. Единый адрес DLE и модулей во всех выбранных сетях. INIT_CODE_HASH автоподставляется из актуального initCode.
- Аналитика: добавлены view‑функции для агрегирования и пагинации.

Пример основных функций DLE v2 (интерфейс):
```solidity
// Создание предложения с фиксацией сети голосования, целевых сетей и таймлока
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
  - Распределение токенов между участниками
  - **Голосующая сила = количество токенов**
  - Проверка баланса токенов при каждой операции

#### 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. Изменение процента кворума
```solidity
function _updateQuorumPercentage(uint256 _newQuorumPercentage) internal
```

#### 3. Изменение текущей цепочки
```solidity
function _updateCurrentChainId(uint256 _newChainId) internal
```

#### 4. События для отслеживания изменений
```solidity
event DLEInfoUpdated(string name, string symbol, string location, string coordinates, uint256 jurisdiction, uint256 oktmo, string[] okvedCodes, uint256 kpp);
event QuorumPercentageUpdated(uint256 oldQuorumPercentage, uint256 newQuorumPercentage);
event CurrentChainIdUpdated(uint256 oldChainId, uint256 newChainId);
```

### Процесс изменения данных 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
- **Аудит**: Все действия отслеживаются в одном месте

##### Техническая реализация:
```javascript
// В приложении 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 операции
```solidity
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

### **Сборка в один безопасный контракт:**
```solidity
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.