RMRKNestable

RMRK team

RMRKNestable

Smart contract of the RMRK Nestable module.

This contract is hierarchy agnostic and can support an arbitrary number of nested levels up and down, as long as gas limits allow it.

Methods

RMRK_INTERFACE

function RMRK_INTERFACE() external pure returns (bytes4 rmrkInterface)

Interface identifier of the @rmrk-team/evm-contracts package

Returns

Name	Type	Description
rmrkInterface	bytes4	Interface identifier for implementations of the @rmrk-team/evm-contracts package

VERSION

function VERSION() external pure returns (string version)

Version of the @rmrk-team/evm-contracts package

Returns

Name	Type	Description
version	string	Version identifier for implementations of the @rmrk-team/evm-contracts package

acceptChild

function acceptChild(uint256 parentId, uint256 childIndex, address childAddress, uint256 childId) external nonpayable

Used to accept a pending child token for a given parent token.

This moves the child token from parent token's pending child tokens array into the active child tokens array.

Parameters

Name	Type	Description
parentId	uint256	ID of the parent token for which the child token is being accepted
childIndex	uint256	Index of a child tokem in the given parent's pending children array
childAddress	address	Address of the collection smart contract of the child token expected to be located at the specified index of the given parent token's pending children array
childId	uint256	ID of the child token expected to be located at the specified index of the given parent token's pending children array

addChild

function addChild(uint256 parentId, uint256 childId, bytes data) external nonpayable

Used to add a child token to a given parent token.

This adds the child token into the given parent token's pending child tokens array.Requirements: - directOwnerOf on the child contract must resolve to the called contract. - the pending array of the parent contract must not be full.

Parameters

Name	Type	Description
parentId	uint256	ID of the parent token to receive the new child token
childId	uint256	ID of the new proposed child token
data	bytes	Additional data with no specified format

approve

function approve(address to, uint256 tokenId) external nonpayable

Used to grant a one-time approval to manage one's token.

Gives permission to to to transfer tokenId token to another account.The approval is cleared when the token is transferred.Only a single account can be approved at a time, so approving the zero address clears previous approvals.Requirements: - The caller must own the token or be an approved operator. - tokenId must exist.Emits an {Approval} event.

Parameters

Name	Type	Description
to	address	Address receiving the approval
tokenId	uint256	ID of the token for which the approval is being granted

balanceOf

function balanceOf(address owner) external view returns (uint256 balance)

Used to retrieve the number of tokens in owner's account.

Parameters

Name	Type	Description
owner	address	Address of the account being checked

Returns

Name	Type	Description
balance	uint256	The balance of the given account

burn

function burn(uint256 tokenId) external nonpayable

Used to burn a given token.

In case the token has any child tokens, the execution will be reverted.

Parameters

Name	Type	Description
tokenId	uint256	ID of the token to burn

burn

function burn(uint256 tokenId, uint256 maxChildrenBurns) external nonpayable returns (uint256 burnedChildren)

Used to burn a given token.

When a token is burned, all of its child tokens are recursively burned as well.When specifying the maximum recursive burns, the execution will be reverted if there are more children to be burned.Setting the maxRecursiveBurn value to 0 will only attempt to burn the specified token and revert if there are any child tokens present.The approvals are cleared when the token is burned.Requirements: - tokenId must exist.Emits a {Transfer} event.

Parameters

Name	Type	Description
tokenId	uint256	ID of the token to burn
maxChildrenBurns	uint256	undefined

Returns

Name	Type	Description
burnedChildren	uint256	Number of recursively burned children

childOf

function childOf(uint256 parentId, uint256 index) external view returns (struct IERC7401.Child child)

Used to retrieve a specific active child token for a given parent token.

Returns a single Child struct locating at index of parent token's active child tokens array.The Child struct consists of the following values: [ tokenId, contractAddress ]

Parameters

Name	Type	Description
parentId	uint256	ID of the parent token for which the child is being retrieved
index	uint256	Index of the child token in the parent token's active child tokens array

Returns

Name	Type	Description
child	IERC7401.Child	A Child struct containing data about the specified child

childrenOf

function childrenOf(uint256 parentId) external view returns (struct IERC7401.Child[] children)

Used to retrieve the active child tokens of a given parent token.

Returns array of Child structs existing for parent token.The Child struct consists of the following values: [ tokenId, contractAddress ]

Parameters

Name	Type	Description
parentId	uint256	ID of the parent token for which to retrieve the active child tokens

Returns

Name	Type	Description
children	IERC7401.Child[]	An array of Child structs containing the parent token's active child tokens

directOwnerOf

function directOwnerOf(uint256 tokenId) external view returns (address owner_, uint256 parentId, bool isNFT)

Used to retrieve the immediate owner of the given token.

If the immediate owner is another token, the address returned will be the parent token's collection address.

Parameters

Name	Type	Description
tokenId	uint256	ID of the token for which the RMRK owner is being retrieved

Returns

Name	Type	Description
owner_	address	Address of the given token's owner
parentId	uint256	The ID of the parent token. Should be `0` if the owner is an externally owned account
isNFT	bool	The boolean value signifying whether the owner is an NFT or not

getApproved

function getApproved(uint256 tokenId) external view returns (address approved)

Used to retrieve the account approved to manage given token.

Requirements: - tokenId must exist.

Parameters

Name	Type	Description
tokenId	uint256	ID of the token to check for approval

Returns

Name	Type	Description
approved	address	Address of the account approved to manage the token

isApprovedForAll

function isApprovedForAll(address owner, address operator) external view returns (bool isApproved)

Used to check if the given address is allowed to manage the tokens of the specified address.

Parameters

Name	Type	Description
owner	address	Address of the owner of the tokens
operator	address	Address being checked for approval

Returns

Name	Type	Description
isApproved	bool	A boolean value signifying whether the operator is allowed to manage the tokens of the owner (`true`) or not (`false`)

nestTransferFrom

function nestTransferFrom(address from, address to, uint256 tokenId, uint256 destinationId, bytes data) external nonpayable

Used to transfer the token into another token.

Parameters

Name	Type	Description
from	address	Address of the direct owner of the token to be transferred
to	address	Address of the receiving token's collection smart contract
tokenId	uint256	ID of the token being transferred
destinationId	uint256	ID of the token to receive the token being transferred
data	bytes	Additional data with no specified format, sent in the addChild call

ownerOf

function ownerOf(uint256 tokenId) external view returns (address owner_)

Used to retrieve the root owner of a given token.

The root owner of the token is an externally owned account (EOA). If the given token is child of another NFT, this will return an EOA address. Otherwise, if the token is owned by an EOA, this EOA will be returned.

Parameters

Name	Type	Description
tokenId	uint256	ID of the token for which the root owner has been retrieved

Returns

Name	Type	Description
owner_	address	The root owner of the token

pendingChildOf

function pendingChildOf(uint256 parentId, uint256 index) external view returns (struct IERC7401.Child child)

Used to retrieve a specific pending child token from a given parent token.

Returns a single Child struct locating at index of parent token's active child tokens array.The Child struct consists of the following values: [ tokenId, contractAddress ]

Parameters

Name	Type	Description
parentId	uint256	ID of the parent token for which the pending child token is being retrieved
index	uint256	Index of the child token in the parent token's pending child tokens array

Returns

Name	Type	Description
child	IERC7401.Child	A Child struct containting data about the specified child

pendingChildrenOf

function pendingChildrenOf(uint256 parentId) external view returns (struct IERC7401.Child[] children)

Used to retrieve the pending child tokens of a given parent token.

Returns array of pending Child structs existing for given parent.The Child struct consists of the following values: [ tokenId, contractAddress ]

Parameters

Name	Type	Description
parentId	uint256	ID of the parent token for which to retrieve the pending child tokens

Returns

Name	Type	Description
children	IERC7401.Child[]	An array of Child structs containing the parent token's pending child tokens

rejectAllChildren

function rejectAllChildren(uint256 tokenId, uint256 maxRejections) external nonpayable

Used to reject all pending children of a given parent token.

Removes the children from the pending array mapping.This does not update the ownership storage data on children. If necessary, ownership can be reclaimed by the rootOwner of the previous parent.Requirements: Requirements: - parentId must exist

Parameters

Name	Type	Description
tokenId	uint256	undefined
maxRejections	uint256	Maximum number of expected children to reject, used to prevent from rejecting children which arrive just before this operation.

safeTransferFrom

function safeTransferFrom(address from, address to, uint256 tokenId) external nonpayable

Used to safely transfer a given token token from from to to.

Requirements: - from cannot be the zero address. - to cannot be the zero address. - tokenId token must exist and be owned by from. - If the caller is not from, it must be approved to move this token by either {approve} or {setApprovalForAll}. - If to refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer.Emits a {Transfer} event.

Parameters

Name	Type	Description
from	address	Address to transfer the tokens from
to	address	Address to transfer the tokens to
tokenId	uint256	ID of the token to transfer

safeTransferFrom

function safeTransferFrom(address from, address to, uint256 tokenId, bytes data) external nonpayable

Used to safely transfer a given token token from from to to.

Parameters

Name	Type	Description
from	address	Address to transfer the tokens from
to	address	Address to transfer the tokens to
tokenId	uint256	ID of the token to transfer
data	bytes	Additional data without a specified format to be sent along with the token transaction

setApprovalForAll

function setApprovalForAll(address operator, bool approved) external nonpayable

Used to approve or remove operator as an operator for the caller.

Operators can call {transferFrom} or {safeTransferFrom} for any token owned by the caller.Requirements: - The operator cannot be the caller.Emits an {ApprovalForAll} event.

Parameters

Name	Type	Description
operator	address	Address of the operator being managed
approved	bool	A boolean value signifying whether the approval is being granted (`true`) or (`revoked`)

supportsInterface

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

Returns true if this contract implements the interface defined by interfaceId. See the corresponding https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP (opens in a new tab) section] to learn more about how these ids are created. This function call must use less than 30 000 gas.

Parameters

Name	Type	Description
interfaceId	bytes4	undefined

Returns

Name	Type	Description
_0	bool	undefined

transferChild

function transferChild(uint256 tokenId, address to, uint256 destinationId, uint256 childIndex, address childAddress, uint256 childId, bool isPending, bytes data) external nonpayable

Used to transfer a child token from a given parent token.

When transferring a child token, the owner of the token is set to to, or is not updated in the event of to being the 0x0 address.

Parameters

Name	Type	Description
tokenId	uint256	ID of the parent token from which the child token is being transferred
to	address	Address to which to transfer the token to
destinationId	uint256	ID of the token to receive this child token (MUST be 0 if the destination is not a token)
childIndex	uint256	Index of a token we are transferring, in the array it belongs to (can be either active array or pending array)
childAddress	address	Address of the child token's collection smart contract.
childId	uint256	ID of the child token in its own collection smart contract.
isPending	bool	A boolean value indicating whether the child token being transferred is in the pending array of the parent token (`true`) or in the active array (`false`)
data	bytes	Additional data with no specified format, sent in call to `_to`

transferFrom

function transferFrom(address from, address to, uint256 tokenId) external nonpayable

Transfers a given token from from to to.

Requirements: - from cannot be the zero address. - to cannot be the zero address. - tokenId token must be owned by from. - If the caller is not from, it must be approved to move this token by either {approve} or {setApprovalForAll}.Emits a {Transfer} event.

Parameters

Name	Type	Description
from	address	Address from which to transfer the token from
to	address	Address to which to transfer the token to
tokenId	uint256	ID of the token to transfer

Events

AllChildrenRejected

event AllChildrenRejected(uint256 indexed tokenId)

Used to notify listeners that all pending child tokens of a given token have been rejected.

Emitted when a token removes all a child tokens from its pending array.

Parameters

Name	Type	Description
tokenId `indexed`	uint256	ID of the token that rejected all of the pending children

Approval

event Approval(address indexed owner, address indexed approved, uint256 indexed tokenId)

Emitted when owner enables approved to manage the tokenId token.

Parameters

Name	Type	Description
owner `indexed`	address	undefined
approved `indexed`	address	undefined
tokenId `indexed`	uint256	undefined

ApprovalForAll

event ApprovalForAll(address indexed owner, address indexed operator, bool approved)

Emitted when owner enables or disables (approved) operator to manage all of its assets.

Parameters

Name	Type	Description
owner `indexed`	address	undefined
operator `indexed`	address	undefined
approved	bool	undefined

ChildAccepted

event ChildAccepted(uint256 indexed tokenId, uint256 childIndex, address indexed childAddress, uint256 indexed childId)

Used to notify listeners that a new child token was accepted by the parent token.

Emitted when a parent token accepts a token from its pending array, migrating it to the active array.

Parameters

Name	Type	Description
tokenId `indexed`	uint256	ID of the token that accepted a new child token
childIndex	uint256	Index of the newly accepted child token in the parent token's active children array
childAddress `indexed`	address	Address of the child token's collection smart contract
childId `indexed`	uint256	ID of the child token in the child token's collection smart contract

ChildProposed

event ChildProposed(uint256 indexed tokenId, uint256 childIndex, address indexed childAddress, uint256 indexed childId)

Used to notify listeners that a new token has been added to a given token's pending children array.

Emitted when a child NFT is added to a token's pending array.

Parameters

Name	Type	Description
tokenId `indexed`	uint256	ID of the token that received a new pending child token
childIndex	uint256	Index of the proposed child token in the parent token's pending children array
childAddress `indexed`	address	Address of the proposed child token's collection smart contract
childId `indexed`	uint256	ID of the child token in the child token's collection smart contract

ChildTransferred

event ChildTransferred(uint256 indexed tokenId, uint256 childIndex, address indexed childAddress, uint256 indexed childId, bool fromPending, bool toZero)

Used to notify listeners a child token has been transferred from parent token.

Emitted when a token transfers a child from itself, transferring ownership to the root owner.

Parameters

Name	Type	Description
tokenId `indexed`	uint256	ID of the token that transferred a child token
childIndex	uint256	Index of a child in the array from which it is being transferred
childAddress `indexed`	address	Address of the child token's collection smart contract
childId `indexed`	uint256	ID of the child token in the child token's collection smart contract
fromPending	bool	A boolean value signifying whether the token was in the pending child tokens array (`true`) or in the active child tokens array (`false`)
toZero	bool	A boolean value signifying whether the token is being transferred to the `0x0` address (`true`) or not (`false`)

NestTransfer

event NestTransfer(address indexed from, address indexed to, uint256 fromTokenId, uint256 toTokenId, uint256 indexed tokenId)

Used to notify listeners that the token is being transferred.

Emitted when tokenId token is transferred from from to to.

Parameters

Name	Type	Description
from `indexed`	address	Address of the previous immediate owner, which is a smart contract if the token was nested.
to `indexed`	address	Address of the new immediate owner, which is a smart contract if the token is being nested.
fromTokenId	uint256	ID of the previous parent token. If the token was not nested before, the value should be `0`
toTokenId	uint256	ID of the new parent token. If the token is not being nested, the value should be `0`
tokenId `indexed`	uint256	ID of the token being transferred

Transfer

event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)

Emitted when tokenId token is transferred from from to to.

Parameters

Name	Type	Description
from `indexed`	address	undefined
to `indexed`	address	undefined
tokenId `indexed`	uint256	undefined

Errors

ERC721AddressZeroIsNotaValidOwner

error ERC721AddressZeroIsNotaValidOwner()

Attempting to grant the token to 0x0 address

ERC721ApprovalToCurrentOwner

error ERC721ApprovalToCurrentOwner()

Attempting to grant approval to the current owner of the token

ERC721ApproveCallerIsNotOwnerNorApprovedForAll

error ERC721ApproveCallerIsNotOwnerNorApprovedForAll()

Attempting to grant approval when not being owner or approved for all should not be permitted

ERC721ApproveToCaller

error ERC721ApproveToCaller()

Attempting to grant approval to self

ERC721InvalidTokenId

error ERC721InvalidTokenId()

Attempting to use an invalid token ID

ERC721NotApprovedOrOwner

error ERC721NotApprovedOrOwner()

Attempting to manage a token without being its owner or approved by the owner

ERC721TransferFromIncorrectOwner

error ERC721TransferFromIncorrectOwner()

Attempting to transfer the token from an address that is not the owner

ERC721TransferToNonReceiverImplementer

error ERC721TransferToNonReceiverImplementer()

Attempting to safe transfer to an address that is unable to receive the token

ERC721TransferToTheZeroAddress

error ERC721TransferToTheZeroAddress()

Attempting to transfer the token to a 0x0 address

RMRKChildAlreadyExists

error RMRKChildAlreadyExists()

Attempting to accept a child that has already been accepted

RMRKChildIndexOutOfRange

error RMRKChildIndexOutOfRange()

Attempting to interact with a child, using index that is higher than the number of children

RMRKIsNotContract

error RMRKIsNotContract()

Attempting to interact with an end-user account when the contract account is expected

RMRKMaxPendingChildrenReached

error RMRKMaxPendingChildrenReached()

Attempting to add a pending child after the number of pending children has reached the limit (default limit is 128)

RMRKMaxRecursiveBurnsReached

error RMRKMaxRecursiveBurnsReached(address childContract, uint256 childId)

Attempting to burn a total number of recursive children higher than maximum set

Parameters

Name	Type	Description
childContract	address	Address of the collection smart contract in which the maximum number of recursive burns was reached
childId	uint256	ID of the child token at which the maximum number of recursive burns was reached

RMRKNestableTooDeep

error RMRKNestableTooDeep()

Attempting to nest a child over the nestable limit (current limit is 100 levels of nesting)

RMRKNestableTransferToDescendant

error RMRKNestableTransferToDescendant()

Attempting to nest the token to own descendant, which would create a loop and leave the looped tokens in limbo

RMRKNestableTransferToNonRMRKNestableImplementer

error RMRKNestableTransferToNonRMRKNestableImplementer()

Attempting to nest the token to a smart contract that doesn't support nesting

RMRKNestableTransferToSelf

error RMRKNestableTransferToSelf()

Attempting to nest the token into itself

RMRKNotApprovedOrDirectOwner

error RMRKNotApprovedOrDirectOwner()

Attempting to interact with a token without being its owner or having been granted permission by the owner to do so

When a token is nested, only the direct owner (NFT parent) can mange it. In that case, approved addresses are not allowed to manage it, in order to ensure the expected behaviour

RMRKPendingChildIndexOutOfRange

error RMRKPendingChildIndexOutOfRange()

Attempting to interact with a pending child using an index greater than the size of pending array

RMRKUnexpectedChildId

error RMRKUnexpectedChildId()

Attempting to accept or transfer a child which does not match the one at the specified index

RMRKUnexpectedNumberOfChildren

error RMRKUnexpectedNumberOfChildren()

Attempting to reject all pending children but children assets than expected are pending

IERC7401 Nestable Multi Asset