Anatomy of a smart contract
- What is a smart contract?
- Deep dive into smart contract types:
- Fungible
- Non-fungible
- Use cases of fungible and non-fungible tokens
What is a smart contract?
A smart contract is a class of code that is deployed to and runs on the blockchain. They can be made up of any arrangement of code and perform a wide range of functionality.
Examples of some common smart contracts:
- Settlement contracts: Facilitates the sale of assets from one user (seller) to another (buyer) by handling the filling of an order, payment and transfer of assets. Typically used by marketplaces in conjunction with an orderbook service.
- Token contracts: Facilitates the creation (minting) of tokens that can be used and transferred between users in the open market.
The main type of smart contract that we are mostly concerned about as developers of blockchain games and NFT applications are token smart contracts.
Token smart contracts
These are smart contracts that govern the issuance (creation) of tokens. These contracts are typically defined by standards, which specify the functions that it needs to have to ensure that there is a standard way that games, applications and other contracts can interact with it.
The two main kinds of token smart contracts that we are concerned with when building games or NFT applications on Immutable X are:
- Non-fungible (defined by the ERC-721 standard) - these produce tokens with unique properties from other tokens in their collection. For example, Bored Ape #1 isn't interchangeable for Bored Ape #2 because they differ across a range of characteristics (ie. image, rarity) that different users will value differently.
- Fungible (defined by the ERC-20 standard) - these produce commodity-like tokens that are interchangeable with another token in its category, ie. ETH, IMX. If you lend someone ETH, it doesn't matter whether they send you back the exact same tokens that you lent them. All ETH tokens are identical and their value is the same.
There are also semi-fungible contracts (defined by the ERC-1155 standard), which can be very useful for blockchain games, however, they are not fully supported by Immutable X yet.
As you might expected, non-fungible token contracts produce non-fungible tokens (NFTs), fungible contracts produce fungible tokens and... well, you get the drift 😉
Key components of fungible and non-fungible token contracts:
| Fungible | Non-fungible | |
|---|---|---|
| Information stored about tokens | How many tokens in total can this contract create? Contract function: totalSupply() returns this value | How many tokens in total can this contract create? Contract function (in ERC-721 enumerable, which is an extension of the ERC-721 standard): totalSupply() returns total tokens in the contractMetadata containing each token's characteristics Contract function: tokenURI() returns the URL with the metadata JSON containing the details of each token |
| Information stored about token ownership | How many tokens does a given user own? Contract function:
| Who owns the token at a given token ID? Contract function:
|
What happens when the mint() function is called? |
|
|
Other useful functions
transfer(tokenAmount, address)- which transfers a specified amount of tokens from the caller's account to another user'sapprove(address, tokenAmount)(fungible) /approve(address, tokenID)(non-fungible) - the caller may approve another user to spend or transfer tokens on their behalf
For the full list of standard functions, see:
Example contract
Our contracts repo on GitHub contains some templates for smart contracts that are compatible with Immutable X.
Asset.sol
Asset.sol is an example of a non-fungible (ERC-721 standard) contract that contains the functions required so that tokens can be minted from it on Immutable X.
It implements the _mintFor function which is called when the asset is minted on L1 when it is withdrawn from Immutable X to Ethereum (see step 4 here). This function calls _safeMint, which is an inherited function from the ERC-721 contract that mints the NFT in a safe way.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.4;
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "./Mintable.sol";
contract Asset is ERC721, Mintable {
constructor(
address _owner,
string memory _name,
string memory _symbol,
address _imx
) ERC721(_name, _symbol) Mintable(_owner, _imx) {}
function _mintFor(
address user,
uint256 id,
bytes memory
) internal override {
_safeMint(user, id);
}
}
The Mintable.sol contract that Asset.sol inherits from provides the token-minting functionality:
/ SPDX-License-Identifier: MIT
pragma solidity ^0.8.4;
import "@openzeppelin/contracts/access/Ownable.sol";
import "./IMintable.sol";
import "./utils/Minting.sol";
abstract contract Mintable is Ownable, IMintable {
address public imx;
mapping(uint256 => bytes) public blueprints;
event AssetMinted(address to, uint256 id, bytes blueprint);
constructor(address _owner, address _imx) {
imx = _imx;
require(_owner != address(0), "Owner must not be empty");
transferOwnership(_owner);
}
modifier onlyIMX() {
require(msg.sender == imx, "Function can only be called by IMX");
_;
}
function mintFor(
address user,
uint256 quantity,
bytes calldata mintingBlob
) external override onlyIMX {
require(quantity == 1, "Mintable: invalid quantity");
(uint256 id, bytes memory blueprint) = Minting.split(mintingBlob);
_mintFor(user, id, blueprint);
blueprints[id] = blueprint;
emit AssetMinted(user, id, blueprint);
}
function _mintFor(
address to,
uint256 id,
bytes memory blueprint
) internal virtual;
}
Things to note about the examples above:
owneris the wallet address you choose to be the minter of the contract, so it should be a very safe, secure wallet.transferOwnership(_owner)does exactly as described, and transfers the ownership of the contract from the contract deployer to the specific wallet address.- The address named
imxrefers to the Immutable X contract address that is interacting with your smart contract to perform minting operations. You can find the address for each environment in the README of the contracts repository. This address is used in theonlyIMXmodifier, which checks if the sender of the transaction is our contract or not. This is a way of whitelisting our contract and ensuring that no one else can mint assets through your smart contract. - The
mintForfunction is called by the Immutable X smart contract at the time of withdrawing the NFT to Ethereum. The function has theonlyIMXmodifier, as explained above. Because you’re minting NFTs, which are unique, ensure that quantity = 1. - The blueprint is saved as on-chain, Immutable metadata in the mapping blueprints. For custom blueprint decoding, you can override the mintFor function in Asset.sol to save it in something like tokenURI, or split the string into different components.
- The function emits an event
AssetMintedwhen the mintFor completes successfully, and this can be listened on by applications.
Fungible tokens
Use cases
- Staking: This process allows individuals to lock specified amounts of their tokens to earn a yield. This is not available to all cryptocurrencies, and those who offer this operate under a Proof of Stake (PoS) consensus mechanism that requires specified amounts of a token to validate transactions.
- Voting: Holders of tokens are often offered voting rights by DAOs, also known as Decentralized Autonomous Organizations, who control ownership of certain token contracts. There are a variety of voting mechanisms, each outlining different requirements, however, it can generally be understood that the weight of a vote is proportional to the number of tokens owned.
- User acquisition: Many projects reward their community with their native tokens. This practice is common within many Web3 organizations, whereby constructive actions within an ecosystem may grant community members ecosystem rewards such as its native token.
- Game rewards: Many Web3 games are governed by a proprietary native token which they leverage to reward their users. These token rewards can then be spent to purchase items and cosmetics that help to drive the in-game economy.
Consider the IMX token: It has the potential to be staked, used for governance, trading rewards, developer incentivization, and in-game rewards as seen in its native projects such as Gods Unchained and Guild of Guardians.
Minting on Immutable X
Currently, L2 minting of fungible tokens are not supported by Immutable X. To transact with these tokens on L2, they must be minted first on L1 then deposited to L2 to be used.
Non-fungible tokens
Use cases
- Ownership: Demonstrate authenticity and ownership of assets (artwork, fashion, licenses, certificates, collectibles).
- Gaming: In game assets can be tokenised enabling players to own their assets and exchange them with others.
- Recurring revenue: Capture royalties from every transaction after the initial sale. This benefits all creators including: artists, designers, musicians, developers.
- Customer insight: Access to transaction data of NFT owners within apps and across platforms.
- Funding source: Increase the scale of investments by enabling fans to coinvest in their favourite artists and projects. NFTs can also be leveraged to reward these users in the future.
- New product lines: Create and sell merchandise which can give access to unique and personalised experiences eg tickets for events, backstage passes.
Minting on Immutable X
You can mint NFTs on Immutable X.
More information: