const Denom
Denom is the only asset this vault accepts.
vault source realm
Realm vault holds GNOT deposits with per-user balances and an explicit, inspectable protocol fee, built on gno.land/p...
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:
Example
1H == 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.
2
18
func BalanceOf
ActionBalanceOf returns addr's claimable balance.
func Claim
crossing ActionClaim sends amount ugnot of the caller's balance back to the caller. Fails if amount is not positive or exceeds the caller's balance.
func ClaimAll
crossing ActionClaimAll sends the caller's entire balance back to the caller. Fails if the caller has no balance.
func Deposit
crossing ActionDeposit 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.
func FeeBps
ActionFeeBps returns the protocol fee applied to future deposits, in basis points of the deposit amount.
func FeeOn
ActionFeeOn previews the fee and credited amount for a deposit of amount at the CURRENT FeeBps.
func FeesAccrued
ActionFeesAccrued returns the fee pot awaiting withdrawal.
func Held
ActionHeld returns the ugnot actually held at the realm address.
func Liabilities
ActionLiabilities returns UsersTotal() + FeesAccrued().
func Render
Render shows configuration, totals, and the live conservation check.
func SetFeeBps
crossing ActionSetFeeBps sets the protocol fee for FUTURE deposits. Admin only; bounded by [0, MaxFeeBps].
func SetFeeRecipient
crossing ActionSetFeeRecipient re-points who may withdraw the fee pot (including fees accrued before the change) and sweep surplus. Admin only; the zero address is rejected.
func Surplus
ActionSurplus 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).
func SweepDenom
crossing ActionSweepDenom 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.
func SweepSurplus
crossing ActionSweepSurplus 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.
func TransferAdmin
crossing ActionTransferAdmin 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).
func UsersTotal
ActionUsersTotal returns the sum of all user balances.
func WithdrawFees
crossing ActionWithdrawFees sends the entire accrued fee pot to the fee recipient. Only the fee recipient may call it. Fails if the pot is empty.
5
- chain stdlib
- chain/banker stdlib
- chain/runtime/unsafe stdlib
- gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/feeledger package
- strconv stdlib
