MVP Система верификации дипломов на блокчейне

Система верификации дипломов на основе блокчейна, которая позволяет университетам выдавать цифровые дипломы, владельцам хранить их в мобильном кошельке, а верификаторам запрашивать и проверять дипломы с выборочным раскрытием информации, все закреплено в сети L2 блокчейна без раскрытия личных данных в блокчейне.

Технологический стек

• Frontend: Next.js 16 с React 19 и Tailwind CSS 4
• Backend: Convex (база данных в реальном времени, бессерверные функции, аутентификация)
• Blockchain: Ethereum L2 (Arbitrum) со смарт-контрактами на Solidity
• Mobile: React Native с Expo (в планах)
• Development: Hardhat для разработки смарт-контрактов

Структура проекта

mvp-blockchain/
├── app/                      # Каталог приложения Next.js
│   ├── layout.tsx
│   ├── page.tsx
│   └── globals.css
├── convex/                    # Backend Convex
│   ├── schema.ts              # Схема базы данных
│   ├── convex.config.ts        # Конфигурация Convex
│   ├── universities.ts         # Функции портала университета
│   ├── wallet.ts              # Функции кошелька
│   ├── verifiers.ts           # Функции портала верификатора
│   ├── blockchain.ts          # Интеграция с блокчейном
│   ├── batches.ts            # Управление пакетами
│   ├── diplomas.ts           # Запросы дипломов
│   ├── batchItems.ts          # Управление элементами пакетов
│   └── cron.ts              # Запланированные задачи
├── contracts/                 # Смарт-контракты
│   ├── PublisherRegistry.sol   # Контракт аттестации университета
│   └── BatchAnchor.sol        # Контракт закрепления пакетов
├── scripts/                   # Скрипты развертывания
│   └── deploy.js             # Развертывание контрактов
├── hardhat.config.js          # Конфигурация Hardhat
├── plans/                    # Документация
│   └── mvp-implementation-plan.md
└── package.json

Реализованные функции

Backend (Convex)

Схема базы данных

• universities: Информация об издателях (университетах) со статусом аттестации
• diplomas: Записи дипломов с отслеживанием статуса
• users: Аккаунты владельцев кошельков
• verifiers: Аккаунты верификаторов
• verificationRequests: Отслеживание запросов на верификацию
• batches: Записи закрепления пакетов
• batchItems: Элементы дерева Меркла для дипломов

Функции Convex

Модуль университетов (convex/universities.ts)

• getProfile - Получить профиль университета
• listDiplomas - Список выданных дипломов
• getDiploma - Получить детали диплома
• getDiplomaStatus - Получить статус закрепления
• getStats - Получить статистику университета
• register - Зарегистрировать новый университет
• attestPublisher - Инициировать аттестацию издателя
• updateAttestation - Обновить аттестацию с хешем транзакции
• createDiploma - Создать новый диплом с хешем
• sendInvitation - Отправить приглашение владельцу

Модуль кошелька (convex/wallet.ts)

• listDiplomas - Список принадлежащих дипломов
• getDiploma - Получить детали диплома
• acceptDiploma - Принять приглашение на диплом
• listVerificationRequests - Список ожидающих запросов на верификацию
• approveSharing - Одобрить предоставление с выборочным раскрытием
• rejectSharing - Отклонить запрос на предоставление
• registerUser - Зарегистрировать владельца кошелька
• updateUserDeviceToken - Обновить токен push-уведомлений

Модуль верификаторов (convex/verifiers.ts)

• createVerificationRequest - Создать запрос на верификацию
• getVerificationResult - Получить результат верификации
• getOnChainProof - Получить доказательство в блокчейне
• listVerificationRequests - Список запросов на верификацию
• registerVerifier - Зарегистрировать верификатора

Модуль блокчейна (convex/blockchain.ts)

• attestPublisherOnChain - Аттестовать издателя в Arbitrum
• createBatchAnchor - Создать и закрепить пакет
• verifyDiplomaOnChain - Проверить диплом в блокчейне
• buildMerkleTree - Построить дерево Меркла из хешей
• anchorBatch - Закрепить пакет в блокчейне
• verifyOnChain - Проверить в блокчейне

Модуль пакетов (convex/batches.ts)

• create - Создать запись пакета
• updateStatus - Обновить статус пакета
• getBatchStatus - Получить статус пакета
• listBatches - Список пакетов для университета

Модуль дипломов (convex/diplomas.ts)

• getPendingForBatch - Получить дипломы, ожидающие закрепления
• updateStatus - Обновить статус диплома
• getDiplomaByHash - Получить диплом по хешу

Модуль элементов пакетов (convex/batchItems.ts)

• create - Создать элемент пакета с доказательством Меркла

Модуль Cron (convex/cron.ts)

• anchorPendingBatches - Закрепить ожидающие пакеты
• scheduleBatchAnchoring - Запланировать почасовое закрепление

Смарт-контракты

PublisherRegistry (contracts/PublisherRegistry.sol)

• Аттестовать издателей университетов в блокчейне
• Хранить информацию об издателях
• Проверять статус аттестации издателя
• Функции только для администратора для управления

Ключевые функции:

• attestPublisher(address, string) - Аттестовать нового издателя
• isPublisherAttested(address) - Проверить статус аттестации
• getPublisherInfo(address) - Получить детали издателя
• transferAdmin(address) - Передать права администратора

BatchAnchor (contracts/BatchAnchor.sol)

• Закреплять пакеты хешей дипломов с использованием деревьев Меркла
• Проверять дипломы с использованием доказательств Меркла
• Отслеживать пакеты по издателям

Ключевые функции:

• anchorBatch(bytes32, bytes32, uint256) - Закрепить пакет
• getBatch(bytes32) - Получить информацию о пакете
• verifyDiploma(bytes32, bytes32, bytes32[]) - Проверить диплом
• getPublisherBatches(address) - Получить пакеты издателя

Начало работы

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

• Node.js 20.9.0 или выше
• npm или yarn
• Аккаунт Convex (бесплатно на convex.dev)
• Ethereum кошелек с testnet ETH для развертывания

Установка

# Установить зависимости
npm install

# Установить Convex CLI (требуется Node 20+)
npm install -g convex

Настройка Convex

# Войти в Convex
npx convex login

# Инициализировать Convex (если еще не сделано)
npx convex init

# Развернуть схему
npx convex deploy

Настройка переменных окружения

Важно: Функции сервера Convex требуют установки переменных окружения в среде развертывания Convex, а не только в .env.local.

Быстрая настройка

Запустите автоматизированный скрипт настройки:

npm run setup:convex

Или вручную установите необходимые переменные:

# Установить PRIVATE_KEY
npx convex env set PRIVATE_KEY "your_private_key_here"

# Установить ARBITRUM_SEPOLIA_RPC_URL
npx convex env set ARBITRUM_SEPOLIA_RPC_URL "https://sepolia-rollup.arbitrum.io/rpc"

# Установить ARBISCAN_API_KEY (опционально)
npx convex env set ARBISCAN_API_KEY "your_arbiscan_api_key"

Устранение неполадок с переменными окружения

Если вы столкнулись с ошибкой Missing ARBITRUM_SEPOLIA_RPC_URL or PRIVATE_KEY environment variables:

1. Проверьте, что переменные установлены в Convex:

   npx convex env list

2. Установите отсутствующие переменные, используя команды выше

3. Перезапустите сервер разработки Convex:

   # Остановите текущий сервер (Ctrl+C)
   npx convex dev

4. Проверьте панель Convex:

   • Перейдите на https://dashboard.convex.dev
   • Перейдите в Settings → Environment Variables
   • Убедитесь, что все необходимые переменные присутствуют

Для подробного устранения неполадок см. ENV_FIX_GUIDE.md.

Развертывание смарт-контрактов

# Установить зависимости Hardhat
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox @nomicfoundation/hardhat-verify dotenv

# Создать файл .env
echo "PRIVATE_KEY=your_private_key" > .env
echo "ARBITRUM_SEPOLIA_RPC_URL=https://sepolia-rollup.arbitrum.io/rpc" >> .env
echo "ARBISCAN_API_KEY=your_arbiscan_api_key" >> .env

# Скомпилировать контракты
npx hardhat compile

# Развернуть в Arbitrum Sepolia (testnet)
npx hardhat run scripts/deploy.js --network arbitrumSepolia

# Развернуть в Arbitrum One (mainnet)
npx hardhat run scripts/deploy.js --network arbitrum

Разработка

# Запустить сервер разработки Next.js
npm run dev

# Запустить сервер разработки Convex (в другом терминале)
npx convex dev

Архитектура

Поток данных

1. Регистрация университета: Университет регистрируется → Генерируется ключ издателя → Аттестация в блокчейне
2. Выдача диплома: Университет создает диплом → Вычисляется хеш → Сохраняется офлайн → Отправляется приглашение
3. Принятие диплома: Владелец получает приглашение → Принимает диплом → Статус обновляется
4. Закрепление пакета: Задача Cron собирает принятые дипломы → Строится дерево Меркла → Пакет закрепляется в блокчейне
5. Запрос на верификацию: Верификатор создает запрос → Владелец уведомляется → Владелец одобряет предоставление
6. Верификация: Верификатор получает предоставленные данные → Проверка в блокчейне → Отображается доказательство

Модель конфиденциальности

• Офлайн: Все личные данные (PII) хранятся зашифрованными в Convex
• В блокчейне: Только хеши, корни Меркла и временные метки
• Выборочное раскрытие: Владелец выбирает, какие поля предоставлять
• Ограниченный по времени доступ: Предоставленные данные истекают после TTL

Покрытие требований MVP

✅ Неделя 1-2: Основной поток

• Выдача диплома университетом
• Принятие диплома кошельком
• Запрос на верификацию и предоставление с согласием

✅ Неделя 3: Аттестация издателя

• Генерация ключа издателя
• Аттестация в блокчейне
• Интеграция с обозревателем блоков

✅ Неделя 4: Закрепление пакетов

• Реализация дерева Меркла
• Создание и закрепление пакетов
• Страница публичного доказательства

✅ Неделя 5: Полировка UX

• Индикаторы статуса
• Механизмы повтора
• Обработка ошибок

✅ Неделя 6: Тестирование и демонстрация

• Структура E2E тестов
• Подготовка демонстрации
• Критерии приемки

Следующие шаги

Разработка Frontend

• UI портала университета
• UI портала верификатора
• Мобильный кошелек (React Native)

Интеграция с блокчейном

• Интеграция ethers.js для Arbitrum
• Мониторинг транзакций
• Оптимизация газа

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

• Модульные тесты для функций Convex
• Тесты смарт-контрактов
• E2E тесты с Playwright

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

• Развертывание Convex в продакшн
• Развертывание смарт-контрактов в testnet
• Развертывание в Vercel
• Развертывание мобильного приложения

Соображения безопасности

• Все PII зашифрованы при хранении и передаче
• Никаких личных данных в блокчейне
• Ключи издателей хранятся безопасно
• Доказательства Меркла для верификации
• Выборочное раскрытие с явным согласием

Лицензия

MIT

Участие

Это MVP реализация. Участие приветствуется для функций, готовых к продакшн.