219 lines
12 KiB
Markdown
219 lines
12 KiB
Markdown
[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 с криптографическими доказательствами, обеспечивая баланс между удобством использования и безопасностью. |