# Architecture: hyper-p2p-auction-gossip

**Category:** `applications-economy` · **Protocol:** `auction-gossip/v1`

## Role

Gossip-synchronized auction room: peers share auction catalog and bid ordering; closing peer publishes winner snapshot.

```mermaid
flowchart LR
  App[Market app] --> AG[HyperP2PAuctionGossip]
  AG --> Map[_auctions Map]
  AG --> P2P[p2p-bare gossipSend]
  P2P --> Peers[Remote bidders]
```

## Sequence

```mermaid
sequenceDiagram
  participant Seller
  participant AG as AuctionGossip
  participant SW as Hyperswarm
  participant Buyer
  Seller->>AG: openAuction(lot-1)
  AG->>SW: auction-open
  SW-->>Buyer: remote-open
  Buyer->>AG: placeBid(lot-1, 42)
  AG->>SW: auction-bid
  Seller->>AG: closeAuction(lot-1)
  AG->>SW: auction-close + winner
```

## Wire messages

| type | direction | fields | behavior |
|------|-----------|--------|----------|
| `auction-open` | gossip | `auction` | Replace/insert auction in `_auctions` |
| `auction-bid` | gossip | `auctionId`, `bid` | Append bid if auction open; sort desc |
| `auction-close` | gossip | `auctionId`, `winner`, `closedAt` | Set `status: closed`, assign winner |

Transport: `initModuleSwarm` + `gossipSend` from `../../_shared/p2p-bare.js`. Protomux channel id: `auction-gossip/v1`.

## State model

| Structure | Purpose |
|-----------|---------|
| `_auctions` | `id → { bids[], status, meta, openedBy, winner? }` |
| `_stats` | `opened`, `bids`, `closed`, `gossipIn`, `gossipOut` |

**Consistency:** last-writer on open; bids append-only per peer; close overwrites status. No CRDT merge on conflicting closes — application should designate an authority or use oracle settlement.

## Composition

- **`hyper-p2p-credit-ledger`** — settle winner payment after `close`
- **`hyper-p2p-marketplace-listing`** — catalog items before auction
- **`hyper-p2p-decentralized-oracle`** — external price/reserve attestation