Architecture
The general architecture of Decentraland can be divided into three main components:
- The Catalyst network : distributed peer servers that host content and provide the core APIs.
- The World Explorer : app for players to log into Decentraland and explore the land.
- The CLI : a command-line interface for creators to develop and deploy content.
The interactive diagram below captures the most important sub-components of the protocol, and can take you to the relevant documentation to learn more.
Catalyst #
A Catalyst is a node in the Decentraland network that provides an array of different services, including access to content, peer-to-peer communications, blockchain inspection and various utility endpoints.
You can inspect the state of the network using the Catalyst Monitor , and host your own node by becoming a Catalyst owner .
Subsystems:
Learn more:
- Subsystem sections listed above
- Catalyst repository
Content Service #
The content service, provided by all Catalysts , allows access to the distributed file-system. With this API, clients can query content indices, retrieve files, deploy entities and download periodic snapshots.
Learn more:
Lambda Service #
The lambda service, provided by all Catalysts , offers a set of utility endpoints that allow clients to retrieve and validate commonly required data.
Some of the endpoints require access to blockchain state to verify the ownership of referenced assets. In these cases, The Graph is used to query the blockchain.
Learn more:
Comms Service #
The archipelago service, provided by all Catalysts , groups players into dynamic clusters called islands, defined by proximity. It automatically balances the number of players on each island, and reassigns them as they travel the world to enable efficient peer-to-peer communications (such as text and voice chat).
The service is based on a generic transport layer that can be backed by different real-time systems in different areas, according to the configuration of each Catalyst.
Learn more:
Backend for Frontend Service (BFF) #
This service was created to resolve client needs to enable faster development of new features without breaking the existing APIs. In the Catalyst context, it’s used for the communications between peers connected to the client, its main responsibility is to manage the P2P signaling.
Learn more:
World Explorer #
The World Explorer is the iconic client of the Decentraland protocol, an application for players to enter the metaverse, explore it and enjoy the experiences created by others.
The reference implementation of a fully-featured World Explorer is the Decentraland Foundation’s project.
Subsystems:
Learn more:
Content system #
The client-side counterpart to the content service of the Catalyst network.
It downloads and caches content files, and can update assets such as a player’s profile on behalf of the user.
Learn more:
Game engine #
The graphics rendering and interactive functions of the World Explorer are provided by a game engine, such as Unity.
Subsystems:
Rendering System #
This subsystem receives instructions from scenes running in the World Explorer and renders the 3D environment.
Each World Explorer implements this system using the capabilities of the chosen game engine.
State System #
The game engine gives life to all entities and components created across scenes, synchronizing a globally maintained state with the individually handled state of each scene.
Learn more:
Input System #
The input system handles user interaction, such as the player’s keyboard, mouse or controller. Events are then routed to the components that subscribed to them, including interactive entities and UI displays.
Learn more:
Scene Runtime #
The scene runtime is the sandboxed environment where community-developed scenes can run in isolation, without interfering with one another or directly accessing security-sensitive system functions.
Learn more
Runtime Library #
The World Explorer’s scene runtime provides a module library with commonly required functionality and access to methods that require authorization to reach beyond the sandbox.
Learn more:
Scenes #
Scenes are community-developed bundles of behavior and assets, and offer the various experiences players can enjoy in Decentraland.
Learn more:
Comms System #
The client-side counterpart to the archipelago comms service of the Catalyst network.
The World Explorer’s comms system can connect to the different peer-to-peer communication networks supported by Decentraland in order to provide text and voice chat functionality for players, and to exchange messages between clients.
Learn more:
CLI #
The dcl
command-line interface
is the principal tool to assist content creators in the development of scenes and other projects.
Among other capabilities, it can bootstrap environments, run and visualize scenes, test them and deploy them to the content network .
Learn more:
Foundation’s World Explorer #
The web browser implementation of a World Explorer is the fully-featured version developed and maintained by the Decentraland Foundation. It leverages the entire set of features offered by the protocol, and is the reference codebase for community projects.
See the Foundation’s architectural diagram to get an overview of the actual implementation components, as used in practice.
Learn more:
Catalyst Client #
This client library can be used to interact with Decentraland’s Catalyst servers. You can both fetch data, or deploy new entities to the server you specify.
Learn more:
Peer Library #
The Peer Library manages Websocket connections for WebRTC signaling, Islands, Notifications and Location Data and WebRTC Connections for peers positions, scene bus, global chat and voice chat (private chat goes through the Matrix Synapse Server and the Matrix Client).
Learn more:
Kernel - Voice Chat Module #
This Module is the codec to hook WebAudio & Worklets to comms
Kernel - Client Comms #
Client-side module to interact with the Decentraland network comms system.
Learn more:
Kernel - Scene Loader System #
Module that loads and unloads the scenes/parcels based on user position.
Kernel - Scene #
High level wrapper around the runtime scene
Kernel - Avatar Scene #
It is a regular Decentraland Scene , it has the size of the world. And it renders the avatars using the SDK
Matrix Client #
The Matrix client can be used to provide interaction between Decentraland’s users, providing the ability to send private messages and add people as friends.
Learn more:
Synapse #
Synapse server is an implementation of the Matrix Protocol , created for secure, decentralized communications. In the Foundation’s explorer, it is used to manage private chats between peers and friends.
Explorer Website #
The React application to load the Kernel and Renderer.
Learn more:
Kernel - Runtime #
The Runtime handles SDK bindings and messaging with the Scene in Kernel
Learn more:
Compiler Bundle #
AMD #
This Module manages loading of RPC modules to interact with different components of Decentraland
Repository: https://github.com/decentraland/js-sdk-toolchain
ECS #
The public library to interact with Decentraland. Sometimes people refers to the ECS as “The SDK”
User Code #
The user generated code is part of the bundle of the Scenes
NATS #
NATS is a message broker that enables the data exchange and communication between services. This is also a building block for future developments and will enable an easy way to connect services using subject-based messaging. In the context of the communication services architecture, it is used to communicate the BFF, Archipelago and LiveKit.
Learn more: https://nats.io/
LiveKit #
LiveKit is an open source project that provides scalable, multi-user conferencing over WebRTC. Instead of doing a P2P network, peers are connected to a Selective Forwarding Unit (SFU) in charge of managing message relay and different quality aspects of the communication. This will be the added infrastructure in order to provide high-performance/high-quality communications between crowds on designated scenes.
Learn more: https://livekit.io/ Repository: https://github.com/decentraland/livekit-adapter
Nginx #
Nginx is the reverse proxy used to route traffic to the Catalysts Services.
Repository: https://github.com/decentraland/catalyst-owner