Search Apps Documentation Source Content File Folder Download Copy Actions Download State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

jury.gno

9.99 Kb · 341 lines
  1// Package jury is a commit-reveal adversarial review protocol for disputes
  2// over agent work.
  3//
  4// The hard part of an agent economy is not paying agents — it is deciding
  5// what happens when an agent's output is disputed. This realm runs a small
  6// jury: a fixed panel of reviewers each *commit* to a hidden verdict, then
  7// *reveal* it. Commit-reveal means no juror can copy another's vote or be
  8// swayed after seeing the tally; every verdict is locked in blind.
  9//
 10// The subject of a case is an opaque string — a receipt sequence, a claim
 11// id, an off-chain artifact hash — so this realm composes with the receipt
 12// and gnomem demos without depending on them.
 13//
 14// Bonding and slashing (a juror stakes coins, loses them for provably bad
 15// verdicts) are the natural economic layer on top; this demo shows the
 16// mechanism without the money.
 17package jury
 18
 19import (
 20	"chain"
 21	"chain/runtime"
 22	"strings"
 23
 24	"gno.land/p/moul/agents/commit/v0"
 25	"gno.land/p/moul/kit/ui/v0"
 26	"gno.land/p/nt/ufmt/v0"
 27)
 28
 29// Phase is a case's position in the commit-reveal lifecycle.
 30type Phase string
 31
 32const (
 33	PhaseCommit Phase = "commit"
 34	PhaseReveal Phase = "reveal"
 35	PhaseClosed Phase = "closed"
 36)
 37
 38// Juror is one panelist and their (eventually revealed) verdict.
 39type Juror struct {
 40	Addr       address
 41	Commitment string // commit.Verdict(verdict, salt)
 42	Committed  bool
 43	Revealed   bool
 44	Verdict    bool // meaningful once Revealed
 45	Height     int64
 46}
 47
 48// Case is a single dispute under review by a fixed panel.
 49type Case struct {
 50	ID       uint64
 51	Subject  string // opaque reference to the disputed thing
 52	Opener   address
 53	Phase    Phase
 54	Jurors   []*Juror
 55	OpenedAt int64
 56	Outcome  string // "upheld" | "rejected" | "tie" once closed
 57	Yes      int
 58	No       int
 59}
 60
 61var cases []*Case // index 0 => ID 1
 62
 63// The bounds on what a wallet may open. OpenCase is callable by anyone, so
 64// without them the case list and every panel grow without limit, and so does
 65// the index page that renders them.
 66const (
 67	MaxCases    = 1000
 68	MaxJurors   = 25
 69	MaxSubject  = 200 // bytes
 70	IndexRecent = 50  // cases the index lists, newest first
 71
 72	MaxCommitment = 128 // bytes; commit.Verdict returns 64
 73)
 74
 75// OpenCase starts a dispute with a fixed panel of jurors, given as
 76// comma-separated addresses. An odd panel size avoids ties; duplicates and
 77// invalid addresses are rejected.
 78//
 79// The panel is a string, not a []address, because MsgCall carries every
 80// argument as a string and the VM decodes no slice but []byte: a []address
 81// parameter made this function unreachable from any wallet.
 82func OpenCase(cur realm, subject, jurorsCSV string) uint64 {
 83	opener := caller(cur)
 84	// Checked after sanitizing: a subject of only zero-width runes is not empty
 85	// as bytes, and renders as nothing.
 86	assert(strings.TrimSpace(ui.Inline(subject)) != "", "empty subject")
 87	assert(len(subject) <= MaxSubject, "subject too long")
 88	assert(len(cases) < MaxCases, "the jury is full")
 89	jurors := parseJurors(jurorsCSV)
 90	assert(len(jurors) >= 1, "need at least one juror")
 91	assert(len(jurors) <= MaxJurors, "panel too large")
 92
 93	seen := make(map[string]bool)
 94	panel := make([]*Juror, 0, len(jurors))
 95	for _, j := range jurors {
 96		key := j.String()
 97		assert(!seen[key], "duplicate juror: "+key)
 98		seen[key] = true
 99		panel = append(panel, &Juror{Addr: j})
100	}
101
102	id := uint64(len(cases)) + 1
103	cases = append(cases, &Case{
104		ID:       id,
105		Subject:  subject,
106		Opener:   opener,
107		Phase:    PhaseCommit,
108		Jurors:   panel,
109		OpenedAt: runtime.ChainHeight(),
110	})
111	chain.Emit("CaseOpened", "id", ufmt.Sprintf("%d", id), "jurors", ufmt.Sprintf("%d", len(panel)))
112	return id
113}
114
115// Commit locks in a juror's hidden verdict. commitment must equal
116// commit.Verdict(verdict, salt) — computed off-chain. When the last juror
117// commits, the case advances to the reveal phase automatically.
118func Commit(cur realm, caseID uint64, commitment string) {
119	who := caller(cur)
120	c := mustCase(caseID)
121	assert(c.Phase == PhaseCommit, "not in commit phase")
122	assert(commitment != "", "empty commitment")
123	// commit.Verdict is a hex sha256; anything longer is not one, and would be
124	// stored and compared on every later Commit in the case.
125	assert(len(commitment) <= MaxCommitment, "commitment too long")
126	j := mustJuror(c, who)
127	assert(!j.Committed, "already committed")
128	// Every commitment is public through Get, so without this a juror could
129	// commit a copy of another's hash, then reveal the same (verdict, salt)
130	// once the first juror's reveal puts it in a transaction. Refusing a
131	// repeat makes a copied commitment unrevealable.
132	for _, other := range c.Jurors {
133		assert(!other.Committed || other.Commitment != commitment, "commitment already used in this case")
134	}
135	j.Commitment = commitment
136	j.Committed = true
137	j.Height = runtime.ChainHeight()
138
139	if allCommitted(c) {
140		c.Phase = PhaseReveal
141		chain.Emit("CasePhase", "id", ufmt.Sprintf("%d", caseID), "phase", string(PhaseReveal))
142	}
143}
144
145// Reveal opens a juror's verdict. The (verdict, salt) must reproduce the
146// commitment made earlier, or the reveal is rejected. When the last juror
147// reveals, the case closes and the majority outcome is recorded.
148func Reveal(cur realm, caseID uint64, verdict bool, salt string) {
149	who := caller(cur)
150	c := mustCase(caseID)
151	assert(c.Phase == PhaseReveal, "not in reveal phase")
152	j := mustJuror(c, who)
153	assert(j.Committed && !j.Revealed, "nothing to reveal")
154	assert(commit.Verdict(verdict, salt) == j.Commitment, "reveal does not match commitment")
155
156	j.Revealed = true
157	j.Verdict = verdict
158	if verdict {
159		c.Yes++
160	} else {
161		c.No++
162	}
163	chain.Emit("VerdictRevealed", "id", ufmt.Sprintf("%d", caseID), "verdict", boolStr(verdict))
164
165	if allRevealed(c) {
166		closeCase(c)
167	}
168}
169
170// ---- read-only API ----
171
172// Get returns a copy of a case (jurors flattened separately via Jury).
173func Get(caseID uint64) Case { return *mustCase(caseID) }
174
175// Outcome returns the recorded outcome, or "" if the case is still open.
176func Outcome(caseID uint64) string { return mustCase(caseID).Outcome }
177
178// Count returns the number of cases.
179func Count() int { return len(cases) }
180
181// ---- internal ----
182
183func closeCase(c *Case) {
184	switch {
185	case c.Yes > c.No:
186		c.Outcome = "upheld"
187	case c.No > c.Yes:
188		c.Outcome = "rejected"
189	default:
190		c.Outcome = "tie"
191	}
192	c.Phase = PhaseClosed
193	chain.Emit("CaseClosed", "id", ufmt.Sprintf("%d", c.ID), "outcome", c.Outcome)
194}
195
196func allCommitted(c *Case) bool {
197	for _, j := range c.Jurors {
198		if !j.Committed {
199			return false
200		}
201	}
202	return true
203}
204
205func allRevealed(c *Case) bool {
206	for _, j := range c.Jurors {
207		if !j.Revealed {
208			return false
209		}
210	}
211	return true
212}
213
214func mustCase(id uint64) *Case {
215	assert(id >= 1 && id <= uint64(len(cases)), "unknown case")
216	return cases[id-1]
217}
218
219func mustJuror(c *Case, addr address) *Juror {
220	for _, j := range c.Jurors {
221		if j.Addr == addr {
222			return j
223		}
224	}
225	panic("caller is not on this jury")
226}
227
228func boolStr(b bool) string {
229	if b {
230		return "yes"
231	}
232	return "no"
233}
234
235func assert(cond bool, msg string) {
236	if !cond {
237		panic(msg)
238	}
239}
240
241// Render shows all cases, or one case's panel + tally at :<id>.
242func Render(path string) string {
243	if path == "" {
244		return renderIndex()
245	}
246	return renderCase(parseID(path))
247}
248
249func renderIndex() string {
250	var sb strings.Builder
251	sb.WriteString("# Agent Jury\n\n")
252	sb.WriteString("_Who checks the agents?_ Blind commit-reveal review by a fixed panel.\n\n")
253	if len(cases) == 0 {
254		sb.WriteString("_No cases yet._\n")
255		return sb.String()
256	}
257	if len(cases) > IndexRecent {
258		sb.WriteString(ufmt.Sprintf("The %d most recent of %d cases, newest first.\n\n", IndexRecent, len(cases)))
259	}
260	sb.WriteString("| # | Subject | Phase | ✅ | ❌ | Outcome |\n")
261	sb.WriteString("|---|---|---|---|---|---|\n")
262	// Newest first, and only the last IndexRecent: the page has to render at
263	// MaxCases too.
264	for i := len(cases) - 1; i >= 0 && i >= len(cases)-IndexRecent; i-- {
265		c := cases[i]
266		out := c.Outcome
267		if out == "" {
268			out = "—"
269		}
270		sb.WriteString(ufmt.Sprintf("| [%d](/r/moul/agents/jury/v0:%d) | %s | %s | %d | %d | %s |\n",
271			c.ID, c.ID, ui.Cell(c.Subject), string(c.Phase), c.Yes, c.No, out))
272	}
273	return sb.String()
274}
275
276func renderCase(id uint64) string {
277	c := mustCase(id)
278	var sb strings.Builder
279	sb.WriteString(ufmt.Sprintf("# Case #%d\n\n", c.ID))
280	sb.WriteString(ufmt.Sprintf("- **Subject:** %s\n", ui.Inline(c.Subject)))
281	sb.WriteString(ufmt.Sprintf("- **Phase:** %s\n", string(c.Phase)))
282	sb.WriteString(ufmt.Sprintf("- **Opened by:** %s at height %d\n", short(c.Opener), c.OpenedAt))
283	if c.Outcome != "" {
284		sb.WriteString(ufmt.Sprintf("- **Outcome:** **%s** (%d ✅ / %d ❌)\n", c.Outcome, c.Yes, c.No))
285	}
286	sb.WriteString("\n## Panel\n\n")
287	sb.WriteString("| Juror | Committed | Revealed | Verdict | Dissent |\n|---|---|---|---|---|\n")
288	majority := c.Yes >= c.No // for dissent marking once closed
289	for _, j := range c.Jurors {
290		verdict, dissent := "—", ""
291		if j.Revealed {
292			verdict = boolStr(j.Verdict)
293			if c.Phase == PhaseClosed && c.Outcome != "tie" && j.Verdict != majority {
294				dissent = "⚠"
295			}
296		}
297		sb.WriteString(ufmt.Sprintf("| %s | %t | %t | %s | %s |\n",
298			short(j.Addr), j.Committed, j.Revealed, verdict, dissent))
299	}
300	return sb.String()
301}
302
303func parseID(s string) uint64 {
304	var n uint64
305	for i := 0; i < len(s); i++ {
306		ch := s[i]
307		assert(ch >= '0' && ch <= '9', "invalid case path: "+s)
308		n = n*10 + uint64(ch-'0')
309	}
310	return n
311}
312
313func short(a address) string {
314	s := a.String()
315	if len(s) <= 12 {
316		return s
317	}
318	return s[:8] + "…" + s[len(s)-4:]
319}
320
321// parseJurors splits a comma-separated panel, trimming spaces around each
322// address and refusing an empty or invalid one.
323func parseJurors(csv string) []address {
324	var out []address
325	for _, part := range strings.Split(csv, ",") {
326		a := address(strings.TrimSpace(part))
327		assert(a.IsValid(), "invalid juror address: "+string(a))
328		out = append(out, a)
329	}
330	return out
331}
332
333// caller is the address that crossed into this realm, after checking that the
334// realm token is this frame's own. Every entry point reads it first, before
335// any other work.
336func caller(cur realm) address {
337	if !cur.IsCurrent() {
338		panic("jury: spoofed realm")
339	}
340	return cur.Previous().Address()
341}