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

# Руководство по деплою DLE v2

## Обзор

DLE v2 (Digital Legal Entity) - это система для создания цифровых юридических лиц с мульти-чейн поддержкой. Основная особенность - использование CREATE с выровненным nonce для обеспечения одинакового адреса смарт-контракта во всех поддерживаемых сетях.

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

### Компоненты системы

1. **DLE.sol** - Основной смарт-контракт с ERC-20 токенами управления
2. **Детерминированный деплой** - через CREATE с выровненным nonce для одинаковых адресов
3. **Модули** - Дополнительная функциональность (Treasury, Timelock, etc.)

### Мульти-чейн поддержка

- **CREATE с выровненным nonce** - Одинаковый адрес во всех EVM-совместимых сетях
- **Single-Chain Governance** - Голосование происходит в одной сети
- **Multi-Chain Execution** - Исполнение в целевых сетях по подписям

## Процесс деплоя

### 1. Подготовка

1. Убедитесь, что у вас есть:
   - Приватный ключ с достаточным балансом в выбранных сетях
   - RPC URLs для всех целевых сетей
   - API ключ Etherscan (опционально, для верификации)

2. Настройте RPC провайдеры в веб-интерфейсе:
   - Откройте страницу настроек: `http://localhost:5173/settings/security`
   - Перейдите в раздел "RPC Провайдеры"
   - Добавьте RPC URLs для нужных сетей:
     - **Ethereum Mainnet**: Chain ID 1
     - **Polygon**: Chain ID 137  
     - **BSC**: Chain ID 56
     - **Arbitrum**: Chain ID 42161
     - **Sepolia Testnet**: Chain ID 11155111
     - И другие нужные сети

3. Приватные ключи вводятся непосредственно в форме деплоя для безопасности

### 2. Деплой через веб-интерфейс

1. Откройте страницу: `http://localhost:5173/settings/dle-v2-deploy`

2. Заполните форму:
   - **Основная информация**: Название, символ токена
   - **Юридическая информация**: Страна, ОКВЭД, адрес
   - **Партнеры**: Адреса и доли токенов
   - **Сети**: Выберите целевые блокчейн-сети
   - **Приватный ключ**: Для деплоя контрактов

3. Нажмите "Развернуть DLE"

### 3. Процесс деплоя

Система автоматически:

1. **Проверяет балансы** во всех выбранных сетях
2. **Компилирует контракты** через Hardhat
3. **Проверяет Factory адреса** в базе данных
4. **Выравнивает nonce** для детерминированного деплоя
5. **Вычисляет адрес DLE** через CREATE с выровненным nonce
6. **Деплоит DLE** с одинаковым адресом во всех сетях
8. **Деплоит базовые модули** (Treasury, Timelock, Reader) в каждой сети
9. **Инициализирует модули** в DLE контракте
10. **Верифицирует контракты** в Etherscan (опционально)

### 4. Результат

После успешного деплоя вы получите:

- **Одинаковый адрес DLE** во всех выбранных сетях
- **Одинаковый адрес Factory** во всех выбранных сетях
- **Базовые модули** (Treasury, Timelock, Reader) в каждой сети
- **Инициализированные модули** в DLE контракте
- **ERC-20 токены управления** распределенные между партнерами
- **Настроенный кворум** для принятия решений
- **Поддержку мульти-чейн операций**

### 5. Управление Factory адресами

Система автоматически управляет Factory адресами:

#### API Endpoints:
- `GET /api/factory` - Получить все Factory адреса
- `GET /api/factory/:chainId` - Получить Factory адрес для сети
- `POST /api/factory` - Сохранить Factory адрес
- `POST /api/factory/bulk` - Сохранить адреса для нескольких сетей
- `DELETE /api/factory/:chainId` - Удалить Factory адрес
- `POST /api/factory/check` - Проверить наличие адресов

#### Автоматическое управление:
- **Кэширование** - Factory адреса сохраняются в базе данных
- **Переиспользование** - Существующие Factory используются повторно
- **Валидация** - Проверка существования Factory в блокчейне
- **Автодеплой** - Новые Factory деплоятся при необходимости

### 6. Проверка одинаковости адресов

Система автоматически проверяет, что все адреса одинаковые:

```javascript
// Проверка адресов DLE
const addresses = results.filter(r => r.success).map(r => r.address);
const uniqueAddresses = [...new Set(addresses)];

if (uniqueAddresses.length === 1) {
  console.log("✅ Все адреса DLE одинаковые:", uniqueAddresses[0]);
} else {
  throw new Error("CREATE2 не обеспечил одинаковые адреса");
}
```

Если адреса не совпадают, это указывает на проблему с:
- Разными Factory адресами в сетях
- Разными salt значениями
- Разными bytecode контрактов

## Технические детали

### База данных Factory адресов

Система использует таблицу `factory_addresses` для хранения адресов:

```sql
CREATE TABLE factory_addresses (
  id SERIAL PRIMARY KEY,
  chain_id INTEGER NOT NULL UNIQUE,
  factory_address VARCHAR(42) NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### CREATE Механизм

Система использует CREATE с выровненным nonce для обеспечения одинаковых адресов:

#### 1. Выравнивание nonce
```javascript
// Выравнивание nonce до целевого значения
while (currentNonce < targetNonce) {
  await sendTransaction({
    to: burnAddress,
    value: 0,
    nonce: currentNonce
  });
  currentNonce++;
}
```

#### 2. Деплой DLE
```javascript
// Вычисление адреса DLE через CREATE
const predictedAddress = ethers.getCreateAddress({
  from: wallet.address,
  nonce: targetNonce
});

// Деплой DLE с предсказанным адресом
await wallet.sendTransaction({
  data: dleInitCode,
  nonce: targetNonce
});
```

#### Ключевые принципы:
- **Выровненный nonce** обеспечивает одинаковые адреса во всех сетях
- **Burn address** используется для выравнивания nonce без потери средств
- **Проверка баланса** перед деплоем предотвращает неудачи
- **DLE Contract** деплоится через Factory с одинаковым salt
- **Результат**: Одинаковый адрес DLE во всех EVM-совместимых сетях

### Структура DLE

```solidity
contract DLE is ERC20, ERC20Permit, ERC20Votes, ReentrancyGuard {
    // Основная информация
    DLEInfo public dleInfo;
    
    // Настройки управления
    uint256 public quorumPercentage;
    
    // Мульти-чейн поддержка
    uint256[] public supportedChainIds;
    uint256 public governanceChainId;
    
    // Система предложений
    mapping(uint256 => Proposal) public proposals;
}
```

### Базовые модули (автоматически деплоятся)

При деплое DLE автоматически развертываются и инициализируются:

- **TreasuryModule** - Управление финансами, депозиты, выводы, дивиденды
- **TimelockModule** - Задержки исполнения критических операций
- **DLEReader** - API для чтения данных DLE

### Дополнительные модули (через голосование)

DLE поддерживает модульную архитектуру:

- **CommunicationModule** - Внешние коммуникации
- **BurnModule** - Сжигание токенов
- **MintModule** - Выпуск новых токенов
- **OracleModule** - Внешние данные
- **CustomModule** - Пользовательские модули

## Управление DLE

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

```solidity
// Создать предложение
uint256 proposalId = dle.createProposal(
    "Описание предложения",
    governanceChainId,
    targetChains,
    timelockHours,
    operationCalldata
);
```

### Голосование

```solidity
// Голосовать за предложение
dle.vote(proposalId, true); // За
dle.vote(proposalId, false); // Против
```

### Исполнение

```solidity
// Исполнить предложение
dle.executeProposalBySignatures(proposalId, signatures);
```

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

### Ключевые принципы

1. **Только токен-холдеры** участвуют в управлении
2. **Прямые переводы токенов заблокированы**
3. **Все операции через кворум**
4. **CREATE2 обеспечивает детерминистические адреса**
5. **EIP-712 подписи для мульти-чейн исполнения**

### Проверки

- Валидация приватных ключей
- Проверка балансов перед деплоем
- Верификация CREATE2 адресов
- Контроль кворума при голосовании

## Устранение неполадок

### Частые проблемы

1. **Недостаточно средств**
   - Проверьте балансы во всех сетях
   - Убедитесь в правильности RPC URLs в настройках

2. **Ошибки компиляции**
   - Проверьте версию Solidity (0.8.20)
   - Убедитесь в корректности импортов OpenZeppelin

3. **Разные адреса в сетях**
   - Проверьте, что Factory контракты имеют одинаковые адреса
   - Проверьте CREATE2 salt для DLE
   - Убедитесь в одинаковом bytecode контрактов
   - Проверьте nonce кошелька деплоера

4. **Ошибки верификации**
   - Проверьте API ключ Etherscan в форме деплоя
   - Убедитесь в корректности constructor arguments

5. **RPC URL не найден**
   - Проверьте настройки RPC провайдеров в `/settings/security`
   - Убедитесь, что Chain ID указан правильно
   - Протестируйте RPC URL через кнопку "Тест" в настройках

### Логи

Логи деплоя доступны в:
- Backend: `backend/logs/`
- Hardhat: `backend/artifacts/`
- Результаты: `backend/contracts-data/dles/`

## Поддержка

Для получения поддержки:
- Email: info@hb3-accelerator.com
- Website: https://hb3-accelerator.com
- GitHub: https://github.com/HB3-ACCELERATOR
