fee_split.gno
20.58 Kb · 659 lines
1package fee_split
2
3import (
4 "chain"
5 "chain/banker"
6 "chain/runtime/unsafe"
7 "sort"
8 "strconv"
9 "strings"
10)
11
12// Split holds a fee-splitting configuration with percentage-based shares
13// denominated in basis points (1 bp = 0.01%, 10000 bp = 100%).
14type Split struct {
15 Owner address
16 PendingOwner address // two-step handover, must AcceptOwnership
17 Recipients []address
18 Shares []int64 // basis points, must sum to 10000
19 Balances map[address]int64
20 TotalDeposited int64
21 TotalClaimed int64
22 Frozen bool
23 Archived bool
24}
25
26const (
27 MaxRecipients = 20
28 MaxSplitsPerOwner = 10
29 // Quotas are PER-OWNER only (round-4 audit): a global cap is a shared
30 // resource 50 sybil accounts could fill forever — and seeding grief
31 // splits with balances to keyless recipients made the fill
32 // unrecoverable even by the sybils. Per-owner quotas mean an attacker
33 // consumes only their own budget; state growth is gas-priced.
34 // Render is bounded separately (MaxRenderSplits).
35 MaxRenderSplits = 100
36 // MaxFeeBps is an IMMUTABLE ceiling on the protocol fee (1%). The
37 // admin can set any fee from 0 up to this cap, never above it — the
38 // cap, not the current setting, is what users must trust.
39 MaxFeeBps = int64(100)
40
41 // Pre-parse input bounds (round-4 audit): caps were enforced only
42 // AFTER full parsing, so a 1MB recipient list burned ~11B gas before
43 // refusal. 20 bech32 addresses + separators fit well within these.
44 MaxRecipientListLen = 1024
45 MaxShareListLen = 128
46
47 // Denomination handled by this realm. Deposits must be exactly one
48 // coin of this denom; claims pay out in it.
49 Denom = "ugnot"
50
51 // Largest single deposit for which share math (amount * share,
52 // share <= 10000) cannot overflow int64.
53 MaxDepositAmount = int64(9223372036854775807) / 10000
54)
55
56var (
57 splits map[string]*Split
58 splitIDs []string // insertion-ordered for deterministic Render
59 ownerSplits map[address]int
60 nextID int
61
62 // Protocol fee: taken from each deposit BEFORE distribution, at the
63 // rate in force at deposit time (never retroactive — credited
64 // balances are never touched). Defaults to zero.
65 feeBps int64
66 feeAdmin address // deployer; can set the fee and claim accrued fees
67 pendingFeeAdmin address // two-step handover, must AcceptFeeAdmin
68 feesAccrued int64
69 feesClaimed int64
70)
71
72func init() {
73 splits = make(map[string]*Split)
74 splitIDs = []string{}
75 ownerSplits = make(map[address]int)
76 nextID = 1
77 // The package deployer becomes the fee admin: on-chain, AddPackage
78 // runs init with the message creator as origin caller (verified
79 // against the VM keeper — a MsgAddPackage's creator is never zero).
80 // If OriginCaller() were ever empty (e.g. the gno test VM, which has
81 // no MsgAddPackage), the fee feature degrades SAFELY to disabled:
82 // SetFee requires the runtime-derived caller to equal feeAdmin and
83 // that caller is never empty, so
84 // feeBps can never leave 0 and no fee ever accrues — zero funds at
85 // risk. Do not "harden" this into a panic; the soft-disable is the
86 // safe behavior. Fee starts at ZERO regardless.
87 feeAdmin = unsafe.OriginCaller()
88 feeBps = 0
89}
90
91// ---------- helpers ----------
92
93func formatPct(bp int64) string {
94 whole := strconv.FormatInt(bp/100, 10)
95 frac := strconv.FormatInt(bp%100, 10)
96 if len(frac) == 1 {
97 frac = "0" + frac
98 }
99 return whole + "." + frac + "%"
100}
101
102func mustGetSplit(id string) *Split {
103 s, ok := splits[id]
104 if !ok {
105 panic("split not found: " + id)
106 }
107 return s
108}
109
110func mustGetActive(id string) *Split {
111 s := mustGetSplit(id)
112 if s.Archived {
113 panic("split is archived: " + id)
114 }
115 return s
116}
117
118func boolStr(v bool) string {
119 if v {
120 return "yes"
121 }
122 return "no"
123}
124
125func parseBasisPoints(raw string) []int64 {
126 if len(raw) > MaxShareListLen {
127 panic("share list too long")
128 }
129 parts := strings.Split(raw, ",")
130 out := make([]int64, len(parts))
131 var total int64
132 for i, s := range parts {
133 v, err := strconv.Atoi(strings.TrimSpace(s))
134 if err != nil || v <= 0 || v > 10000 {
135 // the upper bound is a security invariant, not hygiene: unbounded
136 // shares let the int64 total wrap back to exactly 10000, minting
137 // unbacked balances paid from the shared pool (re-audit P1)
138 panic("invalid share value: " + strings.TrimSpace(s))
139 }
140 out[i] = int64(v)
141 total += int64(v)
142 }
143 if total != 10000 {
144 panic("shares must sum to 10000 basis points, got " + strconv.FormatInt(total, 10))
145 }
146 return out
147}
148
149func parseAddresses(raw string) []address {
150 if len(raw) > MaxRecipientListLen {
151 panic("recipient list too long")
152 }
153 parts := strings.Split(raw, ",")
154 out := make([]address, len(parts))
155 for i, r := range parts {
156 a := address(strings.TrimSpace(r))
157 if a == "" {
158 panic("empty recipient address at position " + strconv.Itoa(i))
159 }
160 if !a.IsValid() || string(a) != strings.ToLower(string(a)) {
161 // lowercase is required, not cosmetic (round-3 audit): bech32
162 // accepts ALL-UPPERCASE as valid, but the runtime always returns
163 // the lowercase canonical form — an uppercase-keyed balance
164 // could never be claimed and would block Archive forever, and
165 // upper/lower duplicates would bypass the duplicate check
166 panic("invalid recipient address: " + string(a))
167 }
168 // NOTE: IsValid is a format check only — a well-formed address with
169 // no key holder (e.g. another package's derived address) will
170 // accumulate a balance nobody can claim, which also blocks Archive
171 // forever. Owners must list addresses they know can call Claim.
172 out[i] = a
173 }
174 return out
175}
176
177func validateRecipients(recipients []address, shares []int64) {
178 if len(recipients) != len(shares) {
179 panic("recipients and shares must have the same length")
180 }
181 if len(recipients) == 0 {
182 panic("at least one recipient is required")
183 }
184 if len(recipients) > MaxRecipients {
185 panic("too many recipients (max " + strconv.Itoa(MaxRecipients) + ")")
186 }
187 seen := make(map[address]bool)
188 for _, r := range recipients {
189 if seen[r] {
190 panic("duplicate recipient: " + string(r))
191 }
192 seen[r] = true
193 }
194}
195
196// sortedBalanceAddrs returns the balance-map keys in deterministic order,
197// so panics and renders never depend on map iteration order.
198func sortedBalanceAddrs(s *Split) []string {
199 addrs := make([]string, 0, len(s.Balances))
200 for a := range s.Balances {
201 addrs = append(addrs, string(a))
202 }
203 sort.Strings(addrs)
204 return addrs
205}
206
207// rejectStraySend aborts when coins are attached to a call that does not
208// accept them — the abort reverts the transfer back to the sender instead
209// of stranding the coins on the realm address (re-audit P3). Direct bank
210// transfers to the realm address remain unrecoverable by design.
211func rejectStraySend(cur realm) {
212 if !cur.IsCurrent() {
213 // every call site passes the entrypoint's own first cur; this
214 // pins that discipline against future call-site drift (v2
215 // audit G3 hardening)
216 panic("realm capability is not current")
217 }
218 if cur.Previous().IsUserCall() && len(unsafe.OriginSend()) > 0 {
219 panic("this function does not accept coins; attach coins to Deposit only")
220 }
221}
222
223// ---------- write operations ----------
224
225// CreateSplit registers a new split. The caller becomes the owner.
226// Recipients and shares are comma-separated; shares are in basis points
227// summing to 10000.
228func CreateSplit(cur realm, recipientList, shareList string) string {
229 rejectStraySend(cur)
230 owner := cur.Previous().Address()
231 if ownerSplits[owner] >= MaxSplitsPerOwner {
232 panic("per-owner split limit reached")
233 }
234
235 recipients := parseAddresses(recipientList)
236 shares := parseBasisPoints(shareList)
237 validateRecipients(recipients, shares)
238
239 id := "split_" + strconv.Itoa(nextID)
240 nextID++
241
242 balances := make(map[address]int64)
243 for _, r := range recipients {
244 balances[r] = 0
245 }
246
247 splits[id] = &Split{
248 Owner: owner,
249 Recipients: recipients,
250 Shares: shares,
251 Balances: balances,
252 }
253 splitIDs = append(splitIDs, id)
254 ownerSplits[owner]++
255 return id
256}
257
258// Deposit distributes the coins sent with the call across recipients
259// proportionally.
260//
261// DEPLOYMENT PRECONDITION (round-4 audit): on a network with
262// restricted/token-locked ugnot transfers, the bank gate is
263// SENDER-whitelist-based — a whitelisted user's Deposit succeeds but
264// Claim sends FROM this realm's (non-whitelisted) address and reverts.
265// Funds would flow in and not out until the restriction lifts. Deploy
266// only to networks with unrestricted ugnot, or have governance
267// whitelist this realm's address first.
268//
269// LIMITATION (round-3 audit, documented): only direct user calls can
270// deposit. A DAO/realm treasury has NO deposit path — a realm-routed
271// call is refused, and a bare banker send to this realm's address is
272// an unrecoverable donation. Realm treasuries must route deposits
273// through a user account. The deposit is the ACTUAL attached send — exactly one
274// coin of Denom — so balances are always backed by funds this realm
275// holds. Direct user calls only: a deposit routed through an
276// intermediary realm would deliver its coins to that realm, not here,
277// and must be rejected. Rounding dust goes to the highest-share
278// recipient (deterministic, not order-dependent).
279func Deposit(cur realm, splitID string) {
280 s := mustGetActive(splitID)
281 if s.Frozen {
282 panic("split is frozen")
283 }
284
285 // IsUserCall, not IsUser: MsgRun passes IsUser but its attached send
286 // goes caller->caller — the coins never reach this realm, and OriginSend
287 // could be re-read across k calls in one run script (re-audit P1). A
288 // direct MsgCall's send provably lands on the called package address.
289 if !cur.Previous().IsUserCall() {
290 panic("deposits must be sent by direct call, not through another realm or a run script")
291 }
292 sent := unsafe.OriginSend()
293 if len(sent) != 1 || sent[0].Denom != Denom {
294 panic("deposit must send exactly one coin of " + Denom)
295 }
296 amount := sent[0].Amount
297 if amount <= 0 {
298 panic("amount must be greater than zero")
299 }
300 if amount > MaxDepositAmount {
301 panic("deposit exceeds maximum supported amount")
302 }
303 if s.TotalDeposited > int64(9223372036854775807)-amount {
304 panic("deposit would overflow split accounting")
305 }
306
307 // Protocol fee comes off the top; everything below distributes the
308 // NET amount, so the per-split conservation invariant
309 // (sum(balances)+TotalClaimed == TotalDeposited) is untouched.
310 // amount <= MaxDepositAmount and feeBps <= 100, so the product is
311 // far below overflow.
312 fee := (amount * feeBps) / 10000
313 if fee > 0 {
314 if feesAccrued > int64(9223372036854775807)-fee {
315 panic("fee accrual would overflow")
316 }
317 feesAccrued += fee
318 amount -= fee
319 }
320 if amount == 0 {
321 panic("deposit too small: fully consumed by the protocol fee")
322 }
323
324 s.TotalDeposited += amount
325
326 // Find the highest-share recipient for dust assignment
327 dustIdx := 0
328 for i := 1; i < len(s.Shares); i++ {
329 if s.Shares[i] > s.Shares[dustIdx] {
330 dustIdx = i
331 }
332 }
333
334 var distributed int64
335 for i, r := range s.Recipients {
336 share := (amount * s.Shares[i]) / 10000
337 s.Balances[r] += share
338 distributed += share
339 }
340
341 // Assign dust to highest-share recipient
342 dust := amount - distributed
343 if dust > 0 {
344 s.Balances[s.Recipients[dustIdx]] += dust
345 }
346}
347
348// Claim withdraws the caller's accumulated balance and SENDS the coins
349// to the caller's address. Balance is zeroed before the transfer.
350// Claims remain possible on frozen splits, and by ex-recipients whose
351// accrued balance predates a share update.
352func Claim(cur realm, splitID string) int64 {
353 rejectStraySend(cur)
354 s := mustGetActive(splitID)
355 addr := cur.Previous().Address()
356
357 bal, exists := s.Balances[addr]
358 if !exists {
359 panic("not a recipient of this split")
360 }
361 if bal == 0 {
362 panic("nothing to claim")
363 }
364
365 s.Balances[addr] = 0
366 s.TotalClaimed += bal
367
368 b := banker.NewBanker(banker.BankerTypeRealmSend, cur)
369 b.SendCoins(cur.Address(), addr,
370 chain.Coins{{Denom: Denom, Amount: bal}})
371 return bal
372}
373
374// UpdateShares replaces recipients and shares. Owner only. Not if frozen.
375// Removed recipients keep any accrued balance and can still Claim it.
376func UpdateShares(cur realm, splitID, recipientList, shareList string) {
377 rejectStraySend(cur)
378 s := mustGetActive(splitID)
379 if cur.Previous().Address() != s.Owner {
380 panic("only the owner can update shares")
381 }
382 if s.Frozen {
383 panic("split is frozen")
384 }
385
386 recipients := parseAddresses(recipientList)
387 shares := parseBasisPoints(shareList)
388 validateRecipients(recipients, shares)
389
390 for _, r := range recipients {
391 if _, ok := s.Balances[r]; !ok {
392 s.Balances[r] = 0
393 }
394 }
395
396 s.Recipients = recipients
397 s.Shares = shares
398}
399
400// TransferOwnership stages a two-step ownership handover; nothing
401// moves until the nominee calls AcceptOwnership. Two-step for the same
402// reason as the fee admin, plus one more (v2 audit Y1): a one-step
403// transfer consumed the RECIPIENT's per-owner quota without consent,
404// so poisoned splits could burn a victim's slots unarchivably. Staging
405// consumes nothing of the nominee's. Pass "" to clear a pending
406// nomination.
407func TransferOwnership(cur realm, splitID string, newOwner address) {
408 rejectStraySend(cur)
409 s := mustGetActive(splitID)
410 if cur.Previous().Address() != s.Owner {
411 panic("only the owner can transfer ownership")
412 }
413 if newOwner == "" {
414 s.PendingOwner = ""
415 return
416 }
417 if !newOwner.IsValid() || string(newOwner) != strings.ToLower(string(newOwner)) {
418 // see parseAddresses: an uppercase owner could never match the
419 // runtime-derived caller again — the split would be owner-less
420 panic("invalid new owner address: " + string(newOwner))
421 }
422 if newOwner == s.Owner {
423 panic("new owner is already the owner")
424 }
425 s.PendingOwner = newOwner
426}
427
428// AcceptOwnership completes the handover; only the nominee can accept.
429// The nominee's quota is checked HERE, at consent time — the split
430// slot moves only with the acceptor's own signature (v2 audit Y1: a
431// recipient's quota is never consumed without consent). A nomination
432// on a split that is later archived is inert (mustGetActive).
433func AcceptOwnership(cur realm, splitID string) {
434 rejectStraySend(cur)
435 s := mustGetActive(splitID)
436 caller := cur.Previous().Address()
437 if s.PendingOwner == "" || caller != s.PendingOwner {
438 panic("caller is not the pending owner")
439 }
440 if ownerSplits[caller] >= MaxSplitsPerOwner {
441 panic("new owner is at the per-owner split limit")
442 }
443
444 ownerSplits[s.Owner]--
445 if ownerSplits[s.Owner] <= 0 {
446 delete(ownerSplits, s.Owner)
447 }
448 ownerSplits[caller]++
449 s.Owner = caller
450 s.PendingOwner = ""
451}
452
453// Freeze permanently locks shares and stops further deposits. One-way,
454// cannot be undone. Claims remain possible.
455func Freeze(cur realm, splitID string) {
456 rejectStraySend(cur)
457 s := mustGetActive(splitID)
458 if cur.Previous().Address() != s.Owner {
459 panic("only the owner can freeze")
460 }
461 s.Frozen = true
462}
463
464// Archive marks a fully-claimed split as archived. Only the owner can
465// archive, and only if EVERY balance — including balances held by
466// ex-recipients removed in a share update — is zero, since archiving
467// blocks all further claims. Cannot be undone.
468func Archive(cur realm, splitID string) {
469 rejectStraySend(cur)
470 s := mustGetActive(splitID)
471 if cur.Previous().Address() != s.Owner {
472 panic("only the owner can archive")
473 }
474
475 for _, a := range sortedBalanceAddrs(s) {
476 if s.Balances[address(a)] > 0 {
477 panic("cannot archive: outstanding balance for " + a)
478 }
479 }
480
481 s.Archived = true
482
483 // Free the owner's slot so they can create new splits
484 ownerSplits[s.Owner]--
485 if ownerSplits[s.Owner] <= 0 {
486 delete(ownerSplits, s.Owner)
487 }
488
489 // Remove from active ID list (keeps map entry for audit)
490 for i, id := range splitIDs {
491 if id == splitID {
492 splitIDs = append(splitIDs[:i], splitIDs[i+1:]...)
493 break
494 }
495 }
496}
497
498// ---------- protocol fee ----------
499
500// SetFee sets the protocol fee in basis points, admin only, hard-capped
501// at MaxFeeBps. Applies to FUTURE deposits only.
502func SetFee(cur realm, bps int64) {
503 rejectStraySend(cur)
504 if cur.Previous().Address() != feeAdmin {
505 panic("only the fee admin can set the fee")
506 }
507 if bps < 0 || bps > MaxFeeBps {
508 panic("fee must be between 0 and " + strconv.FormatInt(MaxFeeBps, 10) + " basis points")
509 }
510 feeBps = bps
511}
512
513// ClaimFees sends all accrued protocol fees to the fee admin.
514func ClaimFees(cur realm) int64 {
515 rejectStraySend(cur)
516 if cur.Previous().Address() != feeAdmin {
517 panic("only the fee admin can claim fees")
518 }
519 if feesAccrued == 0 {
520 panic("no fees accrued")
521 }
522 amount := feesAccrued
523 feesAccrued = 0
524 feesClaimed += amount
525
526 b := banker.NewBanker(banker.BankerTypeRealmSend, cur)
527 b.SendCoins(cur.Address(), feeAdmin,
528 chain.Coins{{Denom: Denom, Amount: amount}})
529 return amount
530}
531
532// NominateFeeAdmin begins a two-step admin handover; the nominee must
533// AcceptFeeAdmin. Pass "" to clear a pending nomination. Two-step
534// because the admin address is a funds destination: a typo'd one-step
535// transfer would strand all future fees.
536func NominateFeeAdmin(cur realm, nominee address) {
537 rejectStraySend(cur)
538 if cur.Previous().Address() != feeAdmin {
539 panic("only the fee admin can nominate a successor")
540 }
541 if nominee == "" {
542 pendingFeeAdmin = ""
543 return
544 }
545 if !nominee.IsValid() || string(nominee) != strings.ToLower(string(nominee)) {
546 panic("invalid nominee address: " + string(nominee))
547 }
548 pendingFeeAdmin = nominee
549}
550
551// AcceptFeeAdmin completes the handover; only the nominee can accept.
552func AcceptFeeAdmin(cur realm) {
553 rejectStraySend(cur)
554 if pendingFeeAdmin == "" || cur.Previous().Address() != pendingFeeAdmin {
555 panic("caller is not the pending fee admin")
556 }
557 feeAdmin = pendingFeeAdmin
558 pendingFeeAdmin = ""
559}
560
561// GetFeeInfo returns the current fee configuration and accrued total.
562func GetFeeInfo() string {
563 return "fee: " + formatPct(feeBps) + " (cap " + formatPct(MaxFeeBps) +
564 ") | admin: " + string(feeAdmin) +
565 " | accrued: " + strconv.FormatInt(feesAccrued, 10) +
566 " | claimed: " + strconv.FormatInt(feesClaimed, 10)
567}
568
569// ---------- read-only queries ----------
570
571// GetSplitInfo returns a human-readable summary.
572func GetSplitInfo(splitID string) string {
573 s := mustGetSplit(splitID)
574
575 var b strings.Builder
576 b.WriteString("Split: " + splitID + "\n")
577 b.WriteString("Owner: " + string(s.Owner) + "\n")
578 if s.PendingOwner != "" {
579 // a nominee must be able to READ the offer before spending gas
580 // probing it with AcceptOwnership (v2 audit Y1-obs)
581 b.WriteString("Pending owner: " + string(s.PendingOwner) + "\n")
582 }
583 b.WriteString("Frozen: " + boolStr(s.Frozen) + "\n")
584 b.WriteString("Archived: " + boolStr(s.Archived) + "\n")
585 b.WriteString("Total deposited: " + strconv.FormatInt(s.TotalDeposited, 10) + "\n")
586 b.WriteString("Total claimed: " + strconv.FormatInt(s.TotalClaimed, 10) + "\n")
587 b.WriteString("Recipients:\n")
588 for i, r := range s.Recipients {
589 b.WriteString(" " + string(r) + " " + formatPct(s.Shares[i]) + " claimable: " + strconv.FormatInt(s.Balances[r], 10) + "\n")
590 }
591 return b.String()
592}
593
594// GetPendingOwner returns the staged nominee for a split, or "" when no
595// handover is pending. The consent half of a two-step transfer only means
596// something if the nominee can inspect the offer without paying gas to
597// probe it (v2 audit Y1-obs); this is that read path.
598func GetPendingOwner(splitID string) string {
599 return string(mustGetSplit(splitID).PendingOwner)
600}
601
602// GetClaimable returns claimable balance for an address.
603func GetClaimable(splitID string, addr address) int64 {
604 s := mustGetSplit(splitID)
605 return s.Balances[addr]
606}
607
608// ---------- render ----------
609
610// Render returns a markdown overview. Never panics.
611func Render(path string) string {
612 if len(splitIDs) == 0 {
613 return "# Fee Split\n\nNo active splits.\n"
614 }
615
616 var b strings.Builder
617 b.WriteString("# Fee Split\n\n")
618 if feeBps > 0 {
619 b.WriteString("**Protocol fee:** " + formatPct(feeBps) + " (hard cap " + formatPct(MaxFeeBps) + ")\n\n")
620 }
621
622 show := splitIDs
623 if len(show) > MaxRenderSplits {
624 b.WriteString("_Showing the most recent " + strconv.Itoa(MaxRenderSplits) + " active splits._\n\n")
625 show = show[len(show)-MaxRenderSplits:]
626 }
627 for _, id := range show {
628 s := splits[id]
629 b.WriteString("## " + id + "\n\n")
630 if s == nil {
631 b.WriteString("_(invalid)_\n\n")
632 continue
633 }
634 b.WriteString("```\n")
635 b.WriteString("Owner: " + string(s.Owner) + "\n")
636 if s.PendingOwner != "" {
637 b.WriteString("Pending owner: " + string(s.PendingOwner) + "\n")
638 }
639 b.WriteString("Frozen: " + boolStr(s.Frozen) + "\n")
640 b.WriteString("Total deposited: " + strconv.FormatInt(s.TotalDeposited, 10) + "\n")
641 b.WriteString("Total claimed: " + strconv.FormatInt(s.TotalClaimed, 10) + "\n")
642 if len(s.Recipients) > 0 {
643 b.WriteString("Recipients:\n")
644 for i, r := range s.Recipients {
645 share := "??%"
646 if i < len(s.Shares) {
647 share = formatPct(s.Shares[i])
648 }
649 bal := "0"
650 if s.Balances != nil {
651 bal = strconv.FormatInt(s.Balances[r], 10)
652 }
653 b.WriteString(" " + string(r) + " " + share + " claimable: " + bal + "\n")
654 }
655 }
656 b.WriteString("```\n\n")
657 }
658 return b.String()
659}
