Updates

applications-economy/hyper-p2p-auction-gossip/docs/api.md

@@ -1,23 +1,43 @@
-# hyper-p2p-auction-gossip API
+# API: hyper-p2p-auction-gossip
 
-**Status:** scaffold · **Protocol:** `auction-gossip/v1`
+**Protocol:** `auction-gossip/v1`  
+**Export:** `{ HyperP2PAuctionGossip, PROTOCOL }`
 
-## Class `HyperP2PAuctionGossip`
+## Constructor
 
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+`new HyperP2PAuctionGossip(opts?)`
 
-### `constructor(opts?)`
+| Option | Type | Description |
+|--------|------|-------------|
+| `topic` | string \| buffer | Hyperswarm topic (optional for local-only) |
+| `keyPair` | keyPair | Override identity |
 
-### `getStats()`
+## Methods
 
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `openAuction(auctionId, meta?)` | auction | Create open auction |
+| `placeBid(auctionId, amount, meta?)` | bid | Append bid (sorted desc) |
+| `closeAuction(auctionId)` | auction \| null | Close; sets `winner` to highest bid |
+| `getAuction(auctionId)` | auction \| null | Lookup |
+| `listOpen()` | auction[] | Active auctions |
+| `ready()` | Promise\<this\> | Join swarm when `topic` set |
+| `close()` | Promise\<void\> | Teardown |
+| `getStats()` | object | Counters + protocol |
 
-### `ready()`
+## Events
 
-Resolves immediately (no-op).
+| Event | Payload |
+|-------|---------|
+| `open` | auction |
+| `bid` | `{ auctionId, bid }` |
+| `close` | auction |
+| `remote-open` | auction |
+| `remote-bid` | gossip payload |
+| `remote-close` | auction |
 
-## Wire (planned)
+## Errors
 
-| Message | Direction | Notes |
-|---------|-----------|-------|
-| TBD | gossip | Defined in implementation pass |
+- `auction already open` / `auction not open`
+- `amount must be a positive number`
+- Validation via `assertNonEmpty` on ids