grants package

Realm grants is a decentralized grants market: a creator escrows GNOT behind a grant with an application deadline, applicants apply on-chain, the creator selects one applicant, and the winner claims the funding minus a transparent protocol fee.

COMPOSITION (per the recorded DISCOVERY / REUSE ANALYSIS): all balance accounting is delegated to feeledger, all coin movement to coinio, and all free-text render output to the ecosystem sanitizer p/nt/markdown/sanitize/v0. This realm owns only the grants state machine: grant records, per-grant applications, open-escrow total, deadlines, and roles.

LIFECYCLE (terminal states are frozen; one transition per grant):

 1CreateGrant (EOA + -send)     : escrow -> openTotal, status Open,
 2                                fee bps SNAPSHOTTED at creation
 3Apply (also re-apply/update)  : while Open and height < deadline;
 4                                keyed by the caller's own address
 5SelectWinner (creator only)   : Open -> Awarded; winner MUST be an
 6                                applicant; escrow -> winner's
 7                                claimable balance minus the
 8                                snapshotted fee
 9CancelGrant (creator only)    : Open -> Cancelled; fee-free refund
10                                to the creator's claimable balance
11ExpireGrant (ANYONE)          : Open -> Expired once height >=
12                                deadline + ExpiryGraceBlocks;
13                                fee-free refund to the creator —
14                                the permissionless valve that makes
15                                fund-trapping impossible
16Claim / ClaimAll (anyone)     : pays out the caller's own ledger
17                                balance (winners and refunds)
18WithdrawFees (fee recipient)  : pays out the fee pot

AUTHORIZATION: every identity is derived from the crossing entrypoint's cur.Previous().Address() — no function takes a caller identity as a parameter. Applications and claimable balances are keyed by that runtime-derived address, so altering another user's application or claiming another user's grant is impossible by construction. The creator cannot apply to their own grant, and SelectWinner only accepts addresses that actually applied.

DEADLINE SEMANTICS: deadline = ChainHeight() + durationBlocks, fixed at creation (bounded by [MinDurationBlocks, MaxDurationBlocks]). The deadline gates NEW/UPDATED applications only; the creator may select or cancel at any time while the grant is Open. After deadline + ExpiryGraceBlocks anyone may expire the grant.

FEE MODEL: fee = floor(amount * bps / 10000), rounding favors the winner; no minimum fee; bps snapshotted into the grant at creation, so SetFeeBps affects future grants only (closes the AWARD-time admin race), and CreateGrant takes the caller's own maxFeeBps ceiling, rejecting creation if the live fee exceeds what the creator signed for (closes the CREATION-time race — audit Y1); hard compile-time cap MaxFeeBps (10%); refunds (cancel/expire) are always fee-free; the pot is withdrawable by the fee-recipient role.

MONETARY INVARIANT (conservation): let H be ugnot held at this realm's address, G = openTotal (Σ amount over Open grants), U the ledger's claimable balances, F the fee pot, S >= 0 out-of-band surplus:

1H == G + U + F + S

Every transition moves value between exactly two terms inside one transaction: CreateGrant raises H and G together (coinio.Receive is the receipt-guaranteed shape, validated live on pearl-1); SelectWinner/CancelGrant/ExpireGrant move amount from G into U+F with feeledger guaranteeing credited + fee == amount; claims and fee withdrawal debit the ledger before coinio.Payout moves the identical amount out (checks-effects-interactions); any panic aborts the whole transaction; this realm never issues or removes coins. Surplus is recoverable only via SweepDenom (fee recipient), which reserves Liabilities() = G + U + F.

ONLY GNOT: CreateGrant rejects any envelope that is not exactly one positive ugnot coin (coinio.Receive). Foreign denominations sit in surplus.