feeledger

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

Overview

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

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

Imports

• errors
• gno.land/p/nt/avl/v0

Constants and variables

BpsDenominator is the fee basis: fees are bps/BpsDenominator of the deposited amount.

const BpsDenominator = int64(10000)

Errors returned by Ledger operations.

var (
	ErrEmptyAccount  = errors.New("feeledger: empty account key")
	ErrInvalidAmount = errors.New("feeledger: amount must be positive")
	ErrInvalidBps    = errors.New("feeledger: fee bps out of range")
	ErrInsufficient  = errors.New("feeledger: insufficient balance")
	ErrOverflow      = errors.New("feeledger: int64 overflow")
)

Types

type Ledger

type Ledger struct {
	maxFeeBps   int64
	balances    *avl.Tree // account string -> int64 (always > 0)
	usersTotal  int64     // == sum of all balances
	feesAccrued int64     // fees charged but not yet withdrawn
}

Ledger tracks per-account balances, their sum (user liabilities), and separately-accrued protocol fees. The zero value is not usable; construct with New.

Ledger.Accounts

func (l *Ledger) Accounts() int

Accounts returns the number of accounts with a non-zero balance.

Ledger.BalanceOf

func (l *Ledger) BalanceOf(account string) int64

BalanceOf returns account's balance, or 0 if absent.

Ledger.Deposit

func (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.

Ledger.FeesAccrued

func (l *Ledger) FeesAccrued() int64

FeesAccrued returns the fee pot: charged but not yet withdrawn.

Ledger.Iterate

func (l *Ledger) Iterate(fn func(account string, balance int64) bool)

Iterate calls fn for each account in sorted order with its balance. Iteration stops early when fn returns true.

Ledger.Liabilities

func (l *Ledger) Liabilities() int64

Liabilities returns UsersTotal() + FeesAccrued() — everything the importing realm owes. Deposit guarantees this sum fits in int64.

Ledger.MaxFeeBps

func (l *Ledger) MaxFeeBps() int64

MaxFeeBps returns the ledger's hard fee cap.

Ledger.MustDeposit

func (l *Ledger) MustDeposit(account string, amount, feeBps int64) (credited, fee int64)

MustDeposit is Deposit but panics on error.

Ledger.MustWithdraw

func (l *Ledger) MustWithdraw(account string, amount int64)

MustWithdraw is Withdraw but panics on error.

Ledger.UsersTotal

func (l *Ledger) UsersTotal() int64

UsersTotal returns the sum of all account balances (user liabilities).

Ledger.Withdraw

func (l *Ledger) Withdraw(account string, amount int64) error

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

Ledger.WithdrawAll

func (l *Ledger) WithdrawAll(account string) (int64, error)

WithdrawAll drains account's entire balance and returns it. Returns (0, nil) if the account holds nothing. Fails only with ErrEmptyAccount.

Ledger.WithdrawFees

func (l *Ledger) WithdrawFees() int64

WithdrawFees drains the accrued fee pot and returns the amount (0 if nothing has accrued). Never fails.

Functions

FeeFor

func FeeFor(amount, bps int64) (int64, error)

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

MustNew

func MustNew(maxFeeBps int64) *Ledger

MustNew is New but panics on error.

New

func New(maxFeeBps int64) (*Ledger, error)

New returns an empty ledger that rejects deposit fees above maxFeeBps. maxFeeBps must be in [0, BpsDenominator].

---

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.