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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +66 -0
- data/LICENSE +21 -0
- data/README.md +754 -0
- data/SECURITY.md +25 -0
- data/lib/sattleme/checkout/cancellation.rb +195 -0
- data/lib/sattleme/checkout/client.rb +1438 -0
- data/lib/sattleme/checkout/errors.rb +165 -0
- data/lib/sattleme/checkout/http_client.rb +294 -0
- data/lib/sattleme/checkout/internal/bolt11.rb +187 -0
- data/lib/sattleme/checkout/internal/channel.rb +147 -0
- data/lib/sattleme/checkout/internal/checkout_link.rb +294 -0
- data/lib/sattleme/checkout/internal/concurrency.rb +450 -0
- data/lib/sattleme/checkout/internal/crypto.rb +63 -0
- data/lib/sattleme/checkout/internal/currencies.rb +47 -0
- data/lib/sattleme/checkout/internal/declaration.rb +135 -0
- data/lib/sattleme/checkout/internal/derive.rb +153 -0
- data/lib/sattleme/checkout/internal/event.rb +110 -0
- data/lib/sattleme/checkout/internal/http.rb +129 -0
- data/lib/sattleme/checkout/internal/json.rb +457 -0
- data/lib/sattleme/checkout/internal/key.rb +116 -0
- data/lib/sattleme/checkout/internal/lnurl.rb +238 -0
- data/lib/sattleme/checkout/internal/nip44.rb +113 -0
- data/lib/sattleme/checkout/internal/onchain/address.rb +58 -0
- data/lib/sattleme/checkout/internal/onchain/basics.rb +352 -0
- data/lib/sattleme/checkout/internal/onchain/lease.rb +326 -0
- data/lib/sattleme/checkout/internal/onchain/merchant_acceptance.rb +168 -0
- data/lib/sattleme/checkout/internal/onchain/node.rb +285 -0
- data/lib/sattleme/checkout/internal/onchain/payment.rb +345 -0
- data/lib/sattleme/checkout/internal/onchain/rest.rb +323 -0
- data/lib/sattleme/checkout/internal/onchain/watch.rb +119 -0
- data/lib/sattleme/checkout/internal/onchain/witness.rb +260 -0
- data/lib/sattleme/checkout/internal/order.rb +228 -0
- data/lib/sattleme/checkout/internal/protocol.rb +260 -0
- data/lib/sattleme/checkout/internal/rates.rb +373 -0
- data/lib/sattleme/checkout/internal/record.rb +179 -0
- data/lib/sattleme/checkout/internal/relay_pool.rb +823 -0
- data/lib/sattleme/checkout/internal/sales.rb +238 -0
- data/lib/sattleme/checkout/internal/secp256k1.rb +234 -0
- data/lib/sattleme/checkout/internal/text.rb +144 -0
- data/lib/sattleme/checkout/internal/urls.rb +172 -0
- data/lib/sattleme/checkout/models.rb +247 -0
- data/lib/sattleme/checkout/version.rb +9 -0
- data/lib/sattleme/checkout/websocket_client.rb +487 -0
- data/lib/sattleme/checkout.rb +72 -0
- 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.
|