vault package

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:

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.

Functions

BalanceOf


              func BalanceOf(addr address) int64

BalanceOf returns addr's claimable balance.

Command

gnokey query vm/qeval -remote "https://rpc.pearl.testnets.gno.land" -data "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault.BalanceOf()"

Result

Claim


              func Claim(cur realm, amount int64)

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.

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "Claim" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "pearl-1" -remote "https://rpc.pearl.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.pearl.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "Claim" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "pearl-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.pearl.testnets.gno.land" call.tx

ClaimAll


              func ClaimAll(cur realm)

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

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "ClaimAll" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "pearl-1" -remote "https://rpc.pearl.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.pearl.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "ClaimAll" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "pearl-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.pearl.testnets.gno.land" call.tx

Deposit


              func Deposit(cur realm)

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.

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "Deposit" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "pearl-1" -remote "https://rpc.pearl.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.pearl.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "Deposit" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "pearl-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.pearl.testnets.gno.land" call.tx

FeeBps


              func FeeBps() int64

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

Command

gnokey query vm/qeval -remote "https://rpc.pearl.testnets.gno.land" -data "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault.FeeBps()"

Result

FeeOn


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

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

Command

gnokey query vm/qeval -remote "https://rpc.pearl.testnets.gno.land" -data "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault.FeeOn()"

Result

FeesAccrued


              func FeesAccrued() int64

FeesAccrued returns the fee pot awaiting withdrawal.

Command

gnokey query vm/qeval -remote "https://rpc.pearl.testnets.gno.land" -data "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault.FeesAccrued()"

Result

Held


              func Held() int64

Held returns the ugnot actually held at the realm address.

Command

gnokey query vm/qeval -remote "https://rpc.pearl.testnets.gno.land" -data "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault.Held()"

Result

Liabilities


              func Liabilities() int64

Liabilities returns UsersTotal() + FeesAccrued().

Command

gnokey query vm/qeval -remote "https://rpc.pearl.testnets.gno.land" -data "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault.Liabilities()"

Result

Render


              func Render(_ string) string

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

Command

gnokey query vm/qeval -remote "https://rpc.pearl.testnets.gno.land" -data "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault.Render()"

Result

SetFeeBps


              func SetFeeBps(cur realm, bps int64)

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

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "SetFeeBps" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "pearl-1" -remote "https://rpc.pearl.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.pearl.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "SetFeeBps" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "pearl-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.pearl.testnets.gno.land" call.tx

SetFeeRecipient


              func SetFeeRecipient(cur realm, next address)

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.

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "SetFeeRecipient" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "pearl-1" -remote "https://rpc.pearl.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.pearl.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "SetFeeRecipient" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "pearl-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.pearl.testnets.gno.land" call.tx

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).

Command

gnokey query vm/qeval -remote "https://rpc.pearl.testnets.gno.land" -data "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault.Surplus()"

Result

SweepDenom


              func SweepDenom(cur realm, denom string)

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.

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "SweepDenom" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "pearl-1" -remote "https://rpc.pearl.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.pearl.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "SweepDenom" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "pearl-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.pearl.testnets.gno.land" call.tx

SweepSurplus


              func SweepSurplus(cur realm)

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.

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "SweepSurplus" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "pearl-1" -remote "https://rpc.pearl.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.pearl.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "SweepSurplus" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "pearl-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.pearl.testnets.gno.land" call.tx

TransferAdmin


              func TransferAdmin(cur realm, next address)

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).

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "TransferAdmin" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "pearl-1" -remote "https://rpc.pearl.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.pearl.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "TransferAdmin" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "pearl-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.pearl.testnets.gno.land" call.tx

UsersTotal


              func UsersTotal() int64

UsersTotal returns the sum of all user balances.

Command

gnokey query vm/qeval -remote "https://rpc.pearl.testnets.gno.land" -data "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault.UsersTotal()"

Result

WithdrawFees


              func WithdrawFees(cur realm)

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

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "WithdrawFees" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "pearl-1" -remote "https://rpc.pearl.testnets.gno.land" ADDRESSgnokey query -remote "https://rpc.pearl.testnets.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/vault" -func "WithdrawFees" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "pearl-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.pearl.testnets.gno.land" call.tx

Overview

Functions

Param

Command

Result

Param

Command

Command

Command

Command

Result

Param

Command

Result

Command

Result

Command

Result

Command

Result

Param

Command

Result

Param

Command

Param

Command

Command

Result

Param

Command

Command

Param

Command

Command

Result

Command