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

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}