fix(pow): surface explicit PoW rejection instead of generic timeout

When mostrod requires NIP-13 PoW and the client sends an event without
satisfying it, the daemon silently drops the event (logs "Not POW
verified event!" on its side) and never replies. The CLI was hiding
that behind a generic timeout message ("deadline has elapsed" /
"Timeout waiting for DM or gift wrap event"), which can mislead users
into suspecting network failures, relay issues, or daemon downtime.

After timing out, wait_for_dm now consults the daemon's kind-38385
info event ("pow" tag) and, if the required difficulty exceeds the
configured POW, returns the new PowRequirementUnmet error with an
actionable message pointing at --pow / POW=. Genuine timeouts keep
their existing WaitForDmTimeout error, so the add-bond-invoice
happy-path branch (which only matches WaitForDmTimeout) is unaffected.

Closes #172

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: grunch

docs/pow_error_handling.md

@@ -0,0 +1,246 @@
+# Spec — Surface explicit PoW rejection error
+
+Tracking issue: [MostroP2P/mostro-cli#172](https://github.com/MostroP2P/mostro-cli/issues/172)
+
+## 1. Problem
+
+When a user sends an event from `mostro-cli` to a `mostrod` instance that
+**requires NIP‑13 Proof‑of‑Work** without providing the required PoW, the
+daemon silently drops the event (logs `Not POW verified event!` on its side)
+and never replies. The CLI eventually times out and surfaces a generic
+timeout error to the user:
+
+```text
+deadline has elapsed
+```
+
+(or, in current `main`, the slightly less awful but still ambiguous
+`Timeout waiting for DM or gift wrap event`).
+
+This is misleading. From the user perspective the message can mean almost
+anything: the relay is slow, mostrod is down, the network is broken, the CLI
+is buggy, or the command was wrong. The real cause — PoW not satisfied — is
+hidden.
+
+## 2. Root cause
+
+The flow that breaks today:
+
+1. `mostro-cli` mines PoW on the outer GiftWrap based on the `POW` env var
+   (default `0`) — see `src/util/messaging.rs::parse_pow_env` and the
+   `WrapOptions { pow, .. }` plumbing.
+2. The wrapped event is published to relays via `client.send_event(...)`.
+3. `wait_for_dm` opens a subscription on the trade key and waits for
+   `FETCH_EVENTS_TIMEOUT` (15 s) for an inbound GiftWrap.
+4. If `mostrod` requires PoW above what the client provided, mostrod
+   silently drops the event in
+   [`mostro/src/app.rs`](https://github.com/MostroP2P/mostro) — the relay
+   accepted it (so there's no NIP‑01 `OK false` from the relay either) and
+   no reply is ever produced.
+5. `tokio::time::timeout` elapses → `wait_for_dm` returns `WaitForDmTimeout`
+   → the user sees the generic timeout message.
+
+The CLI has **no way to distinguish** "daemon silently dropped my event for
+PoW reasons" from "transient relay or network issue".
+
+## 3. Signal we can use
+
+`mostrod` already publishes its required PoW in its **kind‑38385 info event**
+under the tag `["pow", "<difficulty>"]`. See
+[`mostro/src/nip33.rs`](https://github.com/MostroP2P/mostro) (`new_info_event`)
+where the daemon writes:
+
+```rust
+Tag::custom(
+    TagKind::Custom(Cow::Borrowed("pow")),
+    vec![mostro_settings.pow.to_string()],
+),
+```
+
+Reading that tag on the CLI side lets us answer the only question we care
+about: *did this Mostro instance reject our event because we didn't provide
+enough PoW?*
+
+We already fetch kind‑38385 elsewhere in the CLI — see
+`src/util/events.rs::fetch_bond_claim_window_days` — so this is a small
+extension of an existing pattern.
+
+## 4. Design
+
+### 4.1 Error variant
+
+Add a typed error so callers (and tests) can match the PoW failure mode
+distinctly from a generic timeout:
+
+```rust
+#[derive(Debug)]
+pub struct PowRequirementUnmet {
+    pub required: u8,
+    pub configured: u8,
+}
+```
+
+The user-facing `Display` will be explicit:
+
+```text
+This Mostro instance requires NIP-13 proof of work of N bits, but the
+client sent the event with M bits. Re-run with `--pow N` or set
+`POW=N` and try again.
+```
+
+The error lives next to `WaitForDmTimeout` in `src/util/messaging.rs` (same
+module, same idiom: small zero/struct error wrapped via `anyhow`).
+
+### 4.2 Helper — fetch required PoW from kind‑38385
+
+Add a helper in `src/util/events.rs`:
+
+```rust
+/// Best-effort: fetch the Mostro instance's kind-38385 info event and read
+/// the `pow` tag. Returns `None` when no info event is available or the tag
+/// is missing/unparseable. Mirrors `fetch_bond_claim_window_days`.
+pub async fn fetch_required_pow(ctx: &crate::cli::Context) -> Option<u8>;
+```
+
+Implementation details:
+
+- Author filter on `ctx.mostro_pubkey`, kind `NOSTR_INFO_EVENT_KIND`.
+- Pick the **newest** revision by `created_at` (replaceable but lagging
+  relays can still serve old copies; same caveat as the bond-window helper).
+- Scan tags for `["pow", "<value>"]`, parse as `u8`.
+- Any error (fetch failure, missing tag, unparseable value) → `None`.
+
+Returning `None` is the "I don't know" signal; the caller treats it as
+*"can't blame PoW"* and falls back to the generic timeout error. This keeps
+the helper non-fatal: older daemons that don't publish the tag, or unreachable
+relays, never break flows that worked before.
+
+### 4.3 Where to plug it in — `wait_for_dm`
+
+`wait_for_dm` is the single chokepoint that every request/reply flow goes
+through (`add_invoice`, `take_order`, `take_dispute`, `send_msg`, `new_order`,
+`rate_user`, `orders_info`, `restore`, `last_trade_index`, `add_bond_invoice`).
+Centralizing the fix here covers every command in one place.
+
+Postflight check (chosen — see Alternatives below):
+
+```rust
+let event = match waited {
+    Ok(inner) => inner?,
+    Err(_elapsed) => {
+        // Before declaring this a generic timeout, check whether the daemon
+        // advertises a PoW requirement we didn't meet — that's the real
+        // cause "deadline has elapsed" was hiding.
+        if let Some(required) = fetch_required_pow(ctx).await {
+            let configured = parse_pow_env().unwrap_or(0);
+            if required > configured {
+                return Err(PowRequirementUnmet { required, configured }.into());
+            }
+        }
+        return Err(WaitForDmTimeout.into());
+    }
+};
+```
+
+Add an `&Context` parameter? Look at the signature today —
+`wait_for_dm(ctx, order_trade_keys, sent_message)` — `ctx` is already
+passed. We just need to grant the helper access to `ctx.client` and
+`ctx.mostro_pubkey` (already does).
+
+### 4.4 `add_bond_invoice` interplay
+
+`add_bond_invoice` treats `WaitForDmTimeout` as the happy path (Mostro pays
+the invoice without acking over Nostr). The new variant must **not** be
+caught by that branch — a PoW failure on `add-bond-invoice` is *not* a
+successful submission. Concretely:
+
+- The existing `Err(e) if e.downcast_ref::<WaitForDmTimeout>().is_some()`
+  arm continues to match only `WaitForDmTimeout`.
+- A `PowRequirementUnmet` falls through to the generic `Err(e) => return
+  Err(e)` arm and bubbles up to the user, which is the desired behavior.
+
+No code change needed in `add_bond_invoice.rs` — the existing pattern match
+already handles the right split. We assert this with a regression note.
+
+## 5. Alternatives considered
+
+### 5.1 Preflight check (fail before sending)
+
+Run `fetch_required_pow` *before* `send_dm`. Advantages: fail fast (no
+15‑second wait). Disadvantages:
+
+- Adds a relay roundtrip to the happy path for every command.
+- Doubles "you didn't set PoW" errors for daemons that publish the tag but
+  also accept PoW=0 (no real check on that side today).
+- Couples every command to the info event being reachable.
+
+→ Rejected. Postflight has the right cost model: zero overhead when things
+work, and *only* pays for the info-event fetch in the failure path where the
+user is already waiting anyway.
+
+### 5.2 Auto-mine the required PoW
+
+Bump `WrapOptions.pow` to `max(configured, required)` instead of erroring.
+Tempting, but high PoW targets (e.g. 28+ bits) can take minutes to mine on
+a laptop, and the user wouldn't see *why* the CLI is suddenly chewing CPU.
+Better to fail explicitly with an actionable hint and let the user opt in
+by setting `POW` themselves.
+
+→ Rejected. Defer to explicit user opt-in via `--pow` / `POW` env.
+
+### 5.3 Read NIP‑01 `OK false` from the relay
+
+Won't help: mostrod drops the event *after* the relay accepts it, so the
+relay returns `OK true`. There is no rejection signal on the publish path.
+
+→ Rejected.
+
+## 6. Acceptance criteria
+
+(Reproducing the issue's checklist, with concrete bindings.)
+
+- Sending an event from `mostro-cli` to a PoW‑enabled `mostrod` without
+  satisfying PoW must surface an error that mentions PoW. Specifically the
+  `PowRequirementUnmet { required, configured }` variant rendered as:
+  `"This Mostro instance requires NIP-13 proof of work of N bits, but the
+  client sent the event with M bits. Re-run with --pow N or set POW=N and
+  try again."`
+- Genuine timeouts (daemon reachable, no PoW requirement, just slow / no
+  reply) keep returning `WaitForDmTimeout` — its existing message stays.
+- `add_bond_invoice`'s "timeout is the happy path" arm only matches
+  `WaitForDmTimeout`; a `PowRequirementUnmet` propagates and is shown to
+  the user.
+- Older daemons that don't publish `["pow", ...]` in kind‑38385 behave
+  exactly as before (helper returns `None` → generic timeout).
+
+## 7. Test plan
+
+Unit tests in `src/util/messaging.rs` and `src/util/events.rs`:
+
+- `pow_requirement_unmet_display_mentions_required_and_configured` —
+  formatting check on the error message.
+- `fetch_required_pow_returns_none_when_tag_missing` — synthesize a
+  kind-38385 event with no `pow` tag, assert `None`.
+- `fetch_required_pow_picks_newest_revision` — two events, newer with a
+  different pow value; helper returns the newer value. Mirrors the existing
+  `fetch_bond_claim_window_days` pattern.
+- `fetch_required_pow_parses_pow_tag` — single event with `["pow", "12"]`,
+  assert `Some(12)`.
+
+A manual end-to-end check (out of the unit-test scope) is to run against a
+PoW‑enabled local `mostrod`:
+
+```sh
+POW=0 mostro-cli neworder ...
+# expected: PowRequirementUnmet error, not "deadline has elapsed"
+POW=<required> mostro-cli neworder ...
+# expected: normal flow, no error
+```
+
+## 8. Out of scope
+
+- Auto-mining the missing PoW (see 5.2).
+- Removing or restructuring the `POW` env var / `--pow` flag.
+- Surfacing the PoW requirement during `list-orders` / informational
+  flows. The fix is scoped to the request/reply path where the missing
+  PoW silently kills the flow.

src/util/events.rs

@@ -83,15 +83,26 @@ pub fn create_filter(
     }
 }
 
-/// Fetch the Mostro instance's kind-38385 info event and read the
-/// `bond_payout_claim_window_days` tag.
+/// Fetch the Mostro instance's kind-38385 info event and read a tag whose
+/// first slot equals `tag_name`. Returns the second slot as a string.
 ///
-/// Returns `None` when the node publishes no info event, the tag is absent
-/// (older daemon or bonds disabled), or the value can't be parsed. Used to
-/// render the forfeit deadline for an `add-bond-invoice` request locally, per
-/// the protocol's "Bond payout invoice" / "Other events" docs. Best-effort:
-/// any relay error degrades to `None` rather than failing the caller.
-pub async fn fetch_bond_claim_window_days(ctx: &crate::cli::Context) -> Option<i64> {
+/// Best-effort: any relay error or missing tag degrades to `None` so callers
+/// keep working against older daemons that don't publish the tag.
+/// Pure: read the second slot of the first tag whose first slot equals
+/// `tag_name`. Split out so the kind-38385 tag-parsing logic stays unit
+/// testable without spinning up a relay.
+fn read_info_tag_from_event(event: &nostr_sdk::Event, tag_name: &str) -> Option<String> {
+    event.tags.iter().find_map(|tag| {
+        let slice = tag.as_slice();
+        if slice.first().map(String::as_str) == Some(tag_name) {
+            slice.get(1).cloned()
+        } else {
+            None
+        }
+    })
+}
+
+async fn fetch_info_tag(ctx: &crate::cli::Context, tag_name: &str) -> Option<String> {
     let filter = Filter::new()
         .author(ctx.mostro_pubkey)
         .kind(nostr_sdk::Kind::Custom(NOSTR_INFO_EVENT_KIND));
@@ -104,16 +115,38 @@ pub async fn fetch_bond_claim_window_days(ctx: &crate::cli::Context) -> Option<i
 
     // kind-38385 is replaceable, but pick the newest revision by `created_at`
     // explicitly: a lagging relay (or several relays at once) can still surface
-    // an older copy, and a stale claim window would render the wrong, very
-    // user-facing forfeit deadline.
+    // an older copy.
     let event = events.iter().max_by_key(|e| e.created_at)?;
-    for tag in event.tags.iter() {
-        let slice = tag.as_slice();
-        if slice.first().map(String::as_str) == Some("bond_payout_claim_window_days") {
-            return slice.get(1).and_then(|v| v.parse::<i64>().ok());
-        }
-    }
-    None
+    read_info_tag_from_event(event, tag_name)
+}
+
+/// Fetch the Mostro instance's kind-38385 info event and read the
+/// `bond_payout_claim_window_days` tag.
+///
+/// Returns `None` when the node publishes no info event, the tag is absent
+/// (older daemon or bonds disabled), or the value can't be parsed. Used to
+/// render the forfeit deadline for an `add-bond-invoice` request locally, per
+/// the protocol's "Bond payout invoice" / "Other events" docs. Best-effort:
+/// any relay error degrades to `None` rather than failing the caller.
+pub async fn fetch_bond_claim_window_days(ctx: &crate::cli::Context) -> Option<i64> {
+    // A stale claim window would render the wrong, very user-facing forfeit
+    // deadline — same newest-revision caveat as the rest of the info event.
+    fetch_info_tag(ctx, "bond_payout_claim_window_days")
+        .await
+        .and_then(|v| v.parse::<i64>().ok())
+}
+
+/// Fetch the Mostro instance's required NIP-13 proof-of-work difficulty from
+/// the kind-38385 info event (`["pow", "<bits>"]` tag).
+///
+/// Returns `None` when the daemon doesn't publish the tag (older versions),
+/// when the value is unparseable, or when the info event can't be fetched.
+/// Used by [`crate::util::messaging::wait_for_dm`] to distinguish a real
+/// timeout from a silent PoW rejection — see `docs/pow_error_handling.md`.
+pub async fn fetch_required_pow(ctx: &crate::cli::Context) -> Option<u8> {
+    fetch_info_tag(ctx, "pow")
+        .await
+        .and_then(|v| v.parse::<u8>().ok())
 }
 
 #[allow(clippy::too_many_arguments)]
@@ -206,3 +239,56 @@ pub async fn fetch_events_list(
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    async fn make_info_event(keys: &Keys, tags: Vec<Tag>) -> nostr_sdk::Event {
+        EventBuilder::new(nostr_sdk::Kind::Custom(NOSTR_INFO_EVENT_KIND), "")
+            .tags(tags)
+            .sign(keys)
+            .await
+            .expect("sign info event")
+    }
+
+    fn pow_tag(value: &str) -> Tag {
+        Tag::parse(["pow", value]).expect("build pow tag")
+    }
+
+    #[tokio::test]
+    async fn read_info_tag_finds_pow_value() {
+        let keys = Keys::generate();
+        let event = make_info_event(
+            &keys,
+            vec![
+                Tag::parse(["fee", "0.006"]).unwrap(),
+                pow_tag("12"),
+                Tag::parse(["fiat_currencies_accepted", "USD,EUR"]).unwrap(),
+            ],
+        )
+        .await;
+        assert_eq!(read_info_tag_from_event(&event, "pow"), Some("12".into()));
+    }
+
+    #[tokio::test]
+    async fn read_info_tag_returns_none_when_missing() {
+        let keys = Keys::generate();
+        let event = make_info_event(&keys, vec![Tag::parse(["fee", "0.006"]).unwrap()]).await;
+        assert_eq!(read_info_tag_from_event(&event, "pow"), None);
+    }
+
+    #[tokio::test]
+    async fn pow_tag_parses_as_u8() {
+        // u8 parse is what fetch_required_pow chains after the helper.
+        // Lock in that the daemon's stringified u8 round-trips cleanly,
+        // and that garbage values degrade to None.
+        let parse = |s: &str| s.parse::<u8>().ok();
+        assert_eq!(parse("12"), Some(12));
+        assert_eq!(parse("0"), Some(0));
+        assert_eq!(parse("nope"), None);
+        // Out of range for u8 → None, which is the right "ignore this
+        // weird value, fall back to generic timeout" behavior.
+        assert_eq!(parse("999"), None);
+    }
+}