bounties

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

Overview

Realm bounties is a GNOT bounty board that COMPOSES the reusable accounting package gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/feeledger instead of re-implementing balance accounting.

STATE OWNERSHIP (the dependency boundary):

• This realm owns the bounty state machine: bounty records (funder, title, amount, status, winner), the sum of open escrow (openTotal), and per-bounty funder authorization.
• feeledger owns all claimable-balance accounting: per-account balances, the protocol-fee pot, fee rounding, overflow checks, and withdraw arithmetic. This realm never duplicates that logic; it only calls the ledger API and panics on its errors.

LIFECYCLE:

CreateBounty (EOA + -send) : escrow -> openTotal, status Open Award (funder only) : openTotal -> ledger.Deposit(winner, amount, snapshot fee) Cancel (funder only) : openTotal -> ledger.Deposit(funder, amount, 0) [no fee on refund] Claim / ClaimAll (anyone) : pays out the caller's ledger balance WithdrawFees (fee recipient): pays out the fee pot

Awarded and Cancelled are terminal; a bounty transitions exactly once.

FEE MODEL: fee = floor(amount * bps / 10000), rounding favors the recipient, no minimum fee, admin-settable up to the compile-time MaxFeeBps cap, accrued to a pot withdrawable by the fee recipient role. The applicable bps is SNAPSHOTTED INTO THE BOUNTY AT CREATION and charged at Award: the funder commits to the fee they saw, and a later SetFeeBps affects only bounties created afterwards (this closes the admin front-run found in the composition audit). Refunds via Cancel are always fee-free. A failed Award (e.g. ledger overflow) leaves the bounty Open — the funder can retry or Cancel.

COMPOSED ACCOUNTING INVARIANT: let H be ugnot held at this realm's address, B = openTotal (application escrow), U+F the ledger's liabilities, S >= 0 out-of-band surplus. At every transaction boundary:

H == B + U + F + S

Derivation: CreateBounty raises H and B equally (the IsUserCall + envelope guard is the receipt-guaranteed shape, validated live on pearl-1); Award/Cancel move amount from B into U+F within one transaction, and feeledger guarantees credited + fee == amount; Claim/WithdrawFees debit the ledger before sending the identical amount (checks-effects-interactions), lowering H and U+F equally; any panic aborts the whole transaction; this realm never issues or removes coins. The application invariant B == Σ amount(Open) is maintained in lockstep with every status transition.

ONLY GNOT: CreateBounty rejects any envelope that is not exactly one positive ugnot coin. Foreign denominations force-sent to the realm sit in surplus and are recoverable via SweepDenom (fee recipient only), which never touches B, U, or F.

Imports

• chain
• chain/banker
• chain/runtime/unsafe
• gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/feeledger
• gno.land/p/nt/avl/v0
• strconv

Constants and variables

Bounty status values.

const (
	StatusOpen      = "open"
	StatusAwarded   = "awarded"
	StatusCancelled = "cancelled"
)

Denom is the only asset this realm accepts.

const Denom = "ugnot"

MaxFeeBps is the hard protocol-fee cap: 1000 bps = 10%.

const MaxFeeBps = int64(1000)

Functions

Award

func Award(cur realm, id int64, winner address)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Award(cross(cur), ...).

Award closes an open bounty in favor of winner: the escrowed amount leaves the open pool and is credited to winner's claimable balance through the ledger, charging the fee snapshotted at creation. Only the bounty's funder may award it. Terminal: an awarded bounty can never change again.

BalanceOf

func BalanceOf(addr address) int64

BalanceOf returns addr's claimable balance (won bounties + refunds).

BountyInfo

func BountyInfo(id int64) (funder address, title string, amount, feeBps int64, status string, winner address)

BountyInfo returns a bounty's fields by value: funder, title, amount, snapshotted fee bps, status, winner (zero address unless awarded).

Cancel

func Cancel(cur realm, id int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Cancel(cross(cur), ...).

Cancel closes an open bounty and refunds its escrow to the funder's claimable balance, fee-free. Only the bounty's funder may cancel. Terminal: a cancelled bounty can never change again.

Claim

func Claim(cur realm, amount int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Claim(cross(cur), ...).

Claim sends amount ugnot of the caller's claimable balance (won bounties and refunds) back to the caller.

ClaimAll

func ClaimAll(cur realm)

Crossing function. Callable from a transaction via MsgCall, and from another realm as ClaimAll(cross(cur), ...).

ClaimAll sends the caller's entire claimable balance back to the caller. Fails if there is nothing to claim.

CreateBounty

func CreateBounty(cur realm, title string) int64

Crossing function. Callable from a transaction via MsgCall, and from another realm as CreateBounty(cross(cur), ...).

CreateBounty escrows the attached GNOT as a new open bounty and returns its id. Only direct EOA calls with -send are accepted (the receipt-guaranteed shape). The envelope must be exactly one positive ugnot coin. The caller becomes the bounty's funder.

FeeBps

func FeeBps() int64

FeeBps returns the protocol fee that will be snapshotted into newly created bounties (existing bounties keep their own snapshot).

FeesAccrued

func FeesAccrued() int64

FeesAccrued returns the fee pot (the F term).

Held

func Held() int64

Held returns the ugnot actually held at the realm address (the H term).

Liabilities

func Liabilities() int64

Liabilities returns everything this realm owes: openTotal + UsersTotal + FeesAccrued.

NumBounties

func NumBounties() int64

NumBounties returns how many bounties have ever been created.

OpenTotal

func OpenTotal() int64

OpenTotal returns the escrow held by open bounties (the B term).

Render

func Render(_ string) string

Render shows configuration, totals, the composed conservation check, and the most recent bounties (bounded page, newest first).

SetFeeBps

func SetFeeBps(cur realm, bps int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as SetFeeBps(cross(cur), ...).

SetFeeBps sets the protocol fee snapshotted into FUTURE bounties at creation. Existing bounties keep the fee they were created under. Admin only; bounded by [0, MaxFeeBps].

SetFeeRecipient

func SetFeeRecipient(cur realm, next address)

Crossing function. Callable from a transaction via MsgCall, and from another realm as SetFeeRecipient(cross(cur), ...).

SetFeeRecipient re-points the fee/surplus role, including the pot accrued so far. Admin only; zero address rejected.

Surplus

func Surplus() int64

Surplus returns Held() - Liabilities() (the S term; >= 0 unless a conservation bug exists).

SweepDenom

func SweepDenom(cur realm, denom string)

Crossing function. Callable from a transaction via MsgCall, and from another realm as SweepDenom(cross(cur), ...).

SweepDenom sends the surplus of a single denomination to the fee recipient (the bounded escape hatch validated on the vault realm). For ugnot only the excess over Liabilities() moves; other denoms move wholly. Only the fee recipient may call it.

TransferAdmin

func TransferAdmin(cur realm, next address)

Crossing function. Callable from a transaction via MsgCall, and from another realm as TransferAdmin(cross(cur), ...).

TransferAdmin hands the admin role to next. Admin only; zero address rejected. One-step (documented trade-off, as on the vault).

UsersTotal

func UsersTotal() int64

UsersTotal returns the sum of all claimable balances (the U term).

WithdrawFees

func WithdrawFees(cur realm)

Crossing function. Callable from a transaction via MsgCall, and from another realm as WithdrawFees(cross(cur), ...).

WithdrawFees sends the accrued fee pot to the fee recipient. Only the fee recipient may call it.

---

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.