diff --git a/README.md b/README.md index 6ca63a1..f53df13 100644 --- a/README.md +++ b/README.md @@ -1,236 +1,29 @@ -# @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