lnurlcash-kit 0.1.2 → 0.2.0

package/llms.txt

@@ -24,9 +24,32 @@ splitNote(callback, k1s, amountMsat, opts?) -> {k1, change, signature?, changeSi
 mergeNotes(callback, k1s, opts?) -> {k1, signature?}
 meltNote(callback, k1, bolt11, opts?) -> {pr?, verify?}
 settleNote(baseUrl, k1, expectedMsat, sig?, opts?) -> {k1, amountMsat, signature?, callback}
+settleNoteForValue(noteUrl, {mints, minMsat, requireSignature?}, opts?)
+  -> {note, newUrl}   server side: accept a note as payment, rotate to settle
 probeBurnedNote(url, opts?) -> 'live' | 'gone' | 'unknown'
-verifyNoteSignature(k1, amountMsat, sigHex, mintPubkeyHex) -> boolean
-fetchPayRequest(url, opts?) / requestInvoice(cb, msat, opts?) / fetchInvoiceVerification(url, opts?)
+verifyNoteSignature(k1, amountMsat, sigHex, pubkeyHex | pubkeyHex[]) -> boolean
+verifyNoteSignatureAgainst(k1, amountMsat, sigHex, keys) -> {valid, pubkey}
+fetchMintAddress(url, opts?) -> {mintPubkey?, payLink, name?, motd?, contact?,
+  tosUrl?, fees?, version?, previousPubkeys?, mintToHash?, node*?}
+  experimental, often absent
+  mintPubkey verifies note signatures. It is NOT the node key in nodeUri.
+  nodePubkey is a deprecated alias for mintPubkey, dropped next breaking change.
+  mintToHash is the fallback copy of the payRequest's flag - see 13.
+deriveNoteRoot(seedBytes) -> Uint8Array    HMAC-SHA256("lnurlcash-note-v1", seed)
+deriveNoteSecret(root, host, index) -> k1  HMAC-SHA256(root, host + ":" + index)
+derivedSecretSource(root, host, start) -> RandomSecret & {index()}
+restoreNotes(baseUrl, root, host, {gap?, start?}, opts?) -> {found[], next}
+fetchPayRequest(url, opts?) -> {callback, minSendable, maxSendable, metadata,
+  withdrawLink?, mintFee?, mintToHash?}     mintToHash: mint accepts an `h`
+fetchInvoiceVerification(url, opts?)
+requestInvoice(cb, msat, {h?, ...opts}?) -> {pr, verify?, disposable, mintToHash}
+claimMintedNote(withdrawLink, k1, opts?)
+  -> {state: 'minted'|'unminted'|'pending'|'spent', k1, amountMsat, callback}
+encodePaymentRequest(req) -> "lnurlcashreq1..."  base64url(JCS JSON), prefix
+decodePaymentRequest(str, {now?}) -> PaymentRequest  throws ProtocolError
+isPaymentRequest(str) -> boolean       true for an expired one too
+paymentRequestAmountMsat(req) -> msat  request amount is in SAT, this is the
+  only sat-denominated field in the library; never multiply by hand
 parseMintFee(metadata) / applyMintFee(gross, fee) / grossUpForMintFee(net, fee)
 createClient(opts) -> all of the above with opts bound
 
@@ -38,26 +61,64 @@ Options (always last): {fetch?, timeoutMs?, offline?, randomSecret?}
    `amount` in a note URL is an unverified claim.
 2. On rotate/split/merge the WALLET generates the replacement secret and
    discloses only sha256(secret). Never accept a service-supplied k1.
-3. Catch AmbiguousMutationError, PERSIST err.newSecrets before anything
-   else, then call probeBurnedNote to learn what happened. Treating it as
-   failure destroys money the service may already have minted.
+3. On ANY error from a mutation call newSecretsOf(err) FIRST, persist what
+   it returns, then call probeBurnedNote to learn what happened. Treating a
+   failure as a failure destroys money the service may already have minted.
+   AmbiguousMutationError always carries secrets; so does a NoteSpentError
+   or NoteUnknownError from a mutation, because that is also what a retried
+   GET looks like once its first attempt burned the input.
 4. RequestRefusedError means nothing was sent - safe to treat as no-op.
 5. A melt's OK means IN FLIGHT, not spent. PendingNoteError means retry, not
    spent.
 6. Rotate immediately after claiming a minted note: the mint generated that
    preimage, and LUD-21 verify exposes it to anyone who saw the invoice.
+   Does not apply to a note minted with `h` - see 13.
 7. Never log note URLs. The secret is in the query string.
 8. Never branch on error message text. Branch on the error class.
+9. lnurlcashreq1 means ONE schema: {v: 1, id (16 hex), amount (whole sat as
+   a decimal string), currency: "sat", methodDetails: {mints}, to?, memo?,
+   expires?}, JCS-canonicalised, base64url, no padding. Validation is
+   strict, an unrecognised field included. At the expiry is expired. Pass
+   {now: 0} to show a user what they scanned. The decoder also reads the
+   short {a, m, u} form an early 402 rail emitted under this prefix, but
+   NEVER emit it.
+10. Accepting a note as payment MUST end in a rotate. Checking its value
+    and granting access without rotating leaves the payer able to spend it
+    again; the rotate is both the ownership transfer and the replay check.
+11. A mint may rotate its signing key. Verify against its current key plus
+    the previousPubkeys it publishes; a note that verifies only against a
+    retired key should be rotated to be re-signed. An empty key list is a
+    rejection.
+12. With derived secrets, persist the per-host counter in the SAME write
+    that stages the new records and BEFORE the hash goes on the wire. A
+    split consumes two indices, a rotate one; read source.index() for the
+    next unused one. Bumping late re-derives a secret the mint has already
+    seen.
+13. Name the note you are buying where the mint offers it. Read mintToHash
+    off fetchPayRequest FIRST (fetchMintAddress is the fallback for a mint
+    that only says it on that optional document), then derive a secret,
+    persist it, and pass h = hashK1(secret) to requestInvoice. The mint
+    credits the note at that hash, the payment preimage is then not a valid
+    k1, and you claim with claimMintedNote rather than polling verify - no
+    rotate needed, and the note is seed-derived from birth so restoreNotes
+    finds it. Persist the secret BEFORE requesting the invoice. Three
+    places carry the flag: the payRequest and the mint address both mean
+    "I accept an h", InvoiceResult.mintToHash means "I bound THIS quote to
+    your hash". Anything not exactly true is no. A mint that advertises
+    nowhere ignores the h and the preimage path is unchanged.
 
 ## Error classes
 
 RequestRefusedError    nothing sent, note untouched
 ServiceRejectedError   processed and refused (definitive)
   PendingNoteError     a melt is in flight on this k1 - retry
-  NoteSpentError       authoritative: already burned
+  NoteSpentError       authoritative: already burned - but from a MUTATION it
+                       may be a retry whose first attempt landed; read
+                       newSecretsOf(err) before believing it
   NoteUnknownError     service does not recognise it
 AmbiguousMintError     outcome UNKNOWN - assume nothing
   AmbiguousMutationError  carries .newSecrets - persist them
+newSecretsOf(err) -> string[]  the secrets any error is carrying, or none
 ProtocolError          a non-mutating response did not match the spec
 
 ## Conformance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-kit",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "LNURLcash (LUD-25) bearer note client for TypeScript - mint, rotate, split, merge, melt, and verify offline",
   "author": "TheCryptoDonkey",
   "license": "MIT",