Arquitetura da plataforma - BrightCity Chain

A plataforma atual combina microsserviços Django, comunicação interna HTTP ou gRPC, InfluxDB, MongoDB, PostgreSQL e contratos na BrightCity Chain.

Visão geral

Serviços

Repositório	Responsabilidade
`blockchain-gateway-service`	API pública, Keycloak, permissões e orquestração
`blockchain-auth-service`	Vínculo `sensor_admin` por usuário e sensor
`blockchain-meters-service`	Cadastro de sensores e medições em InfluxDB
`blockchain-market-service`	Políticas de preço, ofertas, ordens, trades e matching via Celery Beat
`blockchain-transactions-service`	Operações on-chain, preparação e validação de pagamentos
`blockchain-oracle-service`	Pedidos de bridge, verificação de depósitos e expiração via Celery Beat
`blockchain-indexer-service`	Indexação periódica de eventos da Besu via Celery Beat
`blockchain-device-simulator`	Simulador de smart meter e worker de pagamentos
`blockchain-grpc-protos`	Contratos Protocol Buffer de comunicação interna
`blockchain-contracts`	Contratos MVP `EuroToken`, `SensorRegistry`, `EnergyMarket`, `EnergySettlement` e scripts Hardhat

Rotinas periódicas (Celery)

Market, Indexer e Oracle usam Celery worker + Beat com Redis dedicado por serviço (não compartilhar broker entre microsserviços).

Serviço	Task	Intervalo (env)
Market	`core.tasks.run_matching_cycle_task`	`MATCHING_CYCLE_MINUTES` (default 15)
Indexer	`core.tasks.index_events_task`	`INDEXER_POLL_SECONDS` (default 30)
Oracle	`core.tasks.expire_stale_deposits_task`	`DEPOSIT_EXPIRY_POLL_MINUTES` (default 15)

Variáveis comuns: CELERY_BROKER_URL, CELERY_RESULT_BACKEND. Deploy: containers Redis + celery worker + celery beat por serviço.

Contratos MVP em uso

O runtime atual usa estes contratos pelos ABIs versionados nos serviços Transactions e Indexer:

Contrato	Uso
`EuroToken`	ERC-20 privado `Euro Token`, símbolo `EURT`, 18 decimais, `mint` e `transfer`
`SensorRegistry`	Registro on-chain de sensores, carteira e estado habilitado
`EnergyMarket`	Ofertas e compras on-chain do mercado MVP
`EnergySettlement`	Registro de liquidação energética entre comprador e vendedor

Deploy local Besu registrado:

Contrato	Endereço
`EuroToken`	`0x96A2b35b4C814EE43EDdfbAEf26F63b4cCe9A8A8`
`SensorRegistry`	`0xe13336b13382d3399240E4E2b5D6f894BF1ca547`
`EnergyMarket`	`0x0B99052f60121d1Ae5045c374562E56405e4Cae6`
`EnergySettlement`	`0x170e00134e02D6C84a4b18773D33ccf749C922C5`

O arquivo de deploy também registra chainId: 20260520.

A bridge externa usa EURC na rede principal configurada. Na BrightCity Chain privada, o contrato EuroToken representa o saldo interno com nome Euro Token, símbolo EURT e 18 decimais.

Papéis on-chain

Contrato	Papel	Uso
`EuroToken`	`DEFAULT_ADMIN_ROLE`	Administra papéis do token
`EuroToken`	`MINTER_ROLE`	Executa `mint` após aprovação do bridge
`SensorRegistry`	`DEFAULT_ADMIN_ROLE`	Administra papéis do registro
`SensorRegistry`	`REGISTRAR_ROLE`	Registra, habilita e desabilita sensores
`EnergyMarket`	`DEFAULT_ADMIN_ROLE`	Administra papéis do mercado
`EnergyMarket`	`OPERATOR_ROLE`	Cria, cancela e compra ofertas on-chain
`EnergySettlement`	`DEFAULT_ADMIN_ROLE`	Administra papéis de liquidação
`EnergySettlement`	`OPERATOR_ROLE`	Registra liquidações on-chain

Funções chamadas pelo backend

Serviço	Contrato	Função
Transactions	`EuroToken`	`mint(to, amount)`
Transactions	`EuroToken`	`transfer(to, value)`, preparado sem assinatura para o device comprador
Transactions	`SensorRegistry`	`registerSensor(sensorId, wallet)`
Transactions	`SensorRegistry`	`enableSensor(sensorId)` e `disableSensor(sensorId)`, disponíveis no contrato
Transactions	`EnergyMarket`	`createOffer(sellerSensorId, kwh, pricePerKwh)`
Transactions	`EnergyMarket`	`purchaseOffer(offerId, buyerSensorId, seller, buyer)`, operação on-chain com `transferFrom`
Transactions	`EnergySettlement`	`settle(buyerSensorId, sellerSensorId, kwh, price)`

sensor_id é convertido para bytes32 antes de ir para contratos MVP. Por isso, identificadores usados on-chain precisam caber em 32 bytes quando codificados em UTF-8.

O fluxo automático do Market prepara EuroToken.transfer para assinatura pelo device comprador. A função purchaseOffer fica disponível para operações on-chain com allowance via transferFrom.

Estados on-chain

Contrato	Estado	Valores
`SensorRegistry`	`enabled`	`true` ou `false`
`EnergyMarket`	`OfferStatus`	`OPEN`, `SOLD`, `CANCELLED`

O Market Service também mantém status operacionais nos modelos off-chain: RESERVED, FILLED, PENDING_PAYMENT, PAID e ERROR.

Eventos indexados

O Indexer lê estes eventos:

Contrato	Evento
`EuroToken`	`EuroMinted`
`SensorRegistry`	`SensorRegistered`
`EnergyMarket`	`EnergyOfferCreated`
`EnergyMarket`	`EnergyOfferPurchased`
`EnergySettlement`	`SettlementCreated`

Cada evento indexado é salvo com contract_name, event_name, block_number, tx_hash, log_index e payload_json. A chave única é tx_hash + log_index.

gRPC interno

Os serviços mantêm rotas HTTP internas durante a migração, mas os protos já cobrem os principais fluxos:

Serviço gRPC	Porta padrão	Principais RPCs
`MetersService`	`5049`	`GetSensor`, `RegisterBootSensor`, `AddMeasurement`, `ListMeasurements`
`TransactionsService`	`5050`	`ListPendingPayments`, `PrepareEnergyPayment`, `SubmitEnergyPaymentReceipt`, `RegisterSensorOnChain`
`MarketService`	`5051`	`ConfirmTradeReceipt`, `MarkTradeError`

Autorização interna usa metadata x-internal-token, equivalente ao header HTTP X-Internal-Token.

​Visão geral

​Serviços

​Rotinas periódicas (Celery)

​Contratos MVP em uso

​Papéis on-chain

​Funções chamadas pelo backend

​Estados on-chain

​Eventos indexados

​gRPC interno

Visão geral

Serviços

Rotinas periódicas (Celery)

Contratos MVP em uso

Papéis on-chain

Funções chamadas pelo backend

Estados on-chain

Eventos indexados

gRPC interno