Realm

1package params
2
3// Delegation: letting a realm other than GovDAO manage one specific parameter.
4//
5// This realm holds a capability nothing else can: the `sys/params` stdlib
6// refuses every caller except `gno.land/r/sys/params`, checked in the VM by
7// package path, and the same gate covers the getters. So every parameter write
8// on the chain physically originates here, and "delegating a parameter" can only
9// mean adding a path in this file that authorizes someone other than a GovDAO
10// vote.
11//
12// Two shapes are deliberately NOT used.
13//
14// Not a registry of key -> realm. This realm can never be redeployed
15// (AddPackage refuses an occupied path), and the stdlib gate names this exact
16// path, so making a NEW parameter delegatable already requires editing this
17// file, which means a chain relaunch. A registry's runtime generality would
18// therefore never be exercised: the only freedom that matters is "which realm,
19// or none" for keys already blessed in source. A named slot says exactly that
20// and nothing more. It also removes a whole class of mistake — there is no
21// key string to mis-compose, no container to accidentally expose, and no way for
22// a proposal to name a key the author never considered. A shape-based allowlist
23// like "<module>:p:<name>" would have admitted bank:p:restricted_denoms and
24// auth:p:unrestricted_addrs, which is not a delegation anyone asked for.
25//
26// Not a capability object. Returning something the delegate holds would make
27// authority survive revocation, because the check would have happened at
28// construction. The authority is re-checked on every crossing call instead, so
29// clearing the slot takes effect immediately.
30
31import (
32	"chain"
33
34	"gno.land/r/gov/dao"
35)
36
37// Event names. PascalCase with a named const is the house style across r/sys
38// and r/gov; the bare lowercase "set" elsewhere in this realm predates it.
39const (
40	DelegateSetEvent     = "ParamDelegateSet"
41	DelegateClearedEvent = "ParamDelegateCleared"
42	DelegateWriteEvent   = "ParamDelegateWrite"
43)
44
45// assertDelegate authorizes a caller as the holder of a delegated capability.
46//
47// want is the authorized package path, or "" when nothing is delegated.
48//
49// The empty check comes FIRST and is load-bearing, not defensive. A direct call
50// from a user account has an empty previous package path — that is exactly what
51// IsUserCall tests — so comparing against an unset slot would compare "" to ""
52// and admit every user on the chain. r/gov/dao's own allowlist has the
53// mirror-image bug (it returns true for everyone when the list is empty), kept
54// there deliberately for genesis bootstrap. Nothing here needs that, so empty
55// denies.
56//
57// Matching is exact, never a prefix. A sub-realm identity minted by
58// cur.Sub(subpath) presents the synthesized path "host#subpath", so a delegate
59// may legitimately be a single DAO hosted by a multi-tenant realm — for
60// instance "gno.land/r/nt/commondao/v0#dao/42". An anchored-prefix match on the
61// host would hand the capability to every DAO that realm hosts, and a bare
62// prefix match would additionally match sibling packages. "#" cannot occur in a
63// real package path, so exact matching on the full string is unambiguous.
64//
65// Takes rlm in the non-crossing dispatch position, matching assertValsetCaller
66// so the two gates stay one shape.
67// subject names what is being written, so the refusal stays specific to the
68// capability rather than generic to the mechanism. params_valset_auth.txtar
69// pins valset's exact wording as a regression test for PR #5485.
70func assertDelegate(_ int, rlm realm, want, subject string) {
71	if want == "" {
72		panic("unauthorized: no delegate is configured for " + subject)
73	}
74	// The helper trusts its rlm input, so a future caller threading a stashed
75	// or sibling-frame realm value would otherwise bypass the path check below.
76	if !rlm.IsCurrent() {
77		panic("unauthorized: rlm is not the caller's live cur")
78	}
79	if rlm.Previous().PkgPath() != want {
80		panic("unauthorized: only " + want + " may write " + subject)
81	}
82}
83
84// assertDelegatePath rejects package paths that must never be stored in a
85// delegation slot, at the point a proposal is built rather than when it
86// executes.
87//
88// Rejecting the empty string is the same fail-open guard as in assertDelegate,
89// enforced on the way in as well so an accidental clear-by-empty-set cannot be
90// mistaken for a grant. Requiring the gno.land/r/ prefix excludes user accounts
91// (empty path), pure packages, and ephemeral `maketx run` realms — the last of
92// which matters because a run realm's path is non-empty, so a check based on
93// "is this code" would let one through.
94func assertDelegatePath(pkgpath string) {
95	if pkgpath == "" {
96		panic("invalid delegate: empty package path")
97	}
98	if !isRealmPath(pkgpath) {
99		panic("invalid delegate: must be a gno.land/r/ realm path, got " + pkgpath)
100	}
101	// Reject anything no caller could ever present, so a delegation cannot be
102	// silently dead: GovDAO would believe it granted the capability while the
103	// delegate is refused on every call. The sibling UpdateImpl rejects
104	// whitespace-padded entries for the same reason.
105	for i := 0; i < len(pkgpath); i++ {
106		c := pkgpath[i]
107		switch {
108		case c >= 'a' && c <= 'z', c >= '0' && c <= '9':
109		case c == '/' || c == '.' || c == '-' || c == '_' || c == '#':
110		default:
111			panic("invalid delegate: " + pkgpath +
112				" contains a character no package path or sub-identity can hold")
113		}
114	}
115	if n := countByte(pkgpath, '#'); n > 1 {
116		panic("invalid delegate: more than one '#' in " + pkgpath)
117	}
118}
119
120func countByte(s string, b byte) int {
121	n := 0
122	for i := 0; i < len(s); i++ {
123		if s[i] == b {
124			n++
125		}
126	}
127	return n
128}
129
130const realmPathPrefix = "gno.land/r/"
131
132func isRealmPath(pkgpath string) bool {
133	return len(pkgpath) > len(realmPathPrefix) &&
134		pkgpath[:len(realmPathPrefix)] == realmPathPrefix
135}
136
137// newDelegateProposal builds the GovDAO proposal that applies a delegation
138// change. apply mutates the slot and is run only when the vote passes.
139//
140// event is emitted from inside the executor, so an observer sees the delegation
141// change exactly when it takes effect rather than when it was proposed. from is
142// the previous holder ("" when none), included so a re-delegation is auditable
143// from the single event without reading prior state.
144// apply returns the holder it replaced, read at EXECUTION time. Capturing that
145// at creation would misreport a re-delegation: two set-proposals created while
146// the slot is empty, then executed in sequence, would both emit from="" even
147// though the second replaced the first.
148func newDelegateProposal(cur realm, event, key, to, title, desc string, apply func() string) dao.ProposalRequest {
149	callback := func(cur realm) error {
150		from := apply()
151		chain.Emit(event, "key", key, "from", from, "to", to)
152		return nil
153	}
154	return dao.NewProposalRequest(title, desc,
155		dao.NewSimpleExecutor(0, cur, callback, ""))
156}
157