QBFT Enterprise Network — Hyperledger Besu

Red blockchain privada con consenso QBFT sobre Hyperledger Besu 22.10.3, desplegada con un solo Docker Compose.

graph LR
    U[Usuarios] -->|:80 + API Key| GW[Gateway Nginx]
    GW -->|/tx/| RPC[RPC Nodes x2]
    GW -->|/query/| OBS[Observer]
    GW -->|/explorer/| LE[Lite Explorer]
    RPC -->|P2P :30301| VAL[Validadores x4]
    VAL -->|QBFT| VAL
    OBS -->|RPC| BS[Blockscout]
    BS --> PG[(PostgreSQL)]
    OBS -->|sync| ARC[Archive]

Loading

Stack completo

Componente	Servicios	Perfil docker compose
Red P2P	Bootnode + 4 validadores	core
Transacciones	2 RPC nodes + Gateway Nginx	rpc
Consultas	Observer + Archive node	observability
Exploradores	Blockscout + Lite Explorer + PostgreSQL	explorer
Storage	IPFS	storage
dApp	Frontend MetaMask + Web3.js + Ethers.js	dapp
Monitoreo	Prometheus + Grafana + Node Exporter	monitoring
Todo	Todos los anteriores	all

Inicio rápido

# 1. Generar llaves para todos los nodos
./scripts/generate-all-keys.sh

# 2. Generar archivo de bootnodes
./scripts/bootnodes.sh

# 3. Desplegar stack completo
docker compose -f qbft-network-full.yaml --profile all up -d

# 4. Verificar
curl http://localhost/health
curl -X POST http://localhost/query/ -H "X-API-Key: ak-master-001" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# Stack mínimo (red + validadores, sin RPC ni explorers)
docker compose -f qbft-network-full.yaml --profile core up -d

# Sin explorers
docker compose -f qbft-network-full.yaml --profile core --profile rpc --profile observability up -d

Documentación

Doc	Descripción
docs/01-architecture-overview.md	Topología, 4 capas, protocolos, diagramas de secuencia, IPs, puertos
docs/02-node-roles.md	Roles de cada nodo: bootnode, validador, RPC, observer, archive
docs/03-gateway-api-keys.md	Gateway Nginx con autenticación por API Key
docs/04-smart-contracts.md	Proyecto Hardhat, SBT (intransferible), ERC-1155
docs/05-ipfs-storage.md	IPFS para almacenamiento descentralizado
docs/06-metamask-web3.md	Conexión de MetaMask y Web3.js/Ethers
docs/07-tx-lifecycle.md	Ciclo de vida de una transacción
docs/08-genesis-reference.md	Referencia del genesis.json: QBFT params, reward schedule, contratos pre-desplegados
docs/09-permissioning-contracts.md	Permissioning on-chain: elección de validadores, account/node ingress
docs/10-scripts-reference.md	Referencia de scripts con diagramas de flujo
docs/11-dapp-reference.md	dApp frontend: MetaMask, Web3.js, Ethers.js, mint SBT, IPFS upload
docs/12-monitoring.md	Monitoreo: Prometheus, Grafana, Node Exporter, métricas, dashboard
docs/13-devops-guide.md	DevOps: tests, CI/CD, backup/restore, verificación Blockscout, .env
docs/14-observability.md	Observabilidad: Loki logs, alertas Grafana, LogQL queries
docs/15-node-bootnode.md	Bootnode — Kademlia DHT, discv4, flujo de bootstrap
docs/16-node-validator.md	Validator — QBFT 4 fases, clave sellado, umbral BFT
docs/17-node-rpc.md	RPC Node — JSON-RPC, WebSocket, APIs, TxPool
docs/18-node-gateway.md	Gateway — Nginx, API keys, rate limiting, routing
docs/19-node-observer.md	Observer — snap sync, Blockscout feed, watchtower
docs/20-node-archive.md	Archive — Forest full state, TRACE/DEBUG, auditoría
docs/21-node-combined.md	Combined Node — multifunción dev, combinaciones
docs/22-use-case-diploma.md	Diploma — SBT soulbound, IPFS metadata, verificación
docs/23-technology-stack.md	Tech Stack — versiones, imágenes, puertos, config

Comandos útiles

# Logs de servicios específicos
docker compose -f qbft-network-full.yaml logs -f validator-1 validator-2

# Detener todo
docker compose -f qbft-network-full.yaml down

# Limpiar volúmenes de datos (borra la blockchain)
docker compose -f qbft-network-full.yaml down -v

# Acceso a exploradores
# http://localhost/explorer/  (vía gateway)
# http://localhost:4000       (Blockscout directo)
# http://localhost:8080       (Lite Explorer directo)

# Acceso a dApp
# http://localhost:3001       (directo)
# http://localhost/dapp/      (vía gateway, requiere API Key)

# Acceso a monitoreo
# http://localhost:3000       (Grafana, admin/admin)
# http://localhost:9090       (Prometheus)

# API Key disponibles: ak-master-001, ak-app-tx-001, ak-app-query-001, ak-monitor-001

dApp de Ejemplo

Aplicación frontend en dapp/ que integra MetaMask, Web3.js y Ethers.js:

Funcionalidad	Descripción
Wallet	Conectar MetaMask, switch a QBFT network, ver balance
Mint SBT	Mintear Soulbound Tokens con metadata IPFS
Transfer MultiToken	Transferir tokens ERC-1155
IPFS Upload	Subir archivos a IPFS + generar metadata
Token Query	Consultar SBTs y MultiTokens de cualquier address
Toggle Library	Cambiar entre Web3.js y Ethers.js en tiempo real

docker compose -f qbft-network-full.yaml --profile dapp up -d
# http://localhost:3001  o  http://localhost/dapp/ (con API Key)

Monitoreo

Stack completo de monitoreo con Prometheus + Grafana + Node Exporter:

docker compose -f qbft-network-full.yaml --profile monitoring up -d
# Grafana: http://localhost:3000 (admin/admin)
# Prometheus: http://localhost:9090

Todos los nodos Besu exponen métricas en puerto 9545. Dashboard pre-configurado con block height, peers, gas price, memoria y más.

Smart Contracts

Proyecto Hardhat en contracts/ con:

Contrato	Estándar	Propósito
SBT.sol	ERC-721URIStorage + AccessControl	Credenciales intransferibles (soulbound)
MultiToken.sol	ERC-1155	Activos fungibles y no fungibles

cd contracts
npm install
npx hardhat compile
npx hardhat test                          # 20+ tests
npx hardhat run scripts/deploy.js --network besu           # Deploy
npx hardhat run scripts/deploy-and-verify.js --network besu # Deploy + verify

Configuración

Archivo	Propósito
qbft-network-full.yaml	Docker Compose completo con todos los servicios
config/bootnode.env	Variables de entorno para bootnode
config/validator.env	Variables de entorno para validadores
config/rpc-node.env	Variables de entorno para RPC nodes
config/observer.env	Variables de entorno para observer
config/archive.env	Variables de entorno para archive
config/gateway/nginx.conf	Nginx con API Key auth y rate limiting
config/gateway/api_keys.conf	Definición de API Keys
config/blockscout.env	Configuración compartida de Blockscout
config/prometheus/prometheus.yml	Targets de scraping para Prometheus
config/grafana/datasources/prometheus.yaml	Datasource Prometheus para Grafana
config/grafana/dashboards/besu-overview.json	Dashboard Grafana de la red Besu
dapp/contract-config.json	Direcciones y ABIs de contratos para la dApp
dapp/nginx.conf	Nginx config para la dApp
config/loki/loki-config.yml	Configuración de Loki (log store)
config/promtail/promtail-config.yml	Configuración de Promtail (log collector)
config/grafana/datasources/loki.yaml	Datasource Loki para Grafana
config/grafana/alerting/besu-alerts.yml	Reglas de alerta para nodos Besu
.env.example	Variables de entorno configurables
.github/workflows/ci.yml	CI: tests, YAML lint, shellcheck
genesis.json	Genesis de la red (chain ID 1522)

Tests

cd contracts
npm test
# 20+ tests cubriendo SBT y MultiToken

CI/CD

GitHub Actions en .github/workflows/ci.yml corre en cada push/PR:

• hardhat compile + hardhat test
• Validación sintaxis YAML y scripts
• Verificación de referencias en documentación

Backup y Restore

# Backup completo (volúmenes + configuración)
./scripts/backup.sh

# Restaurar
./scripts/restore.sh 20250622_143022

Verificación en Blockscout

cd contracts
npm run deploy:verify   # Deploy + verify automático

Scripts

Script	Propósito
scripts/generate-all-keys.sh	Genera keys para bootnode + 4 validadores + 2 RPC nodes
scripts/bootnodes.sh	Genera bootnodes.env apuntando al bootnode
scripts/new_key.sh	Genera un par de llaves individual
scripts/initialValidators.sh	Genera archivo genesis con validadores iniciales
scripts/permissioning-smart-contracts.sh	Despliega contratos de permissioning
scripts/backup.sh	Backup de volúmenes Docker y configuración
scripts/restore.sh	Restaura volúmenes desde un backup