# English Auction

> ⚠️ **Experimental — generated with no human supervision** by the daily MCP pipeline (Solidity→Gno port). Not audited. See [r/moul/x/daily](https://github.com/moul/gno-contracts/blob/main/r/moul/x/daily/README.md).

---


An idiomatic gno.land port of the classic Solidity **English (ascending-bid)
auction**. It ports the core mechanics — a seller opens an auction, bidders
submit strictly increasing bids, the displaced top bid becomes refundable, and
after a block deadline anyone can settle it — into a single realm that hosts
many concurrent auctions.

Solidity's `msg.sender` maps to `unsafe.PreviousRealm().Address()`, `block.number`
to `runtime.ChainHeight()`, `require` to `panic`, and events to `chain.Emit`.
There is no real coin transfer: bid amounts and refunds are tracked as plain
`uint64` accounting in ordered `avl.Tree`s (mirroring Solidity's `pendingReturns`
withdraw pattern). Auctions and pending refunds are keyed so `Render` can iterate
deterministically.

## Transactions

- `Start(cur, item string, durationBlocks int64) int64` — open an auction (caller
  becomes the seller); ends at `ChainHeight() + durationBlocks`. Returns the id.
- `Bid(cur, id int64, amount uint64)` — bid; must strictly exceed the current
  highest. The prior top bid becomes refundable.
- `Withdraw(cur, id int64) uint64` — reclaim your displaced bids for an auction.
- `End(cur, id int64)` — after the deadline, award the item to the top bidder.

## Example calls

```
# open a 100-block auction for a painting -> returns id 1
Start("Vintage painting", 100)

# two bidders compete (amounts are accounting units, not real coins)
Bid(1, 500)     # alice
Bid(1, 750)     # bob outbids -> alice's 500 is now refundable
Withdraw(1)     # alice reclaims 500

# once ChainHeight() >= endHeight, anyone settles it
End(1)          # item awarded to bob at 750
```

Visit the realm to see the live table of auctions: item, highest bid + bidder,
blocks remaining or ended, and the winner.

## What changed in v1

State moved from a hand-rolled `avl.Tree` + `nextID` + zero-padding helper to
[`p/moul/kit/store`](/p/moul/kit/store/v0), which keys entries by
[`seqid`](/p/nt/seqid/v0) instead of a fixed-width decimal string.

v0 padded ids to width 12. Past that width the padding stops and the tree
orders `"1000000000000"` before `"999999999999"`, so every list this realm
renders would be wrong from that entry on. `store` keys are 8 big-endian bytes
whose order is numeric for every `uint64`, so there is no width left to outgrow.

`Auction` loses its `ID` field, which the store now owns, and the local
`mustGet` becomes one line: the store's labelled `MustGet` panics
`englishauction: auction #7 not found` where `v0` said only
`englishauction: no such auction`.

`pending`, the refund ledger, keeps its own tree and its composite
`"<id>:<addr>"` key, now built from the plain decimal id instead of the padded
one. It is only ever point-read, never iterated, so it needs a readable key and
not an ordered one. Auction ids already started at 1, so nothing shifts.

This is a storage change, which under this repo's versioning rule is a
compatibility change, hence a new version rather than an edit in place.
[`v0`](https://github.com/moul/gno-contracts/tree/4f2df83869b80470eb81c48a82fdbe82256b8113/r/moul/x/daily/englishauction) stays live and untouched.

<!-- BEGIN GNOCONTRACTS FOOTER (generated by `make readmes`; do not edit below) -->

---

Part of **[moul/gno-contracts](https://github.com/moul/gno-contracts)** — moul's versioned gno.land contracts. See the repository for the full catalog, build/test tooling, and usage.

**Dependency graph:**

![gno.land/r/moul/x/daily/englishauction/v1 dependency graph](https://raw.githubusercontent.com/moul/gno-contracts/main/_assets/gno.land/r/moul/x/daily/englishauction/v1/deps.png)

> 🧪 **Highly experimental — potentially vibe-coded.** Not audited; may break, change, or be removed at any time. Do not use with anything of value. Full disclaimer: [DISCLAIMER](https://github.com/moul/gno-contracts/blob/main/DISCLAIMER.md).

<!-- END GNOCONTRACTS FOOTER -->