@forgesworn/moneyer 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.13.1 - 2026-09-11
+
+- A name's owner can set or clear its `cx1` while self-service registration
+  is closed. Closing registration stops new names; it no longer stops the
+  owner of an existing one, an operator name included, from choosing where
+  it pays. A request for a new name still gets the same 404.
+
+## 0.13.0 - 2026-09-11
+
+- **Names that pay to the holder's own keys.** `POST /names` takes a `cx1`,
+  a watch-only branch, and the key that owns a name can set or clear one
+  later. A zap to such a name is credited to the holder's next key on the
+  branch, and the gift wrap carries only where to look and the index:
+  `/w?p=<cp1>&amount=&sig=<cs1>&i=`, plus an `i` tag. The mint never holds
+  a secret for it.
+- The index is taken when the zap settles, never when the invoice is made,
+  so an unpaid invoice leaves no gap in the holder's scan. A key that
+  already holds a note is skipped.
+- Names gain two columns, `cx1` and `next_index`, added in place on first
+  start.
+
 ## 0.12.0 - 2026-09-11
 
 - LUD-25's renamed parameters are accepted: `p` for the informational

package/README.md

@@ -542,6 +542,31 @@ A registered name resolves on both rails at once:
 The discovery endpoint advertises `namePriceMsat` while registration is
 open, so a wallet can offer the flow without asking.
 
+### A name that pays to your own keys (LUD-25 Part 2)
+
+Add `"cx1": "cx1..."` to the registration body, or send `{"name", "cx1"}`
+again later from the key that owns the name, and payments to it stop being
+custodial. A `cx1` is a watch-only branch: from it the mint can work out each
+of the holder's note keys in turn, but never spend one.
+
+When a zap to the name settles, the mint takes the next index on the branch
+and credits the note to that key. It skips any key already holding a note,
+and an invoice nobody pays takes no index at all, so a wallet scanning its
+branch never meets a gap it did not make. The gift wrap still goes to the
+owner's npub, but it carries no secret: a lookup URL,
+`https://mint.example/w?p=<cp1>&amount=<msat>&sig=<cs1>&i=<index>`, plus an
+`i` tag. The wallet derives the key at that index, checks the certificate,
+and spends with its own `ck1`. A wallet that only knows note URLs sees no
+`k1` and passes the wrap by, and the note waits at the mint for a scan of the
+branch.
+
+`"cx1": null` clears the branch and puts the name back on the custodial path.
+This works while registration is closed too: closing it stops new names, not
+the owner of one choosing where it pays, including a name the operator set up
+in `MONEYER_ZAP_NAMES`.
+Sending a new branch starts it at index 0; sending the same one again keeps
+its place. Zap receipts are unchanged.
+
 ## Reaching the mint over Tor
 
 Set `MONEYER_ONION_URL` to this mint's hidden service address and a request

package/THREAT-MODEL.md

@@ -90,6 +90,14 @@ only the buyer ever held, the preimage is bearer material for nothing, and
 what `/verify` serves is an ordinary payment proof. Wallets should prefer
 that path wherever a mint advertises `mintToHash`.
 
+**What a `cx1` on a name gives away.** A name with a watch-only branch is
+paid to the holder's keys, so the mint never holds a secret for those notes.
+But the mint can work out every key on the branch, so it can link every
+payment to that name, and see when each note is spent. That is no more than
+a custodial name already reveals. A wallet should keep the branch for
+receiving and rotate what arrives onto keys the mint cannot enumerate, which
+is what notecase and lnurl-wallet do.
+
 ## Out of scope
 
 - Compromise of the host or the funding source credentials: at that point

package/dist/names.d.ts

@@ -24,6 +24,8 @@ export type NameGranted = {
     name: string;
     pubkey: string;
     paidMsat: number;
+    cx1: string | null;
+    updated: boolean;
 };
 export declare const isRefusal: (result: NameGranted | NameRefusal) => result is NameRefusal;
 export declare const registerName: (args: {
@@ -32,6 +34,7 @@ export declare const registerName: (args: {
     body: {
         name?: unknown;
         note?: unknown;
+        cx1?: unknown;
     };
     priceMsat: number | undefined;
     reserved: string[];

package/dist/names.js

@@ -1,7 +1,7 @@
 import { sha256 } from '@noble/hashes/sha2.js';
 import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js';
 import { verifyEvent } from 'nostr-tools/pure';
-import { hashK1, noteK1 } from 'lnurlcash-kit';
+import { decodeCx1, hashK1, noteK1 } from 'lnurlcash-kit';
 import { NotePendingError, NoteStore, NoteUnavailableError } from "./store.js";
 // Self-service lightning addresses.
 //
@@ -94,8 +94,6 @@ export const isRefusal = (result) => 'reason' in result;
 // the same name at once.
 export const registerName = (args) => {
     const { store, pubkey, priceMsat } = args;
-    if (priceMsat === undefined)
-        return refuse('This mint is not registering names.', 404);
     const raw = typeof args.body.name === 'string' ? args.body.name.trim().toLowerCase() : '';
     if (!NAME_RULE.test(raw)) {
         return refuse('A name is 3 to 32 characters of a-z, 0-9, dot, dash or underscore, starting with a letter or digit.', 400);
@@ -103,8 +101,31 @@ export const registerName = (args) => {
     if ([...ALWAYS_RESERVED, ...args.reserved.map(name => name.toLowerCase())].includes(raw)) {
         return refuse('That name is reserved.', 403);
     }
-    if (store.zapName(raw))
+    // LUD-25 Part 2: a watch-only branch, so payments to the name are minted
+    // to the holder's own keys. Absent leaves it as it is; null clears it.
+    let cx1;
+    if (args.body.cx1 === null) {
+        cx1 = null;
+    }
+    else if (args.body.cx1 !== undefined) {
+        const given = typeof args.body.cx1 === 'string' ? args.body.cx1.trim().toLowerCase() : '';
+        if (!decodeCx1(given))
+            return refuse('That is not a cx1.', 400);
+        cx1 = given;
+    }
+    const existing = store.zapName(raw);
+    if (existing) {
+        // Its owner may set or clear the branch; nobody else may touch it.
+        if (existing.pubkey === pubkey && cx1 !== undefined) {
+            store.setZapNameCx1(raw, cx1);
+            return { name: raw, pubkey, paidMsat: 0, cx1, updated: true };
+        }
         return refuse('That name is taken.', 409);
+    }
+    // Checked after the owner's update above: closing registration stops new
+    // names, not a holder choosing where their own name pays.
+    if (priceMsat === undefined)
+        return refuse('This mint is not registering names.', 404);
     let paidMsat = 0;
     let noteId;
     if (priceMsat === 0) {
@@ -157,7 +178,7 @@ export const registerName = (args) => {
         paidMsat = note.amountMsat;
     }
     try {
-        store.buyZapName({ name: raw, pubkey, ...(noteId ? { noteId } : {}), paidMsat });
+        store.buyZapName({ name: raw, pubkey, ...(noteId ? { noteId } : {}), paidMsat, cx1: cx1 ?? null });
     }
     catch (err) {
         if (err instanceof NotePendingError)
@@ -168,5 +189,5 @@ export const registerName = (args) => {
         // the name and the note together or not at all.
         return refuse('That name is taken.', 409);
     }
-    return { name: raw, pubkey, paidMsat };
+    return { name: raw, pubkey, paidMsat, cx1: cx1 ?? null, updated: false };
 };

package/dist/server.js

@@ -167,6 +167,7 @@ export const createMoneyer = async (config, deps = {}) => {
             mintFeeLine,
             feeInWords,
             verify: config.verify,
+            certify: (noteId, amountMsat) => certify({ id: noteId, cp1: true }, amountMsat),
             // configFromEnv guarantees this when zap is set; a caller
             // building the config by hand gets the same rule.
             origin: config.publicOrigin ?? (() => {
@@ -448,7 +449,10 @@ export const createMoneyer = async (config, deps = {}) => {
         // a POST because it creates something, and it is authenticated by
         // NIP-98 rather than by anything this mint has to store.
         if (requestUrl.pathname === '/names' && req.method === 'POST') {
-            if (config.namePriceMsat === undefined)
+            // Closed registration still lets a name's owner set where it pays;
+            // registerName refuses a new name there. Without zaps there are no
+            // names at all.
+            if (!zap)
                 return fail('This mint is not registering names.', 404);
             const body = await readBody(req);
             if (body === null)
@@ -480,14 +484,19 @@ export const createMoneyer = async (config, deps = {}) => {
             });
             if (isRefusal(result))
                 return fail(result.reason, result.status);
-            log(`name ${result.name} registered to ${result.pubkey.slice(0, 8)} for ${result.paidMsat} msat`);
+            log(result.updated
+                ? `name ${result.name} ${result.cx1 ? 'now pays to a branch' : 'pays out custodially again'}`
+                : `name ${result.name} registered to ${result.pubkey.slice(0, 8)} for ${result.paidMsat} msat`);
             return send({
                 status: 'OK',
                 name: result.name,
                 pubkey: result.pubkey,
                 address: `${result.name}@${host}`,
                 priceMsat: config.namePriceMsat,
-                paidMsat: result.paidMsat
+                paidMsat: result.paidMsat,
+                // With a cx1 the name pays to the holder's own keys; without, as a
+                // note gift-wrapped to them.
+                cx1: result.cx1
             });
         }
         // Every LNURL endpoint below is a GET. The method matters: /w/cb

package/dist/store.d.ts

@@ -53,6 +53,8 @@ export type ZapNameRow = {
     createdAt: number;
     paidMsat: number;
     source: 'env' | 'self';
+    cx1: string | null;
+    nextIndex: number;
 };
 export type NoteListRow = NoteRow & {
     createdAt: number;
@@ -126,16 +128,27 @@ export declare class NoteStore {
     unsettledZapInvoices(): ZapInvoiceRow[];
     deleteUnsettledZapInvoice(paymentHash: string): void;
     settleZapInvoice(paymentHash: string, noteId: string, wrapJson: string, receiptJson: string | null): boolean;
+    settleZapInvoiceToKey(paymentHash: string, keyAt: (index: number) => string | null, build: (noteId: string, index: number) => {
+        wrapJson: string;
+        receiptJson: string | null;
+    }): {
+        noteId: string;
+        index: number;
+    } | null;
     unpublishedZaps(): ZapInvoiceRow[];
     markZapPublished(paymentHash: string): void;
+    private static readonly NAME_COLUMNS;
+    private nameRow;
     zapName(name: string): ZapNameRow | null;
     zapNames(): ZapNameRow[];
+    setZapNameCx1(name: string, cx1: string | null): void;
     putOperatorZapName(name: string, pubkey: string): void;
     buyZapName(args: {
         name: string;
         pubkey: string;
         noteId?: string;
         paidMsat: number;
+        cx1?: string | null;
     }): void;
     removeZapName(name: string): boolean;
     zapNameCountFor(pubkey: string): number;

package/dist/store.js

@@ -117,6 +117,12 @@ export class NoteStore {
         // Two invoices may not name the same note. SQLite counts NULLs as
         // distinct, so every unbound invoice still fits.
         this.db.exec('CREATE UNIQUE INDEX IF NOT EXISTS mint_invoices_output_id ON mint_invoices (output_id)');
+        const nameColumns = this.db.prepare('PRAGMA table_info(zap_names)').all().map(column => column.name);
+        if (!nameColumns.includes('cx1'))
+            this.db.exec('ALTER TABLE zap_names ADD COLUMN cx1 TEXT');
+        if (!nameColumns.includes('next_index')) {
+            this.db.exec('ALTER TABLE zap_names ADD COLUMN next_index INTEGER NOT NULL DEFAULT 0');
+        }
         this.db.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);');
         // The moment this mint stopped publishing preimages for notes nobody
         // named. Written once, the first time a build carrying this code opens
@@ -440,6 +446,39 @@ export class NoteStore {
         });
     }
     // Settled zaps whose wrap has not yet reached a relay.
+    // A zap to a name with a cx1, minted to the next unused key on its
+    // branch. The index is taken here, at settlement, never when the invoice
+    // is made, so an invoice nobody pays leaves no gap in the holder's scan.
+    // A key that already names a note is skipped, as LUD-25 requires.
+    // `keyAt` answers null for an index that yields no usable key.
+    settleZapInvoiceToKey(paymentHash, keyAt, build) {
+        return this.tx(() => {
+            const row = this.zapInvoiceByHash(paymentHash);
+            if (!row || row.settled)
+                return null;
+            const name = this.zapName(row.name);
+            if (!name?.cx1)
+                return null;
+            let index = name.nextIndex;
+            let noteId = null;
+            for (let tries = 0; tries < 1000 && noteId === null; tries++) {
+                const candidate = keyAt(index);
+                if (candidate !== null && !this.outputIdInUse(candidate))
+                    noteId = candidate;
+                else
+                    index += 1;
+            }
+            if (noteId === null)
+                throw new Error(`no free key on the branch of ${row.name}`);
+            this.insertNote(noteId, row.netMsat);
+            this.db.prepare('UPDATE zap_names SET next_index = ? WHERE name = ?').run(index + 1, row.name);
+            const { wrapJson, receiptJson } = build(noteId, index);
+            this.db
+                .prepare('UPDATE zap_invoices SET settled = 1, note_id = ?, wrap_json = ?, receipt_json = ?, settled_at = ? WHERE payment_hash = ?')
+                .run(noteId, wrapJson, receiptJson, Date.now(), paymentHash);
+            return { noteId, index };
+        });
+    }
     unpublishedZaps() {
         const rows = this.db
             .prepare(`SELECT ${NoteStore.ZAP_COLUMNS} FROM zap_invoices WHERE settled = 1 AND published_at IS NULL`)
@@ -458,25 +497,36 @@ export class NoteStore {
     // One table for both kinds: names the operator set in the environment
     // and names people registered themselves. The lookup path that serves a
     // zap does not care which is which, so there is one of it.
+    static NAME_COLUMNS = 'name, pubkey, created_at, paid_msat, source, cx1, next_index';
+    nameRow(row) {
+        return {
+            name: row.name,
+            pubkey: row.pubkey,
+            createdAt: row.created_at,
+            paidMsat: row.paid_msat,
+            source: row.source,
+            cx1: row.cx1 ?? null,
+            nextIndex: row.next_index
+        };
+    }
     zapName(name) {
         const row = this.db
-            .prepare('SELECT name, pubkey, created_at, paid_msat, source FROM zap_names WHERE name = ?')
+            .prepare(`SELECT ${NoteStore.NAME_COLUMNS} FROM zap_names WHERE name = ?`)
             .get(name.toLowerCase());
-        if (!row)
-            return null;
-        return { name: row.name, pubkey: row.pubkey, createdAt: row.created_at, paidMsat: row.paid_msat, source: row.source };
+        return row ? this.nameRow(row) : null;
     }
     zapNames() {
         const rows = this.db
-            .prepare('SELECT name, pubkey, created_at, paid_msat, source FROM zap_names ORDER BY name')
+            .prepare(`SELECT ${NoteStore.NAME_COLUMNS} FROM zap_names ORDER BY name`)
             .all();
-        return rows.map(row => ({
-            name: row.name,
-            pubkey: row.pubkey,
-            createdAt: row.created_at,
-            paidMsat: row.paid_msat,
-            source: row.source
-        }));
+        return rows.map(row => this.nameRow(row));
+    }
+    // A new branch starts at index 0; the same branch sent again keeps its
+    // place, so re-registering cannot walk the holder's keys backwards.
+    setZapNameCx1(name, cx1) {
+        this.db
+            .prepare('UPDATE zap_names SET next_index = CASE WHEN cx1 IS ? THEN next_index ELSE 0 END, cx1 = ? WHERE name = ?')
+            .run(cx1, cx1, name.toLowerCase());
     }
     // The operator's own names, re-applied at every startup. Idempotent, and
     // the environment wins: it is the operator's mint, and a name they put
@@ -499,8 +549,8 @@ export class NoteStore {
                 this.setNoteState(args.noteId, 'burned');
             }
             this.db
-                .prepare("INSERT INTO zap_names (name, pubkey, created_at, paid_msat, source) VALUES (?, ?, ?, ?, 'self')")
-                .run(args.name.toLowerCase(), args.pubkey, Date.now(), args.paidMsat);
+                .prepare("INSERT INTO zap_names (name, pubkey, created_at, paid_msat, source, cx1) VALUES (?, ?, ?, ?, 'self', ?)")
+                .run(args.name.toLowerCase(), args.pubkey, Date.now(), args.paidMsat, args.cx1 ?? null);
         });
     }
     removeZapName(name) {

package/dist/zap.d.ts

@@ -31,6 +31,7 @@ export type ZapBridgeDeps = {
     feeInWords: string | null;
     verify: boolean;
     origin: string;
+    certify: (noteIdHex: string, amountMsat: number) => string;
     log?: (message: string) => void;
     now?: () => number;
 };

package/dist/zap.js

@@ -1,5 +1,5 @@
 import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils.js';
-import { hashK1 } from 'lnurlcash-kit';
+import { decodeCx1, deriveNotePubkey, encodeCp1, hashK1 } from 'lnurlcash-kit';
 import { tryDecodeBolt11 } from 'farrier-kit/bolt11';
 import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
 import { SimplePool } from 'nostr-tools/pool';
@@ -171,8 +171,7 @@ export const createZapBridge = (deps) => {
         store.recordZapInvoice({ paymentHash, name: lowered, recipient, pr, grossMsat: amountMsat, netMsat: net, zapRequest });
         return { pr, ...(deps.verify ? { verify: `${origin}/verify/${paymentHash}` } : {}) };
     };
-    // The note as the recipient's wallet will paste it, wrapped to them.
-    const buildWrap = (row, k1) => {
+    const wrapTags = (row) => {
         const tags = [
             ['p', row.recipient],
             ['amount', String(row.netMsat)],
@@ -192,15 +191,20 @@ export const createZapBridge = (deps) => {
             // older one simply does not see this.
             tags.push(['description', row.zapRequest]);
         }
-        const rumor = {
-            kind: NOTE_KIND,
-            pubkey,
-            created_at: Math.floor(now() / 1000),
-            tags,
-            content: `${origin}/w?k1=${k1}&amount=${row.netMsat}`
-        };
+        return tags;
+    };
+    const wrap = (row, tags, content) => {
+        const rumor = { kind: NOTE_KIND, pubkey, created_at: Math.floor(now() / 1000), tags, content };
         return wrapEvent(rumor, secret, row.recipient);
     };
+    // The note as the recipient's wallet will paste it, wrapped to them.
+    const buildWrap = (row, k1) => wrap(row, wrapTags(row), `${origin}/w?k1=${k1}&amount=${row.netMsat}`);
+    // A zap to a name with a cx1: the note already belongs to the holder's
+    // key, so the wrap carries no secret at all, only where to look (`p`),
+    // the certificate, and the index `i` the holder derives the key at. A
+    // reader that knows only note URLs sees no k1 and passes it by, and the
+    // note waits at the mint for a scan to find it.
+    const buildKeyWrap = (row, noteId, index) => wrap(row, [...wrapTags(row), ['i', String(index)]], `${origin}/w?p=${encodeCp1(hexToBytes(noteId))}&amount=${row.netMsat}&sig=${deps.certify(noteId, row.netMsat)}&i=${index}`);
     // NIP-57 receipt, without the preimage tag: it is optional there, and
     // here it would only invite someone to mistake it for the note.
     const buildReceipt = (row) => {
@@ -222,6 +226,27 @@ export const createZapBridge = (deps) => {
             }
             if (!paid)
                 continue;
+            const branch = decodeCx1(store.zapName(row.name)?.cx1 ?? '');
+            if (branch) {
+                const receipt = buildReceipt(row);
+                const keyAt = (index) => {
+                    try {
+                        return bytesToHex(deriveNotePubkey(branch.pubkeyXOnly, branch.chainCode, index));
+                    }
+                    catch {
+                        return null;
+                    }
+                };
+                const landed = store.settleZapInvoiceToKey(row.paymentHash, keyAt, (noteId, index) => ({
+                    wrapJson: JSON.stringify(buildKeyWrap(row, noteId, index)),
+                    receiptJson: receipt ? JSON.stringify(receipt) : null
+                }));
+                if (landed) {
+                    minted += 1;
+                    log(`zap: ${row.name} received ${row.netMsat} msat; note minted to key ${landed.index}, wrap parked`);
+                }
+                continue;
+            }
             const k1 = bytesToHex(randomBytes(32));
             const noteId = hashK1(k1);
             const wrap = buildWrap(row, k1);

package/llms.txt

@@ -91,3 +91,9 @@ NoteStore - SQLite store; notes by sha256(k1), never secrets
 /verify/{payment_hash}      LUD-21 verify (mint invoices AND melt payments)
 /w                          LUD-03 informational GET by k1 (secret or ck1) or p (hash or cp1, older h); a cp1 note carries its cs1 as sig
 /w/cb                       melt / rotate / split / merge; inputs secrets or ck1, outputs p1/p2 hashes or cp1 (or older h/h2); cp1 outputs certified as cs1
+POST /names                 claim a name (NIP-98; the signer owns it); body {name, note?, cx1?}.
+                            The owner may resend {name, cx1} to set a branch, or cx1: null to clear it
+/z/cb/{name}                zap invoice for a name. With a cx1 the settled note is credited to the
+                            holder's next key, and the kind 2525 gift wrap carries no secret:
+                            /w?p=<cp1>&amount=&sig=<cs1>&i=<index> plus an `i` tag. The index is
+                            taken at settlement, never at the invoice, and occupied keys are skipped

package/package.json

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