vault package

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:

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.