Crafting Protocol

Combining on-chain tokens from many games to create on-chain tokens for other games.

The Crafting Protocol is a set of abstract contracts and interfaces that build around and interact with ERC1155 tokens strictly.

What is Crafting?

Crafting is the missing piece of cross-game collaboration and utilizing game tokens. The Crafting Protocol is a set of specifications, Smart Contracts, and interfaces that allow web3 games to join hands and collaborate on complex token swap deals. With the Crafting protocol, we aim to create accessible and scalable agreements on exchanging a set of tokens from many games to other tokens from other games.

What is the Goal?

In this protocol, we are targeting three stakeholders:

• Input Web3 Tokens: Web3 Games with tokens to offload (Ingredients)

• Output Web3 Tokens: Web3 Games that want to craft their tokens from other games (Outputs)

• Players who want to engage in the play-to-earn scheme hoping to find a value in the tokens of game 1 by crafting corresponding tokens in game 2.

The motivations for these 3 parties can vary widely based on the use case.

So, we aim to provide a service that allows games to collaborate on defining a new crafting rule with

• Ingredients: a set of ERC1155 tokens with diverse balances, attributes, and origin contracts.

• Outputs: another set of such tokens from other games and contracts.

• Mapping Method: an immutable, generic, scalable, accessible, and efficient manner to define the output balances and attributes based on the ingredients the player provides. We the quantities of interest are:

  • Attributes: A set of unique values that associate with a token ID. ex: sword length, material, ...

  • Balances: The quantity of such tokens. ex: 3 swords with the same attributes.

  So, the mapping rule takes as input the balances and attributes of ingredients and mints tokens with corresponding balances and attributes. for ex:

mapping.sol

...
function rule( Bag memory inBag, ItemAttributes[] memory inAttributes) {
    ...
    // sandwich type:
    // sweet falafel and not hummus => falafel icecream sandwich
    if (falafelAttributes.attributes[0] == 1 && condiment.class != 2) {
      outAttributes[0].attributes[0] = 3;
    } else if ( ... ) {
        ...
    }
}
...

This is just a basic example. To find more details about the types in the parameters for the function, the representation of attributes, ... Check Crafting Rule Contract.

In this system, all partner games - posing as both ingredients and outputs - need to approve said crafting rule to authorize it to:

• transfer player ingredient tokens

• mint output tokens based on the immutable rules

Finally, the system should adhere to the security requirements that prevent members in the system of abusing power, trust, and timing problems.

Architecture Overview

Our system is an end-to-end suite of abstract contracts and interfaces from which any ERC1155 can be inherited. During the development of these components, we aimed to allow the most flexibility to games to define how their own tokens operate, while asking for minimal functions to manipulate and represent some of the entry points.

At the heart of the Crafting Protocol is our Abstract Smart Contracts and Interfaces

Crafting Rule

The Crafting Rule is an abstract contract that implements all the functions required to accept ingredients in a standard format, and mint or transfer outputs. The user will care about two main functions once a crafting rule is deployed

• CraftingRule.craft( ... ) which takes lists of tokens the user owns from the ingredient contracts, maps the balances and attributes, and mints the tokens to the user.
• CraftingRule.redeem( ... ) We designed crafting to be reversible. At any time that you want to redeem the ingredients back to your wallet, call redeem .

The game ERC1155 developers need to worry about three functions before deploying a crafting rule to enforce a standard method to interact with the contract

• CraftingRule._inputItemOrderValid( ... ) : To make sure the user inputs the tokens in a specified and agreed order.
• CraftingRule._outputItemOrderValid( ... ) : To make sure the user inputs the tokens in a specified and agreed order.
• CraftingRule.rule( ... ) : The central function of the contract. In this function you write the mapping code to compute output attributes and balances from input attributes and balances.

Crafting Rule Contract

Craftable Input

ex: contract MyFalafel is CraftableIn, ... {

The Craftable Input is an abstract contract with a set of functions and logic units that augment existing ERC1155 tokens to be consumable by the Crafting Rule.

A key constraint for the input tokens is that they must implement on-chain attribute storage.

The Craftable Input extension to any token contract will be completely transparent to the user.

On the other hand, Game Token Developers must implement the following functions:

• CraftableIn.attributes( ... ): which must return the attribute value at a specific index as ordered in the Definition file hosted for the token. (More about that in Craftable Input Token).
• (optional) function tokenURI( ... ): an optional function to generate a URI for the token in alignment with the OpenSea Metadata standards.

Craftable Output

Similar to Craftable input, but rather than constraining the attributes to be on chain, they can be stored anywhere.

ℹ️ Before moving forwards, we need to introduce the concept of a template. Tokens having the same attribute values are said to have the same template. For each template is associated an ID. (ex: Token #1 (length=2, width=3) and Token #2 (length=2, width=3) have the same template). Templates are important to optimize the storage of attribute lists for similar tokens.

The developers must implement the following functions before deploying:

• CraftableOut._storeTemplateData( ... ) : A function that takes in the attributes for a template to be added and the template ID. This function allows the designer to be flexible in how to store the template data. For example, some would store them in a mapping fashion on-chain, while others will point to pre-hosted off-chain metadata URIs.

• CraftableOut._templateURI( ... ) : Given a template ID, returns the URI pointing to the OpenSea Metadata Formatted JSON file containing the attributes and values. It is flexible for designers to point to external URIs if attributes are handled off-chain or Data URLs for on-chain attribute storage.

Definition Metadata & Web apps

One of the requirements of the protocol is to be accessible to users (players and game managers). This requires an easy way for all parties to lookup what tokens does this ERC1155 contract provide and what are their attributes. While this is a relevant question for business applications, it is not necessary to store the "meaning" of attributes[0] as "length of the sword" on-chain for scalability, generalizability, and storage efficiency. Similarly to how OpenSea requires a metadata file to make sense of the attributes of a certain token, we require a definition metadata file to make sense of the Craftable tokens.

Using the Craftable abstract contracts -as mentioned- all tokens attributes are defined in an ordered list. The meaning of each attribute of the list is stored in a metadata file hosted somewhere accessible to parties but not necessarily on-chain. We call these descriptive files as Definitions.

Definitions are small JSON files that encapsulate the what matters for Games and Players.

For illustration purposes, this is the definition of a falafel ERC1155 Craftable token.

falafel_definition.json

{
  "name": "Falafel",
  "classes": [
    // list of the token "classes" supported
    // here just one class exists, which is Falafel
  
    {
      // definition of the Falafel "class"
      "name": "Falafel",                  // class name
      "class": 1,                         // class ID
      "attributes": [
        // list of attributes
        // order in contract must be honored
        {
          // attribute 1 definition
          "name": "taste",                // attribute name
          "type": "categorical",          // attribute type (for evaluation purposes)
          
          // categorical attributes have different options
          "values": [
            { "name": "sweet", "value": 1 },
            { "name": "hot", "value": 3 },
            { "name": "salty", "value": 2 },
            { "name": "sour", "value": 4 },
            { "name": "bitter", "value": 5 }
          ]
        },
        {
          // attribute 2 definition
          "name": "size",
          "type": "numerical",
          
          // numerical attributes have min, max, 
          // and resolution (number of possible values)
          "min": 0.0,
          "max": 100.0,
          "res": 32
        }
      ]
    }
  ]
}

Helping games create crafting rules

Because we aim to make crafting rules accessible to all games, we offer a no-code tool.

This tool will help you:

• search and display craftable input and output contracts others deployed.

• select from many methods of generating the crafting rule and mapping the attribute combinations of input tokens to output tokens. For example, we provide a spreadsheet approach, filters approach, etc...

• preview the Crafting smart contract and deploy it.