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

Community realm. Read the code first. Community realm, deployed by its author. Read the code before you interact or send coins.

engine.gno

6.91 Kb · 218 lines
  1// Package engine is the "art as code" contract (design §5.2): what a
  2// generative engine implements, what core hands it, and the conformance
  3// rules both core and engine authors check against.
  4//
  5// An engine is registered from its own /r/ adapter realm. Because the
  6// adapter's methods are declared in that realm, core calling them runs the
  7// engine with the adapter's authority, never core's (interrealm v2 borrow
  8// rule #1). Methods receive and return plain values only: an engine never
  9// gets a reference into core state.
 10package engine
 11
 12import (
 13	"errors"
 14	"strconv"
 15
 16	"gno.land/p/g1jz6j9hj6rdf5ltl2kcrpa4jwtdh3w30z0yul06/sinopia/safe/v1"
 17)
 18
 19// Input is everything an engine may depend on. p/ packages are frozen once
 20// deployed, so the fields "living" engines will need later (phase 2) are
 21// here from day one.
 22type Input struct {
 23	Seed           string // 64-hex final seed (sample seeds in Studio)
 24	Params         string // collection params, in the engine's own format
 25	CollectionID   string
 26	TokenID        string
 27	MintHeight     int64
 28	LastMoveHeight int64 // patina: holding time = Height - LastMoveHeight
 29	Moves          int64 // transfers so far
 30	Height         int64 // height of the read (fixed by Verify)
 31}
 32
 33type Trait struct {
 34	Type, Value string
 35}
 36
 37type Manifest struct {
 38	Name, Version, Description, License string
 39	Author                              address // proven by core.ClaimEngine
 40	ParamsSchema                        string  // JSON Schema subset; Studio builds its form from it
 41	TraitTypes                          []string
 42	Living                              bool  // Render depends on LastMoveHeight/Moves/Height
 43	MaxSVGBytes                         int64 // <= MaxSVGBytes
 44	// FeeBps is the author's fee on every primary and secondary sale of a
 45	// collection that uses this engine, 0..MaxFeeBps. It is fixed at
 46	// registration; core snapshots it per collection at Launch, caps it by
 47	// the platform's engine-fee cap and waives it when the collection's
 48	// creator is the author.
 49	FeeBps int64
 50}
 51
 52// Engine is implemented by a stateless value declared in the adapter realm.
 53//
 54// Contract: deterministic in Input; ValidateParams("") must accept the
 55// engine's defaults; Render returns raw SVG (core does the base64); Traits
 56// only uses types listed in the manifest, each at most once.
 57type Engine interface {
 58	Manifest() Manifest
 59	ValidateParams(params string) error
 60	Traits(in Input) []Trait
 61	Render(in Input) string
 62}
 63
 64// Limits core enforces on every engine.
 65const (
 66	MaxSVGBytes      = 65536
 67	MaxTraits        = 32
 68	MaxTraitLen      = 64
 69	MaxNameLen       = 64
 70	MaxVersionLen    = 32
 71	MaxDescLen       = 1024
 72	MaxLicenseLen    = 64
 73	MaxParamsSchema  = 4096
 74	MaxFeeBps        = 500 // 5%: hard cap of an engine author's fee
 75)
 76
 77// SampleInput is the fixed input of an engine's fingerprint: core renders it
 78// at registration and stores sha256(svg); anyone can recompute it later.
 79func SampleInput() Input {
 80	return Input{
 81		Seed:           safe.Sha256Hex(safe.Domain + "|engine-sample|v1"),
 82		CollectionID:   "0",
 83		TokenID:        "0",
 84		MintHeight:     1,
 85		LastMoveHeight: 1,
 86		Height:         1,
 87	}
 88}
 89
 90// SampleSeed returns the i-th Studio/conformance sample seed.
 91func SampleSeed(i int) string {
 92	return safe.Sha256Hex(safe.Domain + "|sample|v1|" + strconv.Itoa(i))
 93}
 94
 95// ValidateManifest checks sizes, text hygiene and the author address.
 96func ValidateManifest(m Manifest) error {
 97	fields := []struct {
 98		name, value string
 99		max         int
100		required    bool
101	}{
102		{"name", m.Name, MaxNameLen, true},
103		{"version", m.Version, MaxVersionLen, true},
104		{"description", m.Description, MaxDescLen, false},
105		{"license", m.License, MaxLicenseLen, false},
106		{"paramsSchema", m.ParamsSchema, MaxParamsSchema, false},
107	}
108	for _, f := range fields {
109		if f.required && f.value == "" {
110			return errors.New("manifest " + f.name + ": must not be empty")
111		}
112		if err := safe.CheckText(f.value, f.max); err != nil {
113			return errors.New("manifest " + f.name + ": " + err.Error())
114		}
115	}
116	if !m.Author.IsValid() {
117		return errors.New("manifest author: invalid address")
118	}
119	if len(m.TraitTypes) > MaxTraits {
120		return errors.New("manifest: too many trait types")
121	}
122	for i, tt := range m.TraitTypes {
123		if tt == "" {
124			return errors.New("manifest: empty trait type")
125		}
126		if err := safe.CheckText(tt, MaxTraitLen); err != nil {
127			return errors.New("manifest trait type: " + err.Error())
128		}
129		for _, prev := range m.TraitTypes[:i] {
130			if prev == tt {
131				return errors.New("manifest: duplicate trait type " + tt)
132			}
133		}
134	}
135	if m.FeeBps < 0 || m.FeeBps > MaxFeeBps {
136		return errors.New("manifest feeBps: must be 0.." + strconv.Itoa(MaxFeeBps))
137	}
138	if m.MaxSVGBytes <= 0 || m.MaxSVGBytes > MaxSVGBytes {
139		return errors.New("manifest maxSVGBytes: must be 1.." + strconv.Itoa(MaxSVGBytes))
140	}
141	return nil
142}
143
144// ValidateTraits checks one Traits() result against the manifest.
145func ValidateTraits(m Manifest, ts []Trait) error {
146	if len(ts) > len(m.TraitTypes) {
147		return errors.New("traits: more traits than manifest trait types")
148	}
149	for i, t := range ts {
150		if !contains(m.TraitTypes, t.Type) {
151			return errors.New("traits: type not in manifest: " + t.Type)
152		}
153		for _, prev := range ts[:i] {
154			if prev.Type == t.Type {
155				return errors.New("traits: duplicate type " + t.Type)
156			}
157		}
158		if err := safe.CheckText(t.Value, MaxTraitLen); err != nil {
159			return errors.New("traits " + t.Type + ": " + err.Error())
160		}
161	}
162	return nil
163}
164
165// CheckSVG is the output rule core applies to every render.
166func CheckSVG(m Manifest, svg string) error {
167	return safe.AssertSVG(svg, int(m.MaxSVGBytes))
168}
169
170// Conformance is the self-test engine authors run in their _test.gno
171// before registering: manifest, default params, determinism, size, SVG
172// hygiene, traits, and — for non-living engines — independence from the
173// living fields.
174func Conformance(e Engine, samples int) error {
175	m := e.Manifest()
176	if err := ValidateManifest(m); err != nil {
177		return err
178	}
179	if err := e.ValidateParams(""); err != nil {
180		return errors.New("default params rejected: " + err.Error())
181	}
182	inputs := []Input{SampleInput()}
183	for i := 0; i < samples; i++ {
184		in := SampleInput()
185		in.Seed = SampleSeed(i)
186		in.TokenID = strconv.Itoa(i + 1)
187		inputs = append(inputs, in)
188	}
189	for _, in := range inputs {
190		svg := e.Render(in)
191		if svg != e.Render(in) {
192			return errors.New("render is not deterministic for seed " + in.Seed)
193		}
194		if err := CheckSVG(m, svg); err != nil {
195			return errors.New("seed " + in.Seed + ": " + err.Error())
196		}
197		if err := ValidateTraits(m, e.Traits(in)); err != nil {
198			return errors.New("seed " + in.Seed + ": " + err.Error())
199		}
200		if !m.Living {
201			moved := in
202			moved.Height, moved.Moves, moved.LastMoveHeight = in.Height+1000, in.Moves+3, in.Height+500
203			if e.Render(moved) != svg {
204				return errors.New("non-living engine depends on Height/Moves/LastMoveHeight")
205			}
206		}
207	}
208	return nil
209}
210
211func contains(list []string, s string) bool {
212	for _, x := range list {
213		if x == s {
214			return true
215		}
216	}
217	return false
218}