Dual IDs
In the ART20 module, each NFT is associated with two key identifiers that together provide a robust and flexible way to reference and manage tokens:
Object ID (UID): Every NFT is represented as an on-chain object in Sui, and like any Sui object, it has a unique Object ID (UID). This UID is a low-level, globally unique identifier assigned by the Sui runtime when the NFT object is created. It is essential for performing transactions on that specific object—such as transferring, burning, or updating it—and serves as the foundational reference for all Move function calls that operate on the NFT.
Asset ID (Collection-Scoped ID): Beyond the global Object ID, ART20 NFTs also have an asset_id, which uniquely identifies the NFT within its own collection. Unlike the Object ID, which is globally unique across the entire blockchain, the asset_id is scoped to a single collection. This approach makes it easier to reason about NFTs at a collection level—for example, referring to "Token #1" or "Token #100" within a specific collection.
The asset_id effectively serves as a "human-friendly" handle or an internal index for tokens in a particular collection. It can be used to:
Locate NFTs within the same collection quickly.
Batch update or transfer tokens based on their asset_id range.
Provide users with a simple reference point (“This is my #25 NFT in the collection.”).
Why Dual IDs?
Global vs. Local Context: The Object ID operates at a global context (the entire blockchain), which is crucial for smart contract operations. The asset_id gives a localized context, making it easier to interact with tokens in bulk or refer to them by simple integers within a known set.
User Experience: Collection-level IDs (asset_ids) are more intuitive for users. Collectors and traders often identify NFTs by a number within a collection rather than a long hexadecimal Object ID. This improves the user experience when browsing, trading, or discussing NFTs.
Development and Integration: On the development side, working with asset_ids simplifies certain operations. For instance, performing batch metadata updates or implementing features like "update_art20_image_uri_by_asset_id" becomes more straightforward, as developers can iterate over a sequence of asset_ids instead of handling a set of unrelated global UIDs.
Example:
When an NFT is minted, it receives:
A globally unique
id(UID) from Sui (e.g.,0x...abc123).An
asset_idwithin the collection (e.g.,#42), incrementing as new NFTs are minted in that particular collection.
Best Practices with Dual IDs:
Use Object IDs (UIDs) for direct operations on specific NFT objects (transfers, updates).
Use asset_ids to group operations, run batch updates, or provide a user-facing numbering system.
Keep a clear mapping in your front-end or indexing layer between Object IDs and asset_ids. This allows you to easily display asset_ids to users while the backend logic still references object IDs for transactions.
By leveraging both the global Object ID and the collection-scoped asset_id, the ART20 module ensures a robust, intuitive, and developer-friendly framework for managing NFTs at both a technical and user-facing level.
Last updated