Craft assets

Estimate time to complete: 20 minutes

Crafting assets is a broad term for the process of combining various in-game resources or items to create new and unique items or equipment. Typically you'll need to orchestrate a series of mint, transfer and burn steps.

The benefits of enabling this in your game includes enriching players' gaming experience, providing additional gameplay mechanisms, and fostering a dynamic and interconnected gaming ecosystem.

At its core, crafting consists of:

• Receiving existing assets from users
• Destroying, or locking the use, of the assets
• Creating new assets with different characteristics (i.e. metadata) to replace the old assets
• Distributing the new assets to users

Sections

• 1. Overview
• 2. Contract configuration
• 3. Executing a craft
• Appendix

---

💡Understand crafting

We recommend reading our crafting guide to learn more about how crafting works before jumping into this tutorial.

💡Early Access

Crafting is currently available in Testnet as an Early Access feature for game studios that have a contract with Immutable. Please stay tuned as we open this to Mainnet and all game studios.

1. Overview

A crafting transaction can be performed using Immutable preset token contracts and the Immutable Multicaller contract. The below diagram highlights the steps involved in a crafting transaction.

1.1. Recipes

Crafting recipes refer to a description of the expected inputs and outputs of a particular crafting transaction. In this guide, we will be demonstrating a common gameplay mechanic where a player will exchange consumable base ingredients, i.e. wood and metal, for a weapon which can then be used as an in-game item (a spear).

We will model this example using the preset ImmutableERC1155. ERC1155 contracts allows for semi-fungible tokens that make it ideal for in-game item representations such as consumables, since different amounts of the same token ID can be minted to different players.

Our example crafting recipe can be defined in non-technical terms as:

Player spends 10 wood and 2 metal and receives 1 spear

Our ERC1155 contract will be modelled as such:

• token ID of 1 represents wood
• token ID of 2 represents metal
• token ID of 3 represents spear

This translates to an atomic crafting transaction in which the following should occur:

• Player burns 10 of token ID 1 on ERC1155 contract
• Player burns 2 of token ID 2 on ERC1155 contract
• Game mints 1 of token ID 3 on ERC1155 contract to Player

note

In our example we are using a single token contract in both the inputs and outputs of our crafting transaction for simplicity. Your recipe can contain any combination of token contracts as long as they are configured with the relevant steps described below.

2. Contract configuration

2.1. Deploy Multicaller contract

Clone the Immutable Multicaller contract from the Immutable contracts repository:

git clone https://github.com/immutable/contracts

Follow the instructions in the foundry installation guide to install the foundry toolkit.

We are using version 2 of the Multicaller preset: Multicaller2. You will need the following inputs for deployment:

Input	Description
PRIVATE_KEY	The private key of the deployer account
ADMIN_ADDRESS	The address of the admin of the contract
MULTICALLER_NAME	Name of the Multicaller (string)
MULTICALLER_VERSION	Version of the Multicaller contract (string)

Deploy the Multicaller contract to zkEVM testnet using the following command:

forge create contracts/multicall/GuardedMulticaller2.sol:GuardedMulticaller2 --rpc-url "https://rpc.testnet.immutable.com" --private-key <PRIVATE_KEY> --constructor-args <ADMIN_ADDRESS> "<MULTICALLER_NAME>" "<MULTICALLER_VERSION>" --gas-price 20000000000 --priority-gas-price 20000000000

Please save the deployed Multicaller contract address, as well as the MULTICALLER_NAME and MULTICALLER_VERSION version used as you will need it for the next steps.

2.2. Deploy token contracts

In order to perform a craft you will need to have deployed and linked the token contracts that will be used as inputs and outputs to the crafting transaction. For the purpose of following the example in this guide an ImmutableERC1155 will need to be deployed.

See this guide for an in-depth tutorial on creating in-game assets including deploying a preset token contract.

See here for a full overview of our preset token contracts.

Grant minting permissions to the Multicaller contract

In order for the Multicaller to perform any mints that are required as an output of the crafting recipe, we will need to grant the Multicaller contract the permission to mint on the token contract.

This can be done whilst deploying your token contracts. In the drawer form Deploy Immutable contract presets that appears when deploying a contract, there is a section Minting Permissions. Add the addresss of the Multicaller contract here to allow the Multicaller to execute crafts on behalf of that token contract.

If you have already deployed your token contract, you can also update the minting permissions to include the Multicaller in Hub by navigating into your token contract page, selecting the Permissions tab and clicking on the Manage Permissions button. The opened drawer contains a section Minter which will allow you to add the address there.

2.3. Add Multicaller to the Operator Allowlist

In order for your Multicaller contract to successfully interact with Immutable's preset token contracts, it will need to be added to the Operator Allowlist, which can be done via our Hub interface.

See this guide for adding a contract to the Operator Allowlist.

2.4. Grant SIGNER_ROLE to the Immutable Signing API

The Multicaller contract operates on a signature based mechanism that allows for securely signing a payload off-chain that can be later executed on-chain by a different user. This is helpful for the use case of crafting, in which a game studio can generate a signature for a crafting transaction that can then be executed by the player. This is done using the secure and common method of EIP-712 hashing and signing.

To acquire a signable key for the Immutable Signing API, please visit the Keys page on your Hub environment. For more information on signable keys, see the Signable Key documentation.

Your Multicaller contract will need to grant the role SIGNER_ROLE to the Immutable Signing API key address, in order to use signatures generated by the Signing API in your crafting transaction. Navigate to the contract page of your deployed Multicaller contract in Immutable's Block Explorer.

Environment	Block explorer URL
testnet	https://explorer.testnet.immutable.com
mainnet	https://explorer.immutable.com

On your contract page, select the Contract > Write contract. If the contract does not show up as verified, click the Verify button. You will be able to add the Immutable Signing API to the Multicaller contract by running the grantMulticallerSignerRole, entering the key address from the table above. This will require signing a transaction using your browser wallet.

Once the Signing API address has been granted the SIGNER_ROLE on the Multicaller contract, signatures generated from the Immutable Signing API will be recognised as valid.

3. Executing a craft

For the purpose of following along with this guide you can clone our sample app:

Crafting sample app

caution

The sample app expects your Node version to be greater or equal 20.

Follow the instructions in the README in order to get the sample app running locally.

Appendix

Token approvals

In order for the Multicaller to operate on behalf of the Player to access their tokens as part of a crafting transaction, token contracts need to approve the Multicaller contract.

The EIP for ERC721 contract standards defines the ability to approve an operator (our Multicaller) for either a specific token ID with the approve function, or all token IDs with the setApprovalForAll function.

The EIP for ERC1155 contract standards defines only the ability to approve an operator (our Multicaller) for all token IDs, with the setApprovalForAll function.

Executing a crafting transcation using the Multicaller

The list of calls required for a crafting transcation is performed by calling the execute function on the Multicaller contract.

The execute function takes the following parameters

Parameter name	Type	Description	Purpose
multicallSigner	address	Address of the signer	Ensure the signature is generated by someone who has been granted the SIGNER_ROLE
reference	bytes32	Reference identifier	Used to prevent the replay attacks - the same transaction being performed twice
calls	Call[]	A list of calls	Instruct what needs to be executed.
deadline	uint256	Expiration timestamp	Controls for how long this craft is able to be executed
signature	bytes	Signature of the Multicaller signer	Validates that this exact transcation has been approved by a recognised signing authority