optovia/blockchain

Optovia Blockchain Infrastructure

Блокчейн инфраструктура для отслеживания отгрузок в приватной сети.

Архитектура

Приватная Сеть (Optovia Private Network)

• Платформа: Hyperledger Besu
• Консенсус: Clique (PoA - Proof of Authority)
• Chain ID: 1337
• Совместимость: EVM (Ethereum Virtual Machine)
• Назначение: Хранение полных данных об отгрузках с участием производителя, покупателя и логиста

Контракты

ShipmentTracker.sol

Основной контракт для отслеживания отгрузок в приватной сети.

Функциональность:

• Создание записей об отгрузках
• Управление информацией от производителя, покупателя, логиста
• Отслеживание статуса отгрузки
• Хранение хешей документов (IPFS)
• Ролевая модель доступа (RBAC)
• Upgradeable (UUPS pattern)

Роли:

• ADMIN_ROLE - администратор контракта
• MANUFACTURER_ROLE - производитель
• BUYER_ROLE - покупатель
• LOGISTICS_ROLE - логистический провайдер

Статусы отгрузки:

• Created - создана
• ManufacturerConfirmed - подтверждена производителем
• InTransit - в пути
• Delivered - доставлена
• Cancelled - отменена

Установка

Требования

• Node.js >= 18.x
• Docker и Docker Compose
• Git

Установка зависимостей

cd blockchain
npm install

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

cp .env.example .env
# Отредактируйте .env файл, добавив необходимые ключи

Запуск Приватной Сети

Запуск Besu нодов

cd docker
docker-compose up -d

Это запустит:

• besu-node1 - валидатор на порту 8545 (RPC), 8546 (WS), 8547 (GraphQL)
• besu-node2 - валидатор на порту 8555
• blockscout - block explorer на порту 4000
• postgres - база данных для BlockScout

Проверка статуса сети

# Проверка версии клиента
curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' http://localhost:8545

# Проверка номера блока
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' http://localhost:8545

# Проверка аккаунтов
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}' http://localhost:8545

Block Explorer

Откройте http://localhost:4000 для просмотра блоков и транзакций.

Развертывание Контрактов

В локальной сети разработки (Hardhat)

# Запустить локальную ноду Hardhat
npm run node

# В другом терминале развернуть контракты
npm run deploy:local

В приватной сети Optovia

# Убедитесь, что Besu ноды запущены
npm run deploy:private -- --network optovia

В тестовой сети (Mumbai/Sepolia)

# Настройте PRIVATE_KEY в .env
npm run deploy:testnet -- --network mumbai
# или
npm run deploy:testnet -- --network sepolia

Компиляция и Тестирование

Компиляция контрактов

npm run compile

Запуск тестов

npm test

Проверка покрытия кода

npm run coverage

Использование Контрактов

Создание отгрузки

const shipmentId = await shipmentTracker.createShipment(
  "SHIP-001",                    // externalId
  manufacturerAddress,           // manufacturer address
  "Manufacturer A",              // manufacturer name
  "MFG-001",                     // manufacturer company ID
  buyerAddress,                  // buyer address
  "Buyer B",                     // buyer name
  "BYR-001",                     // buyer company ID
  ethers.keccak256(data)        // data hash
);

Обновление информации о логисте

await shipmentTracker.updateLogisticsInfo(
  shipmentId,
  logisticsAddress,
  "Logistics Provider C",
  "LOG-001",
  ethers.keccak256(logisticsData)
);

Обновление статуса

// Производитель подтверждает отгрузку
await shipmentTracker.connect(manufacturer)
  .updateShipmentStatus(shipmentId, 1); // ManufacturerConfirmed

// Логист отмечает начало доставки
await shipmentTracker.connect(logistics)
  .updateShipmentStatus(shipmentId, 2); // InTransit

// Логист/Покупатель подтверждает доставку
await shipmentTracker.connect(logistics)
  .updateShipmentStatus(shipmentId, 3); // Delivered

Добавление документов

await shipmentTracker.addDocument(
  shipmentId,
  "QmHash123..."  // IPFS hash
);

Минтинг NFT сертификата

// В публичной сети
await shipmentNFT.mintShipmentCertificate(
  buyerAddress,                  // recipient
  "SHIP-001",                    // external shipment ID
  manufacturerAddress,
  buyerAddress,
  logisticsAddress,
  dataHash,                      // hash from private chain
  privateTxHash,                 // transaction hash from private chain
  "ipfs://QmMetadata..."        // token metadata URI
);

Интеграция с Платформой

1. Backend Integration (Python/Django)

Создайте сервис для взаимодействия с блокчейном:

# blockchain/service.py
from web3 import Web3
import json

class BlockchainService:
    def __init__(self):
        self.w3 = Web3(Web3.HTTPProvider('http://besu-node1:8545'))
        with open('deployments/optovia-private.json') as f:
            deployment = json.load(f)
            self.shipment_tracker_address = deployment['contracts']['ShipmentTracker']['address']

        with open('artifacts/contracts/ShipmentTracker.sol/ShipmentTracker.json') as f:
            abi = json.load(f)['abi']
            self.shipment_tracker = self.w3.eth.contract(
                address=self.shipment_tracker_address,
                abi=abi
            )

    def create_shipment(self, shipment_data):
        # Implement shipment creation
        pass

    def update_status(self, shipment_id, status):
        # Implement status update
        pass

2. Конфигурация переменных окружения

# Backend .env
BLOCKCHAIN_RPC_URL=http://besu-node1:8545
BLOCKCHAIN_CHAIN_ID=1337
BLOCKCHAIN_PRIVATE_KEY=<platform_service_private_key>
SHIPMENT_TRACKER_ADDRESS=<deployed_contract_address>
SHIPMENT_NFT_ADDRESS=<deployed_nft_contract_address>

3. Добавление в Docker Compose

# В основном docker-compose.yml
networks:
  optovia-blockchain:
    external: true

services:
  backend:
    # ...
    networks:
      - optovia-blockchain
    environment:
      - BLOCKCHAIN_RPC_URL=http://besu-node1:8545

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

blockchain/
├── contracts/              # Смарт-контракты
│   ├── ShipmentTracker.sol
│   └── ShipmentNFT.sol
├── scripts/               # Скрипты развертывания
│   ├── deploy-local.js
│   ├── deploy-private.js
│   └── deploy-testnet.js
├── test/                  # Тесты
│   └── ShipmentTracker.test.js
├── docker/                # Docker конфигурация
│   ├── docker-compose.yml
│   └── besu/
│       └── genesis.json
├── deployments/           # Информация о развертываниях
├── hardhat.config.js      # Конфигурация Hardhat
├── package.json
└── README.md

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

Приватные ключи

• НИКОГДА не коммитьте .env файл
• Используйте безопасное хранилище для production ключей (Infisical, Vault)
• Для development используйте тестовые аккаунты

Контракты

• Используется upgradeable pattern (UUPS)
• Ролевая модель доступа (AccessControl)
• Функция паузы для экстренных ситуаций

Сеть

• Приватная сеть доступна только внутри Docker network
• RPC endpoints не должны быть доступны публично
• Используйте firewall для ограничения доступа

Мониторинг

Логи Besu

docker logs -f optovia-besu-node1
docker logs -f optovia-besu-node2

Метрики

Besu предоставляет Prometheus метрики на порту 9545 (нужно включить):

# Добавьте в docker-compose.yml
--metrics-enabled
--metrics-host=0.0.0.0
--metrics-port=9545

Бэкап

Бэкап данных блокчейна

# Остановить ноды
docker-compose down

# Создать бэкап
tar -czf besu-backup-$(date +%Y%m%d).tar.gz docker/besu/node1 docker/besu/node2

# Запустить ноды
docker-compose up -d

Roadmap

Фаза 1 (Текущая)

• ✅ Приватная EVM-совместимая сеть
• ✅ Контракт для отслеживания отгрузок
• ✅ NFT контракт для публичного минтинга
• ✅ Docker инфраструктура

Фаза 2

• Интеграция с Odoo
• API для взаимодействия с контрактами
• IPFS интеграция для документов
• Bridge для связи приватной и публичной сети

Фаза 3

• Оракулы для внешних данных
• Автоматические переходы статусов
• Интеграция с IoT устройствами
• Mobile SDK для производителей/покупателей

Поддержка

Для вопросов и предложений создавайте issues в репозитории.

Лицензия

MIT