Series1155V1

MINTER_ROLE

bytes32 MINTER_ROLE

METADATA_ROLE

bytes32 METADATA_ROLE

PAUSER_ROLE

bytes32 PAUSER_ROLE

ROYALTY_ROLE

bytes32 ROYALTY_ROLE

ADMIN_ROLE

bytes32 ADMIN_ROLE

contractUriFrozen

bool contractUriFrozen

Indicates if the contract URI is frozen

royaltyFrozen

bool royaltyFrozen

Indicates if the royalty is frozen

SeriesCreated

event SeriesCreated(uint256 seriesId, string uri, bool isFungible)

A new series is registered.

Parameters

Name	Type	Description
seriesId	uint256	Unique identifier for the series.
uri	string	IPFS base URI for the series metadata (e.g. “ipfs://“).
isFungible	bool	True if the series is fungible, false for 1-of-1 NFTs.

SeriesMetadataUpdated

event SeriesMetadataUpdated(uint256 seriesId, string oldUri, string newUri)

Series metadata URI updated.

Parameters

Name	Type	Description
seriesId	uint256	Series identifier.
oldUri	string	Previous IPFS base URI.
newUri	string	New IPFS base URI.

SeriesMetadataFrozen

event SeriesMetadataFrozen(uint256 seriesId, string uri)

Series metadata permanently frozen.

Parameters

Name	Type	Description
seriesId	uint256	Series identifier.
uri	string	Frozen IPFS base URI.

SeriesTokensMinted

event SeriesTokensMinted(uint256 seriesId, address to, uint256[] tokenIds, uint256[] amounts, bool isFungible)

Tokens minted for a series.

Parameters

Name	Type	Description
seriesId	uint256	Series identifier.
to	address	Recipient address.
tokenIds	uint256[]	List of token IDs minted.
amounts	uint256[]	Corresponding amounts minted for each token ID.
isFungible	bool	True if the series is fungible.

ContractURIFrozen

event ContractURIFrozen(string uri)

Contract-level metadata URI frozen.

Parameters

Name	Type	Description
uri	string	Frozen contract-level URI.

RoyaltySet

event RoyaltySet(address receiver, uint96 feeBps)

Default royalty configured.

Parameters

Name	Type	Description
receiver	address	Royalty recipient address.
feeBps	uint96	Royalty fee in basis points.

RoyaltyCleared

event RoyaltyCleared()

Default royalty removed.

RoyaltyFrozen

event RoyaltyFrozen()

Default royalty frozen and can no longer be changed.

MaxAtomicOperationUpdated

event MaxAtomicOperationUpdated(uint256 oldLimit, uint256 newLimit)

_maxAtomicOperation updated.

Parameters

Name	Type	Description
oldLimit	uint256	Previous limit.
newLimit	uint256	New limit.

PermanentURI

event PermanentURI(string uri, uint256 tokenId)

Token-level metadata permanently frozen (OpenSea compliant).

https://docs.opensea.io/docs/metadata-standards#freezing-metadata

Parameters

Name	Type	Description
uri	string	Full metadata URI.
tokenId	uint256	Token identifier.

SeriesNotFound

error SeriesNotFound()

Series does not exist.

InvalidCID

error InvalidCID()

IPFS CID is not valid CIDv0.

SeriesFrozen

error SeriesFrozen()

Series metadata is frozen (immutable).

SeriesAlreadyExists

error SeriesAlreadyExists()

Series ID already exists.

LengthMismatch

error LengthMismatch()

tokenIds and amounts array lengths mismatch.

NFTAmountMustBeOne

error NFTAmountMustBeOne()

Amount must be 1 for non-fungible tokens.

DuplicateTokenId

error DuplicateTokenId()

Token ID already minted in this series.

TokenInDifferentSeries

error TokenInDifferentSeries()

Token ID belongs to a different series.

URIFrozen

error URIFrozen()

Contract URI is frozen.

SeriesTooLarge

error SeriesTooLarge(uint256 seriesSize, uint256 maxAtomicOperation)

Series size exceeds _maxAtomicOperation.

ZeroAtomicLimit

error ZeroAtomicLimit()

Atomic operation limit cannot be zero.

InvalidLimit

error InvalidLimit()

Limit parameter is zero or exceeds maximum.

RoyaltyAlreadyFrozen

error RoyaltyAlreadyFrozen()

Royalties are frozen.

RoyaltyTooHigh

error RoyaltyTooHigh()

Royalty fee exceeds maximum basis points.

ZeroAmount

error ZeroAmount()

Amount must be greater than zero.

ZeroAddress

error ZeroAddress()

Zero address.

UpdateInProgress

error UpdateInProgress()

A metadata update is currently in progress for the series.

NoPendingEvents

error NoPendingEvents()

No pending batch events to emit.

seriesExists

modifier seriesExists(uint256 seriesId)

Modifier to check if a series exists

Parameters

Name	Type	Description
seriesId	uint256	Series ID to check

initialize

function initialize(string contractUri) external

Initialize the contract

Parameters

Name	Type	Description
contractUri	string	Contract Metadata URI

_authorizeUpgrade

function _authorizeUpgrade(address) internal virtual

required by the OZ UUPS module

createSeries

function createSeries(string cid, bool isFungible) external returns (uint256 seriesId)

Register a new metadata series.

The seriesId is the keccak256 hash of the raw IPFS CID, making the mapping deterministic across chains. Reverts with: - {InvalidCID} if cid is not a valid CIDv0 - {SeriesAlreadyExists} if the hash is already registered

Parameters

Name	Type	Description
cid	string	Raw IPFS content identifier (CID) that forms the folder for metadata.
isFungible	bool	true → tokens in this series may be multi‑minted; false → every tokenId is a unique 1‑of‑1 NFT.

Return Values

Name	Type	Description
seriesId	uint256	Deterministic identifier assigned to the series. Emits {SeriesCreated}. Requirements: - caller has METADATA_ROLE - contract is not paused

updateSeriesInit

function updateSeriesInit(uint256 seriesId, string cid) external

Start a streamed metadata‑update for a large series.

Stores newCid, resets the internal cursor and emits a single {SeriesMetadataUpdated}. Event emission must be finished via successive calls to {updateSeriesEmit} until it reverts with {NoPendingEvents}.

Parameters

Name	Type	Description
seriesId	uint256	Target series.
cid	string	New IPFS CID.

updateSeriesEmit

function updateSeriesEmit(uint256 seriesId, uint256 limit) external returns (bool hasMore)

Continue a streamed metadata‑update started with {updateSeriesInit}.

Emits up to limit {URI} events from the current cursor. Reverts with: - {InvalidLimit} if limit is 0 or above _maxAtomicOperation - {NoPendingEvents} once the last token has been processed

Parameters

Name	Type	Description
seriesId	uint256	Target series.
limit	uint256	Max tokens to process this call.

Return Values

Name	Type	Description
hasMore	bool	True if there are more tokens to process, false if the update is complete.

freezeSeriesInit

function freezeSeriesInit(uint256 seriesId) external

Begin a streamed metadata‑freeze for a large series.

Sets the frozen flag, resets the cursor and emits one {SeriesMetadataFrozen}. Actual PermanentURI emission is delegated to {freezeSeriesEmit}.

Parameters

Name	Type	Description
seriesId	uint256	Target series.

freezeSeriesEmit

function freezeSeriesEmit(uint256 seriesId, uint256 limit) external returns (bool hasMore)

Continue a streamed metadata‑freeze started with {freezeSeriesInit}.

Emits up to limit {PermanentURI} events and advances the cursor. Reverts with: - {InvalidLimit} if limit is 0 or above _maxAtomicOperation - {NoPendingEvents} once all tokens are processed

Parameters

Name	Type	Description
seriesId	uint256	Target series.
limit	uint256	Max tokens to process this call.

mintBatch

function mintBatch(address to, uint256 seriesId, uint256[] tokenIds, uint256[] amounts) external

Mint tokens in a series

Parameters

Name	Type	Description
to	address	Address to mint tokens to
seriesId	uint256	ID of the series
tokenIds	uint256[]	Array of token IDs to mint
amounts	uint256[]	Array of amounts to mint for each token

seriesCount

function seriesCount() external view returns (uint256)

Total number of series that have ever been created.

listSeries

function listSeries(uint256 offset, uint256 limit) external view returns (uint256[] seriesIds, string[] uris)

List series IDs and their CIDs with pagination.

Parameters

Name	Type	Description
offset	uint256	Starting index in the global series array.
limit	uint256	Maximum items to return.

Return Values

Name	Type	Description
seriesIds	uint256[]	Array of series IDs.
uris	string[]	Array of corresponding IPFS CIDs.

seriesTokenCount

function seriesTokenCount(uint256 seriesId) external view returns (uint256)

Get the number of tokens in a series

Parameters

Name	Type	Description
seriesId	uint256	ID of the series

Return Values

Name	Type	Description
[0]	uint256	count Number of tokens in the series

seriesTokens

function seriesTokens(uint256 seriesId, uint256 offset, uint256 limit) external view returns (uint256[] tokens)

Get tokens in a series with pagination

Parameters

Name	Type	Description
seriesId	uint256	ID of the series
offset	uint256	Starting index
limit	uint256	Maximum number of tokens to return

Return Values

Name	Type	Description
tokens	uint256[]	Array of token IDs in the series

tokenSeries

function tokenSeries(uint256 tokenId) external view returns (uint256)

Get the series ID for a token

Parameters

Name	Type	Description
tokenId	uint256	ID of the token

Return Values

Name	Type	Description
[0]	uint256	seriesId ID of the series the token belongs to

uri

function uri(uint256 tokenId) public view virtual returns (string)

Get the URI for a token

see {ERC1155-uri}

contractURI

function contractURI() public view returns (string)

Returns the contract-level metadata URI (OpenSea compliant).

setContractURI

function setContractURI(string newContractUri) external

Set the contract-level metadata URI

Parameters

Name	Type	Description
newContractUri	string	The new contract-level metadata URI

freezeContractURI

function freezeContractURI() external

Freeze the contract-level metadata URI

setRoyalty

function setRoyalty(address receiver, uint96 feeBps) external

Set the default royalty for the contract

Parameters

Name	Type	Description
receiver	address	The address to receive the royalty
feeBps	uint96	The royalty fee in basis points

clearRoyalty

function clearRoyalty() external

freezeRoyalties

function freezeRoyalties() external

setMaxAtomicOperation

function setMaxAtomicOperation(uint256 newLimit) external

Update {_maxAtomicOperation} cap.

pause

function pause() external

unpause

function unpause() external

_processMint

function _processMint(uint256 seriesId, uint256 tokenId, uint256 amount, bool fungible, bool frozen) internal

When a series is frozen, new token IDs cannot be minted. However, existing fungible tokens in the series can still be minted.

isCid

function isCid(string cid) internal pure returns (bool)

cidIdToUri

function cidIdToUri(string cid, uint256 id) public pure returns (string)

supportsInterface

function supportsInterface(bytes4 interfaceId) public view returns (bool)

See {IERC165-supportsInterface}.

_update

function _update(address from, address to, uint256[] ids, uint256[] values) internal

_Transfers a value amount of tokens of type id from from to to. Will mint (or burn) if from (or to) is the zero address.

Emits a {TransferSingle} event if the arrays contain one element, and {TransferBatch} otherwise.

Requirements:

• If to refers to a smart contract, it must implement either {IERC1155Receiver-onERC1155Received} or {IERC1155Receiver-onERC1155BatchReceived} and return the acceptance magic value.
• ids and values must have the same length.

NOTE: The ERC-1155 acceptance check is not performed in this function. See {updateWithAcceptanceCheck} instead.