ERC-1155 With OpenZeppelin: A Beginner Tutorial With Code

For fungible currency you used ERC20. One contract, one token type, balances stored as a mapping from address to amount. Simple, but if you wanted ten currencies you deployed ten contracts.

For unique collectibles you used ERC721. One contract per collection, every token tracked by a unique ID. Great for art, but if you wanted to mint a thousand identical sword icons for a game, ERC721 forced you to give each sword its own ID and pay storage costs for a thousand unique entries.

ERC1155 collapses both patterns into one contract. The trick is a two dimensional balance mapping. Instead of balanceOf[address] returning a single number, ERC1155 stores balanceOf[address][tokenId]. A single contract can now host gold coins (fungible, you own 1,200), silver coins (fungible, 50 of them), a sword of fire (semi fungible, 3 copies), and a legendary armor (unique, one of one), all inside one deployed contract, all transferable in a single batch call.

Games were the original motivation (Enjin proposed the standard for in game items), but ERC1155 is now used for fractionalized art, event tickets, packaged NFT drops, DeFi receipts, and any product where you need many token kinds without many contracts.

The rest of this tutorial assumes you have Node.js installed and a Solidity workflow (Foundry, Hardhat, or Remix). Every contract below targets Solidity ^0.8.20 and OpenZeppelin Contracts version 5.x.

In a Foundry project:

forge install OpenZeppelin/openzeppelin-contracts

In a Hardhat or Node project:

npm install @openzeppelin/contracts

In Remix, you import directly from npm with no install step:

import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";

Always check the imported version matches the documentation you are reading. The v5.x line dropped the older _setupRole pattern and now uses AccessControl differently, so copy paste from a 2022 tutorial will not compile.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract MyFirstMultiToken is ERC1155, Ownable {
    // ERC1155 needs a URI template at construction.
    // Ownable v5 wants the initial owner explicitly.
    constructor(string memory uri_)
        ERC1155(uri_)
        Ownable(msg.sender)
    {}

    // Only the contract owner can mint. The "data" bytes are an
    // ERC-1155 extension point, almost always empty for simple cases.
    function mint(address to, uint256 id, uint256 amount) external onlyOwner {
        _mint(to, id, amount, "");
    }
}

The import pulls in the OpenZeppelin base contract. It already implements every required ERC1155 function: balanceOf, balanceOfBatch, setApprovalForAll, isApprovedForAll, safeTransferFrom, safeBatchTransferFrom, and supportsInterface. You inherit all of that for free.

The contract inherits both ERC1155 and Ownable. The latter gives you an owner slot and an onlyOwner modifier so the deployer is the only address allowed to mint. The constructor passes the URI template through to the parent and sets the deployer as the first owner. The Ownable(msg.sender) argument is required in OpenZeppelin v5; older v4 examples omit it and will not compile.

_mint(to, id, amount, "") is the internal helper from OpenZeppelin. It updates the balance mapping, fires the TransferSingle event, and calls onERC1155Received on the recipient if the recipient is a contract. The trailing "" is the optional data payload, almost always empty for simple mints.

Deploy this contract with a placeholder URI, call mint(0xYourAddress, 0, 100), and you have just minted one hundred copies of token ID 0 to yourself. Call mint(0xYourAddress, 1, 1) and you own one copy of a different token ID inside the same contract.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract GameCurrencies is ERC1155, Ownable {
    uint256 public constant GOLD   = 0;
    uint256 public constant SILVER = 1;
    uint256 public constant GEMS   = 2;

    constructor()
        ERC1155("https://example.com/metadata/{id}.json")
        Ownable(msg.sender)
    {
        _mint(msg.sender, GOLD,   10_000, "");
        _mint(msg.sender, SILVER, 50_000, "");
        _mint(msg.sender, GEMS,   100,    "");
    }
}

The contract pre mints an initial supply right inside the constructor. The deployer wallet ends up holding all three currencies at deployment time, which is convenient for a faucet pattern (you, the deployer, hand out tokens to players manually or through a separate distribution contract).

uint256 public constant declarations cost nothing extra at deploy time. The compiler inlines them as immutable constants. They give you readable code (GOLD instead of 0) and your contract still serves any token ID a client wants to query.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract CollectionWithMetadata is ERC1155, Ownable {
    constructor()
        ERC1155("https://my-game.example/api/items/{id}.json")
        Ownable(msg.sender)
    {}

    function mint(address to, uint256 id, uint256 amount) external onlyOwner {
        _mint(to, id, amount, "");
    }

    // Optional: let the owner update the URI template after deploy
    function setURI(string calldata newuri) external onlyOwner {
        _setURI(newuri);
    }
}

If you call mint(alice, 5, 1) on this contract, then call the read function uri(5), you get back the literal string https://my-game.example/api/items/{id}.json. The client (OpenSea, Etherscan, your own dApp) is responsible for replacing {id} with 0000000000000000000000000000000000000000000000000000000000000005 and fetching that URL.

Your off chain service therefore needs to respond at the padded hex path with a JSON document like:

{
  "name": "Iron Sword",
  "description": "A simple iron sword.",
  "image": "https://my-game.example/img/iron-sword.png",
  "decimals": 0,
  "properties": { "attack": 5, "rarity": "common" }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract BatchMintExample is ERC1155, Ownable {
    constructor()
        ERC1155("https://example.com/api/items/{id}.json")
        Ownable(msg.sender)
    {}

    /// @notice Mint many token IDs to one recipient in one transaction.
    function mintBatch(
        address to,
        uint256[] calldata ids,
        uint256[] calldata amounts
    ) external onlyOwner {
        _mintBatch(to, ids, amounts, "");
    }
}

Calling mintBatch(alice, [0,1,2,3,4], [100, 50, 25, 10, 1]) in one transaction gives Alice 100 copies of token ID 0, 50 of ID 1, 25 of ID 2, 10 of ID 3, and 1 of ID 4. One signed transaction. One gas payment for transaction overhead (the 21000 base). The per token cost is then dominated by the storage writes, which scale linearly. Batch minting 10 token IDs typically costs around 30 to 40 percent less than 10 separate _mint calls because you skip 9 transaction overheads and reuse the contract context once.

Under the hood, OpenZeppelin’s _mintBatch validates that ids.length == amounts.length (reverts with ERC1155InvalidArrayLength otherwise), updates _balances[id][to] for each pair in a tight loop, and fires one TransferBatch event containing both arrays. Marketplaces and indexers listen for TransferBatch instead of N individual TransferSingle events.

For a contract that accepts ERC1155, here is the minimal receiver:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC1155/utils/ERC1155Holder.sol";

contract MyVault is ERC1155Holder {
    // ERC1155Holder already implements onERC1155Received and
    // onERC1155BatchReceived correctly.
    // Add your business logic here, e.g. crediting the depositor.
}

For users transferring tokens TO a contract, the call site is:

// Single transfer
multiToken.safeTransferFrom(msg.sender, address(vault), tokenId, amount, "");

// Batch transfer
multiToken.safeBatchTransferFrom(msg.sender, address(vault), ids, amounts, "");

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract ConcertTickets is ERC1155, Ownable {
    // Ticket tiers — three token IDs inside one contract.
    uint256 public constant GENERAL   = 0;
    uint256 public constant VIP       = 1;
    uint256 public constant BACKSTAGE = 2;

    // Price per tier, in wei.
    mapping(uint256 => uint256) public priceOf;

    constructor()
        ERC1155("https://my-event.example/tickets/{id}.json")
        Ownable(msg.sender)
    {
        priceOf[GENERAL]   = 0.05 ether;
        priceOf[VIP]       = 0.2 ether;
        priceOf[BACKSTAGE] = 0.5 ether;
    }

    /// @notice Anyone can buy N tickets of one tier in a single transaction.
    function buy(uint256 ticketType, uint256 quantity) external payable {
        uint256 price = priceOf[ticketType];
        require(price > 0, "ConcertTickets: unknown tier");
        require(msg.value == price * quantity, "ConcertTickets: wrong amount");
        _mint(msg.sender, ticketType, quantity, "");
    }

    /// @notice Organiser withdraws ticket revenue.
    function withdraw() external onlyOwner {
        payable(owner()).transfer(address(this).balance);
    }
}

Why this is a great ERC1155 use case: three distinct ticket types live inside one contract, each tier is fungible (a hundred General tickets are interchangeable with each other), buyers can grab multiple tickets in one transaction, and you keep the well known token interface so OpenSea or any other marketplace can list resales without extra work.

The interesting line is _mint(msg.sender, ticketType, quantity, ""). The buyer becomes the recipient. The function is payable, so it accepts ETH; the require check enforces correct payment before any mint happens. Money in, tickets out, both atomic.

priceOf is a public mapping, which Solidity auto exposes as a getter, so a front end can read priceOf(0) to display the General Admission price without a separate view function. To raise prices later, add a small setPrice(id, newPrice) function gated by onlyOwner.

Real production tickets would add: per tier supply caps, a sale start/end window, a refund function, and an event for the indexer. Each is a few extra lines on top of this base. The point of this example is that ERC1155 fits perfectly the moment you have more than one product variant.

Pin the OpenZeppelin version in package.json or foundry.toml. Do not float the version range; a minor bump can change inherited behavior. Use AccessControl with named roles rather than Ownable once more than one human or service needs to mint. It scales better and is auditable on chain via role enumeration.

Add an upper bound on batch sizes. Allowing unlimited ids.length invites out of gas reverts in production. Use ERC1155Supply if uniqueness or supply caps matter. Use ERC1155Burnable if holders should be able to burn their tokens. Pin metadata to IPFS or Arweave for collections you intend to outlast a hosting account; use a centralized HTTPS endpoint only for ephemeral or dynamic metadata.

Emit at least one custom event when you mint, beyond the standard TransferSingle and TransferBatch. A PlayerStarterPackGranted(address player, uint256 timestamp) event gives your indexer a precise hook. And audit before mainnet. ERC1155 itself is well tested at the OpenZeppelin level, but your custom mint logic, supply caps, and role assignments are new code and should be reviewed.

There is no tokenOfOwnerByIndex. ERC1155 does not enumerate tokens by owner on chain. If you need a list-all-tokens-this-wallet-owns feature, you index events off chain (TransferSingle, TransferBatch) or maintain your own list in a separate contract.

There is no tokenURI(id) returning a per token URL. ERC1155 returns one template via uri(id). Wallets that previously rendered ERC721 metadata from tokenURI need extra logic for ERC1155.

There is no per token approval. approve(spender, tokenId) does not exist. Only setApprovalForAll(operator, bool). Marketplaces designed for ERC721 typically need a small adapter layer to handle this. None of these are bugs. They are tradeoffs the ERC1155 authors accepted in exchange for the batch transfer and multi token capabilities.