sattleme-checkout 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +66 -0
  3. data/LICENSE +21 -0
  4. data/README.md +754 -0
  5. data/SECURITY.md +25 -0
  6. data/lib/sattleme/checkout/cancellation.rb +195 -0
  7. data/lib/sattleme/checkout/client.rb +1438 -0
  8. data/lib/sattleme/checkout/errors.rb +165 -0
  9. data/lib/sattleme/checkout/http_client.rb +294 -0
  10. data/lib/sattleme/checkout/internal/bolt11.rb +187 -0
  11. data/lib/sattleme/checkout/internal/channel.rb +147 -0
  12. data/lib/sattleme/checkout/internal/checkout_link.rb +294 -0
  13. data/lib/sattleme/checkout/internal/concurrency.rb +450 -0
  14. data/lib/sattleme/checkout/internal/crypto.rb +63 -0
  15. data/lib/sattleme/checkout/internal/currencies.rb +47 -0
  16. data/lib/sattleme/checkout/internal/declaration.rb +135 -0
  17. data/lib/sattleme/checkout/internal/derive.rb +153 -0
  18. data/lib/sattleme/checkout/internal/event.rb +110 -0
  19. data/lib/sattleme/checkout/internal/http.rb +129 -0
  20. data/lib/sattleme/checkout/internal/json.rb +457 -0
  21. data/lib/sattleme/checkout/internal/key.rb +116 -0
  22. data/lib/sattleme/checkout/internal/lnurl.rb +238 -0
  23. data/lib/sattleme/checkout/internal/nip44.rb +113 -0
  24. data/lib/sattleme/checkout/internal/onchain/address.rb +58 -0
  25. data/lib/sattleme/checkout/internal/onchain/basics.rb +352 -0
  26. data/lib/sattleme/checkout/internal/onchain/lease.rb +326 -0
  27. data/lib/sattleme/checkout/internal/onchain/merchant_acceptance.rb +168 -0
  28. data/lib/sattleme/checkout/internal/onchain/node.rb +285 -0
  29. data/lib/sattleme/checkout/internal/onchain/payment.rb +345 -0
  30. data/lib/sattleme/checkout/internal/onchain/rest.rb +323 -0
  31. data/lib/sattleme/checkout/internal/onchain/watch.rb +119 -0
  32. data/lib/sattleme/checkout/internal/onchain/witness.rb +260 -0
  33. data/lib/sattleme/checkout/internal/order.rb +228 -0
  34. data/lib/sattleme/checkout/internal/protocol.rb +260 -0
  35. data/lib/sattleme/checkout/internal/rates.rb +373 -0
  36. data/lib/sattleme/checkout/internal/record.rb +179 -0
  37. data/lib/sattleme/checkout/internal/relay_pool.rb +823 -0
  38. data/lib/sattleme/checkout/internal/sales.rb +238 -0
  39. data/lib/sattleme/checkout/internal/secp256k1.rb +234 -0
  40. data/lib/sattleme/checkout/internal/text.rb +144 -0
  41. data/lib/sattleme/checkout/internal/urls.rb +172 -0
  42. data/lib/sattleme/checkout/models.rb +247 -0
  43. data/lib/sattleme/checkout/version.rb +9 -0
  44. data/lib/sattleme/checkout/websocket_client.rb +487 -0
  45. data/lib/sattleme/checkout.rb +72 -0
  46. metadata +112 -0
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 7a89f4899adcefd0b8e26cf668fc5501fcc94610a7eadaa41c3de636725c6c78
4
+ data.tar.gz: d2379e77f300a746c5b2e5d8e940feb113675991890920250aab48f585845605
5
+ SHA512:
6
+ metadata.gz: d7149932b1ccec3b2ccc26daa32ce31678d5ef4ebc9c4b074145fdadb5071a078fb6a8a8dd46bf6909c13c769366b49249a7c7a395f95bd3c09ce034c8b99e98
7
+ data.tar.gz: 2786735974ef95731fe480d14f1c8f142d9b35880de710c29a3310cfec755188c13d6f50f9b8beaca1c977feedd86a17dcc1d3e118fa71d1a85af258bf3d0b9f
data/CHANGELOG.md ADDED
@@ -0,0 +1,66 @@
1
+ # Changelog
2
+
3
+ All notable changes to `sattleme-checkout`. Versions follow
4
+ [Semantic Versioning](https://semver.org/); tags are `vX.Y.Z`.
5
+
6
+ Released versions are published to RubyGems.org by CI, from the tag, once a maintainer approves
7
+ the release (README.md, "Releasing").
8
+
9
+ ## 1.0.0 - 2026-11-20
10
+
11
+ First version. Follows version 1.0.0 of the specification
12
+ ([sattleme/checkout-spec](https://github.com/sattleme/checkout-spec)) and passes its
13
+ conformance vectors.
14
+
15
+ - **The client**, `Sattleme::Checkout::Client`: reads the integration key and the merchant
16
+ (`merchant`), makes the invoice of an order and declares it in the merchant's registry
17
+ (`create_invoice`), checks its payment (`get_status`, `wait_for_payment`), finds the invoices of
18
+ an order again (`find_invoices`). Made for a server that lives for one call: nothing is kept
19
+ between calls. Every method takes a `Sattleme::Checkout::Cancellation`.
20
+ - **One order, one invoice at a time**, checked against the registry (`InvoicePendingError`,
21
+ `OrderPaidError`): the payment of an invoice that may still be paid is checked first, even when
22
+ it is the only one, so that an invoice already paid is never handed out again; of several, the
23
+ one a majority of the relays holds is handed out.
24
+ - **Orders in sats or in a currency** (the ISO 4217 currencies), converted exactly and rounded up
25
+ to the sat, at the price of a list of rate sources asked in turn: CoinGecko, mempool.space,
26
+ Coinbase, Kraken, OpenNode, or your own. `Sattleme::Checkout.currency_digits(code)` gives the
27
+ decimals of a currency an order may be priced in (nil for any other code), and
28
+ `Sattleme::Checkout.fiat_to_sats(fiat, price)` the sats of a price.
29
+ - **Lightning payments**: an invoice from the merchant's Lightning address (LUD-16, LUD-21 verify
30
+ URL).
31
+ - **On-chain payments**: from 1 000 sats, a taproot deposit address of the merchant's wallet leased
32
+ for the order, with a single `bitcoin:` QR code (`payment_uri`). A lease is published
33
+ unconfirmed, read again on every relay of the merchant, then marked confirmed: only a confirmed
34
+ lease gives the order its address, and no order leases an address another order holds or a
35
+ witness names. Payment checked on one explorer, paid at 3 confirmations on the explorer read,
36
+ with fee bumps (RBF) and the `unconfirmed` state; `wait_for_payment` watches the address on the
37
+ explorer's WebSocket. BlockCypher tells when a transaction no check saw in time was received.
38
+ - **The merchant's Bitcoin node**: the node the integration's channel names (`bitcoinNode`: its
39
+ URL, by a rule of its own that allows `http` to a host of a local network, its `fallback`
40
+ "mempool" or "none", and `payers`) is the explorer, read over REST and WebSocket with its
41
+ fallback: a node that failed less than 60 s ago in the same call is asked after mempool.space, a
42
+ check's two reads always come from one explorer; with "none", mempool.space is never asked, and
43
+ a node that does not answer leases no address and gives `network`, never `expired`. With
44
+ `payers` true, the checkout links' records name the node, whose page then reads it too. An
45
+ invalid `bitcoinNode` is none. The gem's HTTP and WebSocket clients ask such a node in clear
46
+ HTTP, and no other host.
47
+ - **Witnesses** of the transactions each check sees, which name the invoice they are of: a
48
+ transaction a witness of another invoice names counts for nothing.
49
+ - **The rest of an on-chain underpayment**, payable in Lightning (and on-chain from 1 000 sats),
50
+ shown on the order's checkout links; an order paid both ways is `paid` with `method: "mixed"`.
51
+ - **The merchant's tolerance of on-chain underpayments** (0 to 10 %), read in the integration's
52
+ channel and kept in the lease of each order's address.
53
+ - **The merchant's acceptance** of an order underpaid on-chain at what it received, made by the
54
+ merchant in its app: read by every check on every relay of the merchant, and counted only when a
55
+ majority of them hold it; the order is then paid with `received` below its amount.
56
+ - **Checkout links**: `create_invoice(..., checkout: true, redirect_url:)` gives a `checkout_url`,
57
+ a page of the merchant's web app where the customer pays, then is sent to `redirect_url`.
58
+ - **Outbound requests**: https URLs only (a lowercase host name, no IP address, no host under
59
+ `localhost`), but for the merchant's Bitcoin node (its URL's own rule), no redirect followed, at most 1 MiB read of an answer's body and 16 KiB of its
60
+ head, and `User-Agent: sattleme-Checkout/1`. The relays' WebSocket handshake follows no
61
+ redirect, carries the same User-Agent and offers no compression; a read keeps only what opens
62
+ with its keys, so a relay cannot make the server's memory grow.
63
+ - **Typed errors** with a stable `code` and whether they are retryable.
64
+ - **Stored invoices are JSON** (`Invoice#to_json`, `Invoice.from_json`), with the field names of
65
+ every implementation of the specification: an invoice stored by another one is checked here, and
66
+ the other way round.
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Swiss Bitcoin Pay Sàrl
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.