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
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
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
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 |