vault

curl -sS 'https://pearl.testnets.gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault$download&file=vault.gno' | shasum -a 256

Overview

Realm vault holds GNOT deposits with per-user balances and an explicit, inspectable protocol fee, built on gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/feeledger.

Flow: an EOA deposits GNOT by calling Deposit with coins attached (`-send`); the configured fee (FeeBps, capped at MaxFeeBps) accrues to a separate fee pot and the remainder credits the depositor's balance. Users claim their balance back at any time, partially or fully. The fee recipient — a role distinct from the admin — withdraws the fee pot.

FEE MODEL (all values inspectable via FeeBps/FeeRecipient/MaxFeeBps):

• fee = floor(amount * FeeBps / 10000); rounding favors the depositor; no minimum fee (small deposits may pay 0).
• FeeBps starts at 0 (no fee) and is changed only by the admin via SetFeeBps, hard-capped at MaxFeeBps (10% — the cap itself is a compile-time constant and cannot be raised by anyone).
• A fee change applies to FUTURE deposits only; already-accrued fees and user balances are untouched.
• Fees accrue to a pot, not an address. Changing the fee recipient re-points who may withdraw the pot, INCLUDING what was accrued under the previous recipient (positional, documented trade-off).
• With FeeBps == 0 deposits credit in full and the pot grows by 0.
• The fee can never exceed the deposit: FeeBps <= 10000 structurally and <= 1000 by this realm's cap.

ACCOUNTING INVARIANT (conservation): let H be the ugnot held at this realm's address, U the sum of user balances, F the accrued fee pot. At every transaction boundary:

H == U + F + S, S >= 0

where S (surplus) is ugnot pushed to the realm address outside Deposit (e.g. a direct bank send). S stays 0 if all coins arrive via Deposit. Derivation from chain semantics: (1) a MsgCall `-send` envelope is transferred to the realm address BEFORE the call body runs, and Deposit's IsUserCall guard is exactly the case where that receipt is guaranteed, so Deposit raises U+F by the amount already added to H; (2) Claim/WithdrawFees debit the ledger first, then move the identical amount out via a RealmSend banker, lowering H and U+F equally; (3) any panic aborts the whole transaction, reverting ledger and coin movements together (atomicity); (4) this realm never uses IssueCoin/RemoveCoin. Surplus is intentionally unreachable: it can only be swept by the fee recipient via SweepSurplus, never counted as a user balance.

ONLY GNOT: Deposit rejects any transaction whose send envelope is not exactly one ugnot coin. Other assets force-sent to the realm address are not accepted, not tracked, and sit in surplus.

Imports

• chain
• chain/banker
• chain/runtime/unsafe
• gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/feeledger
• strconv

Constants and variables

Denom is the only asset this vault accepts.

const Denom = "ugnot"

MaxFeeBps is the hard protocol-fee cap: 1000 bps = 10%. Nobody can configure a higher fee; changing this requires deploying a new realm.

const MaxFeeBps = int64(1000)

Functions

BalanceOf

func BalanceOf(addr address) int64

BalanceOf returns addr's claimable balance.

Claim

func Claim(cur realm, amount int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Claim(cross(cur), ...).

Claim sends amount ugnot of the caller's balance back to the caller. Fails if amount is not positive or exceeds the caller's balance.

ClaimAll

func ClaimAll(cur realm)

Crossing function. Callable from a transaction via MsgCall, and from another realm as ClaimAll(cross(cur), ...).

ClaimAll sends the caller's entire balance back to the caller. Fails if the caller has no balance.

Deposit

func Deposit(cur realm)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Deposit(cross(cur), ...).

Deposit credits the caller with the attached GNOT minus the current protocol fee. Only direct EOA calls (maketx call with -send) are accepted: that is the only shape where the chain guarantees the send envelope landed at this realm's address before the body runs. The envelope must be exactly one coin of denom ugnot with positive amount.

FeeBps

func FeeBps() int64

FeeBps returns the protocol fee applied to future deposits, in basis points of the deposit amount.

FeeOn

func FeeOn(amount int64) (fee, credited int64)

FeeOn previews the fee and credited amount for a deposit of amount at the CURRENT FeeBps.

FeesAccrued

func FeesAccrued() int64

FeesAccrued returns the fee pot awaiting withdrawal.

Held

func Held() int64

Held returns the ugnot actually held at the realm address.

Liabilities

func Liabilities() int64

Liabilities returns UsersTotal() + FeesAccrued().

Render

func Render(_ string) string

Render shows configuration, totals, and the live conservation check.

SetFeeBps

func SetFeeBps(cur realm, bps int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as SetFeeBps(cross(cur), ...).

SetFeeBps sets the protocol fee for FUTURE deposits. Admin only; bounded by [0, MaxFeeBps].

SetFeeRecipient

func SetFeeRecipient(cur realm, next address)

Crossing function. Callable from a transaction via MsgCall, and from another realm as SetFeeRecipient(cross(cur), ...).

SetFeeRecipient re-points who may withdraw the fee pot (including fees accrued before the change) and sweep surplus. Admin only; the zero address is rejected.

Surplus

func Surplus() int64

Surplus returns Held() - Liabilities(): ugnot at the realm address that the ledger does not owe to anyone. Negative would indicate a conservation bug (see the invariant in the package doc).

SweepDenom

func SweepDenom(cur realm, denom string)

Crossing function. Callable from a transaction via MsgCall, and from another realm as SweepDenom(cross(cur), ...).

SweepDenom sends the surplus of a single denomination to the fee recipient. This is the bounded escape hatch for when SweepSurplus would exceed gas because a third party force-sent many junk denominations to the realm address: each call touches exactly one denomination, so ugnot surplus can always be recovered regardless of how many foreign denoms accumulate. For ugnot only the excess over Liabilities() moves; any other denom moves wholly. Only the fee recipient may call it.

SweepSurplus

func SweepSurplus(cur realm)

Crossing function. Callable from a transaction via MsgCall, and from another realm as SweepSurplus(cross(cur), ...).

SweepSurplus sends coins that sit at the realm address ABOVE the ledger's liabilities (ugnot force-sent outside Deposit, or any other denomination) to the fee recipient. Only the fee recipient may call it. User balances and the fee pot are untouchable by construction: only the excess over Liabilities() moves. Fails if there is no surplus.

TransferAdmin

func TransferAdmin(cur realm, next address)

Crossing function. Callable from a transaction via MsgCall, and from another realm as TransferAdmin(cross(cur), ...).

TransferAdmin hands the admin role to next. Admin only; the zero address is rejected. One-step: a transfer to a wrong-but-valid address permanently loses fee administration (deposits and claims keep working).

UsersTotal

func UsersTotal() int64

UsersTotal returns the sum of all user balances.

WithdrawFees

func WithdrawFees(cur realm)

Crossing function. Callable from a transaction via MsgCall, and from another realm as WithdrawFees(cross(cur), ...).

WithdrawFees sends the entire accrued fee pot to the fee recipient. Only the fee recipient may call it. Fails if the pot is empty.

---

Doc text is reproduced as vm/qdoc returns it. The node markdown-escapes doc comments, so a bracket or angle bracket may carry a backslash the committed source does not have. The source itself is at source and in this repository.