# Backend Services Esta página fornece uma visão geral abrangente de todos os serviços backend do Decentraland, seus papéis arquiteturais e como interagem dentro do ecossistema. Para especificações detalhadas de API e endpoints, consulte o [Referência de API](https://github.com/decentraland/docs/blob/main/apis/README.md) seção. ## Arquitetura de Serviço O backend do Decentraland é composto por microserviços distribuídos organizados em camadas lógicas: * **Camada Descentralizada** - Rede Catalyst e infraestrutura de entrega de conteúdo * **Camada de Comunicações em Tempo Real** - Descoberta de serviços e comunicações peer-to-peer * **Serviços de Funcionalidade** - Funcionalidade voltada ao usuário (conteúdo, economia, gamificação) * **Serviços Centrais** - Infraestrutura essencial da plataforma (auth, marketplace, notifications) *** ## Camada Descentralizada ### Catalyst **Propósito**: Rede de entrega de conteúdo descentralizada A rede Catalyst forma a base da infraestrutura de conteúdo do Decentraland. Cada nó Catalyst é um servidor completo que fornece: * **Content Server** - Armazenamento e recuperação de entidades (scenes, profiles, wearables) * **Serviço Lambdas** - Endpoints utilitários e consultas de conteúdo * **Servidor de Comunicações** - Transporte de mensagens em tempo real **Papel Arquitetural**: Os nós Catalyst são distribuídos geograficamente e permissionless. A rede fornece redundância e disponibilidade de conteúdo sem controle central. **Integrações Principais**: * Realm Provider - Anuncia disponibilidade do nó * Asset Bundle Registry - Aciona otimização de ativos no deployment * Archipelago Workers - Fornece dados de ilha/cluster **Referência de API**: [API do Catalyst](https://github.com/decentraland/docs/blob/main/apis/catalyst/overview/README.md) ### Lamb2 **Propósito**: Utilitários Lambda e funções serverless Lamb2 fornece endpoints utilitários para consumo de conteúdo e consultas que complementam o Content Server: * Agregação e filtragem de scenes * Consultas de profile com fallbacks * Verificações de status e health checks **Papel Arquitetural**: Atua como uma camada de conveniência sobre o acesso bruto a entidades do Content Server, fornecendo padrões de consulta de nível mais alto comumente necessários pelos clientes. **Referência de API**: [Lamb2 API](https://github.com/decentraland/docs/blob/main/apis/lamb2/overview/README.md) *** ## Camada de Comunicações em Tempo Real ### Realm Provider **Propósito**: Descoberta de serviços e seleção de realm O Realm Provider é o ponto de entrada para todos os clientes do Decentraland. Ele implementa seleção inteligente de realm com base em: * **Otimização geográfica** - Roteia usuários para os nós Catalyst mais próximos * **Monitoramento de saúde** - Filtra nós com problemas ou sobrecarregados * **Rastreamento de capacidade** - Fornece contagens de usuários por realm em tempo real * **Agregação de cenas populares** - Identifica locais populares em todos os realms **Papel Arquitetural**: Fonte única de verdade para a infraestrutura disponível. Os clientes consultam-no uma vez na inicialização para descobrir todos os endpoints de serviço (Catalyst, Comms, BFF). **Integrações Principais**: * Consulta todos os nós Catalyst periodicamente * Agrega estatísticas do Archipelago * Fornece visão unificada da rede distribuída **Referência de API**: [Realm Provider API](https://github.com/decentraland/docs/blob/main/apis/realm-provider/overview/README.md) ### Comms Gatekeeper **Propósito**: Controle de acesso a voz e vídeo O Gatekeeper gerencia o acesso aos servidores de mídia LiveKit para chat de voz e vídeo: * **Geração de tokens** - Cria tokens de acesso com tempo limitado e permissões específicas * **Administração de scenes** - Gerencia direitos de admin de scene e banimentos * **Gerenciamento de stream** - Controla acesso a transmissão ao vivo e chaves RTMP * **Controles de privacidade** - Impõe permissões de chat de voz privado **Papel Arquitetural**: Camada de segurança entre clientes e infraestrutura de mídia. Evita acesso não autorizado enquanto habilita modelos de permissão flexíveis (baseados em scene, privado, comunidade). **Integrações Principais**: * LiveKit - Emite tokens JWT para acesso ao servidor de mídia * Worlds API - Valida propriedade de world para direitos de admin * Signed Fetch - Autentica todas as requisições via assinaturas de wallet **Referência de API**: [Comms Gatekeeper API](https://github.com/decentraland/docs/blob/main/apis/comms-gatekeeper/overview/README.md) ### Archipelago Workers **Propósito**: Agrupamento de comunicações e roteamento de mensagens Archipelago implementa o protocolo de clustering baseado em proximidade que agrupa jogadores próximos em "ilhas": * **Transporte WebSocket** - Mantém conexões persistentes com clientes * **Rastreamento de posição** - Monitora localizações dos jogadores em tempo real * **Formação de ilhas** - Agrupa dinamicamente jogadores com base na distância * **Roteamento de mensagens** - Encaminha mensagens apenas para membros da ilha **Componentes da Arquitetura**: * **Conector WebSocket** - Lida com conexões de clientes e autenticação * **Núcleo do Archipelago** - Implementa algoritmo de clustering e gerenciamento de ilhas * **Serviço de Estatísticas** - Fornece métricas de conexão e contagens de usuários * **Integração com NATS** - Publica atualizações de posição e roteia mensagens **Papel Arquitetural**: Otimiza comunicações peer-to-peer limitando o fanout de mensagens. Em vez de transmitir para todos os usuários em um realm, as mensagens alcançam apenas jogadores dentro do alcance de interação. **Integrações Principais**: * Broker de mensagens NATS - Roteamento distribuído de mensagens * Realm Provider - Fornece estatísticas de ilhas * Places API - Dados de contagem de usuários para cenas populares **Referência de API**: [API dos Archipelago Workers](https://github.com/decentraland/docs/blob/main/apis/archipelago-workers/overview/README.md) *** ## Serviços de Funcionalidade ### Worlds **Propósito**: Hospedagem isolada de scenes fora da grade principal Worlds permite que usuários implantem scenes em ambientes isolados: * **Worlds nomeados** - Acessível via URLs personalizadas (por exemplo, `world.dclworlds.com`) * **Worlds privados** - Controle de acesso gateado por NFT * **Permissões de World** - Direitos de admin e deployment gerenciados pelo owner **Papel Arquitetural**: Estende o modelo de conteúdo do Decentraland além da grade fixa de LAND. Cada world é uma scene independente com seus próprios canais de comunicação e controle de acesso. **Integrações Principais**: * Consulta indexadores de blockchain para verificação de propriedade de NFT * Publica atualizações de world para NATS para sincronização de clientes em tempo real * Integra-se com Comms Gatekeeper para salas de chat de voz * Aciona pipeline de processamento de ativos no deployment **Referência de API**: [Worlds API](https://github.com/decentraland/docs/blob/main/apis/worlds/overview/README.md) ### Eventos **Propósito**: Gestão e descoberta de eventos in-world Gerencia o ciclo de vida completo de eventos virtuais: * **CRUD de eventos** - Criação, atualizações e agendamento * **Rastreamento de participantes** - Participação de usuários e RSVPs * **Descoberta** - Consultas e filtragem baseadas em tempo * **Notificações** - Integração com Events Notifier **Papel Arquitetural**: Fornece contexto temporal ao metaverso. Eventos impulsionam descoberta e engajamento de usuários ao destacar experiências sensíveis ao tempo. **Referência de API**: [Events API](https://github.com/decentraland/docs/blob/main/apis/events/overview/README.md) ### Places **Propósito**: Descoberta e curadoria de pontos de interesse Agrega e seleciona locais interessantes pelo Decentraland: * **Cenas populares** - Popularidade em tempo real baseada em contagens de usuários * **Lugares em destaque** - Locais selecionados editorialmente * **Busca e filtragem** - Descoberta por tags, categorias * **Metadados de POI** - Descrições, miniaturas, coordenadas **Papel Arquitetural**: Resolve o problema de descoberta em um grande mundo aberto. Agrega dados de múltiplas fontes para ajudar usuários a encontrar conteúdo envolvente. **Integrações Principais**: * Catalyst - Metadados de scene e informações de deployment * Archipelago Stats - Contagens de usuários por scene em tempo real * Comms Gatekeeper - Disponibilidade e status de realm **Referência de API**: [Places API](https://github.com/decentraland/docs/blob/main/apis/places/overview/README.md) ### Atlas Server **Propósito**: Dados de mapa e visualização de parcelas Fornece dados abrangentes do mapa mundial: * **Propriedade de parcel** - Dados de LAND indexados em blockchain * **Metadados de scene** - Nomes de scenes implantadas e coordenadas * **Tiles de mapa** - Imagens de tiles pré-renderizadas para exibição em UI * **Consultas espaciais** - Encontra parcels por coordenadas ou owner **Papel Arquitetural**: Fornece o índice espacial para a grade de LAND do Decentraland. Essencial para UIs de mapa e navegação espacial. **Referência de API**: [Atlas Server API](https://github.com/decentraland/docs/blob/main/apis/atlas-server/overview/README.md) ### Camera Reel **Propósito**: Gestão de screenshots geradas pelos usuários Gerencia screenshots e imagens de usuários: * **Uploads de imagem** - Armazenamento autenticado de imagens * **Organização de galeria** - Coleções de screenshots do usuário * **Metadados** - Local da scene, timestamp, tags **Papel Arquitetural**: Habilita compartilhamento de conteúdo e recursos sociais em torno de fotografia gerada pelos usuários. **Referência de API**: [Camera Reel API](https://github.com/decentraland/docs/blob/main/apis/camera-reel/overview/README.md) ### Exploration Games **Propósito**: Gamificação de onboarding e tutoriais Sistema de quests interativas para onboarding de novos usuários: * **Rastreamento de quests** - Progresso através de missões tutoriais * **Conclusão de desafios** - Verificação de tarefas * **Integração de recompensas** - Conecta-se ao sistema de rewards **Papel Arquitetural**: Reduz atrito para novos usuários fornecendo uma introdução estruturada e orientada a objetivos às funcionalidades do Decentraland. **Referência de API**: [Exploration Games API](https://github.com/decentraland/docs/blob/main/apis/exploration-games/overview/README.md) *** ## Serviços Centrais ### Auth Server **Propósito**: Autenticação baseada em wallet e gestão de sessão Implementa o modelo de autenticação wallet-first do Decentraland: * **Verificação de assinatura** - Valida assinaturas de wallet Ethereum * **Emissão de tokens JWT** - Gera tokens de sessão * **Validação de tokens** - Verifica tokens para recursos protegidos * **Ciclo de vida da sessão** - Atualização e expiração de tokens **Papel Arquitetural**: Fornece verificação de identidade descentralizada. Usuários se autenticam via assinaturas de wallet em vez de senhas, alinhando-se aos princípios Web3. **Fluxo de Autenticação**: 1. Cliente solicita challenge 2. Usuário assina challenge com wallet 3. Auth Server verifica assinatura e emite JWT 4. Cliente inclui JWT em requisições API subsequentes **Referência de API**: [Auth Server API](https://github.com/decentraland/docs/blob/main/apis/auth-server/overview/README.md) ### Serviço Social **Propósito**: Grafo social e gestão de comunidade Gerencia relacionamentos sociais e comunidades: * **Sistema de amigos** - Pedidos, aprovações, listas de amigos * **Lista de bloqueio** - Bloqueio de usuários e privacidade * **Comunidades** - Associação a grupos e descoberta * **Status em tempo real** - Notificações de amigos online/offline via NATS * **Mensagens privadas** - Infraestrutura de mensagens diretas **Papel Arquitetural**: Fornece a camada social que transforma o Decentraland de um mundo virtual em um metaverso social. **Integrações Principais**: * Catalyst Client - Busca dados de profile para amigos * NATS - Publica atualizações de status de amigos * Archipelago - Consulta status online e localizações **Referência de API**: [Social Service API](https://github.com/decentraland/docs/blob/main/apis/social-service/overview/README.md) ### Marketplace Server **Propósito**: Integração com marketplace de NFT Backend para o marketplace de wearables e emotes do Decentraland: * **Consultas de listagem** - Navegar e buscar itens do marketplace * **Histórico de transações** - Registros de compra * **Dados de precificação** - Preços de mercado e tendências * **Metadados de coleção** - Coleções de wearables e emotes **Papel Arquitetural**: Faz a ponte entre dados on-chain de NFT e a UI amigável do marketplace. Indexa eventos da blockchain para consultas rápidas. **Referência de API**: [Marketplace Server API](https://github.com/decentraland/docs/blob/main/apis/marketplace-server/overview/README.md) *** ## Serviços de Ativos ### Registro de Pacotes de Assets **Propósito**: Gestão otimizada de ativos Registro de bundles de ativos otimizados para a plataforma: * URLs de asset bundle por plataforma * Versionamento * Distribuição CDN **Referência de API**: [Asset Bundle Registry API](https://github.com/decentraland/docs/blob/main/contributor/apis/asset-bundle-registry/README.md) **Componentes do Sistema**: * **Conversor de Bundle de Ativos** - Constrói bundles específicos por plataforma * **Gerador de LODs** - Cria variantes de nível de detalhe **Fluxo de Processos**: {% @mermaid/diagram content="sequenceDiagram participant Catalyst participant Queue as Deployments Queue participant Converter as AB Converter participant Registry ``` Catalyst->>Queue: New deployment Queue->>Converter: Process assets Converter->>Converter: Build bundles Converter->>Registry: Register bundles" %} ``` ### Camera Reel **Propósito**: Gestão de screenshots e imagens Gestão de conteúdo gerado por usuários: * Armazenamento de screenshots * Uploads de imagem * Organização de galeria **Referência de API**: [Camera Reel API](https://github.com/decentraland/docs/blob/main/contributor/apis/camera-reel/README.md) ### Credits Server **Propósito**: Moeda virtual e economia Gerencia o sistema de créditos virtuais do Decentraland: * **Rastreamento de saldo** - Saldos de créditos dos usuários * **Livro-razão de transações** - Transferências e gastos de créditos * **Integração de compra** - Conversão de fiat para credits * **Sincronização com blockchain** - Consulta indexadores para saldos on-chain **Papel Arquitetural**: Fornece uma alternativa de moeda com menor atrito aos tokens on-chain para compras e funcionalidades dentro do mundo. **Referência de API**: [Credits Server API](https://github.com/decentraland/docs/blob/main/apis/credits-server/overview/README.md) ### Badges **Propósito**: Sistema de conquistas e gamificação Concessões de badges acionadas por eventos: * **Definições de badge** - Conquistas disponíveis * **Inventário do usuário** - Badges conquistados por usuário * **Concessão automática** - Prêmios de badge acionados por eventos **Componentes da Arquitetura**: * **Badges API** - Consultas de badge e inventários de usuários * **Processador de Badges** - Escuta Events Notifier e concede badges **Papel Arquitetural**: Gamifica o engajamento do usuário por meio de conquistas. Fornece visibilidade e reconhecimento para atividades dos usuários. **Referência de API**: [Badges API](https://github.com/decentraland/docs/blob/main/apis/badges/overview/README.md) ### API de Recompensas **Propósito**: Distribuição de recompensas NFT baseada em campanhas Gerencia campanhas promocionais de recompensas NFT: * **Gestão de campanhas** - Programas de recompensa com tempo limitado * **Verificação de elegibilidade** - Verifica qualificação do usuário * **Coordenação de airdrop** - Distribuição de NFT para usuários elegíveis * **Analytics** - Rastreamento de participação na campanha **Papel Arquitetural**: Habilita campanhas de marketing e aquisição de usuários por meio de recompensas em NFT. **Referência de API**: [API de Recompensas](https://github.com/decentraland/docs/blob/main/apis/rewards/overview/README.md) ### Notifications Workers **Propósito**: Sistema de entrega de notificações ao usuário Infraestrutura de notificações multicanal: * **Notificações in-app** - Consultas da caixa de entrada de notificações * **Notificações por email** - Integração com SendGrid * **Push notifications** - Alertas para mobile e desktop * **Rastreamento de status de leitura** - Marcar notificações como lidas/não lidas **Componentes da Arquitetura**: * **Inbox de Notificações** - API para consultar notificações do usuário * **Processor de Notificações** - Gera notificações a partir do Events Notifier **Papel Arquitetural**: Mantém usuários engajados por meio de alertas oportunos sobre atividade de amigos, eventos, recompensas e atualizações do sistema. **Referência de API**: [Notifications Workers API](https://github.com/decentraland/docs/blob/main/apis/notifications-workers/overview/README.md) ### Events Notifier **Propósito**: Barramento de eventos para eventos da plataforma Sistema centralizado de publicação de eventos que aciona ações downstream: * **Eventos de usuário** - Login, compras, deployments * **Eventos mundiais** - Atualizações de scene, ações de admin * **Eventos do sistema** - Manutenção, atualizações **Papel Arquitetural**: Desacopla produtores de eventos de consumidores. Serviços publicam eventos sem saber quem os processa, possibilitando arquiteturas extensíveis. **Integrações Downstream**: * Processor de Notificações - Cria notificações de usuário * Processor de Badges - Concede badges de conquista * Rewards API - Rastrea elegibilidade de campanhas **Referência de API**: [Events Notifier API](https://github.com/decentraland/docs/blob/main/apis/events-notifier/overview/README.md) *** ## Padrões de Interação entre Serviços ### Padrões comuns de integração #### Biblioteca Catalyst Client Muitos serviços backend usam o **Catalyst Client** library para interagir com a rede descentralizada Catalyst: * **Serviço Social** - Busca dados de profile do usuário * **Events API** - Consulta metadados de scene * **Places** - Agrega informações de scene * **Registro de Pacotes de Assets** - Escuta eventos de deployment Esta library abstrai a lógica de consulta multi-nó e failover. #### Broker de Mensagens NATS Atualizações em tempo real e comunicação assíncrona fluem através do NATS: * **Serviço Social** - Publica mudanças de status de amigos * **Worlds** - Transmite atualizações de configuração de world * **Archipelago** - Roteia atualizações de posição entre ilhas * **Events Notifier** - Publica eventos da plataforma NATS permite que serviços se comuniquem sem acoplamento direto. #### Indexadores de Blockchain Serviços consultam indexadores (não a blockchain diretamente) para desempenho: * **Worlds** - Verifica propriedade de NAME NFT * **Atlas** - Busca dados de parcelas LAND * **Credits Server** - Verifica saldos de token * **API de Recompensas** - Verifica condições de elegibilidade Consultas diretas na blockchain seriam muito lentas para APIs em tempo real. ### Pipeline de Deployment de Conteúdo Quando um usuário faz deployment de conteúdo no Catalyst, múltiplos serviços downstream processam-no: {% @mermaid/diagram content="flowchart TB Deploy\[User Deploys Content] Catalyst\[Catalyst Node] Queue\[Deployment Queue] ``` subgraph Processing AB[Asset Bundle Converter] Profile[Profile Image Generator] Badges[Badges Processor] Events[Events Notifier] end Deploy --> Catalyst Catalyst --> Queue Queue --> AB Queue --> Profile Queue --> Events Events --> Badges" %} ``` **Etapas do Pipeline**: 1. **Catalyst** - Armazena dados brutos de entidades 2. **Fila de Deployment** - Aciona processamento assíncrono 3. **Conversor de Bundle de Ativos** - Constrói bundles Unity otimizados 4. **Gerador de Imagem de Profile** - Renderiza thumbnails de avatar (para entidades de profile) 5. **Events Notifier** - Publica evento de deployment 6. **Processador de Badges** - Verifica badges de conquista por deployment ### Matriz de Dependência de Serviços | Serviço | Dependências Centrais | Fornece Dados Para | | ----------------------------- | ---------------------------- | ------------------------------ | | Catalyst | Nenhum (decentralized) | Todos os serviços | | Realm Provider | Catalyst, Archipelago Stats | Todos os clientes | | Auth Server | Nenhum | Todos os serviços protegidos | | Archipelago Workers | NATS, LiveKit | Realm Provider, Places | | Comms Gatekeeper | LiveKit, Worlds API | Clientes (geração de tokens) | | Worlds | Catalyst, NATS, Blockchain | Gatekeeper, Clientes | | Serviço Social | Catalyst, NATS, Archipelago | Clientes | | Places | Catalyst, Archipelago, Comms | Clientes | | Events Notifier | Nenhum | Notifications, Badges, Rewards | | Registro de Pacotes de Assets | Catalyst, Deployment Queue | Clientes (assets otimizados) | | Notifications Workers | Events Notifier, SendGrid | Clientes | *** ## Documentação Relacionada ### Arquitetura * [Visão geral da arquitetura](/contributor/contributor-pt/arquitetura/architecture.md) - Arquitetura completa do sistema * [Catalyst Network](/contributor/contributor-pt/arquitetura/catalyst.md) - Entrega de conteúdo descentralizada * [Infraestrutura](/contributor/contributor-pt/arquitetura/infrastructure.md) - Sistemas de suporte (NATS, LiveKit, databases) ### Referências de API * [Documentação da API](https://github.com/decentraland/docs/blob/main/apis/README.md) - Especificações completas de API * [Autenticação](https://github.com/decentraland/docs/blob/main/contributor/auth/authchain.md) - Fluxos de auth baseados em wallet * [Comunicações](https://github.com/decentraland/docs/blob/main/contributor/comms/overview.md) - Protocolos de mensagem em tempo real ### Desenvolvimento * [Guias para contribuintes](https://github.com/decentraland/docs/blob/main/contributor/contributor-guides/overview.md) - Workflows de desenvolvimento * [Guia de Testes](https://github.com/decentraland/docs/blob/main/contributor/practice/testing.md) - Práticas de teste de serviços --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.decentraland.org/contributor/contributor-pt/arquitetura/services.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.