Skip to content Search Apps Documentation Source Content Run Reset Eval Playground File Folder Download Copy Actions State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

Playground

gnomod.toml

module = "gno.land/p/nt/grc721/metadata/v0"
gno = "0.9"

[addpkg]
  creator = "g1edq4dugw0sgat4zxcw9xardvuydqf6cgleuc8p"

token.gno

package metadata

import (
	"chain"

	"gno.land/p/nt/grc721/v0"
)

const Kind = "metadata"

// NewMetadata attaches a metadata extension and registers it as a core Extension.
// Attach it before the first mint so every token is indexed.
func NewMetadata(coreLedger *grc721.PrivateLedger) (*Metadata, *Ledger) {
	if coreLedger == nil {
		panic("metadata: nil core ledger")
	}

	st := &storage{}
	core := coreLedger.ReadToken()
	led := &Ledger{core: core, st: st}
	coreLedger.RegisterExtension(led)

	return &Metadata{core: core, st: st}, led
}

func (m *Metadata) ExtensionKind() string { return Kind }

func (m *Metadata) TokenID() string { return m.core.ID() }

func (m *Metadata) TokenURI(tid grc721.TokenID) (string, error) {
	v := m.st.uris.Get(tid.String())
	if v == nil {
		return "", ErrNoTokenURI
	}

	return v.(string), nil
}

func (m *Metadata) TokenMetadata(tid grc721.TokenID) (Data, error) {
	v := m.st.data.Get(tid.String())
	if v == nil {
		return Data{}, ErrNoMetadata
	}

	return v.(Data), nil
}

func (m *Metadata) HasTokenURI(tid grc721.TokenID) bool {
	return m.st.uris.Has(tid.String())
}

func (m *Metadata) HasMetadata(tid grc721.TokenID) bool {
	return m.st.data.Has(tid.String())
}

// SetTokenURI sets the EIP-721 tokenURI of tid; issuer-only so a holder cannot
// rewrite the URI after acquisition.
func (led *Ledger) SetTokenURI(tid grc721.TokenID, uri string) error {
	if _, err := led.core.OwnerOf(tid); err != nil {
		return ErrTokenNotMinted
	}

	led.st.uris.Set(tid.String(), uri)

	chain.Emit(
		TokenURIUpdateEvent,
		"token", led.core.ID(),
		"tokenId", tid.String(),
		"uri", uri,
	)

	return nil
}

// SetTokenMetadata sets the OpenSea on-chain metadata of tid; issuer-only.
func (led *Ledger) SetTokenMetadata(tid grc721.TokenID, data Data) error {
	if _, err := led.core.OwnerOf(tid); err != nil {
		return ErrTokenNotMinted
	}

	led.st.data.Set(tid.String(), data)

	chain.Emit(
		MetadataUpdateEvent,
		"token", led.core.ID(),
		"tokenId", tid.String(),
	)

	return nil
}

func (led *Ledger) ExtensionKind() string { return Kind }

func (led *Ledger) OnMint(to address, tid grc721.TokenID)           {}
func (led *Ledger) OnTransfer(from, to address, tid grc721.TokenID) {}

// OnBurn clears per-token state so it cannot resurface on re-mint.
func (led *Ledger) OnBurn(tid grc721.TokenID) {
	tidStr := tid.String()
	led.st.uris.Remove(tidStr)
	led.st.data.Remove(tidStr)
}

token_test.gno

package metadata

import (
	"testing"

	"gno.land/p/nt/grc721/v0"
	"gno.land/p/nt/seqid/v0"
	"gno.land/p/nt/testutils/v0"
	"gno.land/p/nt/uassert/v0"
	"gno.land/p/nt/urequire/v0"
)

// newToken builds via same-realm cross (NewToken requires rlm.IsCurrent()).
func newToken(name, symbol string, id seqid.ID, rlm realm) (tok *grc721.Token, led *grc721.PrivateLedger) {
	func(cur realm) {
		tok, led = grc721.NewToken(name, symbol, id, cur)
	}(cross(rlm))
	return
}

func newMeta(id seqid.ID, rlm realm) (*grc721.PrivateLedger, *Metadata, *Ledger) {
	_, tokenLedger := newToken("Foo", "FOO", id, rlm)
	meta, metaLedger := NewMetadata(tokenLedger)
	return tokenLedger, meta, metaLedger
}

func TestNewMetadata(cur realm, t *testing.T) {
	tests := []struct {
		name      string
		nilLedger bool
	}{
		{"nil token ledger panics", true},
		{"valid token ledger constructs read view and ledger", false},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			if tt.nilLedger {
				uassert.PanicsWithMessage(t, cur, "metadata: nil core ledger", func() {
					NewMetadata(nil)
				})
				return
			}

			_, tokenLedger := newToken("Foo", "FOO", 0, cur)
			meta, metaLedger := NewMetadata(tokenLedger)

			uassert.True(t, meta != nil)
			uassert.True(t, metaLedger != nil)
			uassert.Equal(t, Kind, meta.ExtensionKind())
			uassert.Equal(t, "metadata", meta.ExtensionKind())
			uassert.Equal(t, tokenLedger.ReadToken().ID(), meta.TokenID())
		})
	}
}

func TestSetTokenURI(cur realm, t *testing.T) {
	tests := []struct {
		name    string
		mint    bool
		tid     grc721.TokenID
		uri     string
		wantErr error
	}{
		{"unminted token returns ErrTokenNotMinted", false, "404", "ipfs://x", ErrTokenNotMinted},
		{"minted token sets uri", true, "1", "ipfs://uri-1", nil},
		{"empty uri on minted token is allowed", true, "1", "", nil},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			tokenLedger, meta, metaLedger := newMeta(0, cur)
			if tt.mint {
				urequire.NoError(t, tokenLedger.Mint(testutils.TestAddress("alice"), tt.tid))
			}

			err := metaLedger.SetTokenURI(tt.tid, tt.uri)
			if tt.wantErr != nil {
				uassert.ErrorIs(t, err, tt.wantErr)
				uassert.False(t, meta.HasTokenURI(tt.tid))
				return
			}

			urequire.NoError(t, err)
			uassert.True(t, meta.HasTokenURI(tt.tid))
			got, err := meta.TokenURI(tt.tid)
			urequire.NoError(t, err)
			uassert.Equal(t, tt.uri, got)
		})
	}
}

func TestSetTokenURIOverwrite(cur realm, t *testing.T) {
	tokenLedger, meta, metaLedger := newMeta(0, cur)
	urequire.NoError(t, tokenLedger.Mint(testutils.TestAddress("alice"), "1"))

	urequire.NoError(t, metaLedger.SetTokenURI("1", "ipfs://first"))
	urequire.NoError(t, metaLedger.SetTokenURI("1", "ipfs://second"))

	got, err := meta.TokenURI("1")
	urequire.NoError(t, err)
	uassert.Equal(t, "ipfs://second", got)
}

func TestSetTokenMetadata(cur realm, t *testing.T) {
	full := Data{
		Image:           "ipfs://img-1",
		ImageData:       "<svg/>",
		ExternalURL:     "https://example.com/1",
		Description:     "first",
		Name:            "Token One",
		Attributes:      []Trait{{DisplayType: "string", TraitType: "rarity", Value: "rare"}},
		BackgroundColor: "ffffff",
		AnimationURL:    "ipfs://anim-1",
		YoutubeURL:      "https://youtu.be/abc",
	}

	tests := []struct {
		name    string
		mint    bool
		tid     grc721.TokenID
		data    Data
		wantErr error
	}{
		{"unminted token returns ErrTokenNotMinted", false, "404", Data{Name: "x"}, ErrTokenNotMinted},
		{"minted token stores full metadata", true, "1", full, nil},
		{"minted token stores zero-value metadata", true, "2", Data{}, nil},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			tokenLedger, meta, metaLedger := newMeta(0, cur)
			if tt.mint {
				urequire.NoError(t, tokenLedger.Mint(testutils.TestAddress("alice"), tt.tid))
			}

			err := metaLedger.SetTokenMetadata(tt.tid, tt.data)
			if tt.wantErr != nil {
				uassert.ErrorIs(t, err, tt.wantErr)
				uassert.False(t, meta.HasMetadata(tt.tid))
				return
			}

			urequire.NoError(t, err)
			uassert.True(t, meta.HasMetadata(tt.tid))
			got, err := meta.TokenMetadata(tt.tid)
			urequire.NoError(t, err)
			uassert.Equal(t, tt.data.Name, got.Name)
			uassert.Equal(t, tt.data.Description, got.Description)
			uassert.Equal(t, tt.data.Image, got.Image)
			uassert.Equal(t, len(tt.data.Attributes), len(got.Attributes))
			if len(tt.data.Attributes) > 0 {
				uassert.Equal(t, tt.data.Attributes[0].Value, got.Attributes[0].Value)
				uassert.Equal(t, tt.data.Attributes[0].TraitType, got.Attributes[0].TraitType)
			}
		})
	}
}

func TestSetTokenMetadataOverwrite(cur realm, t *testing.T) {
	tokenLedger, meta, metaLedger := newMeta(0, cur)
	urequire.NoError(t, tokenLedger.Mint(testutils.TestAddress("alice"), "1"))

	urequire.NoError(t, metaLedger.SetTokenMetadata("1", Data{Name: "first"}))
	urequire.NoError(t, metaLedger.SetTokenMetadata("1", Data{Name: "second"}))

	got, err := meta.TokenMetadata("1")
	urequire.NoError(t, err)
	uassert.Equal(t, "second", got.Name)
}

func TestReadsOnUnsetToken(cur realm, t *testing.T) {
	tests := []struct {
		name string
		fn   func(t *testing.T, meta *Metadata)
	}{
		{"TokenURI on unset token returns ErrNoTokenURI", func(t *testing.T, meta *Metadata) {
			uri, err := meta.TokenURI("1")
			uassert.Equal(t, "", uri)
			uassert.ErrorIs(t, err, ErrNoTokenURI)
		}},
		{"TokenMetadata on unset token returns ErrNoMetadata", func(t *testing.T, meta *Metadata) {
			data, err := meta.TokenMetadata("1")
			uassert.Equal(t, "", data.Name)
			uassert.ErrorIs(t, err, ErrNoMetadata)
		}},
		{"HasTokenURI is false on unset token", func(t *testing.T, meta *Metadata) {
			uassert.False(t, meta.HasTokenURI("1"))
		}},
		{"HasMetadata is false on unset token", func(t *testing.T, meta *Metadata) {
			uassert.False(t, meta.HasMetadata("1"))
		}},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			_, meta, _ := newMeta(0, cur)
			tt.fn(t, meta)
		})
	}
}

func TestOnBurnClearsMetadata(cur realm, t *testing.T) {
	alice := testutils.TestAddress("alice")
	tokenLedger, meta, metaLedger := newMeta(0, cur)

	urequire.NoError(t, tokenLedger.Mint(alice, "1"))
	urequire.NoError(t, metaLedger.SetTokenURI("1", "ipfs://uri-1"))
	urequire.NoError(t, metaLedger.SetTokenMetadata("1", Data{Name: "one"}))
	uassert.True(t, meta.HasTokenURI("1"))
	uassert.True(t, meta.HasMetadata("1"))

	urequire.NoError(t, tokenLedger.Burn("1"))
	uassert.False(t, meta.HasTokenURI("1"))
	uassert.False(t, meta.HasMetadata("1"))

	_, err := meta.TokenURI("1")
	uassert.ErrorIs(t, err, ErrNoTokenURI)
	_, err = meta.TokenMetadata("1")
	uassert.ErrorIs(t, err, ErrNoMetadata)

	urequire.NoError(t, tokenLedger.Mint(alice, "1"))
	uassert.False(t, meta.HasTokenURI("1"))
	uassert.False(t, meta.HasMetadata("1"))
}

func TestHooks(cur realm, t *testing.T) {
	alice := testutils.TestAddress("alice")
	bob := testutils.TestAddress("bob")
	tokenLedger, meta, metaLedger := newMeta(0, cur)

	urequire.NoError(t, tokenLedger.Mint(alice, "1"))
	urequire.NoError(t, metaLedger.SetTokenURI("1", "ipfs://uri-1"))
	urequire.NoError(t, metaLedger.SetTokenMetadata("1", Data{Name: "one"}))

	metaLedger.OnMint(alice, "1")
	metaLedger.OnTransfer(alice, bob, "1")
	uassert.True(t, meta.HasTokenURI("1"))
	uassert.True(t, meta.HasMetadata("1"))
	uri, err := meta.TokenURI("1")
	urequire.NoError(t, err)
	uassert.Equal(t, "ipfs://uri-1", uri)

	metaLedger.OnBurn("1")
	uassert.False(t, meta.HasTokenURI("1"))
	uassert.False(t, meta.HasMetadata("1"))
}

types.gno

// Package metadata is a stackable GRC721 extension for EIP-721 tokenURI and
// OpenSea on-chain metadata. Writes are issuer-only so a holder cannot rewrite metadata after acquisition.
package metadata

import (
	"errors"

	"gno.land/p/nt/avl/v0"
	"gno.land/p/nt/grc721/v0"
)

const (
	MetadataUpdateEvent = "MetadataUpdate"
	TokenURIUpdateEvent = "TokenURIUpdate"
)

var (
	ErrTokenNotMinted = errors.New("token is not minted")
	ErrNoMetadata     = errors.New("token has no metadata")
	ErrNoTokenURI     = errors.New("token has no uri")
)

type Metadata struct {
	core *grc721.Token
	st   *storage
}

type Ledger struct {
	core *grc721.Token
	st   *storage
}

// Data is the OpenSea on-chain metadata for a single token.
type Data struct {
	Image           string
	ImageData       string
	ExternalURL     string
	Description     string
	Name            string
	Attributes      []Trait
	BackgroundColor string
	AnimationURL    string
	YoutubeURL      string
}

type Trait struct {
	DisplayType string
	TraitType   string
	Value       string
}

type storage struct {
	uris avl.Tree // grc721.TokenID -> string
	data avl.Tree // grc721.TokenID -> Data
}

var _ grc721.Extension = (*Ledger)(nil)

var _ grc721.ExtensionView = (*Metadata)(nil)