Este guia é para equipes que integram backends, indexadores ou aplicações à BrightCity Chain Testnet via RPC público e explorer. Não descreve infraestrutura interna do consórcio.

​
Arquitetura recomendada

Separe cliente, backend e acesso à rede. O frontend não deve falar com a chain direamente para operações sensíveis; o backend concentra RPC, filas e segredos.

​
Visão geral

​
Fluxo de leitura vs escrita

​
Papel de cada componente

Interface para usuários e operadores urbanos. Exibe saldos, status de transações e dados indexados vindos do backend. Não armazena private keys de deploy nem de serviço.
Orquestra regras de negócio, autenticação e integração com a testnet. Envia transações assinadas via RPC, persiste transactionHash e blockNumber, e expõe APIs estáveis para o frontend.
Endpoint https://rpc.fmartns.dev para métodos eth_*, net_* e web3_*. Leitura de estado, estimativa de gas e envio de transações já assinadas. Sem debug_*, admin_*, engine_* ou txpool_*.
Consulta humana de blocos, transações, endereços e contratos em explorer.fmartns.dev. Complementa o RPC em suporte, auditoria e validação visual de deploys.
Worker que consome eventos (eth_getLogs) a partir do último bloco salvo. Alimenta banco da aplicação com dados de contratos (IoT, identidade, auditoria). Veja acordeão Indexação de eventos abaixo.

​
Ciclo de uma transação

Valide sempre chainId === 20260520 na inicialização do cliente RPC. Detalhes em Usar o RPC.

​
Checklist de integração

  • Fixe chainId = 20260520 no cliente e valide na inicialização.
  • RPC: https://rpc.fmartns.dev.
  • Não assuma que a rede é Ethereum mainnet ou testnet pública.
  • Aguarde receipt com status de sucesso.
  • Em QBFT estável, 1 confirmação costuma bastar para muitos fluxos; fluxos críticos podem exigir política interna adicional.
  • Persista blockNumber e transactionHash no seu banco.
  • Armazene último bloco processado.
  • Retome de último + 1 após restart.
  • Use filtros por contrato e tópicos de evento; evite varrer toda a chain sem necessidade.
  • Retry com backoff em erros transitórios.
  • Timeout configurável.
  • Não faça polling agressivo; respeite limites razoáveis.
  • Trate erros JSON-RPC explicitamente.
  • Nunca coloque private keys no frontend.
  • Separe contas: usuário final, deployer, serviço backend.
  • Use .env, secret manager ou vault em produção.
  • Nunca use chave de validador em aplicação ou deploy.

​
Envio de transações pelo backend

Quando o backend assina transações:
  1. Carregue chave apenas no servidor.
  2. Estime gas (estimateGas) e defina gasPrice compatível com rede legada.
  3. Envie via eth_sendRawTransaction ou SDK equivalente.
  4. Aguarde receipt e grave hash + bloco.
Detalhes: Gas e transações, Usar o RPC.

​
O que não fazer

  • Depender de debug_*, admin_*, engine_* ou txpool_* no endpoint público.
  • Assumir EIP-1559, blobs ou PUSH0 sem verificar Diferenças em relação ao Ethereum.
  • Expor endpoints internos, métricas ou painéis operacionais na documentação voltada ao usuário.
  • Hardcodar chaves privadas em repositório.

​
Evolução futura

Uma página dedicada a backend/indexer (workers, filas, reprocessamento) pode ser adicionada depois. Por ora, combine este guia com Usar o RPC e Consultar no explorer.

​
Próximos passos

FAQ

Perguntas frequentes

Deploy de contratos

Publicar contratos na testnet