Object Display V2

위험

Object Display V2는 Sui v1.68에서 사용할 수 있다. Devnet, Testnet, Mainnet에서 v1.68을 언제 사용할 수 있는지에 대한 자세한 내용은 release schedule을 확인하라.

기존의 모든 V1 display는 system snapshot migration에서 V2로 마이그레이션된다. 사전에 해야 할 일은 없으며, snapshot 이후 준비가 되면 capability를 클레임할 수 있다(Migration and claiming 참조).

V1 end of life

Object Display V1은 이를 이미 지원하는 RPC(JSON-RPC, GraphQL)에서 2026년 7월 말까지 지원된다. 그 이후에는 온체인 V1 display 코드가 폐기되며 abort를 시작한다.

Move 코드에서 display를 생성할 때는 sui::display_registry API를 사용하는 것이 권장된다. 중간 단계에서는 migrate_v1_to_v2 함수를 사용하여 legacy display를 마이그레이션하고 V2 Display<T>와 DisplayCap<T>를 받을 수 있다.

What's new in V2

Display V2는 더 풍부한 templating model, 개선된 rendering pipeline, 더 나은 tooling을 제공하며, 여기에는 다음이 포함된다:

• Collection access: display template에서 vector, set, map을 직접 사용한다.

• Dynamic field access: template에서 object의 dynamic field를 참조한다.

• Object loading: display를 resolve할 때 object를 로드하고 참조한다.

• GraphQL: display를 단순 rendering이 아니라 querying tool로 사용할 수 있는 풍부한 API를 제공한다.

Differences between V1 and V2

V1에서는 타입의 display를 찾기 위해 DisplayCreated<T>와 같은 event에 의존했다. 클라이언트는 타입별 historical event를 조회하고 어떤 object가 display를 나타내는지 추론해야 했다. 이 접근 방식은 historical event data에 의존하고, 전체 이력을 보관하지 않을 수 있는 full node에서 scale되지 않으며, event를 스캔하지 않고 "type T의 display"를 안정적이고 저렴하게 resolve해야 하는 JSON-RPC, gRPC 같은 RPC API에는 적합하지 않다.

V2에서는 타입 T의 display가 global registry와 타입에서 파생된 단일한 deterministic ID를 가진다. 이 ID는 event나 history를 사용하지 않고 오프라인에서 계산할 수 있다. RPC는 파생만으로 "type T의 display"를 resolve할 수 있으며, 이는 full node에 지속 가능한 방식이다. 이것이 JSON-RPC와 gRPC에 대한 주요 이점이다. GraphQL은 자체 indexed state를 유지하므로 영향이 더 적다.

Structural change: N → 1, and derived

Object Display V1에서는 타입당 N개의 display를 가질 수 있었고 이를 조회하기 위해 event를 사용해야 했다. Object Display V2에서는 타입당 1개만 존재하며 파생으로 얻는다.

	V1	V2
Displays per type	Multiple Display<T> could exist.	Exactly one Display<T> per type T.
How you find Display<T>	Query events by type; requires historical events.	Offline derivation. Display<T> is a derived object from (DisplayRegistry UID, DisplayKey<T>). ID is computable from registry and type; no events, no scan.
Identity	Unpredictable (per creation tx).	Deterministic. The same registry and same T result in the same display ID everywhere.

Migration and claiming

모든 V1 display는 system snapshot migration에서 V2로 마이그레이션된다. 그 이후 각 타입에 대해 단일 V2 Display<T>가 cap_id: none 상태로 존재하며, capability가 클레임될 때까지 유지된다.

capability는 두 가지 방법 중 하나로 클레임할 수 있다:

• Publisher using claim_with_publisher: Publisher object를 보유한 경우 이 방법을 사용한다. publisher.from_package<T>()를 통해 타입 소유권을 증명한다.

• Legacy Display using claim: V1 Display<T> object를 보유한 경우 이 방법을 사용한다. 이를 전달하면 object가 consume되고 DisplayCap<T>를 받는다.

클레임이 완료되면 DisplayCap<T> 보유자는 display field를 업데이트(set, unset, clear)할 수 있다. V1 Display<T>를 보유한 사람은 누구나 delete_legacy(display, legacy)를 호출해 legacy object를 burn할 수 있다.