usernames.gno
4.94 Kb · 149 lines
1// Package usernames is the toolbox tool for gno.land identities: it turns a
2// username into an address, an address into a username, and tells you which
3// of the two you are actually holding.
4//
5// It is the page form of
6//
7// gnokey query vm/qeval --data 'gno.land/r/sys/users.ResolveName("akkadia")' -remote https://rpc.gno.land
8//
9// with the three things that query does not tell you: whether the name you
10// asked about is the user's CURRENT name or an alias they renamed away from,
11// what canonical key it collapses to, and whether a lookalike of it is already
12// taken.
13//
14// # Why not r/sys/users.ResolveAny
15//
16// `ResolveAny` returns `(*UserData, bool)` and the bool does not mean "found".
17// For an input that parses as an address it returns `(ResolveAddress(addr),
18// true)` whatever the lookup produced, so an unregistered address comes back
19// as `(nil, true)`. Every caller that reads the bool and dereferences the
20// pointer panics on the first address nobody claimed. [lookup] branches on the
21// input itself and checks the pointer instead.
22//
23// Part of [r/moul/toolbox](/r/moul/toolbox).
24package usernames
25
26import "gno.land/r/sys/users"
27
28// lookup resolves any input to a user record, or nil.
29//
30// An input that parses as a gno.land address is only ever looked up as an
31// address, and anything else only as a name: a bech32 address is not a legal
32// username, so trying both would only widen what a typo can hit.
33func lookup(input string) *users.UserData {
34 if input == "" {
35 return nil
36 }
37 if addr := address(input); addr.IsValid() {
38 return users.ResolveAddress(addr)
39 }
40 data, _ := users.ResolveName(input)
41 return data
42}
43
44// Resolve returns the current username and the address behind any input, a
45// username or a `g1` address.
46//
47// found is false when nobody holds it, which is also the answer for a deleted
48// user: `r/sys/users` keeps the tombstone and resolves it to nothing.
49//
50// gnokey query vm/qeval -data 'gno.land/r/moul/toolbox/usernames.Resolve("moul")'
51func Resolve(input string) (name string, addr string, found bool) {
52 data := lookup(input)
53 if data == nil {
54 return "", "", false
55 }
56 return data.Name(), data.Addr().String(), true
57}
58
59// AddressOf returns the address behind a username or an address, or "" when
60// nobody holds it.
61//
62// It is the call another realm would want, and the one it cannot have: this
63// realm is `private = true`, so nothing can import it. Over `vm/qeval` it is
64// the whole point.
65//
66// gnokey query vm/qeval -data 'gno.land/r/moul/toolbox/usernames.AddressOf("moul")'
67func AddressOf(input string) string {
68 _, addr, found := Resolve(input)
69 if !found {
70 return ""
71 }
72 return addr
73}
74
75// NameOf returns the current username behind a username or an address, or ""
76// when nobody holds it.
77func NameOf(input string) string {
78 name, _, found := Resolve(input)
79 if !found {
80 return ""
81 }
82 return name
83}
84
85// Display returns what a page should print for an input: "@name" when there is
86// a username, and the input unchanged when there is not.
87//
88// So it is total over every input a page actually has, and a caller never has
89// to branch on "not found" the way [NameOf] makes it. The one input it has
90// nothing to say about is "", which it returns unchanged: an empty answer to an
91// empty question, rather than a placeholder a page would then have to special
92// case anyway.
93func Display(input string) string {
94 if name := NameOf(input); name != "" {
95 return "@" + name
96 }
97 return input
98}
99
100// CurrentName reports the user's current name when input is an alias they
101// renamed away from, and "" otherwise.
102//
103// `r/sys/users` keeps old names resolving on purpose, so an address looked up
104// by a name that is no longer current is not an error and nothing in the
105// resolve result says so. This is the one call that does.
106func CurrentName(input string) string {
107 if input == "" {
108 return ""
109 }
110 if addr := address(input); addr.IsValid() {
111 return ""
112 }
113 data, isCurrent := users.ResolveName(input)
114 if data == nil || isCurrent {
115 return ""
116 }
117 return data.Name()
118}
119
120// Canonical returns the canonical key a name collapses to. Two names with the
121// same canonical form cannot both be registered, which is how `r/sys/users`
122// refuses a lookalike of an existing account.
123//
124// gnokey query vm/qeval -data 'gno.land/r/moul/toolbox/usernames.Canonical("M0ul")'
125func Canonical(name string) string { return users.Canonicalize(name) }
126
127// Taken reports whether the exact name is registered, including names that
128// were deleted or renamed away from: it answers "would registering this
129// fail", not "is somebody using this".
130func Taken(name string) bool {
131 if name == "" {
132 return false
133 }
134 return users.IsNameTaken(name)
135}
136
137// CanonicalOwner returns the name that already holds this name's canonical
138// key, or "" when the key is free. A non-empty answer that is not the name
139// itself is a lookalike collision.
140func CanonicalOwner(name string) string {
141 if name == "" {
142 return ""
143 }
144 existing, taken := users.IsCanonicalTaken(name)
145 if !taken {
146 return ""
147 }
148 return existing
149}