@forgesworn/moneyer 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.3.0] - 2026-08-22
+
+- **The mint fee is now ceilinged to a whole sat by default.**
+  `MONEYER_ROUND_FEE_TO_SAT` defaults to `true`, matching dni's
+  lnurl-mint, the reference. **An operator upgrading into this withholds
+  slightly more per mint than before** - up to one sat, whatever the ppm
+  cut worked out to - so it is called out here rather than changed
+  quietly. `MONEYER_ROUND_FEE_TO_SAT=false` restores the old behaviour.
+
+  Why: a mint that deals in fractions of a sat issues notes nothing
+  downstream can spend. An msat-exact fee makes notes like 94.9 sat, and
+  most Lightning wallets can only invoice whole sats, so such a note
+  cannot be withdrawn by them at all. The mint already covered that by
+  advertising `minWithdrawable` as the whole-sat floor and keeping the
+  remainder as dust; rounding at mint time means it never arises. Every
+  note this mint issues for a whole-sat payment is now worth a whole
+  number of sats, on both the pay callback and the zap path, which share
+  one fee function.
+
+  LUD-25 says nothing about rounding and `lnurlcash-kit`'s `mintFeeBand`
+  accepts either, so this is a posture change and not a compliance one.
+  The conformance grader passed both before and passes this now.
+
+## [0.2.1] - 2026-08-22
+
+- `moneyer --dev` settles its invoices a moment after issuing them rather
+  than at the instant of issuance. Settling immediately made the mint
+  report an invoice nobody had paid as already settled, which on the wire
+  is indistinguishable from a mint handing out a note before it has been
+  paid for - the conformance grader failed it on exactly that, and was
+  right to. A dev mint should behave like a fast payer, not one that pays
+  before being asked. `autoSettleAfterMs` sets the delay; it defaults to
+  1.5 seconds, which nobody developing against a local mint notices.
+  A freshly started `--dev` mint now grades 24 passed, 0 failed.
+
 ## [0.2.0] - 2026-08-22
 
 While LUD-25 is a draft, a `0.x` minor bump may be breaking; this one is

package/README.md

@@ -87,7 +87,7 @@ default, and a variable set to an empty string counts as unset.
 | `MONEYER_PREVIOUS_SIGNING_PUBKEYS` | | compressed pubkeys this mint signed under before, comma separated (see below) |
 | `MONEYER_BASE_FEE_MSAT` | `0` | flat mint fee |
 | `MONEYER_FEE_PPM` | `0` | proportional mint fee, parts per million |
-| `MONEYER_ROUND_FEE_TO_SAT` | `false` | ceiling the mint fee to a whole sat (see below) |
+| `MONEYER_ROUND_FEE_TO_SAT` | `true` | ceiling the mint fee to a whole sat (see below) |
 | `MONEYER_MIN_SENDABLE_MSAT` | `1000` | smallest payment the mint advertises |
 | `MONEYER_MAX_SENDABLE_MSAT` | `100000000` | largest payment the mint advertises |
 | `MONEYER_MIN_MINT_MSAT` | `1000` | dust floor: the smallest note the mint will strike |
@@ -269,16 +269,20 @@ the msat-exact amount. Neither is out of spec - lnurlcash-kit's
 `mintFeeBand` treats anything between the two as the mint keeping its
 word, and the conformance grader accepts both.
 
-`MONEYER_ROUND_FEE_TO_SAT=true` switches this mint to the reference's
-behaviour. Off by default: turning it on raises what the mint withholds,
-and that is not a change to make behind an operator's back on a redeploy.
-
-Why you probably want it on anyway: msat-exact fees make notes like 94.9
-sat, and most Lightning wallets can only invoice whole sats, so such a
-note cannot be withdrawn by them. moneyer covers the notes already out
-there by advertising `minWithdrawable` as the note floored to a whole sat
-and accepting a melt for that; the sub-sat remainder is dust the mint
-keeps. Rounding at mint time means it never comes up.
+**moneyer rounds, by default.** A mint that deals in fractions of a sat
+issues notes nothing downstream can spend: msat-exact fees make notes like
+94.9 sat, and most Lightning wallets can only invoice whole sats, so such
+a note cannot be withdrawn by them at all. moneyer covers the notes
+already out there by advertising `minWithdrawable` as the note floored to
+a whole sat and accepting a melt for that, keeping the sub-sat remainder
+as dust - a wart it should not need. Rounding at mint time means it never
+comes up, and every note this mint issues for a whole-sat payment is worth
+a whole number of sats.
+
+`MONEYER_ROUND_FEE_TO_SAT=false` restores the msat-exact fee. An operator
+upgrading into this default withholds slightly more per mint than before,
+which is why the changelog says so plainly rather than letting a redeploy
+change it quietly.
 
 ## Melting to an invoice with no amount
 

package/dist/backends/fake.d.ts

@@ -1,7 +1,9 @@
 import { type LightningBackend } from './types.ts';
 export type FakePayMode = 'succeed' | 'fail-clean' | 'fail-then-paid' | 'ambiguous-paid' | 'ambiguous-unpaid' | 'ambiguous-pending';
+export declare const DEFAULT_AUTO_SETTLE_AFTER_MS = 1500;
 export type FakeBackendOptions = {
     autoSettle?: boolean;
+    autoSettleAfterMs?: number;
 };
 export type FakeBackend = LightningBackend & {
     control: {

package/dist/backends/fake.js

@@ -4,10 +4,28 @@ import { hexToBytes } from '@noble/hashes/utils.js';
 import { bolt11PaymentHash } from 'farrier-kit/bolt11';
 import { fakeBolt11 } from "./fake-bolt11.js";
 import { PaymentAlreadyKnownError, PaymentFailedError, PaymentPendingError } from "./types.js";
+// Long enough that an unpaid invoice reads as unpaid to anything looking
+// at it in the same breath it was issued, short enough that nobody
+// developing against a dev mint notices the wait.
+export const DEFAULT_AUTO_SETTLE_AFTER_MS = 1_500;
+// An invoice is paid if something paid it, or if autoSettle's moment has
+// arrived. Read rather than scheduled: no timer to leak when a mint is
+// closed, and a test that fakes the clock sees the same answer.
+const isSettled = (invoice) => {
+    if (!invoice)
+        return false;
+    if (invoice.settled)
+        return true;
+    return invoice.settleAt !== null && Date.now() >= invoice.settleAt;
+};
 // One bitcoin, so a development mint covers anything it is likely to mint.
 export const FAKE_LOCAL_BALANCE_MSAT = 100_000_000_000;
 export const createFakeBackend = (options = {}) => {
     const autoSettle = options.autoSettle === true;
+    const autoSettleAfterMs = options.autoSettleAfterMs ?? DEFAULT_AUTO_SETTLE_AFTER_MS;
+    // `settleAt` is when autoSettle starts calling this invoice paid; null
+    // for an invoice only control.settleInvoice can settle, which is every
+    // invoice unless autoSettle is on.
     const invoices = new Map();
     const payments = new Map();
     const knownPreimages = new Map();
@@ -18,7 +36,12 @@ export const createFakeBackend = (options = {}) => {
         async createInvoice({ amountMsat, preimageHex, memo }) {
             const paymentHashHex = bytesToHex(sha256(hexToBytes(preimageHex)));
             const pr = fakeBolt11({ amountMsat, paymentHashHex, memo });
-            invoices.set(paymentHashHex, { preimageHex, amountMsat, settled: autoSettle });
+            invoices.set(paymentHashHex, {
+                preimageHex,
+                amountMsat,
+                settled: false,
+                settleAt: autoSettle ? Date.now() + autoSettleAfterMs : null
+            });
             return { pr };
         },
         async payInvoice({ pr, amountMsat }) {
@@ -63,11 +86,11 @@ export const createFakeBackend = (options = {}) => {
             return payment.status === 'complete';
         },
         async isInvoiceSettled(paymentHashHex) {
-            return invoices.get(paymentHashHex)?.settled ?? false;
+            return isSettled(invoices.get(paymentHashHex));
         },
         async invoicePreimage(paymentHashHex) {
             const invoice = invoices.get(paymentHashHex);
-            return invoice?.settled ? invoice.preimageHex : null;
+            return isSettled(invoice) ? invoice.preimageHex : null;
         },
         async paymentPreimage(paymentHashHex) {
             const payment = payments.get(paymentHashHex);
@@ -113,7 +136,11 @@ export const createFakeBackend = (options = {}) => {
                 localBalanceMsat = msat;
             },
             invoiceByHash(paymentHashHex) {
-                return invoices.get(paymentHashHex);
+                const invoice = invoices.get(paymentHashHex);
+                // `settled` here answers "is it paid now", so autoSettle's moment
+                // counts. A caller reading the stored flag would see false for an
+                // invoice the mint itself treats as paid.
+                return invoice && { ...invoice, settled: isSettled(invoice) };
             }
         }
     };

package/dist/config.d.ts

@@ -2,6 +2,7 @@ import type { MintFee } from 'lnurlcash-kit';
 export type BackendConfig = {
     kind: 'fake';
     autoSettle?: boolean;
+    autoSettleAfterMs?: number;
 } | {
     kind: 'cln';
     url: string;
@@ -64,7 +65,7 @@ export declare const DEFAULTS: {
     readonly verify: true;
     readonly maxK1s: 21;
     readonly sunset: false;
-    readonly roundFeeToSat: false;
+    readonly roundFeeToSat: true;
     readonly stats: true;
     readonly statsRatioOnly: false;
     readonly statsPublish: false;

package/dist/config.js

@@ -14,7 +14,7 @@ export const DEFAULTS = {
     verify: true,
     maxK1s: 21,
     sunset: false,
-    roundFeeToSat: false,
+    roundFeeToSat: true,
     stats: true,
     statsRatioOnly: false,
     statsPublish: false,

package/dist/server.js

@@ -49,7 +49,12 @@ const wholeSatFloor = (msat) => Math.floor(msat / 1000) * 1000;
 const backendFor = (config) => {
     switch (config.backend.kind) {
         case 'fake':
-            return createFakeBackend({ autoSettle: config.backend.autoSettle === true });
+            return createFakeBackend({
+                autoSettle: config.backend.autoSettle === true,
+                ...(config.backend.autoSettleAfterMs === undefined
+                    ? {}
+                    : { autoSettleAfterMs: config.backend.autoSettleAfterMs })
+            });
         case 'cln':
             return createClnBackend(config.backend);
         case 'lnd':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "An LNURLcash (LUD-25) mint - strikes Lightning bearer notes. Independent implementation, cln/lnd funding sources, SQLite, zero HTTP framework.",
   "author": "TheCryptoDonkey",
   "license": "MIT",