Plugin Payments: Recovery, Recourse & Reviews Implementation Plan

This implementation plan details the architectural specifications and step-by-step tasks for the settled features:

  1. Offline Export & Import of Purchase Proofs (with cryptographic challenge-response verification)
  2. Checkout DM Recourse (direct encrypted NIP-17 messaging for delayed receipts/refunds)
  3. App Comments & Ratings (NIP-22 Kind 1111 + NIP-32 Kind 1985 with ratings breakdown & WoT filtering)

1. Offline Export & Import of Purchase Proofs

Rationale & Design

Relay retention is unpredictable; relays may prune Kind 9735 zap receipts or go offline. A buyer who has already verified ownership on one device must be able to export their cryptographic license and import it onto another instance without relying on relays.

To prevent piracy / receipt sharing, the import flow enforces a Restoration Challenge: the importing user must cryptographically prove ownership of the buyer pubkey embedded inside the receipt.

Data Structure (.appweaver-license.json)

export type ExportedPurchaseBundle = {
  version: 1;
  app: string;          // Coordinate e.g. "32107:<author-pubkey>:<package-name>"
  buyer: string;        // Buyer pubkey (hex)
  exportedAt: number;   // Unix seconds
  offer: NostrEvent;    // Kind 8107 offer event signed by author
  receipt: NostrEvent;  // Kind 9735 zap receipt signed by provider
};

Flow & Verification Steps

sequenceDiagram
    autonumber
    actor User
    participant CLI as Plugin Manager / Web UI
    participant Validator as Offline Validator
    participant Signer as Buyer Signer (NIP-07 / NIP-46)
    participant CoreDB as Local DB (seenDb)
    participant Relays as Write Relays

    User->>CLI: Imports license bundle (.json)
    CLI->>Validator: Validate offer & receipt signatures offline
    CLI->>Validator: validateZapReceipt(receipt, buyer, offer)
    Note over Validator: Confirm valid amount, recipient, dates, and buyer pubkey
    CLI->>Signer: Issue Restoration Challenge (RestorationChallenge)
    Signer-->>CLI: Signed unpublished challenge event
    CLI->>Validator: validateAndConsume(challenge, signedEvent)
    CLI->>CoreDB: Store proof at plugins.purchase.<app>:<buyer>
    opt Re-seed relays
        CLI->>Relays: Broadcast Kind 8107 offer & Kind 9735 receipt
    end
    CLI-->>User: Purchase restored · App unlocked!

Tasks

2. Checkout DM Recourse & Refund Flow

Rationale & Design

When a buyer pays a Lightning invoice but the Lightning provider fails to publish or deliver the Kind 9735 receipt, the client cannot forge a receipt. Putting the buyer in direct contact with the author via an encrypted NIP-17 DM provides immediate recourse for manual refund or resolution.

DM Payload (Pre-filled)

AppWeaver Purchase Support Request
App: <title> (<coordinate>)
Purchase Attempt: <attemptId>
Invoice: <bolt11>
Timestamp: <created_at>

Payment was settled in my wallet, but the provider did not deliver a zap receipt. Please verify and assist or issue a refund.

Tasks

3. App Comments & Ratings (NIP-22 & NIP-32)

Rationale & Design

App reviews and ratings provide decentralized social proof and community feedback. By leveraging NIP-22 (Kind 1111 comments) and NIP-32 (Kind 1985 labels/ratings), AppWeaver maintains compatibility with existing Nostr app platforms (such as Zapstore).

Relay Strategy

To ensure discoverability and performance, comments and ratings are queried from:

Nostr Event Contracts

1. NIP-22 Comment (Kind 1111)

{
  "kind": 1111,
  "content": "Great app! Seamless setup.",
  "tags": [
    ["A", "32107:<author-pubkey>:<d-identifier>", "<relay-hint>"],
    ["p", "<author-pubkey>"],
    ["l", "5", "rating/5"]
  ]
}

2. Rating & Validation Rules

UI Specifications in /plugins list

  1. Catalog Card Badge:
    • 5 💬 · ⭐ 4.9/5 (42 reviews)
    • Displays count of comments (💬), average star score (⭐), and total reviews.
  2. Review Modal:
    • Header: Overall score and star display (including half-star SVG support for 4 < R < 5).
    • Ratings Breakdown: Histogram showing distribution of 5★, 4★, 3★, 2★, 1★.
    • Filters:
      • Sort by: Most Recent, Highest Rated, Lowest Rated (to surface complaints/issues).
      • Web of Trust (WoT) filter toggle: Filter reviews to show only ratings from followed profiles or trusted contacts.
    • Submit Review:
      • Star picker (1 to 5 stars).
      • Text area for optional review body.
      • Signs and broadcasts to catalog relays and author inbox relays.

Tasks