[English](https://hb3-accelerator.com/gitea/VC-HB3-Accelerator/Docs/src/branch/main/docs.en/back-docs/TASK_REQUIREMENTS.md) | **Русский**

# Задание: Реализация мульти-чейн governance системы для DLE

## Статус выполнения
- ✅ Форма создания предложения работает
- ✅ Предложение создается во всех цепочках DLE
- ✅ Голосование происходит отдельно в каждой цепочке
- ✅ Кворум считается отдельно для каждой цепочки
- ✅ Личный перевод токенов от инициатора предложения
- ✅ Группировка предложений по description + initiator
- ✅ Серверная координация с криптографическими доказательствами
- ✅ Убрана хардкод цепочек - используются deployedNetworks из API

## Контекст
DLE (Digital Legal Entity) - децентрализованная юридическая сущность с контрактами в нескольких блокчейн-сетях. Необходимо реализовать систему управления токенами через мульти-чейн governance, где холдеры токенов могут переводить токены через голосование с кворумом.

## Архитектура системы

### Мульти-чейн компоненты
- **Frontend**: Vue.js приложение с Web3 интеграцией
- **Backend**: Node.js сервер для координации и API
- **Smart Contracts**: DLE контракты в каждой поддерживаемой сети
- **Database**: PostgreSQL для хранения метаданных
- **WebSocket**: Real-time синхронизация между сетями

### Поддерживаемые сети
- Ethereum Sepolia (chainId: 11155111)
- Arbitrum Sepolia (chainId: 421614)
- Base Sepolia (chainId: 84532)

## Требования к функционалу

### 1. Форма создания предложения о переводе токенов
**URL:** `/management/transfer-tokens?address=<DLE_ADDRESS>`

**Поля формы:**
- Адрес получателя (обязательное, address)
- Сумма перевода (обязательное, number в токенах)
- Описание предложения (опциональное, string)
- Время голосования (обязательное, number в днях)

### 2. Логика создания предложений
1. **Определение сетей:** Получение списка `deployedNetworks` через API `/dle-v2`
2. **Параллельное создание:** Предложения создаются одновременно во ВСЕХ сетях DLE
3. **Кодирование операции:** `_transferTokens(address,uint256)` для перевода токенов от инициатора

### 3. Логика голосования
1. **Независимое голосование:** Каждая сеть голосует отдельно
2. **Локальный кворум:** Кворум считается по формуле `(forVotes / totalSupply) >= quorumPercentage`
3. **Голосование токенами:** Вес голоса = баланс токенов избирателя

### 4. Логика исполнения
1. **Локальное исполнение:** Каждый контракт проверяет свой локальный кворум
2. **Серверная координация:** Backend собирает результаты кворумов из всех сетей
3. **Криптографические доказательства:** Сервер подписывает глобальный статус кворума
4. **Глобальное исполнение:** Контракт проверяет подпись и выполняет операцию

## Техническая спецификация

### Smart Contract (DLE.sol)

#### Структура Proposal
```solidity
struct Proposal {
    uint256 id;
    string description;
    uint256 forVotes;
    uint256 againstVotes;
    bool executed;
    bool canceled;
    uint256 deadline;
    address initiator;           // Создатель предложения
    bytes operation;             // Закодированная операция
    uint256[] targetChains;      // Целевые сети для исполнения
    uint256 snapshotTimepoint;   // Точка снимка для голосования
    mapping(address => bool) hasVoted;
}
```

#### Функция _transferTokens
```solidity
function _transferTokens(address _sender, address _recipient, uint256 _amount) internal {
    require(balanceOf(_sender) >= _amount, "Insufficient balance");
    _transfer(_sender, _recipient, _amount);
    emit TokensTransferredByGovernance(_recipient, _amount);
}
```

#### События
```solidity
event ProposalCreated(uint256 proposalId, address initiator, string description);
event QuorumReached(uint256 proposalId, uint256 chainId);
event ProposalExecuted(uint256 proposalId, bytes operation);
```

### Backend (Node.js)

#### Сервис координации кворумов
```javascript
class QuorumCoordinator {
    // Сбор результатов голосования из всех сетей
    async collectQuorumResults(proposalId) {
        // Слушать события QuorumReached из всех сетей
        // Сохранять в базу данных
    }

    // Генерация криптографических доказательств
    async generateGlobalQuorumProof(proposalId) {
        // Подписать глобальный статус кворума
        // Вернуть подпись для контрактов
    }
}
```

#### API Endpoints
- `GET /dle-v2` - получение информации о DLE и сетях
- `POST /api/dle-proposals/get-proposals` - получение списка предложений
- `POST /api/dle-proposals/create-proposal` - создание предложения
- `POST /api/dle-proposals/vote-proposal` - голосование
- `POST /api/dle-proposals/execute-proposal` - исполнение

### Frontend (Vue.js)

#### Компонент TransferTokensFormView
- Валидация формы
- Кодирование операции перевода
- Параллельное создание предложений во всех сетях
- Обработка ошибок и отображение результатов

#### Компонент DleProposalsView
- Группировка предложений по `description + initiator`
- Отображение статуса по каждой сети
- Кнопки голосования для каждой активной сети
- Кнопка исполнения при глобальном кворуме

## Алгоритм работы

### Сценарий использования

1. **Пользователь открывает форму** `/management/transfer-tokens?address=0xdD27...9386`
2. **Вводит данные:**
   - Получатель: `0x123...abc`
   - Сумма: `1000` токенов
   - Описание: `"Перевод средств подрядчику"`
   - Время: `7` дней
3. **Нажимает "Создать"**
4. **Система:**
   - Определяет сети: Sepolia, Arbitrum Sepolia, Base Sepolia
   - Создает предложения в каждой сети параллельно
   - Кодирует `_transferTokens(инициатор, получатель, сумма)`

5. **На странице предложений** появляется одна карточка с статусом по сетям
6. **Пользователи голосуют** в каждой сети отдельно
7. **При локальном кворуме** контракт эмитирует `QuorumReached`
8. **Backend собирает** результаты из всех сетей
9. **При глобальном кворуме** сервер подписывает доказательство
10. **Пользователь вызывает** `executeWithGlobalQuorum()` с подписью
11. **Контракт проверяет** подпись и выполняет перевод

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

### Уровни защиты
1. **On-chain проверки:** Баланс токенов, сроки голосования, кворум
2. **Криптографические доказательства:** Подпись сервера для глобального кворума
3. **Многоуровневая валидация:** Локальный + глобальный кворум
4. **Отказоустойчивость:** Graceful degradation при недоступности сетей

### Риски и mitigation
- **Сервер скомпрометирован:** Проверка подписи предотвращает подделку
- **Сеть недоступна:** Локальное голосование работает независимо
- **Replay attacks:** Проверка ID предложения и chainId
- **Front-running:** Использование commit-reveal схемы при необходимости

## Тестирование

### Критерии приемки
- [x] Форма создания предложения работает
- [x] Предложение создается во всех цепочках DLE
- [x] Голосование происходит отдельно в каждой цепочке
- [x] Кворум считается отдельно для каждой цепочки
- [x] Перевод токенов происходит от инициатора предложения
- [x] Серверная координация с криптографическими доказательствами
- [x] Группировка предложений в интерфейсе
- [x] Обработка ошибок и edge cases

### Test cases
1. Создание предложения в мульти-чейн среде
2. Голосование в одной сети при недоступности других
3. Исполнение при глобальном кворуме
4. Исполнение при частичном кворуме (должен fail)
5. Перевод токенов от инициатора с достаточным балансом
6. Попытка перевода с недостаточным балансом (должен fail)

## Развертывание

### Требования к инфраструктуре
- **Backend сервер** с доступом к RPC всех сетей
- **Database** для хранения метаданных предложений
- **SSL сертификаты** для безопасной коммуникации
- **Monitoring** для отслеживания состояния сетей

### Переменные окружения
```bash
# RPC URLs
SEPOLIA_RPC_URL=https://1rpc.io/sepolia
ARBITRUM_SEPOLIA_RPC_URL=https://sepolia-rollup.arbitrum.io/rpc
BASE_SEPOLIA_RPC_URL=https://sepolia.base.org

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/dle

# Server keys for signing
SERVER_PRIVATE_KEY=0x...
```

## Заключение

Реализована полнофункциональная мульти-чейн governance система для управления токенами DLE. Система обеспечивает децентрализованное принятие решений с координацией через trusted server с криптографическими доказательствами, обеспечивая баланс между удобством использования и безопасностью.