NFT tokenURI ve metadata inceleme: görsel, JSON ve zincir kaydını ayırma

Bir NFT sayfasında görselin görünmemesi, tek başına tokenın kaybolduğu anlamına gelmez. Zincirdeki kayıt, metadata belgesi ve görsel dosyası farklı katmanlar olabilir. Bu rehber bu katmanları okumayı öğretir; NFT satın alma, değer biçme veya yatırım önerisi içermez. Cüzdan bağlamadan çalışacağız. Örneğimizde bir tasarım öğrencisi, hazırladığı eğitim sunumunda “NFT görseli nerede durur?” sorusunu cevaplamak için yerel bir JSON belgesini inceliyor.

1. Token kimliğiyle dosya adresini ayırın

ERC-721 standardında sözleşme adresi ile token kimliği birlikte belirli bir tokenı tanımlar; metadata uzantısındaki tokenURI ise açıklama verisine giden URI sağlayabilir. Bu ayrım önemlidir: token numarası bir dosya adı değildir. İnceleme notunuza ağ, sözleşme, token kimliği ve metadata URI’si için ayrı satırlar açın. Tasarım öğrencimiz önce bu dört kutuyu çizer. Görseli ilk kutuya koymak yerine, hangi bağlantı üzerinden erişildiğini sonraki katmanda gösterir.

2. Metadata belgesini yapılandırılmış metin olarak okuyun

Bir metadata belgesinde isim, açıklama ve görsel adresi gibi alanlarla karşılaşabilirsiniz. Alanın bulunması, içeriğin doğru veya güvenilir olduğunu kendiliğinden kanıtlamaz. Bu eğitimde dosyayı çalıştırmıyoruz; JSON olarak okuyoruz. Bir görsel alanına bakarken adres şemasını, kaynak konumunu ve dosyanın nasıl sunulduğunu ayrı değerlendirin. Metin içinde başka bir siteye yönlendirme bulunuyorsa bunu otomatik olarak açmanız gerekmez. Özellikle bilinmeyen içeriği HTML olarak çalıştırmakla düz metin olarak incelemek farklı davranışlardır.

3. Yerel örnekle alan kontrolü yapın

Aşağıdaki Python kodu kendi içinde oluşturulan örnek JSON’u okur. example.com eğitim için ayrılmış örnek alan adıdır; gerçek bir NFT koleksiyonunun dosyası olarak kullanılmamalıdır. Kod bağlantı açmaz, görsel indirmez ve cüzdanınıza erişmez. İlk hedef, dosyanın hangi alanları sunduğunu ve image değerinin hangi URI şemasını kullandığını göstermek. Böylece görselin kendisiyle onu tarif eden belgenin farklı nesneler olduğunu çıktıda görebilirsiniz.

import json
from urllib.parse import urlparse

text = '''{
  "name": "Eğitim Kartı 7",
  "description": "Yerel inceleme için kurgusal metadata.",
  "image": "https://example.com/demo.png"
}'''
metadata = json.loads(text)
for field in ("name", "description", "image"):
    value = metadata.get(field)
    print(field, ":", value if isinstance(value, str) else "eksik")
image_uri = metadata.get("image", "")
print("Görsel URI şeması:", urlparse(image_uri).scheme)

4. IPFS URI’siyle ağ geçidi URL’sini karıştırmayın

IPFS belgeleri, içeriğe ait tanımlayıcı ile ona web üzerinden erişim sağlayan ağ geçidi bağlantısını ayrı ele alır. ipfs:// biçimiyle karşılaştığınızda bunun sıradan bir HTTPS adresi olmadığını fark edin. Bir ağ geçidinin yanıt vermemesi, içeriğin bütün IPFS ağından silindiğini tek başına göstermez. Buna karşılık bir CID bulunması da dosyanın her zaman erişilebilir kalacağını garanti etmez. Öğrencimiz şemada “içerik tanımı” ve “erişim yolu” için iki farklı ok kullanır.

5. Görsel görünmediğinde hangi katman bozuk?

Önce metadata URI’sinin var olup olmadığını, sonra belgenin okunup okunmadığını, ardından görsel alanının ne içerdiğini kontrol edin. Üç adımı aynı hata etiketi altında toplamayın. Örneğin geçerli JSON içinde boş bir görsel alanı varsa sorunla, JSON adresine hiç erişememek farklıdır. Öğrencimiz her denemede sadece bir katmanı değiştirerek not alır. Böylece “NFT çalışmıyor” yerine “metadata açılıyor, fakat image alanı boş” gibi daha araştırılabilir bir cümle kurabilir.

6. Değişmezlik ve sahiplik iddialarını ayrı okuyun

Bir tokenın varlığı, bağlantılı görselin bütün kullanım haklarının size geçtiğini otomatik açıklamaz. Aynı şekilde URI’nin belirli bir anda bir dosyayı göstermesi, metadata tasarımının her durumda değişmez olduğunu kanıtlamaz. ERC-721 açıklaması metadata URI’sinin değişebilir olabileceğini belirtir. Bu rehber hukuki hak değerlendirmesi yapmaz; teknik inceleme notuna “içerik kaynağı” ve “hak açıklaması” için farklı alanlar eklemenizi önerir. Teknik kimlik, dosya erişimi ve kullanım koşullarını tek cümlede birleştirmeyin.

7. Sunum için dört kutulu açıklama hazırlayın

Son çalışmanızda “ağ ve sözleşme”, “token kimliği”, “metadata belgesi” ve “görsel dosyası” kutularını çizip aralarındaki ilişkiyi anlatın. Kutuların tamamını aynı veritabanıymış gibi göstermeyin; kullanılan tasarıma göre içerik zincir dışında veya farklı biçimde tutulabilir. Kod çıktısını şemanın metadata kutusuna yerleştirin ve örneğin kurgusal olduğunu yazın. Bu ayrım anlaşılır olduğunda, bir NFT sayfasındaki eksik görseli panik halinde yorumlamak yerine hangi teknik katmanın incelenmesi gerektiğini tarif edebilirsiniz.

İlgili okumalar

• Seed phrase yedekleme planı: kelimeleri paylaşmadan hazırlık ve kontrol
• Blok gezgininde işlem makbuzu okuma: durum, alıcı ve varlığı birlikte kontrol etme