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