openreceive-rails 0.4.11 → 0.4.13

data/skills/integrate-openreceive/references/laravel.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Laravel)
 
-These directions describe OpenReceive 0.4.11.
+These directions describe OpenReceive 0.4.13.
 
 Add OpenReceive to a Laravel application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the package is on Packagist
@@ -35,71 +35,94 @@ The one required credential is a receive-only NWC code (Nostr Wallet Connect):
 a string from the merchant's wallet that can create invoices and read their
 status, and cannot spend. A swap provider (an "LSC" code) optionally lets the
 payer send USDT, USDC, ETH or SOL instead, converted into that same
-Lightning payment. You supply those credentials and three hooks — `authorize`,
+Lightning payment. Step 0 collects those credentials from the user; you write three hooks — `authorize`,
 `amountFor`, `onPaid` on one `App\OpenReceive\Host` class;
 OpenReceive supplies invoices, polling, settlement and the checkout UI. It never
 owns orders, users, prices, or fulfillment.
 
-## Step 0 — check the environment before you write code
-
-Do this before installing the package or editing files.
-
-1. Look for `NWC_URI` in this app's server environment — `.env`, the deploy
-   config, Forge/Vapor/Envoyer environment panels, whatever this app already
-   uses. If the app runs in a container the value is in none of those: ask the
-   running process (`docker exec <container> printenv NWC_URI`), because finding
-   the NAME in a compose file or `.env.example` proves nothing about the value.
-   Never print or echo the value itself; only report whether it is set. Check
-   for `LSC_URI_PRIMARY` in the same pass. Remember `php artisan config:cache`:
-   a cached config captured the values at cache time, and editing `.env`
-   afterwards changes nothing until the cache is rebuilt.
-
-   If OpenReceive is already installed here, `php artisan openreceive:doctor`
-   answers this whole step in one command — every credential as set/unset, the
-   host class and which hooks are still placeholders, the route mount, and the
-   wallet preflight. It never prints a value.
-2. If BOTH are already set — the common case in an existing app — say so and go
-   straight to the quickstart. Steps 3 and 4 are for an environment that is
-   missing one; do not stop to ask about altcoins that are already configured.
-   If only `NWC_URI` is set, Bitcoin already works: continue, and raise the
-   altcoin question at step 4 rather than blocking on it.
-3. If `NWC_URI` is missing or empty, stop and tell the user exactly what to
-   create:
-
-   > OpenReceive cannot issue an invoice without a receive-only NWC code. Get
-   > one at https://openreceive.org/get_a_nwc_code_to_receive_payments, then
-   > put `NWC_URI=<the code>` in this app's server environment — for most apps
-   > that is a `.env` file in the project root — and tell me when it's set.
-
-   Wait for the user before wiring OpenReceive; do not invent a placeholder
-   value. Waiting is not idleness: you may write `.env.example` with the
-   variable NAMES only (`NWC_URI=`, `LSC_URI_PRIMARY=`) so the merchant has a
-   file to copy, and keep building the parts of the host that do not touch
-   OpenReceive — the order model, the cart, the routes. The stop guards the
-   credential, not the rest of the app.
-4. If `LSC_URI_PRIMARY` was not already set, ask the user: "Do you want to
-   accept altcoins and stablecoins (USDT, USDC, ETH, SOL) as well as
-   Bitcoin?"
-
-   - Yes → send them to https://openreceive.org/set_up_swap_provider for a
-     swap-provider (LSC) code, to set as `LSC_URI_PRIMARY` in the same server
-     environment. Do NOT wait for it: no application code reads the value, so
-     the integration is identical with or without it — the engine picks it up
-     from the environment and swaps switch on. What a yes DOES change is the
-     refund route back (the swap non-negotiable below): build it as part of
-     this integration, not when the code arrives.
-   - No → skip it. Bitcoin over Lightning works with `NWC_URI` alone, and you
-     can add a swap provider later without changing application code.
-5. Check the environment again and confirm `NWC_URI` is present.
-   `LSC_URI_PRIMARY` may land later; swaps stay off until it does, and no code
-   changes when it arrives.
-6. If OpenReceive is ALREADY installed here, check the installed versions of
-   `openreceive/laravel` (`composer show openreceive/laravel`) and
-   `@openreceive/browser` against the release named at the top of this file.
-   The headless display models below do not exist in older versions, and the
-   first tile click throws with nothing saying why. Upgrade first — and if this
-   app runs in containers, rebuild the images: `vendor/` is baked into the
-   image, so an in-place `composer update` is undone by the next `compose up`.
+## Step 0 — ask for the two codes, one question at a time
+
+Before anything else, look at one file: the project's `.env`, if it exists.
+Read it only far enough to see whether `NWC_URI` and `LSC_URI_PRIMARY` are
+there and non-empty, and never print the values. A code that is already
+set is not asked for again; if both are set, skip to step 5
+(making the server load the file), then the quickstart.
+
+Otherwise your next action is a question to the user. Do not install the package,
+edit the app, write `.env.example`, or search anywhere else before asking
+it. Do not read deploy config (compose files, Forge/Vapor/Envoyer panels), Docker containers, or process environments, and never run
+`printenv`. A new shop has neither code yet: hunting for one burns the turn and
+can leak other secrets into the transcript.
+
+Two server-only URIs are needed before the quickstart:
+
+- `NWC_URI` — a receive-only Nostr Wallet Connect code,
+  `nostr+walletconnect://…`. Required for Bitcoin.
+- `LSC_URI_PRIMARY` — a Lightning Swap Connect URI,
+  `lightning+swapconnect://…`. Required for USDT, USDC, ETH and SOL. Skip it
+  only when the user says they want Bitcoin alone.
+
+The user never edits an environment file. They paste each code into the chat;
+you store it. Ask one question per message.
+
+1. **First message — the NWC code, and nothing else.** Ask for it and walk them
+   through getting it:
+
+   > To receive payments I need a receive-only wallet code. In Rizful: open
+   > the menu, tap NWC, choose Receive-only NWC code, and tap Copy
+   > (https://openreceive.org/get_a_nwc_code_to_receive_payments). If you would
+   > rather run your own wallet, Alby Hub works too: Connections → Add
+   > Connection → Read Only. Paste the code here and I will store it.
+
+   Do not mention `.env`, exports, or "tell me when it's set".
+2. **When they paste it.** If it does not start with `nostr+walletconnect://`,
+   ask them to copy the receive-only code again. Otherwise write
+   `NWC_URI=<paste>` into the project's `.env`, creating the file if needed.
+   Make sure `.gitignore` covers `.env` (and `.dockerignore`, if the app has
+   one). Never echo the value, commit it, or put it in client code. Reply only
+   that it is saved, then ask the next question.
+3. **Second message — swaps.** If the user already asked for stablecoins or
+   altcoins, skip the yes/no and go straight to the walkthrough. Otherwise ask
+   whether payers should also be able to pay with USDT, USDC, ETH or SOL. The
+   walkthrough:
+
+   > Go to https://lightning-swap.com, sign in for API keys, create a key, and
+   > copy the whole URI (https://openreceive.org/set_up_swap_provider). Paste
+   > it here and I will store it — or say "Bitcoin only" and I will continue
+   > without it.
+
+   Mention FixedFloat only if they already use it.
+4. **When they paste it.** If it does not start with
+   `lightning+swapconnect://`, ask them to copy it again. Otherwise add
+   `LSC_URI_PRIMARY=<paste>` to the same `.env`, without echoing it. Swaps
+   are now on, so build the refund route back (the swap non-negotiable below) as
+   part of this integration. If they chose Bitcoin only, leave
+   `LSC_URI_PRIMARY` unset and skip that route.
+5. **Make the server load the file — yourself.** Laravel loads
+   `.env` itself. If the app runs `php artisan config:cache`, run
+   `php artisan config:clear` (or re-cache) after writing the file: a cached
+   config never reads `.env` again. When the app is started with Docker
+   Compose, give the service `env_file: .env`. Restart the server after
+   writing the file.
+
+Do not invent placeholder URIs. Start the quickstart only once `NWC_URI` is
+saved and `LSC_URI_PRIMARY` is saved or explicitly declined. The first boot
+runs the receive-only preflight: if it reports spend methods such as
+`pay_invoice`, remove `NWC_URI` from `.env` and ask for a receive-only code
+again. Never set the spend-capable override to get past it.
+
+### Upgrading an existing install
+
+This is not the opening move of a new integration. When OpenReceive is ALREADY
+installed here, `php artisan openreceive:doctor` reports every credential as
+set/unset (never the value), the host class and any placeholder hooks, the
+route mount, and the wallet preflight. Check the installed
+`openreceive/laravel` (`composer show openreceive/laravel`) and
+`@openreceive/browser` against the release named at the top of this file: the
+headless display models below do not exist in older versions, and the first
+tile click throws with nothing saying why. Upgrade first — and if this app runs
+in containers, rebuild the images: `vendor/` is baked into the image, so an
+in-place `composer update` is undone by the next `compose up`.
 
 Only then start the quickstart.
 
@@ -302,12 +325,18 @@ passes. The page it comes from is https://openreceive.org/guides/quickstart-lara
 
 ## Laravel quickstart
 
-Requires PHP ≥ 8.2 (64-bit) and Laravel ≥ 11 (12 current). Extensions:
-`ext-gmp` is REQUIRED — the NWC transport's elliptic-curve math depends on it
-— plus `sodium`, `mbstring` and the `pdo_*` driver for your database
-(`pdo_pgsql`, `pdo_mysql` or `pdo_sqlite`). `php -m` lists what your build
-has; on Debian/Ubuntu it is `apt-get install php8.2-gmp`, in the official
-Docker image `docker-php-ext-install gmp`.
+Requires PHP ≥ 8.2 (64-bit) and Laravel ≥ 11 (12 current). You also need these
+PHP extensions:
+
+- `ext-gmp`, which is REQUIRED. The NWC transport's elliptic-curve math depends
+  on it.
+- `sodium` and `mbstring`.
+- The `pdo_*` driver for your database (`pdo_pgsql`, `pdo_mysql` or
+  `pdo_sqlite`).
+
+`php -m` lists what your build has. To add gmp on Debian/Ubuntu, run
+`apt-get install php8.2-gmp`. In the official Docker image, run
+`docker-php-ext-install gmp`.
 
 Add the Laravel package:
 
@@ -315,10 +344,10 @@ Add the Laravel package:
 composer require openreceive/laravel
 ```
 
-That is the whole install: `openreceive/laravel` depends on
-`openreceive/openreceive`, the engine, so the default wallet client — built from
-`NWC_URI` — works with nothing else added, and package discovery registers the
-service provider. Hosts that bring their own NWC client bind
+That is the whole install. `openreceive/laravel` depends on
+`openreceive/openreceive`, the engine. So the default wallet client works with
+nothing else added. It is built from `NWC_URI`. Package discovery registers the
+service provider. If your app brings its own NWC client, bind
 `OpenReceive\Nwc\ReceiveNwcClient` in the container instead.
 
 Then run:
@@ -330,35 +359,36 @@ php artisan migrate
 
 `openreceive:install` writes three files:
 
-- `config/openreceive.php` — the settings. The host hook is a CLASS NAME, not
-  a closure, because `php artisan config:cache` serializes this file and a
-  closure anywhere in it fails the cache;
-- `app/OpenReceive/Host.php` — the three hooks (`authorize`, `amountFor`,
-  `onPaid`), with the two generated placeholders wired and the fulfillment
-  note as comments;
-- `database/migrations/*_create_openreceive_tables.php` — one migration for
-  both engine tables (`openreceive_payments` and `openreceive_meta`). Its DDL
-  comes from the engine's `PaymentsSchema::statements()` for your connection's
-  driver — PostgreSQL, MySQL/MariaDB and SQLite — and `php artisan migrate` runs
-  it like any migration of your own; there is no second runner.
+- `config/openreceive.php`: the settings. The host hook is a CLASS NAME, not a
+  closure. `php artisan config:cache` serializes this file, and a closure
+  anywhere in it makes the cache fail.
+- `app/OpenReceive/Host.php`: the three hooks (`authorize`, `amountFor`,
+  `onPaid`), with the two generated placeholders wired in and the fulfillment
+  note as comments.
+- `database/migrations/*_create_openreceive_tables.php`: one migration for both
+  engine tables (`openreceive_payments` and `openreceive_meta`). Its DDL comes
+  from the engine's `PaymentsSchema::statements()` for your connection's
+  driver: PostgreSQL, MySQL/MariaDB or SQLite. `php artisan migrate` runs it
+  like any of your own migrations. There is no second runner.
 
 → [OpenReceive\Storage](https://openreceive.org/guides/api-reference.md#openreceivestorage)
 
 There is no Eloquent model for the engine's tables, and you do not write one.
 The engine owns the table's commit locking, write-once settlement, and
-reconciliation state machine. `reference` is indexed but not unique (a
-reference may have many historical attempts); `payment_hash` is globally unique.
+reconciliation state machine. `reference` is indexed but not unique, because
+one reference may have many historical attempts. `payment_hash` is globally
+unique.
 
 #### Fulfill exactly once
 
 Within OpenReceive's own settlement paths, `onPaid` runs at most once per
-reference: a second payment to a second invoice is recorded with
+reference. A second payment to a second invoice is recorded with
 `status_reason = "duplicate_settlement"` and never fulfills again.
 
-The one thing you own: **if anything other than OpenReceive can also fulfill
-an order** — an admin action, a second payment processor, a replayed job —
-those paths race each other, and `onPaid` must be idempotent. The generated
-`Host.php` spells this out and shows the guarded transition:
+One case is yours to handle. **If anything other than OpenReceive can also
+fulfill an order**, such as an admin action, a second payment processor, or a
+replayed job, those paths race each other. Then `onPaid` must be idempotent.
+The generated `Host.php` explains this and shows the guarded transition:
 
 ```php
 public function onPaid(PaymentSettlement $settlement): void
@@ -374,23 +404,28 @@ public function onPaid(PaymentSettlement $settlement): void
 }
 ```
 
-Delivery is at-least-once: `onPaid` runs inside the settlement transaction,
-and an exception rolls it back for the next pass to retry. Keep it to database
-writes on the order — an email or webhook sent from here would survive the
-rollback and go out again. The `'paid'` transition above is the flag; let your
-own job drain it after commit, or implement `OpenReceive\Hosts\AfterPaid`:
-its `afterPaid(PaymentSettlement $settlement)` runs after COMMIT, best-effort,
-for the same first settled attempt — the place for `FulfillOrder::dispatch(…)`
-or an event. And open no `DB::transaction()` of your own inside `onPaid`: the
-engine already holds the transaction on this connection, and PDO refuses a
-nested `BEGIN`.
-
-**A query-builder `update()` fires no model events.** That is the point — it is
-one conditional `UPDATE`, so the claim is atomic and there is no model code
+Delivery is at-least-once. `onPaid` runs inside the settlement transaction. If
+it throws, the transaction rolls back and the next pass retries. So keep
+`onPaid` to database writes on the order. An email or webhook sent from here
+would survive the rollback and go out again. The `'paid'` transition above is
+the flag. Drain it after commit in one of two ways:
+
+- Let your own job drain it.
+- Implement `OpenReceive\Hosts\AfterPaid`. Its
+  `afterPaid(PaymentSettlement $settlement)` runs after COMMIT, best-effort,
+  for the same first settled attempt. Put `FulfillOrder::dispatch(…)` or an
+  event there.
+
+Do not open a `DB::transaction()` of your own inside `onPaid`. The engine
+already holds the transaction on this connection, and PDO refuses a nested
+`BEGIN`.
+
+**A query-builder `update()` fires no model events.** That is intended. It
+runs one conditional `UPDATE`, so the claim is atomic and no model code runs
 between the check and the write. It also means no observer, no `saved` event
-and no `Model::updated` listener runs, which is fine for a job draining the
-flag and useless for a model that owns the transition through events. If yours
-does, take a row lock for the duration instead:
+and no `Model::updated` listener runs. That is fine for a job that drains the
+flag. It does not work for a model that owns the transition through events. If
+yours does, take a row lock for the duration instead:
 
 ```php
 public function onPaid(PaymentSettlement $settlement): void
@@ -403,26 +438,29 @@ public function onPaid(PaymentSettlement $settlement): void
 }
 ```
 
-**Unlocking a download works the same way.** If what the payer bought is a
-file, do not unlock it in the browser: gate the download route on the paid
-order row — `Order::where('id', $id)->where('user_id', $request->user()->id)->where('state', 'paid')->firstOrFail()`
-or a 404 — and serve the file only then. The `'paid'` written above is the
-unlock; the client never decides an order was fulfilled, it re-reads the row.
-Buy a Button's `ShopController::download` is this in twenty lines.
-
-Both shapes are idempotent, and both are correct. They differ only in whether
-your model layer gets to run: the query-builder `update()` skips it and is the
-right default; the row lock holds the row for the duration of the method and
-is what you want when the transition has to go through your model. The
-generated fulfillment note says the same thing — if your fulfillment is a
-read-modify-write that cannot be expressed as one conditional `UPDATE`, take
-the lock.
-
-A runnable illustration of this boundary — not a template to copy models from —
-is Buy a Button
-(`examples/buttons/server/laravel`).
-It has products, visitors, and orders, with the three hooks as the only bridge.
-Map that shape onto the models in THIS app.
+**Unlocking a download works the same way.** If the payer bought a file, do not
+unlock it in the browser. Gate the download route on the paid order row, and
+serve the file only if that row exists:
+`Order::where('id', $id)->where('user_id', $request->user()->id)->where('state', 'paid')->firstOrFail()`,
+or a 404 otherwise. The `'paid'` written above is the unlock. The client never
+decides that an order was fulfilled. It re-reads the row. Buy a Button's
+`ShopController::download` does this in twenty lines.
+
+Both shapes are idempotent and correct. They differ only in whether your model
+layer runs:
+
+- The query-builder `update()` skips the model layer. It is the right default.
+- The row lock holds the row for the duration of the method. Use it when the
+  transition has to go through your model.
+
+The generated fulfillment note says the same thing. If your fulfillment is a
+read-modify-write that one conditional `UPDATE` cannot express, take the lock.
+
+Buy a Button
+(`examples/buttons/server/laravel`)
+is a runnable illustration of this boundary. It is not a template to copy
+models from. It has products, visitors, and orders, and the three hooks are the
+only bridge. Map that shape onto the models in THIS app.
 
 ### Add wallet credentials
 
@@ -436,31 +474,37 @@ LSC_URI_BACKUP=
 ```
 
 1. Get a receive-only NWC code from a compatible wallet
-   ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments))
-   → `NWC_URI`.
-2. Optionally set up a [swap provider](https://openreceive.org/set_up_swap_provider)
-   → `LSC_URI_PRIMARY` (and `LSC_URI_BACKUP` if you have one).
-
-Never put these values in browser code. Your application refuses to start if
-the NWC code also advertises spend methods such as `pay_invoice`; mint a
-receive-only code ([Security](https://openreceive.org/guides/security.md)).
-
-Under `php artisan config:cache` Laravel never reads `.env` at runtime — the
-values are captured when you cache, as for every other Laravel secret — so
+   ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments)).
+   Put it in `NWC_URI`.
+2. Optional: set up a [swap provider](https://openreceive.org/set_up_swap_provider).
+   Put its connection string in `LSC_URI_PRIMARY`, and a second one in
+   `LSC_URI_BACKUP` if you have one.
+
+Never put these values in browser code. Your app refuses to start if the NWC
+code also advertises spend methods such as `pay_invoice`. Create a
+receive-only code instead ([Security](https://openreceive.org/guides/security.md)).
+
+Under `php artisan config:cache`, Laravel never reads `.env` at runtime. The
+values are captured when you cache, as with every other Laravel secret. So
 re-run `config:cache` after changing one. The engine redacts connection
-strings in every log line, and `php artisan openreceive:doctor` prints each
-variable as set/unset only.
+strings in every log line. `php artisan openreceive:doctor` prints each
+variable only as set or unset.
 → [Environment variables](https://openreceive.org/guides/environment-variables.md).
 
 ### Configure the host hooks
 
 `app/OpenReceive/Host.php` needs three things: authorization, the trusted
-price, and fulfillment. All three receive the `reference` — a string you
-choose, and the fulfillment identity: your order id, one per thing you
-fulfill, created before checkout, kept across retries, never reused.
-OpenReceive never looks inside it, but `onPaid` commits fulfillment once per reference, a new
-checkout under a reference that already settled is refused with 409, and a
-fresh id per page load lets one order be paid twice.
+price, and fulfillment. All three receive the `reference`. This is a string you
+choose, and it is the fulfillment identity. Use your order id:
+
+- one per thing you fulfill,
+- created before checkout,
+- kept across retries,
+- never reused.
+
+OpenReceive never looks inside it. But `onPaid` commits fulfillment once per
+reference, and a new checkout under a reference that already settled is
+refused with 409. A fresh id per page load would let one order be paid twice.
 
 ```php
 <?php
@@ -521,67 +565,74 @@ final class Host implements OpenReceiveHost
 }
 ```
 
-`config/openreceive.php` names that class (`'host' => App\OpenReceive\Host::class`)
-and the provider resolves it from the container, so it may take constructor
-dependencies. `onPaid` runs inside the settlement transaction, only for the
-first settled attempt for a reference.
+`config/openreceive.php` names that class
+(`'host' => App\OpenReceive\Host::class`). The provider resolves it from the
+container, so it may take constructor dependencies. `onPaid` runs inside the
+settlement transaction, only for the first settled attempt for a reference.
 → [OpenReceive\Host](https://openreceive.org/guides/api-reference.md#openreceivehost) ·
 [the authorize context](https://openreceive.org/guides/api-reference.md#the-authorize-context-php)
 
-The routes mount under `config('openreceive.route_prefix')` (`openreceive`) and
-`config('openreceive.middleware')` (`['web']`). The `web` group is how the
-engine picks up your application's session and CSRF protection: Laravel's
-`VerifyCsrfToken` reads `X-CSRF-TOKEN`, and the checkout client sends it from
-`<meta name="csrf-token" content="{{ csrf_token() }}">` automatically — keep
-that tag in the layout that renders the checkout. The same group brings every
-middleware it carries; a global `auth` redirect on the `web` group would send
-the engine's JSON routes to a login page too, so keep such guards on your own
-route groups, not on `web` itself.
-
-The generated `Host.php` ships `use LoggingOnPaid;` — a placeholder that only
-logs the settlement and fulfills nothing. Replace it with your real fulfillment
-(as above); the engine warns every time your application boots while the
-placeholder is still there, because orders would otherwise be recorded as
-settled without ever being fulfilled. The same applies to `use
-AllowAllAuthorize;`, the generated allow-all placeholder: it treats
-possession of the reference as authorization, which is safe only while
-references are unguessable, and the engine warns at boot until you replace it
-with your own ownership check (as above). Replace both, not just `onPaid`.
-
-The amount always comes from your own order record; payer-supplied amounts are
+The routes mount under `config('openreceive.route_prefix')` (`openreceive`),
+with the middleware in `config('openreceive.middleware')` (`['web']`). The
+`web` group is how the engine picks up your application's session and CSRF
+protection. Laravel's `VerifyCsrfToken` reads `X-CSRF-TOKEN`. The checkout
+client sends it automatically from
+`<meta name="csrf-token" content="{{ csrf_token() }}">`, so keep that tag in
+the layout that renders the checkout.
+
+The `web` group also brings every middleware it carries. A global `auth`
+redirect on the `web` group would send the engine's JSON routes to a login page
+too. Keep such guards on your own route groups, not on `web` itself.
+
+The generated `Host.php` ships two placeholders. Replace both, not just
+`onPaid`:
+
+- `use LoggingOnPaid;` only logs the settlement and fulfills nothing. Replace
+  it with your real fulfillment (as above). Until you do, orders would be
+  recorded as settled without ever being fulfilled, so the engine warns every
+  time your application boots.
+- `use AllowAllAuthorize;` allows everything. It treats possession of the
+  reference as authorization, which is safe only while references are
+  unguessable. The engine warns at boot until you replace it with your own
+  ownership check (as above).
+
+The amount always comes from your own order record. Payer-supplied amounts are
 rejected. The engine's `PaymentRepository` interface remains the escape hatch
-for custom-storage applications and is not part of the quickstart.
-
-For public web shops, opt into the per-IP invoice cap with
-`'rate_limiting' => true`; leave it off (the default) when many payers share
-one IP. The client IP is `$request->ip()`, so Laravel's `TrustProxies` decides
-who the payer is behind a proxy. → [Rate limiting](https://openreceive.org/guides/rate-limiting.md)
-
-In production the engine builds the wallet client — and runs its receive-only
-preflight — eagerly when your application boots, so a missing `NWC_URI`, a
-dead relay, or a spend-capable wallet stops the deploy instead of surfacing as
-customer-facing 500s on the first checkout. Outside production (tests,
-consoles) the client is built lazily so no live wallet is needed.
-
-PHP builds the whole engine again on every request, so that same preflight
-would run per request under PHP-FPM or Apache; the package remembers the
-wallet's info event in your default cache store for
-`config('openreceive.wallet_info_cache_seconds')` (600) so a checkout request
-costs one relay round trip, not two.
+for apps with custom storage. It is not part of the quickstart.
+
+For public web shops, turn on the per-IP invoice cap with
+`'rate_limiting' => true`. Leave it off (the default) when many payers share
+one IP. The client IP is `$request->ip()`, so behind a proxy Laravel's
+`TrustProxies` decides who the payer is. → [Rate limiting](https://openreceive.org/guides/rate-limiting.md)
+
+In production, the engine builds the wallet client when your app boots. It
+also runs the receive-only preflight right away: it reaches the wallet and
+checks that the code cannot spend. A missing `NWC_URI`, a dead relay, or a
+spend-capable wallet then stops the deploy. Otherwise those problems would
+show up as 500 errors for customers on the first checkout. Outside production
+(tests, consoles), the engine builds the client lazily, on first use, so no
+live wallet is needed.
+
+PHP builds the whole engine again on every request. Under PHP-FPM or Apache,
+that same preflight would then run per request. To avoid that, the package
+caches the wallet's info event in your default cache store for
+`config('openreceive.wallet_info_cache_seconds')` (600). A checkout request
+then costs one relay round trip, not two.
 
 ### Render the checkout
 
-Serve the compiled `styles.css` without Tailwind processing: import it from
-JavaScript (with a CSS-capable bundler) or use a plain `<link rel="stylesheet">`.
-Do not `@import` it into the host Tailwind entry. Its zero-specificity rules
-allow host styles to override checkout styles; scoping does not prevent that.
+Serve the compiled `styles.css` without Tailwind processing. Either import it
+from JavaScript (with a CSS-capable bundler) or use a plain
+`<link rel="stylesheet">`. Do not `@import` it into your Tailwind entry. Its
+rules have zero specificity, so your own styles can override checkout styles.
+Scoping does not prevent that.
 
-The engine serves JSON checkout routes only — rendering is your view. Any
-OpenReceive frontend package works against the `/openreceive` mount; the
-smallest is the custom element (its default `prefix` is already
-`/openreceive`, and the package ships a self-contained `styles.css`; it is
-scoped to what OpenReceive renders). Laravel ships Vite, so the package installs like any
-other frontend dependency:
+The engine serves JSON checkout routes only. Your view does the rendering. Any
+OpenReceive frontend package works against the `/openreceive` mount. The
+smallest is the custom element. Its default `prefix` is already
+`/openreceive`. The package ships a self-contained `styles.css`, scoped to what
+OpenReceive renders. Laravel ships Vite, so the package installs like any other
+frontend dependency:
 
 ```sh
 npm install @openreceive/elements
@@ -605,32 +656,32 @@ defineElements();
 ```
 
 The element creates the checkout for `reference`, then renders and polls
-itself. React/Vue/Svelte/Angular apps use the matching wrapper package instead
-— same props and defaults ([Frontend checkout](https://openreceive.org/guides/frontend-checkout.md)). Build a
-custom checkout only if this app cannot use a drop-in; then
-`@openreceive/browser/headless` is the API
-([Headless checkout](https://openreceive.org/guides/headless-checkout.md)).
+itself. React, Vue, Svelte, and Angular apps use the matching wrapper package
+instead, with the same props and defaults
+([Frontend checkout](https://openreceive.org/guides/frontend-checkout.md)). Build a custom checkout only if
+this app cannot use a drop-in. In that case `@openreceive/browser/headless` is
+the API ([Headless checkout](https://openreceive.org/guides/headless-checkout.md)).
 
 Everything the checkout draws ships inside the JavaScript: the payment-method
 icons, the wallet logos and the pay tutorials. There is no image file to copy
 or serve and no asset option to set. Deploy your normal JavaScript and CSS
 build output, including any generated JavaScript chunks. Bundlers with code
-splitting can defer tutorial screenshots until first open; single-file builds
-(including the standalone checkout) include them upfront. If your
-Content-Security-Policy has a strict `img-src`, allow `data:`
+splitting can load tutorial screenshots only when a tutorial is first opened.
+Single-file builds, including the standalone checkout, include them upfront. If
+your Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
-Then open the checkout in a browser, confirm the payment-method icons and
+Then open the checkout in a browser. Confirm the payment-method icons and
 wallet logos render, and open a wallet's pay tutorial to check its screenshots.
-If an image is missing, inspect the console for CSP violations and the Network
+If an image is missing, check the console for CSP violations and the Network
 panel for failed JavaScript chunks. Allow `data:` in `img-src` and deploy the
 complete build output. Do not add image routes, copy package source images, or
 use registry `icon_path` / tutorial `path` keys as browser URLs.
 
 **No npm in this project?** Every GitHub release attaches
-`standalone-checkout-<version>.tar.gz`: one self-registering ESM file, its
-stylesheet and a `MANIFEST.json` of hashes. Unpack it into
-`public/openreceive/` and the same element needs two tags:
+`standalone-checkout-<version>.tar.gz`. It holds one self-registering ESM file,
+its stylesheet and a `MANIFEST.json` of hashes. Unpack it into
+`public/openreceive/`, and the same element needs just two tags:
 
 ```blade
 <link rel="stylesheet" href="/openreceive/openreceive-checkout.css" />
@@ -639,7 +690,7 @@ stylesheet and a `MANIFEST.json` of hashes. Unpack it into
 <openreceive-checkout reference="{{ $order->id }}"></openreceive-checkout>
 ```
 
-`MANIFEST.json` carries the version and a SHA-256 per file; keep the tarball
+`MANIFEST.json` carries the version and a SHA-256 per file. Keep the tarball
 version in step with the Composer package.
 
 ### Reconciliation
@@ -655,33 +706,40 @@ load:
 php artisan openreceive:notifications
 ```
 
-It listens for the wallet's NWC-02 `payment_received` notifications and runs
-a periodic reconcile pass in the same process — one per deployment, not per
-web instance. `php artisan openreceive:reconcile` is the one-shot pass if you
-want to drive one yourself, and `php artisan openreceive:doctor` reports every
-credential as set/unset, the host and its placeholders, the route mount and
-the wallet preflight.
+The worker listens for the wallet's NWC-02 `payment_received` notifications.
+The same process also runs a periodic reconcile pass. Run one per deployment,
+not one per web instance.
+
+Two more commands help:
+
+- `php artisan openreceive:reconcile` runs one pass, if you want to drive it
+  yourself.
+- `php artisan openreceive:doctor` reports every credential as set or unset,
+  the host and its placeholders, the route mount, and the wallet preflight.
 
 ### Swap secrets
 
-The package recognizes `LSC_URI_PRIMARY` and `LSC_URI_BACKUP` using the
-shared [Lightning Swap Connect](https://openreceive.org/guides/lightning-swap-connect.md) vectors: setting either one
-auto-builds the matching provider, so an app that wants swaps only supplies the
-connection strings ([Environment variables](https://openreceive.org/guides/environment-variables.md)). The
-`openreceive.swap_providers` container binding is the override knob — bind a
-list of your own adapters to replace the auto-built set, or `[]` to disable
-swaps.
+The package recognizes `LSC_URI_PRIMARY` and `LSC_URI_BACKUP`, using the
+shared [Lightning Swap Connect](https://openreceive.org/guides/lightning-swap-connect.md) vectors. Setting
+either one auto-builds the matching provider. So an app that wants swaps only
+supplies the connection strings
+([Environment variables](https://openreceive.org/guides/environment-variables.md)). To override this, use the
+`openreceive.swap_providers` container binding. Bind a list of your own
+adapters to replace the auto-built set, or `[]` to disable swaps.
 
-One `openreceive_payments` row holds at most one provider order in its
+One `openreceive_payments` row holds at most one provider order, in its
 server-only `swap_data`. The engine never returns `swap_data` from its routes
 or writes it to a log. Do not select it into your own API, serialize it, or
-log it; it may contain a provider credential.
+log it. It may contain a provider credential.
 
 **Setting either connection string commits you to refunds.** A swap deposit can
-arrive short or late, which leaves it `refund_required` at the provider with
-only your UI able to claim it — and the payer claims it on a second visit,
-after leaving your page for an address in another wallet. That needs a
-per-order URL your app serves, a route that restores the order behind it, and
-something that restores the ATTEMPT, since `/checkouts/prepare` returns none.
-[Swap refunds](https://openreceive.org/guides/swap-refunds.md) is the whole of it; read it before you set
+arrive short or late. The provider then marks it `refund_required`, and only
+your UI can claim it. The payer claims it on a second visit, after leaving your
+page to get an address in another wallet. That needs three things:
+
+- a per-order URL your app serves,
+- a route that restores the order behind it,
+- something that restores the ATTEMPT, since `/checkouts/prepare` returns none.
+
+[Swap refunds](https://openreceive.org/guides/swap-refunds.md) covers all of it. Read it before you set
 `LSC_URI_PRIMARY`.