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}