ADR-145: Pick Realm Algorithm V2

More details about this document
Latest published version:
GitHub decentraland/adr (pull requests, new issue, open issues)
Edit this documentation:
GitHub View commits View commits on


This document describes the changes needed in the realm picking algorithm to take into account the resources of the computer and the catalyst version.

The logic on the realm scoring algorithm should be improved to take into consideration more variables in order for a server to be more eligible. As with the current model, any added variable needs to be modifiable through Feature Flags so that they can be changed in case of need without a release or a reboot of the server.

Context, Reach & Prioritization

Some aspects that should be considered:

Solution Space Exploration

The current implementation (as described in Realm Picking Algorithm ADR) is expansible by adding new links. In this proposal a filter and a new link will be added:


Accepting Users Filter


Publicly exposing the Catalyst Node's available resources is a security risk, so their estimation should be done in the Catalyst (specifically in the BFF) and not in the Kernel.

This way, the BFF will leverage the usage of the field accepting_users in the /about endpoint.

The logic from the Kernel side will be simple: it will filter out the catalysts having that value as false.

On the other hand, the BFF will have a set of rules to calculate that value. The accepting_users field will be false if:

Pseudo Code:

To filter out a new check will need to be added to:

export function fetchCatalystStatus() {
  if (currentChecks && result.accepting_users) {
    // ...

  return undefined


This configuration will be at BFF (Catalyst) level

export type AcceptingUsersConfig = {
  config?: { maxAmountOfUsers: number; maxCpu: number; maxMemory: number }

Catalyst Version Link


Each Catalyst (BFF) exposes the version of Content and Lambdas that it's using. The Kernel should read that field, compare them and prioritize the ones having the highest value. As Content Server and Lambdas share the same version for each Catalyst and they are using semver, there is always an unique way to sort the candidates.

Pseudo Code:

export function versionLink() {
  const catalystsWithVersion: { realm: string; version: string } = peers.sortByVersion()
  const versionBuckets: PriorityQueue<{ realm: string; version: string }[]> =
  // This selects randomly between the candidates in the selected bucket
  // And chooses the bucket with the same algorithm used for close peers
  return selectFirstByScore(context, score, definitiveDecisionThreshold)


Copyright and related rights waived via CC0-1.0. Draft