Abstract

This document defines the protocol to describe a realm.

Realm

A realm is a set of services needed for the client to work: current there is comms, content and lambdas. A valid realm is pointed by a URL defining /about endpoint in the proper format, which describes the realm and its status.

Usage

Realms are used by the Explorer ADR-102 to set up and configure each browsing session.

Canonically, a realm can be selected by executing the /changerealm <baseUrl> command in the chat.

Examples:

• /changerealm peer.decentraland.org
• /changerealm https://worlds-content-server.decentraland.org/world/menduz.dcl.eth

Other mechanisms may be available to resolve realm baseUrl out of a string, like the ENS resolution defined at ADR-144

/about

This endpoint must return the well-known schema defined in the protocol repository:

type About = {
  healthy: boolean
  acceptingUsers: boolean
  configurations: {
    networkId: number
    realmName?: string
    scenesUrn: string[]
    globalScenesUrn: string[]
    cityLoaderContentServer?: string
  }
  content: {
    healthy: boolean
    version?: string
    commitHash?: string
    publicUrl: string
  }
  comms: {
    healthy: boolean
    protocol: string
    fixedAdapter?: string
    usersCount?: number
  }
  lambdas: {
    healthy: boolean
    version?: string
    commitHash?: string
    publicUrl: string
  }
  bff?: {
    healthy: boolean
    userCount: number
    commitHash?: string
    publicUrl: string
  }
}

Example https://peer.decentraland.org/about:

{
  "healthy": true,
  "content": {
    "healthy": true,
    "version": "6.0.6",
    "commitHash": "d2eeccaffe2a9c22ac963348851c7791b63fc517",
    "publicUrl": "https://peer-ec2.decentraland.org/content/"
  },
  "lambdas": {
    "healthy": true,
    "version": "6.0.6",
    "commitHash": "d2eeccaffe2a9c22ac963348851c7791b63fc517",
    "publicUrl": "https://peer-ec2.decentraland.org/lambdas/"
  },
  "configurations": {
    "networkId": 1,
    "globalScenesUrn": [],
    "scenesUrn": [],
    "realmName": "hela"
  },
  "comms": {
    "healthy": true,
    "protocol": "v3",
    "commitHash": "b3ec3327ceef53473853068dcdad8ea08d7a0f9c"
  },
  "bff": {
    "healthy": true,
    "commitHash": "1a2ff915a216191ecc6ef85f3822f0809fe16f3c",
    "userCount": 4,
    "protocolVersion": "1.0_0",
    "publicUrl": "/bff"
  },
  "acceptingUsers": true
}

Example https://worlds-content-server.decentraland.org/world/menduz.dcl.eth/about:

{
  "healthy": true,
  "configurations": {
    "networkId": 1,
    "globalScenesUrn": [],
    "scenesUrn": [
      "urn:decentraland:entity:bafkreihiv5zkzjui46gvxtsnk5pfogmq7kyzijxpf3gjqlb2ivydcuwgxq?baseUrl=https://worlds-content-server.decentraland.org/contents/"
    ],
    "minimap": {
      "enabled": false
    },
    "skybox": {},
    "realmName": "menduz.dcl.eth"
  },
  "content": {
    "healthy": true,
    "publicUrl": "https://peer.decentraland.org/content"
  },
  "lambdas": {
    "healthy": true,
    "publicUrl": "https://peer.decentraland.org/lambdas"
  },
  "comms": {
    "healthy": true,
    "protocol": "v3",
    "fixedAdapter": "signed-login:https://worlds-content-server.decentraland.org/get-comms-adapter/world-prd-menduz.dcl.eth"
  },
  "acceptingUsers": true
}

Health property

healthy: boolean is used to inform whether the realm is in a healthy state, the endpoint must return an HTTP status of 200, otherwise it should return 503. This way just by checking the response HTTP status, a client looking for a realm to connect may decide whether to join or not the realm.

The healthy field in the root of the structure) will be true only if all the referenced services are healthy.

Accepting users property

acceptingUsers: boolean is used to inform whether is accepting new users. It differs from healthy in conditions like "maximum communications capacity" or "high server load".

Configurations section

Describes explorer-specific configurations.

• realmName?: string is used to set a human-readable name for the realm
• networkId?: uint defines the EVM network id in which this realm is configured, defaults to 1
• globalScenesUrn?: string[] declares which global scenes should be loaded by default on the realm. This is used for showing custom "in-world" UIs or for enabling cross-scene mechanics.
• scenesUrn?: string[] declares the list of scenes to be loaded. This feature enables World realms ADR-111
• minimap?: {enabled: boolean, dataImage: string, estateImage: string} configures the minimap of the explorer
• skybox?: {fixedHour: float} configures the skybox hour
• cityLoaderContentServer?: string defines the baseUrl to enable genesis-city-like scene loading. It uses the endpoint /entities/active to fetch the scenes around the user. Defaults to https://peer.decentraland.org/content. If null and scenesUrn are provided, then city-loading behaviors will be disabled. City loading ADR is pending

Comms section

Describes the communications services parameters and connection information.

When protocol: "v3" is currently the only valid and implemented version of comms.

• Providing fixedAdapter means the client will connect to the given adapter, and no clustering process is involved. The available adapters can be found at ADR-180

  {
    "comms": {
      "healthy": true,
      "protocol": "v3",
      "fixedAdapter": "ws-room:mini-comms.decentraland.org/rooms/test-room"
    }
  }
  

• If no fixedAdapter is provided, the client will negotiate through the BFF to join a cluster. For details about this check ADR-70

{
  "comms": {
    "healthy": true,
    "protocol": "v2",
    "version": "1.0.0",
    "commitHash": "43d2173cf5e2078b32bddab5adb90e4778170c44",
    "usersCount": 152
  }
}

License