Skip to content
This repository was archived by the owner on Jul 14, 2026. It is now read-only.

chore: deprecate in favor of decentraland/core-libs #355

Merged
LautaroPetaccio merged 1 commit into from
Apr 25, 2026
Merged

chore: deprecate in favor of decentraland/core-libs #355

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
243 changes: 18 additions & 225 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,236 +1,29 @@
<img src="https://ui.decentraland.org/decentraland_256x256.png" height="128" width="128" />

# @dcl/content-validator
# @dcl/content-validator — DEPRECATED

[![Coverage Status](https://coveralls.io/repos/github/decentraland/content-validator/badge.svg?branch=main)](https://coveralls.io/github/decentraland/content-validator?branch=main)
> ⚠️ **This repository is deprecated.**
>
> `@dcl/content-validator` has moved into the [`decentraland/core-libs`](https://github.com/decentraland/core-libs) monorepo and now lives under [`libs/content-validator`](https://github.com/decentraland/core-libs/tree/main/libs/content-validator).
>
> Future development, issues, and pull requests should happen there. This repository is kept around only for historical reference and will not receive new releases.

Decentraland entity deployment validation library for Catalyst servers. Contains all validations to ensure only valid and authorized content is deployed to the [Decentraland content network](https://docs.decentraland.org/contributor/content/entities/).
## Migrating

## Table of Contents

- [@dcl/content-validator](#dclcontent-validator)
- [Table of Contents](#table-of-contents)
- [Features](#features)
- [Installation](#installation)
- [Design Guidelines](#design-guidelines)
- [Validation Types](#validation-types)
- [Size Limits (ADR-51)](#size-limits-adr-51)
- [Usage](#usage)
- [Basic Usage](#basic-usage)
- [Access Validation Strategies](#access-validation-strategies)
- [On-Chain Validation](#on-chain-validation)
- [Subgraph Validation](#subgraph-validation)
- [Getting Started](#getting-started)
- [Development](#development)
- [Debugging Tests](#debugging-tests)
- [Adding New Entity Types](#adding-new-entity-types)
- [Project Structure](#project-structure)
- [External Dependencies](#external-dependencies)
- [Versioning and Publishing](#versioning-and-publishing)
- [AI Agent Context](#ai-agent-context)

## Features

- **Entity Structure Validation** - Validates JSON structure, required fields, and content references for all Decentraland entity types
- **Access Permission Checking** - Verifies deployer ownership via blockchain (on-chain) or The Graph (subgraph)
- **IPFS Content Integrity** - Ensures content file hashes are valid IPFS CIDs and files exist
- **Size Enforcement** - Enforces max size limits per entity type following ADR-51 specifications
- **Metadata Schema Validation** - Validates metadata against `@dcl/schemas` definitions
- **Signature Authentication** - Verifies AuthChain signatures for entity authenticity
- **Multi-Entity Support** - Validates scenes, profiles, wearables, emotes, stores, and outfits
- **Dual Access Strategies** - Supports both on-chain and subgraph-based ownership verification
- **Legacy Compatibility** - Maintains backwards compatibility with legacy content migrations

## Installation
The npm package name is unchanged — `@dcl/content-validator`. New versions are published from the monorepo and will continue to appear on the same npm dist-tags. To pick up the latest fixes, simply bump the dependency as usual:

```bash
npm i @dcl/content-validator
```

## Design Guidelines

- Validate as early as possible to prevent invalid content from being stored
- Provide clear, actionable error messages for deployment failures
- Support both on-chain and subgraph-based access verification
- Maintain backwards compatibility with legacy content migrations
- Ensure all validation functions are stateless where possible

Implementation decisions:

- The library exports a `createValidator` factory function as the main entry point
- Validation functions return `{ ok: boolean, errors?: string[] }` responses
- Access checking supports two strategies: on-chain (direct blockchain) and subgraph (The Graph)
- Size limits are defined per entity type following [ADR-51](https://adr.decentraland.org/adr/ADR-51)

## Validation Types

The validator performs the following checks on entity deployments:

| Validation | Description |
|------------|-------------|
| **Entity Structure** | Validates JSON structure, required fields, and content references |
| **IPFS Hashing** | Ensures content file hashes are valid IPFS CIDs |
| **Metadata Schema** | Validates metadata against `@dcl/schemas` definitions |
| **Signature** | Verifies AuthChain signatures for entity authenticity |
| **Size** | Enforces max size limits per entity type (see below) |
| **Access** | Verifies deployer owns the entity pointers (LAND, NFTs, names) |
| **Content** | Ensures all referenced content files exist and are accessible |
| **Entity-Specific** | Additional validations per type (wearables, emotes, profiles, scenes, outfits) |

### Size Limits (ADR-51)

| Entity Type | Max Size | Notes |
|-------------|----------|-------|
| Scene | 15 MB | Per parcel |
| Profile | 2 MB | |
| Wearable | 3 MB | |
| Wearable (Skin) | 9 MB | Special category |
| Emote | 3 MB | |
| Store | 1 MB | |
| Outfits | 1 MB | |

## Usage

### Basic Usage

```typescript
import { createValidator, ContentValidatorComponents, DeploymentToValidate } from '@dcl/content-validator'

// Create validator with required components
const validator = createValidator({
logs: logsComponent,
externalCalls: {
isContentStoredAlready: async (hashes) => { /* ... */ },
fetchContentFileSize: async (hash) => { /* ... */ },
validateSignature: async (entityId, auditInfo, timestamp) => { /* ... */ },
ownerAddress: (auditInfo) => { /* ... */ },
isAddressOwnedByDecentraland: (address) => { /* ... */ },
calculateFilesHashes: async (files) => { /* ... */ }
},
accessValidateFn: accessValidator // on-chain or subgraph-based
})

// Validate a deployment
const deployment: DeploymentToValidate = {
entity: { /* entity data */ },
files: new Map([/* content files */]),
auditInfo: { authChain: [/* auth chain */] }
}

const result = await validator(deployment)
if (!result.ok) {
console.error('Validation failed:', result.errors)
}
npm install @dcl/content-validator@latest
# or
yarn add @dcl/content-validator@latest
# or
pnpm add @dcl/content-validator@latest
```

### Access Validation Strategies

The library supports two access validation strategies:

#### On-Chain Validation

Direct blockchain queries for ownership verification:

```typescript
import { createOnChainAccessCheckValidateFns, createOnChainClient } from '@dcl/content-validator'

const validateFns = createOnChainAccessCheckValidateFns({
logs,
externalCalls,
client: createOnChainClient({ logs, L1, L2 }),
L1: { checker, collections, thirdParty, blockSearch },
L2: { checker, collections, thirdParty, blockSearch }
})
```

#### Subgraph Validation

Uses The Graph for ownership queries (more efficient for bulk queries):

```typescript
import { createSubgraphAccessCheckValidateFns, createTheGraphClient } from '@dcl/content-validator'

const validateFns = createSubgraphAccessCheckValidateFns({
logs,
externalCalls,
theGraphClient: createTheGraphClient({ logs, subGraphs }),
subGraphs,
tokenAddresses: { land: '0x...', estate: '0x...' }
})
```

## Getting Started

### Development

Install dependencies and run tests:

```bash
yarn
yarn build
yarn test
```

### Debugging Tests

If you are using VS Code, install the recommended extensions and debug tests using the Jest extension which adds UI support.

## Adding New Entity Types

Before adding any validation for new entities:

1. **Create entity schema** on [@dcl/schemas](https://github.com/decentraland/common-schemas)
2. **Add entity type and schema** on [catalyst-commons](https://github.com/decentraland/catalyst-commons/)
3. **Add access checker** in [access/index.ts](./src/validations/access/index.ts) and implement entity-specific validation
4. **Add size limit** in [ADR51.ts](./src/validations/ADR51.ts)
5. **Verify URN resolution** - if required, add a new resolver in [@dcl/urn-resolver](https://github.com/decentraland/urn-resolver)

## Project Structure

```
src/
├── index.ts # Main entry point, createValidator factory
├── types.ts # Core types (DeploymentToValidate, ValidationResponse, etc.)
├── utils.ts # Utility functions
└── validations/
├── index.ts # Validation function aggregator
├── access/ # Access permission validators
│ ├── common/ # Shared access validation logic
│ ├── on-chain/ # Direct blockchain access checking
│ └── subgraph/ # The Graph-based access checking
├── items/ # Item-specific validations
│ ├── emotes.ts
│ └── wearables.ts
├── ADR45.ts # ADR-45 validation rules
├── ADR51.ts # Size limits per entity type
├── content.ts # Content file validation
├── entity-structure.ts # Entity JSON structure validation
├── ipfs-hashing.ts # IPFS hash validation
├── metadata-schema.ts # Metadata schema validation
├── outfits.ts # Outfits-specific validation
├── profile.ts # Profile-specific validation
├── scene.ts # Scene-specific validation
├── signature.ts # AuthChain signature validation
├── size.ts # Entity size validation
└── timestamps.ts # Important timestamp constants
```

## External Dependencies

| Dependency | Purpose |
|------------|---------|
| `@dcl/schemas` | Entity type definitions and validation schemas |
| `@dcl/urn-resolver` | URN parsing and validation for items |
| `@dcl/block-indexer` | Blockchain block search for timestamp-based queries |
| `@dcl/hashing` | IPFS content hashing |
| `@well-known-components/thegraph-component` | The Graph subgraph queries |

## Versioning and Publishing

Versions are handled manually using GitHub releases and semver.

Main branch is automatically published to the `@next` dist tag to test integrations before final releases happen.
The public API is unchanged, so no code changes are required for consumers.

## AI Agent Context
## Where to file issues / PRs

For detailed AI Agent context including service purpose, key capabilities, technology stack, and validation details, see [docs/ai-agent-context.md](./docs/ai-agent-context.md).
- **Issues:** https://github.com/decentraland/core-libs/issues
- **Pull requests:** https://github.com/decentraland/core-libs/pulls
- **Source for `@dcl/content-validator`:** https://github.com/decentraland/core-libs/tree/main/libs/content-validator
Loading