OpenReceive v0.2.1

First test publish to NPM and RubyGems

Second audit sweep

A second full-repo audit fixed 24 correctness bugs, removed 22 trust-model
violations, closed 7 wrapper-parity gaps, and finished the order_id →
reference rename. The behavior changes worth knowing:

• Settlement. A notified payment_received now checks pendingness BY HASH
  (payments.findPendingAttempt) instead of membership in the oldest-200
  batch, so a notified settlement no longer waits for a backlog to drain.
  A reconcile result that reports settled with no paidAt is reported as a
  failure instead of skipped silently, and the request-path reconcile pass now
  runs AFTER the body's cheap refusals so an anonymous garbage POST cannot
  claim the gate. Rails exempts unauthenticated GET /rates from the pass,
  matching the JS handler.
• Wallet scans. A list_transactions page whose rows are all unusable now
  fails the scan in both engines rather than reading as an empty wallet — an
  empty-looking scan at expiry+grace closes unpaid attempts. Within a page, a
  row whose PRESENT fields cannot be read (a non-hex payment_hash, an
  unparsable amount) is skipped and counted; absent fields still mean absent.
• Invoice expiry. A wallet that clamps expiry no longer fails every
  checkout: the ledger stores the wallet's own expires_at and logs
  checkout.invoice_expiry.adjusted. A caller-supplied expirySeconds (only
  the swap path sets one) stays a hard floor, and only when the wallet comes
  in short.
• Swaps. Provider transport failures on /swaps, /swaps/status and
  /swaps/refunds map to 502/503 instead of a generic 500. A provider order
  without an expiry fails the create rather than inventing a 10-minute window,
  and a provider amount that is present-but-unparsable throws instead of
  vanishing. When every configured provider fails its catalog fetch, methods
  report provider_unreachable, not provider_unconfigured. A 429 backoff no
  longer resets when the weight window rolls.
• Checkout UI. startSwap now quotes before it starts, in the SHARED
  session, so React and the custom element behave identically — an
  out-of-range amount is an accepted-range panel in both, built from one
  createSwapUnavailableModel. Expired-mid-swap keeps the wizard in both. The
  refund review gate is explicitly client-side: refund_nonce and
  refund_nonce_expires_at are gone from the browser wire types (the server
  never sent them), and SwapDisplayModel carries refundAllowed: boolean.
  A swap deposit QR that cannot encode its amount now throws instead of
  silently degrading to an amount-less payment URI.
• Renames. Option types match their factories (CreateHostOptions,
  CreateStackOptions, CreateHttpHandlerOptions, DefineElementsOptions,
  …). @openreceive/browser exports createLightningUri / createQrSvg /
  createQrPngDataUrl under those names on both entry points, and no longer
  exports the internal readJsonResponse. The adapter packages no longer
  re-export the 14 generated Wire* body types (still on
  @openreceive/http). Ad-hoc app-route console loggers are
  createAppConsoleLogger / createAppBrowserConsoleLogger, so Host names
  only the persistence object.
• New. createStack takes onBootFailure, and a failed boot answers
  503 WALLET_UNAVAILABLE in the error contract instead of rethrowing the raw
  cause. payInAssetNetwork in @openreceive/core owns the
  pay_in_asset → network split that four call sites re-derived.

ORM handles wrap in one call: knexDb, prismaDb, typeOrmDb, sequelizeDb

• @openreceive/http ships a named SqlAdapter factory per ORM whose handle
  createSqlPayments cannot accept directly. The parameter types are
  structural (no ORM dependency); dialect stays a required argument. The
  guide's copy-paste recipes are gone — and the shipped prismaDb fixes a bug
  the Prisma recipe carried: only ^select statements ran through
  $queryRawUnsafe, so an UPDATE … RETURNING fulfillment claim (the
  guide's own onPaid example) lost its rows and never fulfilled.
• sequelizeDb closes the last gap: Sequelize was a first-class scaffold flag
  whose only documented wiring was "open a second pg Pool to the same
  database, or hand-roll an adapter". It binds parameters through Sequelize's
  bind option and threads the managed transaction into every statement
  inside it — Sequelize carries the transaction on the same instance, so a
  hand-rolled adapter that missed that ran settlement outside the transaction.
• The scaffold's wiring guide no longer prints hand-rolled SqlAdapter
  snippets for Prisma/Knex/TypeORM/Sequelize; each section is now the shipped
  factory in one line.
• npm run test:orms proves the factories against the real ORMs: knex,
  typeorm, and prisma (7, via its better-sqlite3 driver adapter) each drive
  the payments repository — commit, write-once settlement, reconcile-gate
  CAS — on sqlite. Weekly orm-adapters job in demos.yml; the ORMs are
  devDependencies only. The no-database-driver gate now checks the root
  workspace manifest on its runtime dependencies (package and example
  manifests stay strict in full) so the lane's sqlite driver can exist at
  dev time.

The browser's swap requests no longer throw Illegal invocation

• Every swap route call (/swaps, /swaps/quote, /swaps/status,
  /swaps/refunds) invoked the caller's fetch as a method of its options
  object, rebinding this — and window.fetch, the default, throws
  Illegal invocation for any this but the window. The swap flow was
  broken in real browsers across all four wrappers; the e2e swap specs catch
  it now. Checkout and status requests always bare-called a local and were
  unaffected.

Cross-site requests are refused by the handler; the Rails engine inherits protect_from_forgery

• Every body-bearing route now answers 415 for a body that is not
  application/json and 403 for a request the browser labels
  Sec-Fetch-Site: cross-site, in both engines and before authorize runs. A
  cross-site form cannot set a JSON content type, a cross-origin fetch that
  does is CORS-preflighted (never answered), and the Sec-Fetch-Site gate
  covers the remaining no-cors forgery. Golden vectors 11 and 12 pin
  both refusals; vectors may now declare extra request headers.
• OpenReceive::ApplicationController no longer calls
  skip_forgery_protection: the host's protect_from_forgery applies to the
  engine's routes as it does to the host's own, and a failed check is the
  shared 403 instead of an opaque 500. The browser client sends
  X-CSRF-Token from <meta name="csrf-token"> on every request when the
  page renders one (csrf_meta_tags), from one shared requestHeaders
  helper; a host headers value still wins. The Rails demo drops its
  :null_session override and runs Rails' default.

reference, not order_id: the host's order is not part of the story

• The grouping key OpenReceive stores is now called reference everywhere —
  the openreceive_payments column, every HTTP request and response body,
  the browser snapshots, the <Checkout reference> prop (route-reference
  for the element wrappers), AuthorizeResource.reference, and the
  settlement passed to onPaid / config.on_paid (PaymentSettlement,
  formerly OrderSettlement). It is a string the host chooses — its order
  id, one per payable thing and never reused — that OpenReceive groups
  attempts under and fulfills at most once. Rails hosts recreate the engine tables
  (bin/rails db:reset on a development database).
• loadOrder + amountForOrder collapsed into one hook: amountFor(reference)
  returns the trusted price or null for a 404 (Rails: config.amount_for,
  nil). The host is consulted only where a price is minted or quoted; status
  polls and refunds are answered from OpenReceive's own rows. This also fixes
  the Rails engine selecting attempts by the loaded object's .id rather than
  the id it was given, which broke hosts whose lookup key was not their
  primary key.
• openreceive:install no longer takes --order-model; the generated
  initializer names no model. authorize defaults to possession of the
  reference and config.amount_for is left for you to write (the engine
  refuses to serve checkouts until it is set).
• The fulfillment note rendered into every scaffolded migration, the Rails
  initializer, and the wiring guide now says only what OpenReceive guarantees
  about onPaid and what the host must guarantee. Its "optional foreign key"
  recipe is gone, as is every "OpenReceive never reads, locks, or joins your
  order table" paragraph in the docs and source — there is no relationship to
  explain. npx openreceive scaffold payments rejects the long-removed
  --order-model/--order-table/--order-id-type/--skip-foreign-key flags
  as plain unknown options.

One subpath under the UI: @openreceive/browser/headless

• @openreceive/browser/internal is gone. It was public API with a
  discouraging name — 130 values and 46 types that @openreceive/react,
  @openreceive/elements, and the wrappers imported and nothing documented.
  Those names now live on ./headless, the one curated, documented surface
  the renderers and headless integrations share; 15 names only tests used are
  no longer exported. npm run check:example-imports had nothing left to
  reject and is removed.
• docs/internal/display-boundary-findings.md was deleted. Its
  display-boundary rule (formatters throw, display boundaries blank) is
  superseded by the AGENTS.md trust model: our own server, the configured NWC
  wallet, and the configured swap provider are trusted, and a throw in a
  checkout panel is our own API surfacing, not a display-boundary bug class to
  defend against.

The OpenReceive prefix is gone; the import path is the namespace

• 415 exported and internal names drop the OpenReceive / openReceive
  prefix: createOpenReceiveHttpHandler → createHttpHandler,
  createOpenReceiveHost → createHost, createOpenReceiveStack →
  createStack, OpenReceiveHttpError → HttpError,
  OpenReceiveServiceError → ServiceError, OpenReceiveDecimalError →
  DecimalError, openReceiveCheckoutLabels → checkoutLabels,
  formatOpenReceiveMsats → formatMsats, OpenReceiveWire* → Wire*, and
  so on, one rule throughout. Kept, each for a reason: OPENRECEIVE_*
  constants (they read as config keys) and the custom-element tag names;
  OpenReceive, createOpenReceive, and OpenReceiveError (OpenReceive is
  the noun there, and Error is taken); the three mounts openReceiveExpress,
  openReceiveFastify, openReceiveNextHandlers; and markOpenReceivePaidOnce
  / createOpenReceiveCheckoutElementAttributes, which sit beside an
  unprefixed sibling that means something else. Where the bare name was
  already taken the rename picks a clearer one: openReceiveRoutes →
  checkoutRoutes, reconcileOpenReceivePayments → reconcileHostPayments,
  openReceiveClientIp → resolveClientIp.
• status is deriveStatus (its only in-tree caller already renamed it on
  import), and OpenReceiveFiatAmount — a currency-tagged decimal that is
  fiat OR BTC/SAT — is MoneyAmount.

Fewer exports: what nothing outside the package reaches for

• 51 names leave the public surface because no guide, example, smoke check,
  or other package named them — only tests, which now read the source
  modules directly. @openreceive/node lists its public types explicitly
  instead of export type *, so its service-internal types
  (NodeOptions, OpenReceiveServiceContext, ResolvedCreateAmount,
  NormalizedCreateCheckoutRequest) stay internal. Gone, by package:
  • core: the price-feed tuning constants (OPENRECEIVE_PRICE_FEED_*,
    OPENRECEIVE_*_PRICE_FEED_URL, OPENRECEIVE_INVOICE_QUOTE_TTL_SECONDS,
    OPENRECEIVE_STATIC_BTC_FIAT_RATES) — spec/data/rates/price-sources.json
    is their contract; the *_URL_ENV names stay.
  • node: normalizeNwcWalletError, summarizeWalletCapabilities, the LSC
    env helpers (parseLscUri, readLscConnectionsFromEnvironment,
    createLscSwapProvidersFromEnvironment, LSC_ENV_NAMES,
    LSC_URI_PROTOCOL), the log-level helpers and
    createOpenReceiveConsoleLogger, requireNwcFromEnvironment,
    SPEND_CAPABILITY_WARNING_DELAY_MS, isOpenReceiveSwapTerminalState.
  • http: resolveSqlAdapter, openReceivePaymentInsert,
    openReceiveClientIpBucket, OPENRECEIVE_DEFAULT_IP_RATE_LIMIT_PER_HOUR,
    OPENRECEIVE_ATTEMPT_REUSE_BUFFER_SECONDS.
  • browser: the console-logger level helpers and
    createOpenReceiveBrowserConsoleLogger.
  • elements: renderCheckoutCreatingHtml, renderOpenReceivePaymentWizardHtml,
    wireTransactionDetailsCopy, OpenReceiveElementsSwapOption.
  • react: useCheckoutResume and its option/result types (unused,
    undocumented); CheckoutEventHandlers.
  • provider-data: listCryptoRoutes, getCryptoRoute,
    listDisqualifiedProviders (no caller anywhere).

checkPayment is gone; reconcilePayments is the only wallet-history read

• service.checkPayment, @openreceive/core's checkPayment, and Ruby
  Service#check_payment were a one-hash wrapper around the same
  list_transactions walk reconcilePayments already runs. The mounted
  POST /payments/check route never called them. Check one invoice with
  reconcilePayments({ attempts: [{ paymentHash, createdAt }] }). A truncated
  walk omits that hash (retry next pass) instead of throwing
  WALLET_UNAVAILABLE.

The all-in-one options say which mode they are

• createOpenReceiveStack and the adapters' all-in-one form take
  wallet: { nwc } | { service } and storage: { db, onPaid, tableName? } | { payments, onPaid } instead of five optional, mutually-constrained
  top-level keys. onPaid's parameter type follows the storage branch, the
  "exactly one of nwc or service" runtime check is gone (the type says so),
  and the cast that once landed a custom repository in db mode is gone with
  it.

The spec's own response shapes are closed

• PaymentMethod, FiatQuote, and PaymentDetails are named, closed
  component schemas; PrepareCheckoutResponse, Checkout, and
  PaymentCheck reference them instead of additionalProperties: true.
  Swap and SwapCheckout compose an open SwapBase and close themselves
  with unevaluatedProperties: false (OpenAPI 3.1 is JSON Schema 2020-12),
  replacing the hand-copied field list. The generated wire types follow
  (OpenReceiveWirePaymentMethod, OpenReceiveWireFiatQuote,
  OpenReceiveWirePaymentDetails; every wire type is now closed).

One status vocabulary; one error vocabulary per layer

• TransactionSettlementStatus (pending | settled | expired | failed) is
  the base every status extends: PaymentStatus adds not_found,
  OpenReceiveAttemptStatus adds attention, the browser's Status is
  exactly the base. The relationship is now in the types, not only the prose.
  TransactionSettlementDetection is readonly like everything else.
• The host's authorize() returning false is 403 FORBIDDEN (was
  UNAUTHORIZED, which in NIP-47 means the key has no wallet). The HTTP
  error vocabulary drops INSUFFICIENT_BALANCE and PAYMENT_FAILED — a
  receive-only library can never send them — and a wallet's own FORBIDDEN
  still normalizes to RESTRICTED. Both engines and the vectors move
  together; Ruby's UnauthorizedError is ForbiddenError.

Maintenance

• swap.providers is swap.provider + swap.failoverProviders: the name
  now says what the code always did — failovers are consulted only when the
  primary throws, never to fill assets it omits.

• prepareCheckout takes PrepareCheckoutOptions (order id, prefix, fetch,
  headers): the type no longer accepts a memo it silently dropped.

• The spend-capability warning no longer pauses boot (the 5-second delay
  defaults to 0; nothing in the repo constructs a wallet client from a
  terminal, so there was no CLI site to keep it). The stack's boot-failure
  line logs the error message, not the object and its raw cause.

• @openreceive/http describes itself as framework-neutral over Web
  Request/Response and built on the Node runtime. openReceivePaymentsIndexName
  measures identifiers with .length (they are ASCII by construction) and
  keeps the digest that makes truncated names unique.

• fixedfloat.ts (1,134 lines, nine jobs) is six modules along the seams
  its siblings already used — transport, currencies, orders, quote, field
  readers, and the provider assembly. Move-only: the conformance vectors
  prove it.

• The hand-rolled Keccak-256 in the Ruby gem now has known-answer tests
  (NIST/Keccak digests and the EIP-55 specification addresses).

openreceive is the CLI; the library is @openreceive/*

• The unscoped openreceive package no longer re-exports the library. It
  ships the openreceive command only (npx openreceive scaffold payments,
  npx openreceive doctor), forwarding to @openreceive/node/cli. Its 23
  openreceive/* subpaths are gone: import the scoped package you installed
  (@openreceive/express, @openreceive/react, …). One package per install,
  one package per import, and 646 fewer symbols in the public-API snapshot.

Compatibility ranges are ranges that run

• @getalby/sdk ^8 (was ^7; v8's one breaking change is requiring Node
  22, already this repo's floor). @openreceive/next declares
  next ^14 || ^15 || ^16 (13 dropped; the adapter uses Web
  Request/Response only). openreceive-rails requires Rails >= 8.0 (7.1
  and 7.2 are past security support and were never run here; 8.1 is what CI
  runs).

Wallet preflight proves receive-only from the connection's own list

• Receive-only is proved from NIP-47 get_info.methods — what this
  connection may call — rather than the kind-13194 info event, which
  advertises the wallet service at large. A receive-only connection on a
  service that also serves spend-capable apps now boots; a connection whose
  own list carries pay_invoice is still refused. The event still supplies
  encryption modes, and stands in for the method list only when the client
  exposes no get_info (logged as nwc.info_event.methods_fallback). Ruby
  already read get_info first; both engines now agree.
• AlbyNwcReceiveClient.close() waits for an in-flight client construction,
  closes the relay client exactly once, and makes later calls reject.

Naming: camelCase TypeScript, Checkout everywhere

• Server-side TypeScript surfaces are all camelCase now: the authorize
  resource carries orderId/paymentHash, and the rate quote carries
  btcFiatPrice/amountSats/amountMsats/asOf/expiresAt. The wire
  itself stays snake_case.
• The minted invoice is Checkout at every layer: the service type Checkout
  (was CheckoutInvoice), the generated wire body type WireCheckout (was
  OpenReceiveWireCheckout; from the OpenAPI document, shipped by
  @openreceive/http), and the browser's client-held snapshot type
  CheckoutSnapshot.
• The advanced rate-limit hook option is rateLimitHook (was rateLimit), so
  it reads as what it is and composes with the boolean rateLimiting.

onPaid in both host modes (onSettlement removed)

• The settlement hook is onPaid in BOTH host modes; onSettlement no longer
  exists. db mode receives PaymentSettlement (was
  OpenReceiveOrderSettlement: reference, was orderId, plus the
  transactional query); custom-repository mode receives SettlementEvent
  (was OpenReceiveSettlementEvent: paymentHash/paidAt/details), with
  write-once still enforced by the library.

Curated exports and the public-api gate

• @openreceive/express, @openreceive/fastify, and @openreceive/next
  re-export only the curated @openreceive/http surface: handler/stack
  factories, the error surface, the notification worker, and the
  options/context/hook types. The generated Wire* body types (was
  OpenReceiveWire*) and the host-integration internals — the SQL payment
  repository, the reconcile gate, createHost (was createOpenReceiveHost),
  the rate-limit helpers — live only on @openreceive/http (and
  openreceive/http).
• The UI wrappers export only the wrapper factories plus props/theme types,
  and @openreceive/core no longer exports internal formatting helpers
  (satsToFiatValue, formatBtcFromSats, …).
• A new npm run check:public-api gate pins every public surface in CI.
• trustProxyIpHeader (opt-in proxy-set client-IP header for rateLimiting)
  now exists on all three adapters.

Scan topology

• Every scan entry point — the opportunistic request-path pass, the
  notification worker's periodic pass, and startReconciler (was
  startOpenReceiveReconciler) — claims the durable openreceive_meta
  reconcile gate, so all of them share the one NWC scan budget.
  Unauthenticated GET /rates never triggers a scan.
• payments/check serves payment_methods from a 60-second per-amount warm
  cache instead of one provider call per poll.
• Superseded rows are excluded from live-attempt matching, and the 409 create
  conflict no longer leaks the live/supersede vocabulary on the wire ("An
  unpaid checkout for this payment method is already in progress for this
  order.").

prefix is the only URL the browser takes

• prefix — the base path the shipped router is mounted at — is now the
  single URL input of @openreceive/browser, @openreceive/react,
  @openreceive/elements and the Vue/Svelte/Angular wrappers. All seven
  routes are derived from it (/checkouts, /checkouts/prepare,
  /payments/check, /swaps, /swaps/quote, /swaps/status,
  /swaps/refunds), so create and settle can no longer point at different
  mounts.
• Removed: checkoutUrl (both the string and the (orderId) => string
  callback) on prepareCheckout/requestCheckout — pass prefix, which is
  now required, not optional.
• Removed: {orderId} / {order_id} templating in checkout URLs. The order
  id travels in the request body, as it already did for every other route.
• Removed: the orderUrl prop (React <Checkout>, useCheckout,
  PaymentWizard) and the matching order-url element attribute — pass
  prefix instead.
• Removed: orderUrl={false} as the polling switch. Use polling={false}
  (polling="false" on the element), which was already the documented knob.
  Behaviour note: orderUrl={false} also cut the payment wizard off from
  /swaps*, so it silently disabled swaps; polling={false} stops status
  polling only and leaves the swap flow working.

Frontend

• The fiat/country wing and the crypto method tile are removed: the payment
  method union is "bitcoin", and the swap flow is unchanged behind it.
• @openreceive/elements and @openreceive/react ship self-contained
  compiled styles.css files — a plain <link rel="stylesheet"> works.
• React snapshot mode polls through the default /openreceive prefix like
  create mode; polling and poll-interval-ms (pollIntervalMs) knobs exist
  on the element and every wrapper.

Schema

• openreceive_payments gains a locally clocked inserted_at column and
  CHECK constraints, and the install migrations seed the shared
  schema_version row in openreceive_meta. The per-IP rate-limit budget
  counts on inserted_at with a (client_ip, inserted_at) index in both
  engines (vector: rate-limit-window.json).

Ruby engine parity

• Truncation-safe reconcile: a wallet-history walk cut short (page cap, pass
  deadline, or a wallet that ignores offset) omits undecided hashes instead
  of reporting not_found, so a truncated scan can never close a paid attempt
  — pinned by the new cross-language wallet-scan-truncation.json vector
  family. Each pass takes the oldest 200 pending attempts
  (RECONCILE_BATCH_SIZE).
• Schema-version refusal: the engine refuses to operate a database whose
  stored schema_version is newer than the library.
• The generated Rails migration supports MySQL alongside PostgreSQL and
  SQLite.
• Production boot builds the service (and its wallet preflight) eagerly, so a
  bad deploy fails closed instead of surfacing checkout-time 500s. The
  initializer template defaults config.on_paid to
  OpenReceive::LOGGING_ON_PAID, and the engine warns at every boot until it
  is replaced.
• rake test works from each gem directory, and the Ruby suites use glob
  test discovery.

CI

• Per-push rails-example job; check:public-api runs per push; wrapper type
  checks (vue-tsc, svelte-check) and real wrapper mount tests.

Release

• npm run release:gem:build works on prerelease versions. RubyGems rewrites
  an npm-style prerelease through Gem::Version (0.2.0-alpha.0 becomes
  0.2.0.pre.alpha.0), so the release script no longer guesses the artifact
  filename from the workspace version — it normalizes through Ruby, builds
  straight into the output directory with gem build --output, and compares
  that same normalized version against rubygems.org when checking whether a
  version is already published.