Display V2: Redesigning How Sui Objects Are Rendered

Key Takeaways

• Display V2 is a major redesign of Sui's protocol-level rendering system, ensuring that NFTs and on-chain objects look the same across wallets, explorers, and marketplaces. By enforcing exactly one display per type, it eliminates the old problem of having to figure out which display is the "real" one.

• This change is part of a broader shift in which Sui is migrating its entire data infrastructure from JSON-RPC to gRPC/GraphQL. Since the old approach simply wouldn't work under the new infrastructure, adopting V2 wasn't optional. Both Display V1 and JSON-RPC reach end-of-life in July 2026.

• V2 allows templates to directly express information that previously required off-chain services: collection data, child objects, default values, and more. As builders start taking advantage of these capabilities, the richness of NFT information visible in wallet interfaces could look very different from what we see today.

If you've ever minted an NFT on Ethereum or Solana, you've probably run into this: the image shows up fine in your wallet, but when you take it to a marketplace, the name is missing or the description is completely wrong. This happens all the time on most blockchains, because how an NFT "looks" doesn't depend on the chain itself. It depends on each platform's metadata API, third-party services, or unwritten conventions.

Sui's Display was an attempt to solve this at the protocol level. The idea was to define on-chain how an object should be rendered, so that any wallet or explorer would show the same result. Display V2, shipped with Sui v1.68, is the first major redesign of this system. But rather than a simple feature addition to Sui's Display, its full significance only becomes clear when read in the context of Sui's entire infrastructure stack being in motion.

1. What Display Is

Display is an on-chain object that registers with the network a rule: "objects of this type should be shown like this." When creators launch an NFT collection, they create a Display<T> and define fields like name, image_url, and description as templates. When a wallet or explorer queries the object, on-chain data gets substituted into these templates to produce the rendered output.

Let's start by looking at V1's Display<T> struct.

It's a straightforward structure that stores templates as key-value pairs in fields. For example, if you set the image_url field to "<https://api.capy.art/capy/{id}/svg>", each object's id value gets automatically inserted. The key point is that this lives on-chain and is controlled by the type owner, so no external metadata service is needed.

Other chains leave this function to the ecosystem rather than the protocol. ERC-721's tokenURI is the classic example: if the server that the metadata URI points to goes down, the NFT image disappears with it. Sui took the position that the network itself should manage this, and Display is the implementation of that stance.

2. Problems with Display V1

The concept was sound, but V1's implementation had practical limitations.

The first problem was that multiple displays could exist for the same type. In V1, anyone with Publisher authority could create as many as they wanted. The event emitted at display creation reveals this structure.

As expressed in the source code, wallets and explorers had to dig through historical event logs to find a type's display. Since there was no guarantee that only one existed, when multiple turned up, the client had to decide on its own which one was authoritative.

The second problem was that this event-scanning approach is incompatible with Sui's new infrastructure. Sui is currently transitioning its data access layer from JSON-RPC to gRPC and GraphQL.

JSON-RPC serializes data as text-based JSON, relies on request-response patterns, and uses loose typing. In an environment like Sui, where massive volumes of object state need to be queried quickly, all three become bottlenecks. gRPC offers 3-10x better performance through Protocol Buffers binary serialization, natively supports server-side streaming so real-time data arrives without polling, and catches errors at compile time through strongly typed interfaces defined in .proto files. GraphQL also reduces over-fetching by letting you query exactly the fields you need. Sui's decision to move away from JSON-RPC isn't about chasing a technology trend; it's a deliberate move to fundamentally improve data access for an object-centric blockchain.

The problem is that scanning historical events simply doesn't fit the design of gRPC. gRPC is optimized for state queries and real-time streaming, not for digging through past events. In practice, display rendering was impossible on gRPC altogether.

The third problem was that templates were too simplistic. The existing Display could only reference an object's top-level fields. Structured data like attribute lists, maps, or dynamic fields couldn't be accessed from templates, forcing builders to create off-chain services. The irony was that Display's whole purpose of managing metadata on-chain was being undermined by off-chain workarounds.

3. V2's Core Change: Deterministic Lookup

The most fundamental change in V2 is that Display is no longer a regular object created arbitrarily. Instead, it's an object derived deterministically from a global registry. I was able to confirm this registry's singleton address in object.move.

DisplayRegistry is a singleton object fixed at address @0xd. In V2, the ID of a Display<T> is deterministically derived by combining this registry's UID with type T. This leverages Sui's Derived Object pattern, where a unique ID is computed from the combination of (DisplayRegistry UID, DisplayKey<T>).

In V1, display creation used object::new(ctx) to generate a regular UID, so IDs were generated non-deterministically based on the transaction context.

In V2, because the ID is derived from the registry, the same type T always yields the same ID. Clients no longer need to scan events or wonder which display is canonical.

Why does this matter for users? When a wallet displays an NFT, V1 required digging through event history, which was either slow or, if the full node didn't retain history, could fail to find the display entirely. In V2, the ID can be computed instantly, making display lookups fast and reliable. It's also this deterministic lookup that makes display rendering possible on gRPC for the first time.

4. Expanded Template Model

V2 also significantly broadened what templates can express.

• Collection access: Structured data stored in objects, such as vectors, sets, and maps, can now be referenced directly in templates. For instance, an NFT with a list of traits can selectively display specific traits without any off-chain service.

• External object loading: Dynamic fields and related objects can be fetched during the display resolution process. This means a game item can show information about its equipped gear (child objects) directly in the display.

• Defaults: Using the format {{image_url}} | <default_image>, a fallback can be defined for when a field is missing or empty. Instead of a missing image, a default image appears, reducing those "no image" moments in wallets.

Taken together, these three changes eliminate much of the off-chain metadata service work that builders previously had to build separately. For users, NFTs and on-chain objects should be displayed with richer and more consistent visual information.

5. Migration and Timeline

Existing V1 displays were automatically migrated to V2 through a system snapshot. NFTs that were already visible in wallets and marketplaces won't break or change.

The authority to modify V2 displays has been separated into a dedicated DisplayCap<T> capability. It can be claimed using an existing Publisher object or by burning a legacy V1 display. New packages should use sui::display_registry instead of sui::display.

After July 31, 2026, V1 APIs will no longer be callable. This coincides with the end of JSON-RPC support.

6. Implications

Viewed in isolation, Display V2 might read as a straightforward improvement to an NFT metadata system. But it's one piece of a larger transition that Sui is undertaking.

Sui is currently overhauling its entire data access infrastructure from JSON-RPC to gRPC and GraphQL. The goal is to replace the performance ceiling of text-based serialization, the inefficiency of polling-based real-time data access, and the risk of runtime errors from loose typing with binary serialization, native streaming, and strongly typed interfaces. The end-of-life date for JSON-RPC is set for July 2026, and Display V1's sunset is aligned to the same timeline. Display V2's shift from event scanning to deterministic lookup was a prerequisite for this infrastructure transition. Object rendering simply could not function on the new data stack under V1's event-history-dependent architecture.

The immediate impact for users may not be dramatic, since existing NFT displays aren't changing. But as builders begin leveraging V2's expanded templates, the depth of information that NFTs and on-chain objects can convey may shift considerably. With dynamic fields, child objects, and collection data now expressible directly in displays, information that was previously only accessible through separate web pages or external services can move into the wallet itself.

It's also worth noting that a protocol having an opinion on how objects are rendered is a choice unique to Sui. On Ethereum or Solana, how an NFT looks is entirely the ecosystem's responsibility. Whatever you put behind tokenURI, however a marketplace chooses to interpret it, the protocol stays out of it. This approach is flexible, but as mentioned earlier, it comes at the cost of cross-platform inconsistency and external service dependency. Sui went the other direction. The network provides a rendering standard, and V2 goes further by enforcing exactly one display per type. This is a tradeoff: gaining consistency at the expense of some flexibility. If a builder wants context-specific display variations for the same type (say, different presentations for a marketplace versus in-game), V2's "one per type" model could become a constraint. Whether this design limits ecosystem diversity in the long run remains to be seen.