ERC-721 Transfer Module

Manage ERC-721 token transfers within a diamond

Key Features

• All functions are internal for use within facets.
• Uses the diamond storage pattern (EIP-8042) for state management.
• Emits a Transfer event upon successful token transfer.
• Includes specific errors for common ERC-721 transfer failures.

Module Usage

This module provides internal functions for use in your custom facets. Import it to access shared logic and storage.

Overview

This module provides internal functions to manage ERC-721 token transfers using diamond storage. Facets can import this module to perform token ownership changes, ensuring consistency across the diamond. State modifications are immediately visible to all facets accessing the shared ERC-721 storage.

Storage

ERC721Storage

Storage layout for ERC-721 token management. Defines ownership, balances, approvals, and operator mappings per ERC-721 standard. storage-location: erc8042:erc721

Definition

struct ERC721Storage {
  mapping(uint256 tokenId => address owner) ownerOf;
  mapping(address owner => uint256 balance) balanceOf;
  mapping(address owner => mapping(address operator => bool approved)) isApprovedForAll;
  mapping(uint256 tokenId => address approved) approved;
}

State Variables

Property	Type	Description
STORAGE_POSITION	bytes32	Diamond storage slot position for this module (Value: keccak256("erc721"))

Functions

getStorage

Returns the ERC-721 storage struct from its predefined slot. Uses inline assembly to access diamond storage location.

function getStorage() pure returns (ERC721Storage storage s);

Returns:

Property	Type	Description
s	ERC721Storage	The storage reference for ERC-721 state variables.

---

transferFrom

Transfers ownership of a token ID from one address to another. Validates ownership, approval, and receiver address before updating state.

function transferFrom(address _from, address _to, uint256 _tokenId) ;

Parameters:

Property	Type	Description
_from	address	The current owner of the token.
_to	address	The address that will receive the token.
_tokenId	uint256	The ID of the token being transferred.

Events

Emitted when ownership of a token changes, including minting and burning.

Signature:

event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);

Parameters:

Property	Type	Description
_from	address	The address transferring the token, or zero for minting.
_to	address	The address receiving the token, or zero for burning.
_tokenId	uint256	The ID of the token being transferred.

Errors

Thrown when the sender is not the owner of the token.

Signature:

error ERC721IncorrectOwner(address _sender, uint256 _tokenId, address _owner);

Thrown when the receiver address is invalid (e.g., zero address).

Signature:

error ERC721InvalidReceiver(address _receiver);

Thrown when attempting to interact with a non-existent token.

Signature:

error ERC721NonexistentToken(uint256 _tokenId);

Best Practices

Best Practice

• Ensure caller is the owner or has been approved for the token before calling transferFrom.
• Handle ERC721IncorrectOwner, ERC721InvalidReceiver, and ERC721NonexistentToken errors when interacting with transferFrom.
• Verify that the ERC721Storage struct definition remains compatible with the diamond's storage layout upon upgrades.

Integration Notes

Shared Storage

This module reads and writes to diamond storage at the slot designated by keccak256(\"erc721\"). The ERC721Storage struct defines the layout for token ownership and related metadata. Changes made via the transferFrom function are immediately reflected in this shared storage, making them visible to all facets that access the same storage position. The getStorage function provides a read-only view of this state using inline assembly.

Was this helpful?

Last updated:March 13, 2026