DLE/docs/SMART_CONTRACTS.md

<!--
  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

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

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

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

#### 1. Токен управления (ERC-20)
- **Описание**: Стандартный ERC-20 токен для управления DLE
- **Функции**:
  - Минтинг токенов при создании DLE
  - Распределение токенов между участниками
  - **Голосующая сила = количество токенов**
  - Проверка баланса токенов при каждой операции

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

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

#### 4. Мультиподпись через токен-холдеров
- **Описание**: Система подписей для критических операций
- **Функции**:
  - Подписание операций токен-холдерами
  - Проверка баланса токенов при подписи
  - Сбор подписей до достижения кворума
  - Выполнение операций после сбора подписей

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

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

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

### Иерархическая система голосования 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

#### Концепция
Каждое 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** - встроенная мультиподпись
- **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** - мультиподпись
- ✅ **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 протоколами