58 lines
1.9 KiB
Markdown
58 lines
1.9 KiB
Markdown
# 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
|