Repository navigation
Releases
0.6.0 — Latch is now Detent
npm install detent402The first release as Detent (detent402). detent402@0.5.0 was published
earlier the same day by mistake, from this code under the old version number;
use 0.6.0.
- Renamed from Latch (
latch402) to Detent (detent402on npm). Another
x402 project, the @latch402 readiness scanner for OKX.AI, used the name
first; npm refuses a baredetentas too close todedent. Install
detent402; import from"detent402","detent402/x402"and
"detent402/conformance". Renamed exports:latchX402→detentX402,
X402Latch→X402Detent,X402LatchOptions→X402DetentOptions,
LatchError→DetentError,isLatchError→isDetentError. Error
codeslatch_unavailableandlatch_unsupported_paymentare now
detent_unavailableanddetent_unsupported_payment, and the token the 402
carries is in adetentextension instead oflatch. Database tables keep
theirlatch_names, so existing journals and receipts work unchanged. The
demo folder is now.detent-demo/, and the demo moves an old
.latch-demo/across. The GitHub repository is now Hitek-cel/detent; old
links redirect. Earlier entries keep the old name. - A
stuckpayment's retry is now answered503 payment_unresolved, not
409 (withdetent.http()). Recovery spec 0.9 splits the two "don't pay
again yet" answers:409 operation_in_flightwithRetry-Afterwhile the
payment can still resolve, and503with noRetry-Afteronce it is stuck
(control 11). The body is unchanged and names the reason, so a client can
tell it apart from a server-health 503. Payments still in flight keep 409. - A payment recovered from the chain now keeps its settlement transaction.
When the facilitator's reply was lost (a crash, a timeout), Detent learned
fromauthorizationStatethat the payment landed but not which transaction
did it, so the report showed "—" and the receipt had nosettlementRef.
eip3009Oraclenow hasfindTransaction, which finds the
AuthorizationUsedevent within the payment's own time window, in chunks
small enough for public RPCs (logRangeBlocks, default 200;maxLogCalls,
default 30). A customSettlementOraclemay add its ownfindTransaction.
Best effort: if it fails or finds nothing, the payment is delivered exactly as
before, without the link. Payments recovered earlier are not rewritten. - The x402 demo takes
--facilitator payaito run against PayAI's public
facilitator instead of x402.org (only those two are allowed).
0.5.0 — 409 operation_in_flight
-
Added
latch.http(httpServer): a payment still in flight gets
409 operation_in_flight, not a 402. The proposed x402 recovery extension
(x402-foundation/x402#3848,
§5.1(6)–(7), control 9) says a copy that loses the claim, or a retry while a
settle is unresolved, MUST NOT get a payment challenge: a 402 invites a second
signature for one purchase. The SDK turns every hook refusal into a full 402,
and hooks cannot choose the status, solatch.http()wraps the SDK's
x402HTTPResourceServerand rewrites only the refusals Latch made as
"in flight". It also covers the SDK's own settlement-failure 402 when the
payment could still land. Every other answer is unchanged.app.use(paymentMiddlewareFromHTTPServer(latch.http(new x402HTTPResourceServer(server, routes))));
-
A
stuckpayment's retry is now refused aspayment_unresolved(409
withlatch.http()), notpayment_closed: its outcome is unknown, so the
purchase stays blocked and the caller is never invited to sign again. -
The demo uses
latch.http(); steps 3 and 4 now show the 409.
Also the first npm release of the 0.4.0 and 0.4.1 changes, which were never
published on their own:
journalReport(sql): a read-only, self-contained HTML dashboard of every
payment in a Postgres journal — where each one ended, activity over time,
recoveries, filters, CSV export, light and dark themes.journalReportData(sql): the same data as plain objects.npm run reportopens that page for the demo's payments.
Full details in CHANGELOG.md.
npm install latch402@0.5.00.3.2 — purchasePaymentId
- Added
purchasePaymentId(...parts)inlatch402/x402: a payment
identifier derived from the purchase, for the buyer's side. The
payment-identifierextension only stops a re-signed retry from being
charged twice when the retry carries the same identifier; the stock client
sends none, and generating a random one per call protects nothing. Reported
by Selliksss after running the demo. - The demo has a new step: a buyer told "failed" signs a new payment for
the same order. The second signature is refused, and retrying the original
finishes the purchase with one charge. - The README states the identifier requirement plainly.
0.3.1 — ran live on Base Sepolia
No change to the library's behaviour. Documentation, tests and a demo.
- Ran live on Base Sepolia through the public x402 facilitator with test
USDC. All five demo steps held, and the chain showed exactly three charges
for three purchases. The README's status section now says what has and has
not been run. - A runnable demo in the repository:
npm run example(offline, no keys)
andnpm run example:testnet(Base Sepolia). It is not part of the npm
package. - Documented a limit: while a settle is unresolved, a client that signs a
new payment can be charged twice unless the route declares the
payment-identifierextension. The quickstart now declares it, and two
tests pin both cases. - Tested against
@x402/core2.31.0 as well as 2.30.0. - The author is credited in the README and the package metadata.
0.3.0 — works with the official x402 SDK
Latch now works with the official x402 SDK instead of beside it.
Added
latch402/x402— a bridge for the official SDK.latchX402(server, …)
registers lifecycle hooks on anx402ResourceServerand journals every
payment on theexactscheme's default flow. Route handlers do not change.- One atomic claim per payment, keyed by (payer, nonce) as the chain keys it.
Concurrent copies of a payment run the handler once. - The response is stored before the settle is requested, so a payment that
lands always has something to deliver. - A failed or timed-out settle is checked against an oracle before anything
is concluded. Money that moved is delivered; a payment that can still land
waits; one that cannot is voided. - A retry of a settled payment gets the stored response back, authorised by a
per-402 replay token carried in alatchextension. A new signature under
the samepayment-identifieris answered from the store and never settled. sweep()andrecover()finish or close payments whose process died.
Recovery never initiates a charge.
- One atomic claim per payment, keyed by (payer, nonce) as the chain keys it.
eip3009Oracle— asks the token contractauthorizationState(payer, nonce)over JSON-RPC. No key, no dependency.postgresAuthorizedPaymentStorage— the SDK'sauth-capture
AuthorizedPaymentStorageinterface on Postgres, so the record of escrow
holds survives a restart.- A JavaScript build with type declarations. The package now runs on Node 20+
without a TypeScript loader.
Changed
Latch.sweep()skips invoices opened by the x402 bridge, so the two can
share one journal.- The package exports compiled files from
dist/. Import paths are unchanged.
Notes
- The strict gate (
quote/redeem) is unchanged and still does not speak
the x402 wire format. Use the bridge for x402. - Nothing in this release has been run against a live facilitator. See
"Status" and "Limits" in the README.