restaurant/docs/nostr-layer.md

# Nostr layer

Why Nostr at all? Two reasons:

1. **Live menu propagation.** Customer apps subscribe to a
   restaurant's pubkey and pick up menu changes (new items, price
   updates, sold-out states) without polling.
2. **Cross-instance discoverability.** A festival or food court
   curator publishes a [[webapp-integration|NIP-51 list]] of
   restaurant pubkeys; any client can resolve it into a unified
   menu without needing to know which LNbits instance hosts each
   restaurant.

## What gets published

| Kind | Source | When |
|---|---|---|
| `0` (NIP-01 metadata) | restaurant profile | restaurant create / update |
| `30402` (NIP-99 classified listing, parameterized replaceable, `d`-tag = item id) | menu items | item create / update; node rename re-publishes the whole subtree's items |
| `5` (NIP-09 deletion request) | menu items | item delete |

Menu listings carry structured tags so subscribers can filter
without parsing markdown:

| Tag | Format | Purpose |
|---|---|---|
| `d` | item.id | addressable identifier |
| `title` | item.name | listing title |
| `summary` | first 140 chars of description | preview |
| `price` | `["price", n, currency]` | structured price (NIP-99) |
| `image` | url | one per image, repeatable |
| `t` | `"menu"` | universal anchor |
| `t` | `<slug>` per ancestor | root-first, slugified to lowercase ASCII (e.g. `hot-beverages`); lets clients filter by category |
| `t` | dietary tag | `vegan`, `gluten_free`, etc. |
| `t` | `allergen:<x>` | structured allergens |
| `t` | `ingr:<x>` | structured ingredients |
| `l` | `"restaurant:<id>"` | back-link to the operator |
| `location` | restaurant location | physical reference |
| `g` | restaurant geohash | geo-filterable |
| `status` | `"active"` or `"sold"` | NIP-99 sold-out state |

Builders live in `nostr_publisher.py`:

- `build_restaurant_metadata_event`
- `build_menu_item_event(..., ancestor_names=...)`
- `build_delete_event`

`_slugify` produces the ancestor `t` tag values. Renaming a
[[menu-tree|menu node]] re-publishes every item in the subtree so
the new tag set lands.

## Signing

Each restaurant has an effective Nostr identity:

- If `restaurant.nostr_pubkey` is set, that's a per-restaurant
  identity (a per-restaurant signer/vault is **out of scope**
  in v1; the column is informational until that's wired up).
- Otherwise, the wallet owner's signer is resolved via
  `lnbits.core.signers.resolve_for_wallet` (wallet → account →
  signer, with a `can_sign()` gate). The signer backend
  (`LocalSigner` / `RemoteBunkerSigner` / `ClientSideOnlySigner`)
  is transparent to this extension.

`nostr_publisher.publish_event(client, event, signer)` hands the
unsigned event dict to the resolved `NostrSigner`, which fills in
`id` / `pubkey` / `sig` per NIP-01 / BIP-340 and ships to the relay
via the [[architecture|nostrclient extension's]] internal WebSocket.
The extension itself does no direct Schnorr signing — that lives in
the signer abstraction.

## What gets listened for

`nostr_sync.wait_for_nostr_events` subscribes to:

- `kind 30402` with `#t=menu`, `limit 200` for backfill, then live.
  Currently used only as an echo confirmation of our own publishes;
  federated foreign-menu indexing is on the roadmap.
- `kind 1059` (NIP-17 gift-wrapped DMs), only when
  `settings.nostr_orders_enabled`. The unwrap step (NIP-44 v2) is
  **stubbed** — the dispatcher (`_place_order_from_dm`) is complete
  and ready for the decryption hook.

## NIP-17 order intake (planned)

The intended flow once unwrap lands:

1. Customer's webapp encrypts an order payload with NIP-44 v2 to
   the restaurant's pubkey, gift-wraps it (kind 13 → kind 1059),
   and publishes.
2. The restaurant's `nostr_sync` receives the wrap, decrypts
   layers, and produces a `CreateOrder`.
3. Order placement goes through the same `services.place_order`
   path as REST — including invoice creation. The bolt11 is sent
   back to the customer pubkey via another NIP-17 DM.
4. Status updates (`paid → preparing → ready`) flow back the same
   way.

REST stays the supported transport until that lands, since LNbits
already has tested invoice plumbing.

## What does NOT get published

[[menu-tree|Menu nodes]] themselves. They're internal organizational
structure; only items and the restaurant profile carry public Nostr
identity. If we ever want categories to be discoverable as
standalone entities, NIP-51 lists are the right vehicle, not a new
kind.

## See also

- [[architecture]] — extension lifecycle starts the NostrClient
- [[menu-tree]] — ancestor names come from here
- [[order-flow]] — what NIP-17 will eventually deliver
- [[webapp-integration]] — clients of this layer