const BpsDenominator
BpsDenominator is the fee basis: fees are bps/BpsDenominator of the deposited amount.
feeledger source pure
Package feeledger is a pure accounting primitive for realms that hold coins on behalf of users and charge an explicit...
Package feeledger is a pure accounting primitive for realms that hold coins on behalf of users and charge an explicit protocol fee on deposits. It tracks per-account balances, the sum of user liabilities, and a separately-accrued fee pot. It never touches coins itself: the importing realm moves coins and drives this ledger, keeping the two in lock-step so that
Example
1coins held by realm == UsersTotal() + FeesAccrued() + surplus
where surplus is coins pushed to the realm outside the ledger's flow (always >= 0, and 0 if every coin movement goes through the ledger).
Fee model:
- Fees are expressed in basis points (1 bps = 0.01%); BpsDenominator is 10000, so bps == 10000 means the whole deposit is fee.
- fee = floor(amount * bps / 10000). Rounding always favors the DEPOSITOR: any fractional fee is dropped, the account is credited amount - fee. A small deposit may therefore pay zero fee.
- There is no minimum fee. The maximum fee is bounded by the per-ledger cap set at construction (maxFeeBps <= 10000), so a fee can never exceed its deposit.
- bps == 0 is a valid configuration: fee is exactly 0 and the full amount is credited.
All failures are returned as errors and leave the ledger COMPLETELY UNCHANGED; callers in realms typically wrap calls so an error panics and aborts the transaction. Must* wrappers are provided and are the only functions in this package that panic.
The ledger is address-agnostic: accounts are non-empty strings. Realms normally use address.String().
1
1
var ErrEmptyAccount, ErrInvalidAmount, ErrInvalidBps, ErrInsufficient, ErrOverflow
1var (
2 ErrEmptyAccount = errors.New("feeledger: empty account key")
3 ErrInvalidAmount = errors.New("feeledger: amount must be positive")
4 ErrInvalidBps = errors.New("feeledger: fee bps out of range")
5 ErrInsufficient = errors.New("feeledger: insufficient balance")
6 ErrOverflow = errors.New("feeledger: int64 overflow")
7)Errors returned by Ledger operations.
3
func FeeFor
FeeFor returns the fee charged on amount at bps, using the ledger's rounding rule: floor(amount * bps / BpsDenominator). It is a pure preview — no state is read or written beyond validation against BpsDenominator (NOT the ledger cap; use it to inspect any policy). amount must be >= 0 and bps in [0, BpsDenominator].
func MustNew
MustNew is New but panics on error.
func New
New returns an empty ledger that rejects deposit fees above maxFeeBps. maxFeeBps must be in [0, BpsDenominator].
1
type Ledger
structLedger tracks per-account balances, their sum (user liabilities), and separately-accrued protocol fees. The zero value is not usable; construct with New.
Methods on Ledger
func Accounts
method on LedgerAccounts returns the number of accounts with a non-zero balance.
func BalanceOf
method on LedgerBalanceOf returns account's balance, or 0 if absent.
func Deposit
method on Ledger1func (l *Ledger) Deposit(account string, amount, feeBps int64) (credited, fee int64, err error)Deposit credits account with amount minus the fee at feeBps, accruing the fee to the fee pot. Returns the credited amount and the fee (credited + fee == amount always). Fails with ErrEmptyAccount, ErrInvalidAmount (amount <= 0), ErrInvalidBps (feeBps outside [0, MaxFeeBps]), or ErrOverflow if the account balance or total liabilities would leave int64 range. On error nothing is modified.
func FeesAccrued
method on LedgerFeesAccrued returns the fee pot: charged but not yet withdrawn.
func Iterate
method on LedgerIterate calls fn for each account in sorted order with its balance. Iteration stops early when fn returns true.
func Liabilities
method on LedgerLiabilities returns UsersTotal() + FeesAccrued() — everything the importing realm owes. Deposit guarantees this sum fits in int64.
func MaxFeeBps
method on LedgerMaxFeeBps returns the ledger's hard fee cap.
func MustDeposit
method on LedgerMustDeposit is Deposit but panics on error.
func MustWithdraw
method on LedgerMustWithdraw is Withdraw but panics on error.
func UsersTotal
method on LedgerUsersTotal returns the sum of all account balances (user liabilities).
func Withdraw
method on LedgerWithdraw debits amount from account. Fails with ErrEmptyAccount, ErrInvalidAmount (amount <= 0), or ErrInsufficient if the balance is smaller than amount. A balance drained to zero is removed from storage. On error nothing is modified.
func WithdrawAll
method on LedgerWithdrawAll drains account's entire balance and returns it. Returns (0, nil) if the account holds nothing. Fails only with ErrEmptyAccount.
func WithdrawFees
method on LedgerWithdrawFees drains the accrued fee pot and returns the amount (0 if nothing has accrued). Never fails.
2
- errors stdlib
- gno.land/p/nt/avl/v0 package
