Metadata
Dojo supports associating offchain metadata with the world and its resources. This provides additional context about the world and its resources, such as their name, description, icon URI, and more. This enables external services to easily index and distribute worlds and experiences built on them.
During migration, sozo
automatically manages metadata for you, uploading it to IPFS in JSON
format and registering it in the world contract through the ResourceMetadata
Dojo model. sozo
does this by parsing the metadata defined in the Dojo profile configuration dojo_<PROFILE>.toml
.
World Metadata
To set world metadata, create the following section in your dojo_<PROFILE>.toml
:
[world]
name = "example"
seed = "dojo_examples"
description = "example world"
icon_uri = "file://assets/icon.png"
cover_uri = "file://assets/cover.png"
website = "https://dojoengine.org"
[world.socials]
x = "https://twitter.com/dojostarknet"
github = "https://github.com/dojoengine/dojo"
discord = "https://discord.gg/FB2wR6uF"
The toolchain supports the name
, description
, icon_uri
, cover_uri
, website
and socials
attributes by default.
*_uri
attributes can point to an asset in the repo using the file://
schema or to remote resources using either ipfs://
or https://
. For local assets, sozo
will upload them to IPFS and replace the corresponding URIs with an IPFS URI.
Arbitrary social links can be set by adding key-value pairs under the socials
section. For example, you could add telegram = "https://t.me/dojoengine"
.
Resource Metadata
To set resource metadata, create the following sections in your dojo_<PROFILE>.toml
, using [[models]]
, [[contracts]]
or [[events]]
depending on the type of the resource:
[[models]]
tag = "ns-Position"
description = "Position of the player in the world"
icon_uri = "file://assets/position_icon.png"
[[events]]
tag = "ns-Moved"
description = "Event emitted when a player has moved"
icon_uri = "file://assets/moved_icon.png"
[[contracts]]
tag = "ns-actions"
description = "Available actions for a player in the world"
icon_uri = "file://assets/actions_icon.png"
For each type of resource, the toolchain supports the description
and icon_uri
attributes by default. The name
of the resource, retrieved from its tag
, is also stored in the resource metadata.
*_uri
attributes can point to an asset in the repo using the file://
schema or to remote resources using either ipfs://
or https://
. For local assets, sozo
will upload them to IPFS and replace the corresponding URIs with an IPFS URI.
IPFS Configuration
The toolchain supports IPFS configuration options in the profile configuration file dojo_<PROFILE>.toml
. This configuration is required for uploading local assets and metadata to IPFS.
[env]
ipfs_config.url = "https://ipfs.infura.io:5001"
ipfs_config.username = "2EBrzr7ZASQZKH32sl2xWauXPSA"
ipfs_config.password = "12290b883db9138a8ae3363b6739d220"
Technical Implementation
Dojo uses the ResourceMetadata
model to store metadata on-chain. This model is defined in Cairo as:
#[derive(Introspect, Drop, Serde, PartialEq, Clone, Debug)]
#[dojo::model]
pub struct ResourceMetadata {
#[key]
pub resource_id: felt252,
pub metadata_uri: ByteArray,
pub metadata_hash: felt252,
}
Fields
resource_id
: A unique identifier for the resource (world, model, contract, or event)metadata_uri
: The URI pointing to the metadata JSON file (typically an IPFS URI)metadata_hash
: A hash of the metadata content for integrity verification