DLE/docs/SMART_CONTRACTS.md

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

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

### Концепция
Адрес смарт контракта одновременно выполняет функции банковского счета и контактных данных (как email/телефонный номер).

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

#### 1. Токен управления
- Пользователь заполняет форму в приложении для ручного деплоя
- Токен дает права голоса держателям
токен передается только через кворум мультиподписей

#### 2. Казначейские функции
- Управление финансами через голосование токен-холдеров
- Мультиподпись токен-холдеров для выполнения транзакций (проверка баланса)
- Функции банковского счета
- НЕТ админских ролей - все через коллективное голосование

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

#### 4. Система настраиваемых таймлоков (отдельный модуль)
- **Архитектура**: Отдельный контракт TimelockController, создаваемый при деплое DLE
- **Настройки при деплое**:
  - Минимальная задержка таймлока (настраиваемая)
  - Максимальная задержка таймлока (настраиваемая)
  - Задержка по умолчанию (настраиваемая)
  - Возможность настройки индивидуальной задержки для каждого предложения
- **Функции модуля**:
  - Инициатор предложения устанавливает индивидуальную задержку
  - Динамическое изменение параметров таймлока через голосование
  - Отмена предложений до истечения таймлока
  - Выполнение предложений после истечения таймлока
- **Пример параметров**: 1 день задержки, 7 дней голосования, 2 дня timelock

#### 5. Модульная система
- Настройка отдельных модулей с формами в приложении
- Деплой дополнительных смарт контрактов через голосование
- Расширяемость функционала

#### 6. Коммуникационные функции
- Прием сообщений от криптокошельков и смарт контрактов
- Прием звонков (аудио/видео) от владельцев кошельков
- Адрес контракта = универсальный контакт (как email/телефон)
- Кворум мультиподписей токен-холдеров для приема звонков и отправки сообщений
- НЕТ админских ролей - все через коллективное голосование

#### 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. Cross-chain система голосования
- Возможность выбора сети для инициации голосования
- Кворум рассчитывается по токенам в выбранной сети
- Результаты голосования синхронизируются во все сети
- Выполнение решений может происходить в любой из развернутых сетей

#### 4. Cross-chain синхронизация операций
- Функция связывания операций между сетями
- Атомарное выполнение операций во всех целевых сетях
- Система откатов при сбоях в одной из сетей
- Таймауты и fallback механизмы

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

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

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

### Поддерживаемые сети
- деинамическое и только те которые добавлены в таблицу rpc провайдеров

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

#### Cross-Chain операции
```solidity
contract DLE_CrossChainSync {
    struct CrossChainOperation {
        uint256[] targetChains;     // Целевые сети для выполнения
        bytes[] callData;           // Данные для выполнения
        uint256 executedChains;     // Количество выполненных сетей
        bool isCompleted;           // Статус завершения
        uint256 timeout;            // Время истечения операции
    }
    
    function executeMultiChainOperation(bytes32 operationId, uint256 chainId) external;
    function syncTokenOperation(address[] holders, uint256[] amounts, uint256[] chains) external;
}
```

#### Типы синхронизируемых операций
- **Передача токенов** между партнерами
- **Минтинг новых токенов** для новых участников
- **Сжигание токенов** при выходе участников
- **Изменение прав доступа** и ролей
- **Выполнение решений голосования**

### Упрощенная архитектура governance

#### Single-Chain Governance контракт
```solidity
contract DLE_Governance {
    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 действия** - пауза, разморозка, восстановление
- **Модульные операции** - добавление/удаление функциональности

### Безопасность мульти-чейн операций

#### Требования к безопасности
- Кворум для cross-chain операций не менее 67%
- Подтверждение операций в нескольких блоках (минимум 12)
- Система откатов при сбоях синхронизации
- Мониторинг состояния во всех сетях

#### Механизмы защиты
- **Timelock для критических операций** - задержка выполнения
- **Emergency pause** - остановка операций при обнаружении проблем
- **Fallback сеть** - резервная сеть при сбоях основной
- **Валидация состояния** - проверка консистентности данных

### Безопасность 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
- Синхронизация состояния между сетями
- Защита от MEV-атак при cross-chain операциях
- Оптимизация газа для массовых операций
- Поддержка различных bridge протоколов

### Технические требования упрощенной архитектуры
- Детерминистический деплой через 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 протоколами