Decentraland Crypto

2.3.0 verified Sat Apr 25 auth: no javascript

Decentraland Crypto (dcl-crypto) is a TypeScript library for authentication and cryptographic operations within the Decentraland ecosystem, currently available in versions 2.3.0 (stable) through 3.6.0. It provides utilities for signing messages, verifying identities, and interacting with Ethereum-based authentication schemes. The library is designed specifically for Decentraland's authentication protocol and is maintained by the Decentraland core team with regular releases (~monthly). Key differentiators include built-in support for Decentraland's identity model and provider abstractions.

Common errors

error Module not found: Error: Can't resolve 'dcl-crypto' in '/path/to/file' ↓

cause Importing from the deprecated unscoped package name after upgrading to v3.

fix

Change import to '@dcl/crypto' and run npm install @dcl/crypto.

error TypeError: Authenticator.validateSignature is not a function ↓

cause Calling old method signature after upgrading to v3 where the API changed.

fix

Check docs for new signature: Authenticator.validateSignature(authChain, authLink, message).

error MissingProviderError: No provider found. Please inject an Ethereum provider. ↓

cause Trying to use createIdentity without providing a valid provider.

fix

Ensure you pass a valid provider (e.g., from ethers or eth-connect) as the second argument.

error Error: The message is too long (max 10000 characters) ↓

cause Signing a message that exceeds the maximum allowed length.

fix

Shorten the message or split it into chunks that are individually signed.

Warnings

breaking In v3.0.0, package was renamed from 'dcl-crypto' to '@dcl/crypto'. All imports must be updated. ↓

fix Change 'import ... from "dcl-crypto"' to 'import ... from "@dcl/crypto"'.

breaking In v3.0.0, the 'Authenticator' class was rewritten. The 'validateSignature' method signature changed. ↓

fix Update to new signature: `Authenticator.validateSignature(authChain, authLink, message)`.

deprecated The 'createIdentity' function accepts an optional third parameter (provider) that is deprecated in favor of using eth-connect providers. ↓

fix Use eth-connect provider and pass it as second argument to 'createIdentity'.

gotcha When using Node.js, 'ethers' must be installed separately as a peer dependency, but it is not listed in package.json. ↓

fix Run `npm install ethers` to use the wallet functionality.

gotcha The 'Identity' type uses an array for 'authChain' which may be non-serializable if containing functions. Ensure serialization before sending over network. ↓

fix Use `JSON.parse(JSON.stringify(identity))` to serialize.

Install

npm install dcl-crypto

yarn add dcl-crypto

pnpm add dcl-crypto

Imports

Identity
wrong
```
import Identity from '@dcl/crypto'
```
correct
```
import { Identity } from '@dcl/crypto'
```
Identity is a named export, not a default one. Common mistake when migrating from CommonJS.
Authenticator
wrong
```
const { Authenticator } = require('dcl-crypto')
```
correct
```
import { Authenticator } from '@dcl/crypto'
```
Use the scoped @dcl/crypto package for ESM compatibility. The unscoped 'dcl-crypto' is deprecated.
createIdentity
wrong
```
import { createIdentity } from 'decentraland-crypto'
```
correct
```
import { createIdentity } from '@dcl/crypto'
```
Correct package name is '@dcl/crypto'. The full name 'decentraland-crypto' is a common alias but may not resolve correctly.
AuthLink
```
import type { AuthLink } from '@dcl/crypto'
```
Use 'import type' for type-only imports to avoid runtime bundling issues.

Quickstart

Demonstrates creating an identity and signing/verifying a message using browser Ethereum provider.

import { Authenticator, createIdentity } from '@dcl/crypto';
import { ethers } from 'ethers';

async function authenticate() {
  const provider = new ethers.providers.Web3Provider(window.ethereum);
  const signer = provider.getSigner();
  const address = await signer.getAddress();
  
  const identity = await createIdentity(address, signer);
  console.log('Identity created:', identity);
  
  const message = 'Hello, Decentraland!';
  const authChain = await Authenticator.initializeMessage(identity, message);
  const isValid = await Authenticator.validateSignature(identity.authChain, authChain, message);
  console.log('Signature valid:', isValid);
}

authenticate().catch(console.error);