MYCELIUM CORE

Настольное sandbox-приложение для моделирования, проведения и аудита электронного голосования на локальной Ethereum-сети. Симулятор для Master Degree Project.

 

Артефакты · Архитектура · Дизайн · Скриншоты · Быстрый старт · Конфигурация · Безопасность · FAQ

---

Обзор

MYCELIUM CORE — автономная desktop-среда для симуляции процесса блокчейн-голосования. Система использует единственный Solidity смарт-контракт (VotingCore.sol) как абсолютный источник истины, эфемерный локальный узел Geth для исполнения и многослойный графический интерфейс на PyQt6.

Проект демонстрирует полный жизненный цикл on-chain выборов: подготовку, голосование и событийно-ориентированный криптографический аудит.

Артефакты

Категория	Артефакт	Кол-во	Ссылка
Документация	Сайт MkDocs (EN/RU)	70+ стр.	Открыть
UML-диаграммы	Component, Class, Sequence, State, Activity, UseCase, Deployment, C4	17	Каталог
Процессы BPMN	Setup, Voting, Mass Vote, Audit, Error Handling, Session Lifecycle	6	Каталог
ADR	ADR-001 -- ADR-007	7	Обзор
Безопасность	STRIDE модель угроз + SEC-01..06	7	Угрозы
API Reference	Спецификации модулей ядра	10	API
UI-макеты	Figma-файл с аннотациями	53 ноты	Figma
Дизайн-система	Цвета, шрифты, компоненты	6 стр.	Дизайн
SRS	Проект + Документация	2	SRS
Тесты	Unit + Integration (реальный Geth)	180	Тесты
Глоссарий	Термины и аббревиатуры	33	Глоссарий
FAQ	Частые вопросы	16	FAQ

Архитектура

Система реализует строгую слоистую архитектуру. Слою представления (UI) запрещено импортировать Web3, Solidity или криптографические библиотеки напрямую.

┌─────────────────────────────────────┐
│  UI Layer (PyQt6 Widgets + Workers) │
└──────────────┬──────────────────────┘
               ▼
┌─────────────────────────────────────┐
│  AppController (Facade)             │
└──────────────┬──────────────────────┘
               ▼
┌─────────────────────────────────────┐
│  Services (Voting / Audit / Error)  │
└──────────────┬──────────────────────┘
               ▼
┌─────────────────────────────────────┐
│ Infrastructure (Web3 / Geth / Nonce)│
└──────────────┬──────────────────────┘
               ▼
┌─────────────────────────────────────┐
│  VotingCore.sol (Smart Contract)    │
└─────────────────────────────────────┘

Дизайн

UI-макеты с полной системой аннотаций поддерживаются в Figma.

Открыть Figma-файл (только просмотр)

Файл содержит:

• 4 макета вкладок (Admin, Vote, Audit, Logs)
• 5 типов диалогов (Новая сессия, Массовое голосование, Финансирование, Выход, Сброс)
• Вариативные компоненты (StatusBadge, Toast, ProgressBar, LogBox)
• 53 аннотационные ноты с цветовой кодировкой по категориям
• Маркеры-пины, связывающие ноты с элементами интерфейса

Полная спецификация: Дизайн-система | Цветовая палитра | Структура Figma

Скриншоты

Вкладка Admin — деплой контракта, кандидаты, избиратели, управление стадией

Тёмная тема	Светлая тема

Вкладка Голосование — аутентификация, выбор кандидата, QR-квитанция

Тёмная тема	Светлая тема

Вкладка Аудит — SEC-проверки, результаты, экспорт

Тёмная тема	Светлая тема

Вкладка Логи — лог сессии, живой поиск, автопрокрутка

Тёмная тема	Светлая тема

Диалоги — О программе, Сброс блокчейна

О программе	Сброс блокчейна

Быстрый старт

1. Предварительные требования

• Python 3.11+
• Бинарник Go-Ethereum (Geth), размещённый в mycelium-core/bin/ (bin/geth.exe для Windows, bin/geth для Linux/macOS).

2. Установка

git clone https://github.com/AlexAgents/mycelium-core.git
cd mycelium-core/mycelium-core
python -m venv venv

# Windows
venv\Scripts\activate
# Linux/macOS
# source venv/bin/activate

pip install -r requirements.txt
cp .env.example .env

3. Запуск приложения

python main.py

4. Запуск документации (MkDocs)

Для локального рендера UML-диаграмм скачайте plantuml.jar и поместите его в папку docs/.

cd ../../docs
pip install -r requirements-docs.txt
mkdocs serve
# Открыть http://127.0.0.1:8000

Конфигурация

Все параметры времени выполнения настраиваются через .env. Скопируйте .env.example в .env и измените нужные значения.

Режимы Geth

Приложение запускает Geth только в режиме --dev. Это архитектурное решение (см. ADR-002).

Параметр	По умолчанию	Описание
RPC_HOST	127.0.0.1	Хост JSON-RPC Geth
RPC_PORT	8545	Порт JSON-RPC Geth
GETH_NETWORK_ID	1337	ID локальной сети

Параметры транзакций

Параметр	По умолчанию	Описание
DEFAULT_GAS	500000	Лимит газа на транзакцию
DEFAULT_GAS_PRICE	1000000000	Цена газа в Wei (1 Gwei)

Параметры UI — время и таймауты

Захардкожены в коде — при необходимости менять в исходниках:

Константа	Файл	Значение	Описание
_TOAST_DURATION_MS	toast.py	2500	Время показа тоста (мс)
_TOAST_GAP_MS	toast.py	150	Пауза между тостами (мс)
--dev.period	geth_manager.py	5	Интервал блоков (сек)
RPC_WAIT_TIMEOUT_SEC	web3_provider.py	30	Таймаут RPC (сек)
timeout	voting_service.py	120	Таймаут TX (сек)

Dev-режим

Параметр	По умолчанию	Описание
DEV_MODE	true	Включает dev-удобства
DEV_ADMIN_KEY	(пусто)	Автозаполнение admin key
LOG_LEVEL	INFO	DEBUG / INFO / WARNING
SOLIDITY_VERSION	0.8.20	Версия компилятора Solidity

Инварианты безопасности

Критические бизнес-правила обеспечиваются проактивно на уровне смарт-контракта и верифицируются реактивно через AuditService:

Код	Проверка	Контракт	Аудит
SEC-01	Двойной голос	hasVoted[sender]	Нет дублей событий
SEC-02	Whitelist	require(whitelist[sender])	Все в whitelist
SEC-03	Стадия	onlyStage(Active)	Голоса в диапазоне блоков
SEC-04	Кандидаты	require(candidates[c].registered)	Только зарегистрированным
SEC-05	Admin	модификатор onlyOwner	TX от владельца
SEC-06	Целостность	неявно votes += 1	Событий = сумма голосов

Лицензия

Распространяется под лицензией MIT. Подробнее — в файле LICENSE.

Автор: AlexAgents