Registry Server

This server is hooked into the event-driven architecture to listen for Catalysts' and World Content Server's entities deployments in order to act as a gateway to retrieve the latest available version of these entities.

Each entity has its specific way to determine its own latest version. Most of them depends on Asset Bundles conversions, therefore this server also listens to the events being reported by these services to make them available to clients once all the optimizations are already in place.

Table of Contents

• Features
• Dependencies & Related Services
• API Documentation
• Database
  • Schema
  • Migrations
• Getting Started
  • Prerequisites
  • Installation
  • Configuration
  • Running the Service
• Testing
  • Running Tests
  • Test Structure
• AI Agent Context

Features

• Bundles registry: Provides an endpoint to retrieve latest optimized version of scenes, emotes, wearables and worlds entities.
• Bundles state transition: Listen for events regarding entities deployments and bundles optimizations to transition state of entities stored in the database in order to ensure their latest version is always returned.
• Profiles registry: Provides an endpoint to retrieve validated Catalysts' profiles.
• Profiles sync: Polls entities from all Catalysts to react over new profiles deployments to store them in a multi-layer storage (memory cache and database).
• Profiles curation: Triggers a job every N minutes to validate ownership of all profiles stored in the rapid access cache.

Dependencies & Related Services

This service interacts with the following services:

• Deployments to SQS: Listens for events triggered by this service to react over new Catalyst deployments
• World Content Server: Listens for events triggered by this server to react over new Worlds deployments
• Asset Bundle Converter: Listens for events triggered by these services to react over bundle optimizations
• Catalyst: Used to validate received entities deployments and sanitize profiles stored in the cache

External dependencies:

• SNS and SQS from AWS Cloud Provider
• PostgreSQL
• Redis

API Documentation

The API is fully documented using the OpenAPI standard. Its schema is located at docs/openapi.yaml.

Database

Schema

See docs/database-schemas.md for detailed schema, column definitions, and relationships

Migrations

The service uses node-pg-migrate for database migrations. These migrations are located in src/migrations/. The service automatically runs the migrations when starting up.

It also exposes scripts to nurture the database with deployments exported from Catalyst.

Create a new migration

Migrations are created by running the create command:

yarn migrate create name-of-the-migration

This will result in the creation of a migration file inside of the src/migrations/ directory. This migration file MUST contain the migration set up and rollback procedures.

Manually applying migrations

If required, these migrations can be run manually.

To run them manually:

yarn migrate up

To rollback them manually:

yarn migrate down

Getting Started

Prerequisites

Before running this service, ensure you have the following installed:

• Node.js: Version 20.x or higher (LTS recommended)
• Yarn: Version 1.22.x or higher
• Docker: For containerized deployment

Installation

1. Clone the repository:

git clone https://github.com/decentraland/asset-bundle-registry.git
cd asset-bundle-registry

2. Install dependencies:

yarn install

3. Build the project:

yarn build

Configuration

The service uses environment variables for configuration. Create a .env file in the root directory containing the environment variables for the service to run. Use the .env.default variables as an example.

Running the Service

Setting up the environment

In order to successfully run this server, external dependencies such as databases, memory storages and such must be provided. To do so, this repository provides you with a docker-compose file for that purpose. In order to get the environment set up, run:

docker-compose up

Running in development mode

To run the service in development mode:

yarn start:dev

Testing

This service includes comprehensive test coverage with both unit and integration tests.

Running Tests

Run all tests with coverage:

yarn test

Run tests in watch mode:

yarn test --watch

Run only unit tests:

yarn test test/unit

Run only integration tests:

yarn test test/integration

Test Structure

• Unit Tests (test/unit/): Test individual components and functions in isolation
• Integration Tests (test/integration/): Test the complete request/response cycle

For detailed testing guidelines and standards, refer to our Testing Standards documentation.

AI Agent Context

For detailed AI Agent context, see docs/ai-agent-context.md.