Definition Metadata

JSON objects that make it easier to Web3 interfaces and webapps to parse and make sense of the "craftable" tokens and Crafting Rulel.

For illustrative purposes, every example will follow from the clothes.sol showcased in Craftable Token.

Providing definition metadata allows applications like Craftware to display crafting info for registered tokens and perform crafting operations. Craftable game tokens on a given smart contract will store attribute values as lists. a definition will allow us for example to know what each value stands for in terms of game environments.

Uses for the definition file

Registering the Definition URI

To associate the URI to a given contract, the contract must be initialized with the correct URI at deploy time in the token constructor.

Reading the Definition URI

Once deployed, the definition URI is accessible through the defUri() function.

token.defURI() // => .../token-definition.json

Metadata Structure

The purpose of the metadata is to describe the classes and their attributes for each ERC1155 token.

Here is an example for the clothes.sol contract.

clothes-definition.json

{
    "name": "Clothes",
    "classes": [...]
}

Here's how each of these properties work:

name	Name of the ERC1155 contract providing the various tokens
classes	These are the various classes of tokens that can be minted in this contract. for example, for clothes that would be 2 classes: hats and pants.

Class Definition

To be able to craft multiple categories of items in one contract, we define a list of acceptable classes of tokens to be part of the contract. All tokens of the same class have the same set of attributes but not the same attribute values.

Here is an example of the class attributes

clothes-definition.json

{
    ...
    "classes": [
        {
            "name": "Hat",
            "class" : 1,
            "attributes" : [...], 
        }
    ]
}

Here is how each of the class properties work:

name	Name of the class
class	The class ID for this class. All tokens of the same class must have this value for the classes(_id) in the contract.
attributes	A list of attribute definitions for this class.

In the contract, we recommend to define the IDs as constants in the start of the contract. uint256 public HAT_CLASS = 1;

The order of attributes in the definition must match the order of attributes when we interact with the contract. In other words, the attribute at position 1 in the definition has a value in the contract that can be read at token.attributes[1] and so on.

Attribute Definition

Inside the smart contract, the attribute values are strictly integers (uint256 to be specific). This means that we need to develop smart ways to represent floats, dropdown fields, ...

The attribute definition helps parties decipher and translate the on-chain integer value to the intended game value. It might look something like this.

clothes-definition.json

{
    // the pants class
    ...
    "attributes": [
        // attribute at index 1
        {
          name: "material",
          type: "categorical",
          values: [
            { name: "jeans", value: 1 },
            { name: "lenin", value: 2 },
            ...
          ],
        },
        // attribute at index 2
        {
          name: "length",
          type: "numerical",
          min: 0.0,
          max: 100.0,
          res: 8,
        },
        ...
    ]
    ...
}

So depending on this definition we can translate the attributes of a pants token

// Solidity storage for token 1
[ 1, 64, ... ]

// translated attribute values

{ "material": "jeans", "length": 25, ... }

The fixed properties for any attribute definition are:

name	Name of the attribute
type	an attribute can be of many types. each type tells the web-app to translate the integer value differently.

Depending on the type of the attribute, each attribute might have different properties. For now, we support three types of attributes that can be expanded later on:

• Categorical Attribute

• Numerical Attribute

• Boolean Attribute

Categorical Attribute

type: "categorical"

A categorical attribute is any attribute for a game item that accepts a value from a finite set of choices that can be in text or numbers.

The only extra property to add to the definition is the list options: [...]. Each option has a name and value. value is the on-chain integer, while name is the game-specific value.

Numerical Attribute

type: "numerical"

A numerical attribute is an approximation for any floating value attribute. Since, we can use integers only on-chain, it means that we can represent specific points in the range of values. For example, if we are using 2 bits of resolution, we can represent 2^2 = 4 values. for the range [1, 3] we can represent the following intermediate values spread out uniformly:

Integer value	Bits representation	In-game value
0	00	1
1	01	5/3 ~ 1.66666667
2	10	7/3 ~ 2.33333333
3	11	3

Hence the properties are:

min	The minimum possible value. Lower end of the interval.
max	The maximum possible value. Higher end of the interval.
res	The resolution. The number of possible value points in the interval [min, max] is 2 to the power of res. The larger the resolution, the more accurate you can be in representing intermediate values.

Boolean Attribute

type: "boolean"

A boolean attribute is simple as the name suggests. It is an attribute than can be either True or False. The corrsponding integer value can be respectively 0 or 1. No extra propreties are needed if you define a boolean attribute.