const AuctionOpen, AuctionSettled, AuctionClosed, AuctionCancelled
Auction status values. Settled, Closed and Cancelled are terminal.
auction source realm
Realm auction is an ascending (English) auction settled in ugnot, holding real coins. A SELLER lists a lot with a res...
Realm auction is an ascending (English) auction settled in ugnot, holding real coins. A SELLER lists a lot with a reserve price and a duration; BIDDERS raise each other by attaching coins; the standing high bid is escrowed by the realm and every OUTBID bid becomes a pull-claimable refund; at close the winner's payment is credited to the seller, the protocol fee splitting off at the ledger. A bid landing inside the anti-snipe window extends the end, so the auction closes only when bidding actually stops.
It is the one market shape this portfolio never had: COMPETITIVE PRICE DISCOVERY with escrowed settlement. The routing realms move a known amount to known parties (r/fee_split, r/revshare), the disbursement realms pay a known total out on a schedule (r/vesting, r/payroll, r/budgets), the credit realm lends principal out and takes a larger total back (r/loans), and r/crowdfund POOLS many contributions toward one shared goal. An auction is none of those: N rival bidders, one escrowed winner, automatic refunds for the rest, and a price nobody knows in advance. See [DISCOVERY.md].
Custody — the conservation invariant is the product
A custodial realm, so the monetary invariant governs it exactly as it does r/loans and r/subscriptions, with one extra bucket for the escrowed bids:
Example
1Held == locked + feeledger.Liabilities()
where `locked` is the sum of the CURRENT high bids across all open auctions (coins the realm holds but that are not yet claimable by anyone), and the ledger holds the two claimable kinds — OUTBID refunds and, after close, SELLER proceeds — plus the fee pot. Every value transition preserves the equality; see the DELTA-form conservation test.
Refunds are PULL, never push: an outbid bid is credited to the bidder's claimable balance (fee 0 — a refund is a full return, not a fee event) and the bidder withdraws it with Claim. Nothing is sent to a third party during someone else's Bid, so a bid cannot be griefed by a hostile previous bidder and there is no cross-call reentrancy surface in the bid path.
What the realm settles, and what it does NOT
The realm settles PAYMENT and records the WINNER; it does not custody or deliver the lot, which is identified by a free-text description and changes hands off-chain (or by a downstream realm reading [Winner]). This is the scope decision, stated rather than discovered: an on-chain-asset auction (grc20/grc721 custody) is a v2, and it is exactly the escrow-of-the-asset surface this v1 deliberately omits. A winner pays and is recorded; delivery is the parties' concern, as it is for r/loans' off-chain use of principal.
REALM-CALLER CAVEAT, inherited from the siblings: coinio's receipt guard admits only EOA payers, so every BIDDER is an EOA. The SELLER is whoever calls CreateAuction; a realm may create an auction, but like revshare's members a realm seller must expose its own crossing path to Claim or its proceeds strand — the seller's concern, not a realm or third-party hazard. assertNoSend reads the ORIGIN envelope, so every non-payable function refuses any transaction that attached coins anywhere.
5
const MinBid, MaxBid, MinDuration, MaxDuration, MaxAntiSnipe, MaxLotLen, MaxAuctionsPerSeller, RenderLimit
1const (
2 // MinBid is the dust floor for any bid and any non-zero reserve; MaxBid
3 // keeps every bid, the increment and the fee split far from int64
4 // overflow. The bidder must ATTACH the bid, so the real ceiling is their
5 // balance.
6 MinBid = int64(1_000)
7 MaxBid = int64(1_000_000_000_000) // 1,000,000 GNOT
8
9 // Duration and anti-snipe bounds, in blocks. The floor keeps an auction
10 // off a one-block treadmill; the ceiling keeps height arithmetic far from
11 // overflow. A 0 anti-snipe window disables the extension.
12 MinDuration = int64(10)
13 MaxDuration = int64(7_500_000)
14 MaxAntiSnipe = int64(7_500_000)
15
16 // MaxLotLen bounds the stored lot description.
17 MaxLotLen = 200
18
19 // MaxAuctionsPerSeller bounds one seller's stored auctions; terminal
20 // auctions do NOT free the slot, because a settled/closed/cancelled
21 // auction is a permanent record a bidder and auditor may need to read.
22 MaxAuctionsPerSeller = 50
23
24 // RenderLimit bounds every rendered list — an unbounded Render was YELLOW
25 // in three prior audits.
26 RenderLimit = 20
27)Input bounds.
const Denom
Denom is the only asset this realm accepts.
const MaxFeeBps
MaxFeeBps is the hard protocol-fee cap: 1000 bps = 10%. The fee applies only to the WINNER's payment at close, never to a refund.
const MinIncrementBps
MinIncrementBps is the minimum raise over the standing high bid: 500 = 5%. It stops penny-increment griefing without a per-auction knob.
33
func AcceptAdmin
crossing Actionfunc AuctionInfo
Action1func AuctionInfo(auctionID int64) (seller address, reserve, highBid, endHeight, antiSnipe, feeBps, createdHeight int64, highBidder address, status string)AuctionInfo returns an auction's terms and standing state. Lot text is a separate view (Lot) so this stays a numeric/address tuple.
func AuctionsOf
Actionfunc Bid
crossing ActionBid raises the standing high bid on an open auction. The caller attaches the bid; it must beat the current high bid by at least MinIncrementBps (or meet max(reserve, MinBid) if it is the first bid), and the auction must still be open and before its end. The previous high bidder's escrowed bid becomes a pull-claimable refund. A bid inside the anti-snipe window extends the end.
func BlocksLeft
ActionBlocksLeft is how many blocks until the end (0 once ended).
func Cancel
crossing ActionCancel withdraws an auction that has not yet received a bid. Seller only. Once any bid stands, the auction can only run to close — a seller cannot pull the lot out from under a committed bidder.
func Claim
crossing ActionClaim sends amount ugnot of the caller's claimable balance — outbid refunds and, if the caller is a seller of a settled auction, proceeds — to the caller.
func ClaimAll
crossing ActionClaimAll sends the caller's entire claimable balance to the caller.
func ClaimableOf
Actionfunc Close
crossing ActionClose finalizes an auction whose end height has passed. Anyone may call it; no auction's terminal state may depend on a party acting. With a winner, the high bid is credited to the seller (fee split at the ledger) and the auction is Settled; with no bids it is Closed. The winner's escrowed payment moves from `locked` into the seller's claimable balance.
func CreateAuction
crossing ActionCreateAuction lists a lot for ascending-bid sale. The caller becomes the seller. `reserve` is 0 (no reserve) or a floor in [MinBid, MaxBid] the first bid must meet; the auction runs for `durationBlocks` blocks; a bid landing within `antiSnipe` blocks of the end extends the end to now+antiSnipe (0 disables). The current protocol fee is snapshotted in. Returns the id.
func EndHeight
ActionEndHeight is the current end height (which anti-snipe may have extended).
func FeeBps
Actionfunc FeesAccrued
Actionfunc HasAuction
Actionfunc Height
Actionfunc Held
Actionfunc HighBid
ActionHighBid is the standing high bid (0 if none).
func IsCloseable
ActionIsCloseable reports whether Close would succeed right now.
func IsOpen
ActionIsOpen reports whether the auction is open and still before its end.
func Liabilities
Actionfunc Locked
Actionfunc Lot
ActionLot returns the auction's free-text lot description.
func MinNextBid
ActionMinNextBid is the smallest bid that would be accepted right now: the first bid's floor when there are no bids, else the standing high bid plus the minimum increment.
func NumAuctions
Actionfunc Render
func Reserve
ActionReserve is the auction's reserve price (0 if none).
func SetFeeBps
crossing Actionfunc SetFeeRecipient
crossing Actionfunc Status
ActionStatus is the auction's status string.
func SweepDenom
crossing ActionSweepDenom recovers out-of-band coins to the fee recipient. For the ledger denom the reserve is locked + Liabilities() — escrowed high bids, claimable refunds, seller proceeds and the fee pot are all structurally unreachable.
