- Kind
- Pure package
- Name
- v0
- Namespace
- nt / treasury
- Exported functions
- n/a — not supported for pure packages by the node (vm/qfuncs)
- Module
- gno.land/p/nt/treasury/v0
- gno
- 0.9
types.gnogno
1package treasury23import (4 "errors"56 "gno.land/p/nt/bptree/list/v0"7 "gno.land/p/nt/bptree/v0"8
not supported for pure packages by the node (vm/qfuncs)
Signatures reconstructed verbatim from vm/qfuncs — interface params keep their inline definitions.
"gno.land/p/nt/mux/v0"
9)
10
11// Treasury is the main structure that holds all bankers and their payment
12// history. It also provides a router for rendering the treasury pages.
13type Treasury struct {
14 bankers *bptree.BPTree // string -> *bankerRecord
15 router *mux.Router
16 realmPath string // owning realm's PkgPath, captured at New() (used for render links)
17}
18
19// bankerRecord holds a Banker and its payment history.
20type bankerRecord struct {
21 banker Banker
22 history list.List // List of Payment.
23}
24
25// Banker is an interface that allows for banking operations.
26//
27// SECURITY: Send takes (int, realm, Payment), so handing a Banker value to
28// untrusted code yields a capability token to whatever Send impl that code
29// dispatches into. The set of canonical impls is closed (*CoinsBanker,
30// *GRC20Banker); any public function that accepts a Banker as a parameter
31// from external callers MUST verify it via IsCanonicalBanker and reject
32// otherwise. treasury.New enforces this for its own intake; future
33// Banker-accepting APIs must do the same. An unexported-marker "seal" does
34// NOT defend against this — see
35// p/test/seal/filetests/z_seal_iface_embedding_filetest.gno.
36//
37// Note that IsCanonicalBanker validates dynamic TYPE only, not captured
38// STATE: a canonical *CoinsBanker constructed via NewCoinsBankerWithOwner
39// with a hostile owner argument passes the allowlist but its read methods
40// (Balances, Address) report data tied to that hostile address. Treasury
41// operators must construct their own bankers and NEVER accept pre-built
42// *Banker values from external realms.
43type Banker interface {
44 ID() string // Get the ID of the banker.
45 Send(int, realm, Payment) error // Send a payment to a recipient.
46 Balances() []Balance // Get the balances of the banker.
47 Address() string // Get the address of the banker to receive payments.
48}
49
50// IsCanonicalBanker reports whether b is one of treasury's canonical
51// concrete Banker impls. Use this at any public entry point in /p/ or /r/
52// that accepts a Banker from an external caller before invoking its methods.
53//
54// Foreign types — including embedding-based wrappers like
55// `type Evil struct { *CoinsBanker }` — are rejected because type assertions
56// are nominal: *Evil is not *CoinsBanker, regardless of method promotion.
57//
58// To add a new canonical type: extend the switch below AND add a regression
59// test (under filetests/ in this package) that an embedded-impl bypass is
60// rejected.
61//
62// Mirrors the precedent of chain/banker.IsCanonical and
63// p/jaekwon/allowancesender's canonical-impl check.
64func IsCanonicalBanker(b Banker) bool {
65 switch b.(type) {
66 case *CoinsBanker, *GRC20Banker:
67 return true
68 default:
69 return false
70 }
71}
72
73// Payment is an interface that allows getting details about a payment.
74type Payment interface {
75 BankerID() string // Get the ID of the banker that can process this payment.
76 String() string // Get a string representation of the payment.
77}
78
79// IsCanonicalPayment reports whether p is one of treasury's canonical concrete
80// Payment impls. Use this at any public entry point that accepts a Payment
81// from an external caller and shows it to a human before it is processed.
82//
83// The immutability the constructors provide is a property of these two types,
84// not of the interface: a foreign impl's String() says whatever its realm
85// likes, and no Banker will process it, because Banker.Send type-asserts and
86// so fails only at execution — after a vote has been spent on it.
87//
88// Only the value types are listed, deliberately. Banker.Send asserting
89// p.(coinsPayment) is what makes this check meaningful, so accepting
90// *coinsPayment would pass a payment that still fails at execution.
91//
92// To add a new canonical type: extend the switch below AND add a regression
93// test (under filetests/ in this package) that a foreign impl is rejected.
94//
95// Mirrors IsCanonicalBanker above.
96func IsCanonicalPayment(p Payment) bool {
97 switch p.(type) {
98 case coinsPayment, grc20Payment:
99 return true
100 default:
101 return false
102 }
103}
104
105// Balance represents the balance of an asset held by a Banker.
106type Balance struct {
107 Denom string // The denomination of the asset
108 Amount int64 // The amount of the asset
109}
110
111// Common Banker errors.
112var (
113 ErrCurrentRealmIsNotOwner = errors.New("current realm is not the owner of the banker")
114 ErrNoOwnerProvided = errors.New("no owner provided")
115 ErrInvalidPaymentType = errors.New("invalid payment type")
116 ErrSpoofedRealm = errors.New("rlm does not match the current crossing frame")
117)
118