v0 source pure

v0 - Unaudited: This is an initial version that has not yet been formally audited. A fully audited version will be pu...

v0 - Unaudited This is an initial version of this package that has not yet been formally audited. A fully audited version will be published as a subsequent release. Use in production at your own risk.

treasury

Package treasury provides treasury management for handling coin and GRC20 token transfers in Gno realms.

v0 - Unaudited: This is an initial version that has not yet been formally audited. A fully audited version will be published as a subsequent release. Use in production at your own risk.

Package treasury provides treasury management for handling coin and GRC20 token transfers in Gno realms.

1const (
2	DefaultHistoryPreviewSize = 5  // Number of payments in the history preview.
3	DefaultHistoryPageSize    = 20 // Number of payments per page in the history.
4)

source

1var (
2	ErrNoListerProvided   = errors.New("no lister provided")
3	ErrGRC20TokenNotFound = errors.New("GRC20 token not found")
4)

source

1var (
2	ErrNoBankerProvided       = errors.New("no banker provided")
3	ErrDuplicateBanker        = errors.New("duplicate banker")
4	ErrBankerNotFound         = errors.New("banker not found")
5	ErrSendPaymentFailed      = errors.New("failed to send payment")
6	ErrNonCanonicalBankerImpl = errors.New("non-canonical Banker impl: only *CoinsBanker / *GRC20Banker accepted")
7)

source

1var (
2	ErrCurrentRealmIsNotOwner = errors.New("current realm is not the owner of the banker")
3	ErrNoOwnerProvided        = errors.New("no owner provided")
4	ErrInvalidPaymentType     = errors.New("invalid payment type")
5	ErrSpoofedRealm           = errors.New("rlm does not match the current crossing frame")
6)

source

Common Banker errors.

1var ErrNonCanonicalBanker = errors.New("inner banker is not the canonical chain/banker.Banker")

source

1func IsCanonicalBanker(b Banker) bool

source

IsCanonicalBanker reports whether b is one of treasury's canonical concrete Banker impls. Use this at any public entry point in /p/ or /r/ that accepts a Banker from an external caller before invoking its methods.

Foreign types — including embedding-based wrappers like `type Evil struct { *CoinsBanker }` — are rejected because type assertions are nominal: *Evil is not *CoinsBanker, regardless of method promotion.

To add a new canonical type: extend the switch below AND add a regression test (under filetests/ in this package) that an embedded-impl bypass is rejected.

Mirrors the precedent of chain/banker.IsCanonical and p/jaekwon/allowancesender's canonical-impl check.

1func NewCoinsBankerWithOwner(owner address, banker_ banker.Banker) (*CoinsBanker, error)

source

NewCoinsBankerWithOwner creates a new CoinsBanker with the given address.

banker_ must be the canonical Banker produced by banker.NewBanker; hand-rolled Banker implementations (no-op fakes, decorators) are rejected via banker.IsCanonical. Without this check, a callee receiving a *CoinsBanker constructed from a fake banker would not be able to tell that Send is a no-op (no real coins move). The pkgAddr-vs-owner mismatch is still surfaced lazily by the inner banker's own SendCoins check.

1func NewGRC20BankerWithOwner(owner address, lister TokenListerFunc) (*GRC20Banker, error)

source

NewGRC20BankerWithOwner creates a new GRC20Banker with the given address.

1func NewCoinsPayment(coins chain.Coins, toAddress address) Payment

source

NewCoinsPayment creates a new coinsPayment.

1func NewGRC20Payment(tokenKey string, amount int64, toAddress address) Payment

source

NewGRC20Payment creates a new grc20Payment.

1func New(bankers []Banker, pkgPath string) (*Treasury, error)

source

New creates a new Treasury instance with the given bankers.

pkgPath should be the package path of the owning realm. It is captured on the Treasury and used to build the "See full history" link in RenderBanker. Pass `cur.PkgPath()` from the owning realm's init (or another live-cur context). Passing "" disables the link.

The path is stored as plain data — no IsCurrent guard inside this /p/ constructor. The caller is the trust boundary; it must derive the value from a real `cur realm` rather than accept it from untrusted input. The captured path is consumed only for render output (Class-2 designation-forgery shape, accepted as display-only — see docs/resources/gno-security.md).

Each banker must be one of treasury's canonical concrete impls (*CoinsBanker, *GRC20Banker) per IsCanonicalBanker. Foreign-realm impls (including embedded wrappers around canonical types) are rejected: a malicious Send impl would receive a capability token via its rlm parameter when treasury.Send dispatches into it.

The allowlist validates type only, not captured state. Treasury operators must construct their own bankers; never accept a pre-built *Banker value from an external realm.

1type Balance struct {
2	Denom  string // The denomination of the asset
3	Amount int64  // The amount of the asset
4}

source

Balance represents the balance of an asset held by a Banker.

1type Banker interface {
2	ID() string                     // Get the ID of the banker.
3	Send(int, realm, Payment) error // Send a payment to a recipient.
4	Balances() []Balance            // Get the balances of the banker.
5	Address() string                // Get the address of the banker to receive payments.
6}

source

Banker is an interface that allows for banking operations.

SECURITY: Send takes (int, realm, Payment), so handing a Banker value to untrusted code yields a capability token to whatever Send impl that code dispatches into. The set of canonical impls is closed (*CoinsBanker, *GRC20Banker); any public function that accepts a Banker as a parameter from external callers MUST verify it via IsCanonicalBanker and reject otherwise. treasury.New enforces this for its own intake; future Banker-accepting APIs must do the same. An unexported-marker "seal" does NOT defend against this — see p/test/seal/filetests/z_seal_iface_embedding_filetest.gno.

Note that IsCanonicalBanker validates dynamic TYPE only, not captured STATE: a canonical *CoinsBanker constructed via NewCoinsBankerWithOwner with a hostile owner argument passes the allowlist but its read methods (Balances, Address) report data tied to that hostile address. Treasury operators must construct their own bankers and NEVER accept pre-built *Banker values from external realms.

1type CoinsBanker struct {
2	owner  address       // The address of this coins banker owner.
3	banker banker.Banker // The underlying std banker, must be a BankerTypeRealmSend.
4}

source

CoinsBanker is a Banker that sends banker.Coins.

1func (cb *CoinsBanker) Address() string

source

Address implements Banker.

1func (cb *CoinsBanker) Balances() []Balance

source

Balances implements Banker.

1func (CoinsBanker) ID() string

source

ID implements Banker.

1func (cb *CoinsBanker) Send(_ int, rlm realm, p Payment) error

source

Send implements Banker.

rlm must be the caller's own captured cur (i.e. the cur of the immediate crossing-function caller). Sending with rlm = cur.Previous() or any other realm value is rejected: rlm.IsCurrent() asserts pointer identity against the topmost crossing frame. Combined with the rlm.Address() == cb.owner check, this restricts Send to the owning realm acting in its own frame.

1type GRC20Banker struct {
2	owner  address         // The address of this GRC20 banker owner.
3	lister TokenListerFunc // Allows to list tokens from methods that require it.
4}

source

GRC20Banker is a Banker that sends GRC20 tokens listed using a getter set during initialization.

1func (gb *GRC20Banker) Address() string

source

Address implements Banker.

1func (gb *GRC20Banker) Balances() []Balance

source

Balances implements Banker.

1func (GRC20Banker) ID() string

source

ID implements Banker.

1func (gb *GRC20Banker) Send(_ int, rlm realm, p Payment) error

source

Send implements Banker.

rlm must be the caller's own captured cur (i.e. the cur of the immediate crossing-function caller). Sending with rlm = cur.Previous() or any other realm value is rejected: rlm.IsCurrent() asserts pointer identity against the topmost crossing frame. Combined with the rlm.Address() == gb.owner check, this restricts Send to the owning realm acting in its own frame.

1type Payment interface {
2	BankerID() string // Get the ID of the banker that can process this payment.
3	String() string   // Get a string representation of the payment.
4}

source

Payment is an interface that allows getting details about a payment.

1type TokenListerFunc func() map[string]*grc20.Token

source

TokenListerFunc is a function type that returns a map of GRC20 tokens.

1type Treasury struct {
2	bankers   *bptree.BPTree // string -> *bankerRecord
3	router    *mux.Router
4	realmPath string // owning realm's PkgPath, captured at New() (used for render links)
5}

source

Treasury is the main structure that holds all bankers and their payment history. It also provides a router for rendering the treasury pages.

1func (t *Treasury) Address(bankerID string) (string, error)

source

Address returns the address of the banker with the given ID.

1func (t *Treasury) Balances(bankerID string) ([]Balance, error)

source

Balances returns the balances of the banker with the given ID.

1func (t *Treasury) HasBanker(bankerID string) bool

source

HasBanker checks if a banker with the given ID is registered.

1func (t *Treasury) History(
2	bankerID string,
3	pageNumber int,
4	pageSize int,
5) ([]Payment, error)

source

History returns the payment history sent by the banker with the given ID. Payments are paginated, with the most recent payments first.

1func (t *Treasury) ListBankerIDs() []string

source

ListBankerIDs returns a list of all registered banker IDs.

1func (t *Treasury) Render(path string) string

source

Render renders content based on the given path.

1func (t *Treasury) RenderBanker(bankerID string, path string) string

source

RenderBanker renders the details of a specific banker.

1func (t *Treasury) RenderBankerHistory(bankerID string, path string) string

source

RenderBankerHistory renders the payment history of a specific banker.

1func (t *Treasury) RenderLanding(path string) string

source

RenderLanding renders the landing page of the treasury.

1func (t *Treasury) Send(_ int, rlm realm, p Payment) error

source

Send sends a payment using the corresponding banker. rlm is threaded to the banker's Send for IsCurrent + owner validation.

Readme View source

treasury

Overview

Constants 1

Variables 4

Functions 6

Types 7

Methods on CoinsBanker

Methods on GRC20Banker

Methods on Treasury

Imports 15

Source Files 12