> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-pt/arquitetura/services.md). # Serviços de backend Esta página fornece uma visão abrangente de todos os serviços de backend da Decentraland, os seus papéis arquitetónicos e como interagem dentro do ecossistema. Para especificações detalhadas da API e endpoints, consulte a [Referência da API](https://github.com/decentraland/docs/tree/main/apis/README.md) . ## Arquitetura de Serviços O backend da 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 Funcionalidades** - funcionalidades voltadas para o utilizador (conteúdo, economia, gamificação) * **Serviços Principais** - infraestrutura essencial da plataforma (auth, Marketplace, notifications) *** ## Camada Descentralizada ### Catalyst **Objetivo**: rede de entrega de conteúdo descentralizada A rede Catalyst forma a base da infraestrutura de conteúdo da Decentraland. Cada nó Catalyst é um servidor completo que fornece: * **Servidor de conteúdo** - armazenamento e recuperação de Entities (scenes, profiles, wearables) * **Lambdas Service** - endpoints utilitários e consultas de conteúdo * **Communications Server** - transporte de mensagens em tempo real **Papel na Arquitetura**: os nós Catalyst são distribuídos geograficamente e sem permissões. A rede fornece redundância e disponibilidade de conteúdo sem controlo central. **Integrações Principais**: * Realm Provider - anuncia a disponibilidade do nó * Asset Bundle Registry - desencadeia a otimização de assets na deployment * Archipelago Workers - fornece dados de ilhas/cluster **Referência da API**: [Catalyst API](https://github.com/decentraland/docs/tree/main/apis/catalyst/overview/README.md) ### Lamb2 **Objetivo**: utilitários Lambda e funções serverless O 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 profiles com fallbacks * verificações de status e de saúde **Papel na Arquitetura**: atua como uma camada de conveniência sobre o acesso bruto a Entities do Content Server, fornecendo padrões de consulta de nível superior normalmente necessários pelos clientes. **Referência da API**: [Lamb2 API](https://github.com/decentraland/docs/tree/main/apis/lamb2/overview/README.md) *** ## Camada de Comunicações em Tempo Real ### Realm Provider **Objetivo**: descoberta de serviços e seleção de realm O Realm Provider é o ponto de entrada para todos os clientes da Decentraland. Implementa uma seleção inteligente de realm com base em: * **otimização geográfica** - encaminha os utilizadores para os nós Catalyst mais próximos * **monitorização de saúde** - filtra nós com problemas ou sobrecarregados * **rastreamento de capacidade** - fornece contagens de utilizadores em tempo real por realm * **agregação de scenes em alta** - identifica locais populares em todos os realms **Papel na Arquitetura**: fonte única de verdade para a infraestrutura disponível. Os clientes consultam-no uma vez no arranque para descobrir todos os endpoints de serviço (Catalyst, Comms, BFF). **Integrações Principais**: * faz polling a todos os nós Catalyst periodicamente * agrega estatísticas do Archipelago * fornece uma visão unificada da rede distribuída **Referência da API**: [Realm Provider API](https://github.com/decentraland/docs/tree/main/apis/realm-provider/overview/README.md) ### Comms Gatekeeper **Objetivo**: controlo de acesso para voz e vídeo O Gatekeeper gere o acesso aos media servers do LiveKit para chat de voz e vídeo: * **geração de tokens** - cria tokens de acesso com prazo limitado e permissões específicas * **administração de scenes** - gere direitos de admin de scenes e banimento * **gestão de stream** - controla o acesso a livestreaming e chaves RTMP * **controlos de privacidade** - aplica permissões privadas de chat de voz **Papel na Arquitetura**: camada de segurança entre os clientes e a infraestrutura de media. Impede acesso não autorizado enquanto permite modelos de permissão flexíveis (baseados na scene, privados, comunidade). **Integrações Principais**: * LiveKit - emite tokens JWT para acesso ao media server * Worlds API - valida a propriedade do world para direitos de admin * Signed Fetch - autentica todos os pedidos através de assinaturas da Wallet **Referência da API**: [Comms Gatekeeper API](https://github.com/decentraland/docs/tree/main/apis/comms-gatekeeper/overview/README.md) ### Archipelago Workers **Objetivo**: clustering de comunicações e encaminhamento de mensagens O Archipelago implementa o protocolo de clustering baseado em proximidade que agrupa jogadores próximos em "ilhas": * **transporte WebSocket** - mantém ligações persistentes com os clientes * **rastreamento de posição** - monitoriza as localizações dos jogadores em tempo real * **Formação de ilhas** - agrupa dinamicamente os jogadores com base na distância * **Roteamento de mensagens** - encaminha mensagens apenas para os membros da ilha **Componentes da Arquitetura**: * **WebSocket Connector** - trata das ligações dos clientes e da autenticação * **Archipelago Core** - implementa o algoritmo de clustering e a gestão de ilhas * **Serviço de estatísticas** - fornece métricas de ligação e contagens de utilizadores * **Integração NATS** - publica atualizações de posição e encaminha mensagens **Papel na Arquitetura**: otimiza as comunicações peer-to-peer ao limitar o fanout das mensagens. Em vez de fazer broadcast para todos os utilizadores num realm, as mensagens chegam apenas aos jogadores dentro do intervalo de interação. **Integrações Principais**: * broker de mensagens NATS - encaminhamento distribuído de mensagens * Realm Provider - fornece estatísticas da ilha * Places API - dados de contagem de utilizadores para scenes em alta **Referência da API**: [Archipelago Workers API](https://github.com/decentraland/docs/tree/main/apis/archipelago-workers/overview/README.md) *** ## Serviços de Funcionalidades ### Worlds **Objetivo**: alojamento isolado de scenes fora da grelha principal Os Worlds permitem que os utilizadores implementem scenes em ambientes isolados: * **Worlds Nomeados** - acessíveis através de URLs personalizadas (por exemplo, `world.dclworlds.com`) * **Worlds Privados** - controlo de acesso com gating por NFT * **Permissões de World** - direitos de admin e deployment geridos pelo owner **Papel na Arquitetura**: estende o modelo de conteúdo da Decentraland para além da grelha fixa de LAND. Cada world é uma scene autónoma com os seus próprios canais de comunicação e controlo de acesso. **Integrações Principais**: * faz consultas a indexers de blockchain para verificação de propriedade de NFT * publica atualizações do world para o NATS para sincronização em tempo real com o cliente * integra-se com o Comms Gatekeeper para salas de chat de voz * desencadeia o pipeline de processamento de assets na deployment **Referência da API**: [Worlds API](https://github.com/decentraland/docs/tree/main/apis/worlds/overview/README.md) ### Eventos **Objetivo**: gestão e descoberta de eventos in-world Gere o ciclo de vida completo de eventos virtuais: * **CRUD de eventos** - criação, atualizações e agendamento * **rastreamento de participantes** - participação dos utilizadores e RSVPs * **Descoberta** - consultas e filtragem baseadas no tempo * **notifications** - integração com o Events Notifier **Papel na Arquitetura**: fornece contexto temporal ao metaverso. Os eventos impulsionam a descoberta e o envolvimento dos utilizadores ao destacar experiências sensíveis ao tempo. **Referência da API**: [Events API](https://github.com/decentraland/docs/tree/main/apis/events/overview/README.md) ### Places **Objetivo**: descoberta e curadoria de pontos de interesse Agrega e seleciona localizações interessantes em toda a Decentraland: * **scenes em alta** - popularidade em tempo real com base nas contagens de utilizadores * **locais em destaque** - localizações selecionadas editorialmente * **pesquisa e filtragem** - descoberta por tags, categorias * **metadata de POI** - descrições, miniaturas, coordenadas **Papel na Arquitetura**: resolve o problema de descoberta num grande mundo aberto. Agrega dados de múltiplas fontes para ajudar os utilizadores a encontrar conteúdo envolvente. **Integrações Principais**: * Catalyst - metadata de scenes e informações de deployment * Archipelago Stats - contagens de utilizadores em tempo real por scene * Comms Gatekeeper - disponibilidade e estado do realm **Referência da API**: [Places API](https://github.com/decentraland/docs/tree/main/apis/places/overview/README.md) ### Atlas Server **Objetivo**: dados do mapa e visualização de parcels Fornece dados abrangentes do mapa do world: * **propriedade de parcels** - dados de LAND indexados em blockchain * **metadata de scenes** - nomes e coordenadas de scenes em deployment * **map tiles** - imagens de tiles pré-renderizadas para exibição na UI * **consultas espaciais** - encontra parcels por coordenadas ou owner **Papel na Arquitetura**: fornece o índice espacial para a grelha de LAND da Decentraland. Essencial para UIs de mapa e navegação espacial. **Referência da API**: [Atlas Server API](https://github.com/decentraland/docs/tree/main/apis/atlas-server/overview/README.md) ### Camera Reel **Objetivo**: gestão de capturas de ecrã geradas pelos utilizadores Gere capturas de ecrã e imagens dos utilizadores: * **upload de imagens** - armazenamento de imagens autenticado * **organização da galeria** - coleções de capturas de ecrã dos utilizadores * **metadata** - localização da scene, timestamp, tags **Papel na Arquitetura**: permite partilha de conteúdo e funcionalidades sociais em torno da fotografia gerada pelos utilizadores. **Referência da API**: [Camera Reel API](https://github.com/decentraland/docs/tree/main/apis/camera-reel/overview/README.md) ### Exploration Games **Objetivo**: gamificação de onboarding e tutoriais Sistema interativo de quests para onboarding de novos utilizadores: * **rastreamento de quests** - progresso através de missões do tutorial * **conclusão de desafios** - verificação de tarefas * **integração de recompensas** - conecta-se ao sistema de rewards **Papel na Arquitetura**: reduz o atrito para novos utilizadores ao fornecer uma introdução estruturada e orientada por objetivos às funcionalidades da Decentraland. **Referência da API**: [Exploration Games API](https://github.com/decentraland/docs/tree/main/apis/exploration-games/overview/README.md) *** ## Serviços Principais ### Servidor de Auth **Objetivo**: autenticação baseada em Wallet e gestão de sessão Implementa o modelo de autenticação first-wallet da Decentraland: * **Verificação de assinatura** - valida assinaturas da 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** - refresh e expiração do token **Papel na Arquitetura**: fornece verificação de identidade descentralizada. Os utilizadores autenticam-se através de assinaturas da Wallet em vez de passwords, alinhando-se com os princípios Web3. **Fluxo de Autenticação**: 1. O cliente solicita um challenge 2. O utilizador assina o challenge com a Wallet 3. O Auth Server verifica a assinatura e emite o JWT 4. O cliente inclui o JWT em pedidos subsequentes à API **Referência da API**: [Auth Server API](https://github.com/decentraland/docs/tree/main/apis/auth-server/overview/README.md) ### Serviço social **Objetivo**: grafo social e gestão da comunidade Gere relações sociais e comunidades: * **sistema de amigos** - pedidos, aprovações, listas de amigos * **lista de bloqueios** - bloqueio de utilizadores e privacidade * **comunidades** - pertença a grupos e descoberta * **estado em tempo real** - notificações online/offline de amigos via NATS * **mensagens privadas** - infraestrutura de mensagens diretas **Papel na Arquitetura**: fornece a camada social que transforma a Decentraland de um mundo virtual num metaverso social. **Integrações Principais**: * Catalyst Client - obtém dados de profile para amigos * NATS - publica atualizações de estado de amigos * Archipelago - consulta estado online e localizações **Referência da API**: [Social Service API](https://github.com/decentraland/docs/tree/main/apis/social-service/overview/README.md) ### Marketplace Server **Objetivo**: integração com o Marketplace de NFT Backend para o Marketplace de wearables e emotes da Decentraland: * **consultas de listagens** - navegar e pesquisar itens do Marketplace * **histórico de transações** - registos de compra * **dados de preços** - preços de mercado e tendências * **metadata de coleções** - coleções de wearables e emotes **Papel na Arquitetura**: faz a ponte entre dados de NFT on-chain e uma UI do Marketplace amigável ao utilizador. Indexa eventos da blockchain para consultas rápidas. **Referência da API**: [Marketplace Server API](https://github.com/decentraland/docs/tree/main/apis/marketplace-server/overview/README.md) *** ## Asset Services ### Asset Bundle Registry **Objetivo**: gestão otimizada de assets Registo de asset bundles otimizados pela plataforma: * URLs de asset bundles por plataforma * Versionamento * distribuição CDN **Referência da API**: [Asset Bundle Registry API](https://github.com/decentraland/docs/tree/main/contributor/apis/asset-bundle-registry/README.md) **Componentes do Sistema**: * **Asset Bundle Converter** - cria bundles específicos para a plataforma * **Gerador de LODs** - cria variantes de nível de detalhe **Fluxo do Processo**: ```mermaid sequenceDiagram participant Catalyst participant Queue as Deployments Queue participant Converter as AB Converter participant Registry Catalyst->>Queue: Novo deployment Queue->>Converter: Processar assets Converter->>Converter: Criar bundles Converter->>Registry: Registar bundles ``` ### Camera Reel **Objetivo**: gestão de capturas de ecrã e imagens gestão de conteúdo gerado pelo utilizador: * armazenamento de capturas de ecrã * upload de imagens * organização da galeria **Referência da API**: [Camera Reel API](https://github.com/decentraland/docs/tree/main/contributor/apis/camera-reel/README.md) ### Credits Server **Objetivo**: moeda virtual e economia Gere o sistema de créditos virtuais da Decentraland: * **rastreamento de saldo** - saldos de crédito dos utilizadores * **livro-razão de transações** - transferências e gastos de créditos * **integração de compra** - conversão de fiat para créditos * **sincronização blockchain** - consulta indexers para saldos on-chain **Papel na Arquitetura**: fornece uma alternativa de moeda com menor atrito do que tokens blockchain para compras e funcionalidades in-world. **Referência da API**: [Credits Server API](https://github.com/decentraland/docs/tree/main/apis/credits-server/overview/README.md) ### Badges **Objetivo**: sistema de conquistas e gamificação atribuição de badges orientada por eventos: * **definições de badges** - conquistas disponíveis * **inventário do utilizador** - badges conquistados por utilizador * **atribuição automática** - atribuição de badges acionada por eventos **Componentes da Arquitetura**: * **Badges API** - consultas de badges e inventários de utilizadores * **Badges Processor** - ouve o Events Notifier e atribui badges **Papel na Arquitetura**: gamifica o envolvimento dos utilizadores através de conquistas. Fornece visibilidade e reconhecimento das atividades dos utilizadores. **Referência da API**: [Badges API](https://github.com/decentraland/docs/tree/main/apis/badges/overview/README.md) ### API de recompensas **Objetivo**: distribuição de rewards NFT baseada em campanhas Gere campanhas promocionais de rewards NFT: * **gestão de campanhas** - programas de recompensa com prazo limitado * **verificação de elegibilidade** - verificar a qualificação do utilizador * **coordenação de airdrop** - distribuição de NFT a utilizadores elegíveis * **Analytics** - rastreamento da participação na campanha **Papel na Arquitetura**: permite campanhas de marketing e aquisição de utilizadores através de rewards NFT. **Referência da API**: [API de recompensas](https://github.com/decentraland/docs/tree/main/apis/rewards/overview/README.md) ### Notifications Workers **Objetivo**: sistema de entrega de notifications ao utilizador infraestrutura de notifications multicanal: * **notifications in-app** - consultas à caixa de entrada de notifications * **notifications por email** - integração com o SendGrid * **push notifications** - alertas móveis e desktop * **rastreamento do estado de leitura** - marcar notifications como lidas/não lidas **Componentes da Arquitetura**: * **Caixa de Entrada de Notifications** - API para consultar notifications do utilizador * **Notifications Processor** - gera notifications a partir do Events Notifier **Papel na Arquitetura**: mantém os utilizadores envolvidos através de alertas oportunos sobre atividade de amigos, events, rewards e atualizações do sistema. **Referência da API**: [Notifications Workers API](https://github.com/decentraland/docs/tree/main/apis/notifications-workers/overview/README.md) ### Events Notifier **Objetivo**: barramento de eventos para eventos da plataforma sistema centralizado de publicação de eventos que desencadeia ações a jusante: * **eventos de utilizador** - login, compras, deployments * **Eventos de World** - atualizações de scenes, ações de admin * **eventos do sistema** - manutenção, atualizações **Papel na Arquitetura**: desacopla produtores de eventos de consumidores. Os serviços publicam eventos sem saber quem os processa, permitindo arquiteturas extensíveis. **Integrações a Jusante**: * Notifications Processor - cria notifications do utilizador * Badges Processor - atribui badges de conquistas * Rewards API - rastreia a elegibilidade para campanhas **Referência da API**: [Events Notifier API](https://github.com/decentraland/docs/tree/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 de backend usam a **biblioteca Catalyst Client** para interagir com a rede Catalyst descentralizada: * **Serviço social** - obtém dados de profile do utilizador * **Events API** - consulta metadata de scenes * **Places** - agrega informações de scenes * **Asset Bundle Registry** - Escuta eventos de implantação Esta biblioteca abstrai a lógica de consulta em vários nós e de failover. #### Broker de Mensagens NATS Atualizações em tempo real e comunicação assíncrona passam pelo NATS: * **Serviço social** - Publica mudanças de status de amigos * **Worlds** - Transmite atualizações de configuração do World * **Archipelago** - Encaminha atualizações de posição entre ilhas * **Events Notifier** - Publica eventos da plataforma O NATS permite que serviços se comuniquem sem acoplamento direto. #### Indexadores de Blockchain Os serviços consultam indexadores (não a blockchain diretamente) para desempenho: * **Worlds** - Verifica a propriedade do NFT NAME * **Atlas** - Obtém dados de parcels LAND * **Credits Server** - Verifica saldos de tokens * **API de recompensas** - Verifica condições de elegibilidade Consultas diretas à blockchain seriam muito lentas para APIs em tempo real. ### Pipeline de Implantação de Conteúdo Quando um usuário faz deploy de conteúdo para o Catalyst, vários serviços subsequentes o processam: ```mermaid flowchart TB Deploy[Usuário faz deploy de conteúdo] Catalyst[Nó Catalyst] Queue[Fila de Implantação] subgraph Processamento AB[Asset Bundle Converter] Profile[Gerador de Imagem de Perfil] Badges[Processador de Badges] Events[Notificador de Eventos] end Deploy --> Catalyst Catalyst --> Queue Queue --> AB Queue --> Profile Queue --> Events Events --> Badges ``` **Etapas do Pipeline**: 1. **Catalyst** - Armazena dados brutos de Entity 2. **Fila de Implantação** - Aciona processamento assíncrono 3. **Asset Bundle Converter** - Compila bundles otimizados do Unity 4. **Gerador de Imagem de Perfil** - Renderiza miniaturas de avatar (para entities de perfil) 5. **Events Notifier** - Publica evento de implantação 6. **Badges Processor** - Verifica badges de conquista de implantação ### Matriz de Dependências dos Serviços | Serviço | Dependências Principais | Fornece dados para | | --------------------- | ------------------------------------- | ---------------------------------- | | Catalyst | Nenhum (descentralizado) | Todos os serviços | | Realm Provider | Catalyst, Estatísticas do Archipelago | Todos os clientes | | Servidor de Auth | 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, Clients | | Serviço social | Catalyst, NATS, Archipelago | Clients | | Places | Catalyst, Archipelago, Comms | Clients | | Events Notifier | Nenhum | Notifications, Badges, Recompensas | | Asset Bundle Registry | Catalyst, Fila de Implantação | Clientes (assets otimizados) | | Notifications Workers | Events Notifier, SendGrid | Clients | *** ## 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 descentralizada de conteúdo * [Infraestrutura](/contributor/contributor-pt/arquitetura/infrastructure.md) - Sistemas de suporte (NATS, LiveKit, bases de dados) ### Referências da API * [Documentação da API](https://github.com/decentraland/docs/tree/main/apis/README.md) - Especificações completas da API * [Autenticação](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain.md) - Fluxos de autenticação baseados em Wallet * [Comunicações](https://github.com/decentraland/docs/tree/main/contributor/comms/overview.md) - Protocolos de mensagens em tempo real ### Desenvolvimento * [Guias de Colaborador](https://github.com/decentraland/docs/tree/main/contributor/contributor-guides/overview.md) - Fluxos de trabalho de desenvolvimento * [Guia de Testes](https://github.com/decentraland/docs/tree/main/contributor/practice/testing.md) - Práticas de teste de serviços --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.decentraland.org/contributor/contributor-pt/arquitetura/services.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.