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)