> For the complete documentation index, see [llms.txt](https://doc.cryptostone.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.cryptostone.org/crypto-stone/crypto-stone-wp-kr/protocol-architecture/40_-_-_.md).

# 40 메타데이터 구조

CryptoStone은 시각적 표현을 부정하지 않는다. 보석 NFT는 사용자의 경험과 수집 편의성을 위해 이미지, 영상, 3D 모델, 시각적 카드 형태로 표현될 수 있다.

그러나 이미지는 CryptoStone의 본질이 아니다. CryptoStone의 본질은 다음 데이터에 있다.

| 데이터                      | 설명                                          |
| ------------------------ | ------------------------------------------- |
| `stoneType`              | 보석 종류                                       |
| `weight`                 | 무게                                          |
| `colorGrade`             | 색상 등급                                       |
| `clarityGrade`           | 투명도 등급                                      |
| `cutGrade`               | 컷팅 등급                                       |
| `rarity`                 | Common, Rare, Epic, Legendary, Genesis 중 하나 |
| `rarityScore`            | 사용자 친화적 희귀도 점수                              |
| `probabilityRarityIndex` | 확률 기반 희귀도 지표                                |
| `minedAt`                | 채굴 시점                                       |
| `minedFromPool`          | 채굴된 마이닝 풀                                   |
| `tokenId`                | NFT 고유 식별자                                  |
| `generation`             | 원본 또는 제련 세대                                 |

CryptoStone은 NFT의 기본 메타데이터를 HTTPS metadata API를 통해 제공할 수 있다. 이 방식은 민팅 직후 사용자가 지갑이나 마켓플레이스에서 이름, 설명, 속성, 등급, tokenId를 빠르게 확인할 수 있게 한다.

## 40.1 Metadata Trust Model

CryptoStone의 메타데이터 구조는 핵심 속성과 표현 계층을 분리한다. 보석의 본질적 속성은 컨트랙트와 공개 검증 가능한 데이터에 의해 결정되고, HTTPS metadata API는 이를 지갑, 마켓플레이스, 프론트엔드가 읽기 쉬운 JSON 형태로 제공하는 표시 계층이다.

| Layer                | 역할                                      | 신뢰 기준                  |
| -------------------- | --------------------------------------- | ---------------------- |
| Smart Contract       | stoneType, 속성, rarity, tokenId, 소유권의 원천 | 온체인 검증                 |
| HTTPS Metadata API   | 이름, 설명, attributes, 미디어 링크 제공           | 온체인 값과 DB 기록의 일치성      |
| Watcher Finalization | 이미지/영상 생성, IPFS 업로드, JSON 업데이트          | 트랜잭션 로그와 tokenId 기준 처리 |
| IPFS Media           | 최종 이미지와 영상의 보관 경로                       | CID 기반 미디어 참조          |

이미지와 영상은 watcher finalization 프로세스가 후속으로 생성하고, IPFS에 업로드한 뒤 메타데이터 API와 JSON 응답을 업데이트한다. 이 과정은 사용자의 추가 지갑 컨펌 없이 진행되며, 유저가 지갑에서 승인해야 하는 핵심 트랜잭션은 claim 또는 refinement 실행 단계로 제한된다.

초기 메타데이터는 다음과 같은 상태를 가질 수 있다.

| 상태          | 의미                                                        |
| ----------- | --------------------------------------------------------- |
| `revealing` | 온체인 속성과 기본 메타데이터는 확인되었으나 이미지 또는 영상 finalization이 진행 중인 상태 |
| `finalized` | watcher가 이미지, 영상, IPFS 업로드, JSON 업데이트를 완료한 상태             |

따라서 IPFS 업로드나 미디어 생성이 지연되더라도, Gem NFT의 핵심 속성은 컨트랙트와 HTTPS metadata API를 통해 먼저 확인될 수 있어야 한다. 이후 watcher가 IPFS image/video data를 채우면 NFT 마켓플레이스와 지갑 UI는 갱신된 미디어를 표시할 수 있다.

HTTPS metadata API가 일시적으로 중단되더라도 NFT 소유권과 핵심 속성의 원천은 컨트랙트에 남아 있어야 한다. API는 표시와 접근성을 위한 계층이며, watcher는 온체인 이벤트와 tokenId를 기준으로 누락된 미디어 finalization을 재시도할 수 있어야 한다.

이 설계는 사용자가 메타데이터 최종화를 위해 추가 지갑 컨펌을 반복하지 않도록 하기 위한 것이다. 또한 이미지 서버나 API가 일시적으로 지연되더라도 CryptoStone NFT의 핵심 속성은 온체인 또는 공개 검증 가능한 데이터 구조에 남아 있어야 한다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://doc.cryptostone.org/crypto-stone/crypto-stone-wp-kr/protocol-architecture/40_-_-_.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.