@nano133/late-returns 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.3.0
+
+- `perSenderPerDay` (off by default): at most that many returns per sender per
+  UTC day. Later payments from that sender that day are recorded as "kept"
+  (reason "limit"), marked used, and never sent; they don't count toward
+  `perDay`. For a site that doesn't want a flood of payments from one address
+  to cost it a return each.
+- `releaseKept({ rpc, store }, hash, by)`: sends a kept payment back after all
+  (once, with the next run). The sender is read again from your node.
+- `ReturnStore`: `record()` takes an optional `SenderLimit`, a store says
+  `senderLimit: true` and has `release()`. `memoryStore` and `firestoreStore`
+  have both; a store of your own without them works as before, unless you turn
+  `perSenderPerDay` on (then the run stops with a clear error).
+- `firestoreStore`: a sender's daily counter is `sender-<day>-<hash>` in `days`
+  (or `meta`): no address in it, and a `deleteAt` for a TTL policy.
+
 ## 0.2.0
 
 - `firestoreStore`: `mark` names every collection that gets a return's "used"

package/README.md

@@ -30,6 +30,7 @@ to its sender:
 | Never a payment an open checkout can still claim | your `isClaimable()` |
 | Never a payment from these senders | `never` (your own wallets, an admin's top-ups) |
 | At most | 3 new returns per run (`perRun`), 30 per day (`perDay`) |
+| At most, per sender | no limit (`perSenderPerDay`, off by default) |
 
 Each return is recorded together with a "used" mark for the payment, so a
 late claim can't also take it. The wallet then receives exactly that payment
@@ -87,6 +88,32 @@ await runLateReturns({
 Your claim code must refuse a payment whose hash is already in a `used`
 collection; then a payment that went back can never also pay a checkout.
 
+### A limit per sender
+
+Someone can flood your wallet with small wrong payments, and each one costs
+you a return (two blocks). Set `perSenderPerDay` to stop that:
+
+```ts
+await runLateReturns({ /* … */, perSenderPerDay: 10 });
+```
+
+A sender's first 10 late payments in a UTC day go back. From the 11th that
+day, a payment is **kept**: its record has `status: "kept"` and
+`reason: "limit"`, it is marked used (no checkout can claim it), and it is
+never sent. Kept payments don't count toward `perDay`, so one sender can't
+use up the day's returns for everyone else. Say so in your terms.
+
+To send a kept payment back after all (a real customer who made mistakes):
+
+```ts
+import { releaseKept } from "@nano133/late-returns";
+await releaseKept({ rpc, store }, blockHash, "admin@example.com"); // "released" | "not-kept" | "missing"
+```
+
+It goes back with the next run, exactly once. `firestoreStore` keeps each
+sender's daily count in a document `sender-<day>-<hash of the address>` with a
+`deleteAt` date: add a TTL policy on `deleteAt` for that collection.
+
 ### Your own database
 
 Implement `ReturnStore` (see `src/types.ts`). The one hard rule: `record()`

package/ai/SPEC.md

@@ -86,6 +86,12 @@ Pick one:
   - `record()` is one transaction: unless a return exists for the hash, the
     payment is used, or today's count reached the limit, create the return
     (status `pending`), mark the payment used, add one to today's count.
+  - Optional (only for `perSenderPerDay`): `record()` takes a third argument
+    `{ key, max }`. When the sender's count for `key` is already `max`, create
+    the return with status `kept` (reason `limit`) and mark the payment used,
+    without counting the day; otherwise count the sender too. Set
+    `senderLimit: true` and add `release(hash, to, by)`, which turns a `kept`
+    return into `pending` in one transaction.
   - `lock(ttl)` is one row/document `{ owner, until }`. `take()` succeeds only
     when it is free or expired. Every `update()` runs in a transaction that
     first checks `owner` and `until > now`, and throws `LockLost` otherwise.

package/dist/firestoreStore.d.ts

@@ -3,6 +3,11 @@ import { type ReturnStore } from "./types.js";
 /**
  * A store in Firestore (firebase-admin).
  *
+ * With perSenderPerDay, each sender's daily count is a document
+ * "sender-<day>-<hash of the address>" in `days` (or `meta`), with a
+ * `deleteAt` two days after its day: add a TTL policy on `deleteAt` for that
+ * collection to remove old counters.
+ *
  * - `returns`: the collection for return records, one document per payment hash.
  * - `used`: the collections where your checkouts record a claimed payment
  *   (one document per payment hash). A payment with a document in any of them

package/dist/firestoreStore.js

@@ -3,6 +3,11 @@ import { LockLost } from "./types.js";
 /**
  * A store in Firestore (firebase-admin).
  *
+ * With perSenderPerDay, each sender's daily count is a document
+ * "sender-<day>-<hash of the address>" in `days` (or `meta`), with a
+ * `deleteAt` two days after its day: add a TTL policy on `deleteAt` for that
+ * collection to remove old counters.
+ *
  * - `returns`: the collection for return records, one document per payment hash.
  * - `used`: the collections where your checkouts record a claimed payment
  *   (one document per payment hash). A payment with a document in any of them
@@ -30,16 +35,26 @@ export function firestoreStore(db, opts) {
             const snaps = await Promise.all(used.map((c) => c.doc(H).get()));
             return snaps.some((s) => s.exists);
         },
-        async record(r, day) {
+        senderLimit: true,
+        async record(r, day, sender) {
             const H = r.hash.toUpperCase();
             const ref = returns.doc(H);
             const dayRef = days.doc(`returns-${day.key}`);
+            const senderRef = sender ? days.doc(`sender-${sender.key}`) : null;
             return db.runTransaction(async (tx) => {
-                const [ret, d, ...marks] = await Promise.all([tx.get(ref), tx.get(dayRef), ...used.map((c) => tx.get(c.doc(H)))]);
+                const [ret, d, s, ...marks] = await Promise.all([tx.get(ref), tx.get(dayRef), senderRef ? tx.get(senderRef) : Promise.resolve(null), ...used.map((c) => tx.get(c.doc(H)))]);
                 if (ret.exists)
                     return "exists";
                 if (marks.some((m) => m.exists))
                     return "used";
+                const sent = s?.data()?.n ?? 0;
+                if (sender && sent >= sender.max) {
+                    // Over the sender's limit: kept (marked used so no checkout claims it), not sent, not counted in the day.
+                    for (const c of mark)
+                        tx.set(c.doc(H), { return: H, at: Date.now() });
+                    tx.set(ref, { ...r, hash: H, status: "kept", reason: "limit", day: day.key, createdAt: Date.now() });
+                    return "kept";
+                }
                 const n = d.data()?.n ?? 0;
                 if (n >= day.max)
                     return "limit";
@@ -47,9 +62,22 @@ export function firestoreStore(db, opts) {
                     tx.set(c.doc(H), { return: H, at: Date.now() });
                 tx.set(ref, { ...r, hash: H, status: "pending", createdAt: Date.now() });
                 tx.set(dayRef, { n: n + 1 });
+                // A sender's counter holds no address; deleteAt lets a Firestore TTL policy remove it after the day.
+                if (senderRef)
+                    tx.set(senderRef, { n: sent + 1, deleteAt: new Date(Date.parse(`${day.key}T00:00:00Z`) + 2 * 86_400_000) });
                 return "created";
             });
         },
+        release: (hash, to, by) => db.runTransaction(async (tx) => {
+            const ref = returns.doc(hash.toUpperCase());
+            const r = (await tx.get(ref)).data();
+            if (!r)
+                return "missing";
+            if (r.status !== "kept")
+                return "not-kept";
+            tx.update(ref, { status: "pending", to, releasedBy: by, releasedAt: Date.now() });
+            return "released";
+        }),
         async get(hash) {
             const d = await returns.doc(hash.toUpperCase()).get();
             return d.exists ? d.data() : null;

package/dist/index.d.ts

@@ -28,6 +28,14 @@ export type LateReturnOptions = {
     perRun?: number;
     /** New returns per day (UTC). Default 30. */
     perDay?: number;
+    /**
+     * Returns per sender per day (UTC). Off by default (no limit). When set, a
+     * sender's later payments that day are kept: recorded with status "kept"
+     * and reason "limit", marked used, never sent unless you call releaseKept().
+     * Kept payments don't count toward `perDay`. Needs a store with
+     * `senderLimit` (memoryStore and firestoreStore have it).
+     */
+    perSenderPerDay?: number;
     /**
      * Also look at the wallet's recent receives, not only its waiting payments.
      * Turn on if something else receives into this wallet (a payout run does).
@@ -46,6 +54,15 @@ export type LateReturnOptions = {
 };
 /** Finds late payments and records their returns (it sends nothing). Returns how many it recorded. */
 export declare function findLateReturns(o: LateReturnOptions): Promise<number>;
+/** A sender's counter for a day: the day and a hash of the address (the address itself is not stored in it). */
+export declare const senderKey: (day: string, address: string) => string;
+/**
+ * Releases a kept payment: it goes back to its sender with the next run
+ * (exactly once, like any return). The sender is read again from your node
+ * (block_info), so this works even if your site replaced the stored address.
+ * `by` records who released it. A payment that isn't kept is left alone.
+ */
+export declare function releaseKept(o: Pick<LateReturnOptions, "rpc" | "store">, hash: string, by: string): Promise<"released" | "not-kept" | "missing">;
 /** Sends the pending returns back, each exactly once. Returns how many it sent. Needs the lock. */
 export declare function settleReturns(o: LateReturnOptions, lock: ReturnType<ReturnStore["lock"]>): Promise<number>;
 /**

package/dist/index.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { nanoPrefix } from "./address.js";
 import { sendOnce } from "./sendOnce.js";
 import { LockLost } from "./types.js";
@@ -36,6 +37,9 @@ export async function findLateReturns(o) {
     const d = defaults(o);
     const never = new Set([o.signer.address, ...(o.never ?? [])].map(nanoPrefix));
     const day = { key: new Date(d.now).toISOString().slice(0, 10), max: d.perDay };
+    const perSender = o.perSenderPerDay;
+    if (perSender !== undefined && !o.store.senderLimit)
+        throw new Error("perSenderPerDay needs a store with senderLimit (memoryStore and firestoreStore have it)");
     let made = 0;
     for (const [hash, amount] of await candidates(o, d.minRaw)) {
         if (made >= d.perRun)
@@ -55,7 +59,7 @@ export async function findLateReturns(o) {
             continue;
         if (await o.isClaimable({ hash, amount, from, seenAt }))
             continue;
-        const res = await o.store.record({ hash, amount, to: from, by: "auto" }, day);
+        const res = await o.store.record({ hash, amount, to: from, by: "auto" }, day, perSender === undefined ? undefined : { key: senderKey(day.key, from), max: perSender });
         if (res === "limit")
             break;
         if (res === "created")
@@ -63,6 +67,26 @@ export async function findLateReturns(o) {
     }
     return made;
 }
+/** A sender's counter for a day: the day and a hash of the address (the address itself is not stored in it). */
+export const senderKey = (day, address) => `${day}-${createHash("sha256").update(nanoPrefix(address)).digest("hex").slice(0, 32)}`;
+/**
+ * Releases a kept payment: it goes back to its sender with the next run
+ * (exactly once, like any return). The sender is read again from your node
+ * (block_info), so this works even if your site replaced the stored address.
+ * `by` records who released it. A payment that isn't kept is left alone.
+ */
+export async function releaseKept(o, hash, by) {
+    if (!o.store.release)
+        throw new Error("this store can't release kept payments (it has no release())");
+    const H = hash.toUpperCase();
+    const r = await o.store.get(H);
+    if (!r)
+        return "missing";
+    if (r.status !== "kept")
+        return "not-kept";
+    const info = await o.rpc({ action: "block_info", hash: H, json_block: "true" });
+    return o.store.release(H, nanoPrefix(info.block_account), by);
+}
 /** Sends the pending returns back, each exactly once. Returns how many it sent. Needs the lock. */
 export async function settleReturns(o, lock) {
     const d = defaults(o);

package/dist/memoryStore.d.ts

@@ -8,5 +8,6 @@ export declare function memoryStore(used?: Set<string>): ReturnStore & {
     returns: Map<string, ReturnRecord>;
     used: Set<string>;
     days: Map<string, number>;
+    senders: Map<string, number>;
     expireLock: () => void;
 };

package/dist/memoryStore.js

@@ -8,11 +8,15 @@ import { LockLost } from "./types.js";
 export function memoryStore(used = new Set()) {
     const returns = new Map();
     const days = new Map();
+    /** Returns per sender per day (key: senderKey()). */
+    const senders = new Map();
     let held = null;
     const store = {
         returns,
         used,
         days,
+        senders,
+        senderLimit: true,
         /** Tests only: makes the current lock expire now. */
         expireLock: () => {
             if (held)
@@ -21,20 +25,37 @@ export function memoryStore(used = new Set()) {
         async isUsed(hash) {
             return used.has(hash.toUpperCase());
         },
-        async record(r, day) {
+        async record(r, day, sender) {
             const hash = r.hash.toUpperCase();
             if (returns.has(hash))
                 return "exists";
             if (used.has(hash))
                 return "used";
+            const s = sender ? (senders.get(sender.key) ?? 0) : 0;
+            if (sender && s >= sender.max) {
+                used.add(hash);
+                returns.set(hash, { ...r, hash, status: "kept", reason: "limit", day: day.key, createdAt: Date.now() });
+                return "kept";
+            }
             const n = days.get(day.key) ?? 0;
             if (n >= day.max)
                 return "limit";
             used.add(hash);
             returns.set(hash, { ...r, hash, status: "pending", createdAt: Date.now() });
             days.set(day.key, n + 1);
+            if (sender)
+                senders.set(sender.key, s + 1);
             return "created";
         },
+        async release(hash, to, by) {
+            const r = returns.get(hash.toUpperCase());
+            if (!r)
+                return "missing";
+            if (r.status !== "kept")
+                return "not-kept";
+            Object.assign(r, { status: "pending", to, releasedBy: by, releasedAt: Date.now() });
+            return "released";
+        },
         async get(hash) {
             const r = returns.get(hash.toUpperCase());
             return r ? structuredClone(r) : null;

package/dist/types.d.ts

@@ -57,10 +57,17 @@ export type ReturnRecord = {
     amount: string;
     /** Where it goes back to: the payment's sender. */
     to: string;
-    status: "pending" | "returned";
+    /** "kept": over the sender's daily limit (perSenderPerDay); it waits, unsent, until releaseKept(). */
+    status: "pending" | "returned" | "kept";
     /** "auto" for the scan, or who asked (an admin). */
     by: string;
     createdAt: number;
+    /** Why a payment was kept ("limit"), and the UTC day it counted on. */
+    reason?: string | null;
+    day?: string | null;
+    /** Who released a kept payment, and when. */
+    releasedBy?: string | null;
+    releasedAt?: number | null;
     /** The receive of this payment, once the wallet has it ("earlier" when an earlier run received it). */
     recv?: string | null;
     send?: SendIntent | null;
@@ -68,7 +75,12 @@ export type ReturnRecord = {
     error?: string | null;
     tries?: number;
 };
-export type RecordResult = "created" | "exists" | "used" | "limit";
+export type RecordResult = "created" | "exists" | "used" | "limit" | "kept";
+/** A sender's daily limit for record(): `key` names the sender and the day (it holds no address), `max` the returns it may have. */
+export type SenderLimit = {
+    key: string;
+    max: number;
+};
 /** The wallet's lock: one run at a time. Every money write proves it still holds the lock. */
 export interface Lock {
     /** Takes the lock, or returns false when another run holds it. */
@@ -88,6 +100,11 @@ export interface ReturnStore {
      * In one atomic step: unless a return exists for the hash, the payment is
      * used, or today's count reached `day.max`, create the pending return, mark
      * the payment used (so no checkout can claim it later) and count it.
+     *
+     * With `sender` (only when the store has `senderLimit`): a payment whose
+     * sender already has `sender.max` returns today is recorded as "kept"
+     * instead (marked used, not sent, not counted in `day`), and the result is
+     * "kept". Otherwise the sender's count goes up with the day's.
      */
     record(r: {
         hash: string;
@@ -97,7 +114,15 @@ export interface ReturnStore {
     }, day: {
         key: string;
         max: number;
-    }): Promise<RecordResult>;
+    }, sender?: SenderLimit): Promise<RecordResult>;
+    /** True when record() takes a SenderLimit, and release() exists (perSenderPerDay needs both). */
+    senderLimit?: boolean;
+    /**
+     * A kept payment goes back after all: in one atomic step, a "kept" record
+     * becomes "pending" (sent by the next run), going to `to`. Anything else is
+     * left alone.
+     */
+    release?(hash: string, to: string, by: string): Promise<"released" | "not-kept" | "missing">;
     get(hash: string): Promise<ReturnRecord | null>;
     pending(limit: number): Promise<ReturnRecord[]>;
     /** A lock for one run, held for `ttlMs` unless renewed. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano133/late-returns",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Send Nano (XNO) payments that nothing claimed back to their sender, exactly once.",
   "type": "module",
   "main": "dist/index.js",

package/src/firestoreStore.ts

@@ -5,6 +5,11 @@ import { LockLost, type Lock, type RecordResult, type ReturnRecord, type ReturnS
 /**
  * A store in Firestore (firebase-admin).
  *
+ * With perSenderPerDay, each sender's daily count is a document
+ * "sender-<day>-<hash of the address>" in `days` (or `meta`), with a
+ * `deleteAt` two days after its day: add a TTL policy on `deleteAt` for that
+ * collection to remove old counters.
+ *
  * - `returns`: the collection for return records, one document per payment hash.
  * - `used`: the collections where your checkouts record a claimed payment
  *   (one document per payment hash). A payment with a document in any of them
@@ -32,22 +37,42 @@ export function firestoreStore(db: Firestore, opts: { returns: string; used: str
       const snaps = await Promise.all(used.map((c) => c.doc(H).get()));
       return snaps.some((s) => s.exists);
     },
-    async record(r, day): Promise<RecordResult> {
+    senderLimit: true,
+    async record(r, day, sender): Promise<RecordResult> {
       const H = r.hash.toUpperCase();
       const ref = returns.doc(H);
       const dayRef = days.doc(`returns-${day.key}`);
+      const senderRef = sender ? days.doc(`sender-${sender.key}`) : null;
       return db.runTransaction(async (tx) => {
-        const [ret, d, ...marks] = await Promise.all([tx.get(ref), tx.get(dayRef), ...used.map((c) => tx.get(c.doc(H)))]);
+        const [ret, d, s, ...marks] = await Promise.all([tx.get(ref), tx.get(dayRef), senderRef ? tx.get(senderRef) : Promise.resolve(null), ...used.map((c) => tx.get(c.doc(H)))]);
         if (ret.exists) return "exists";
         if (marks.some((m) => m.exists)) return "used";
+        const sent = (s?.data()?.n as number | undefined) ?? 0;
+        if (sender && sent >= sender.max) {
+          // Over the sender's limit: kept (marked used so no checkout claims it), not sent, not counted in the day.
+          for (const c of mark) tx.set(c.doc(H), { return: H, at: Date.now() });
+          tx.set(ref, { ...r, hash: H, status: "kept", reason: "limit", day: day.key, createdAt: Date.now() } satisfies ReturnRecord);
+          return "kept";
+        }
         const n = (d.data()?.n as number | undefined) ?? 0;
         if (n >= day.max) return "limit";
         for (const c of mark) tx.set(c.doc(H), { return: H, at: Date.now() });
         tx.set(ref, { ...r, hash: H, status: "pending", createdAt: Date.now() } satisfies ReturnRecord);
         tx.set(dayRef, { n: n + 1 });
+        // A sender's counter holds no address; deleteAt lets a Firestore TTL policy remove it after the day.
+        if (senderRef) tx.set(senderRef, { n: sent + 1, deleteAt: new Date(Date.parse(`${day.key}T00:00:00Z`) + 2 * 86_400_000) });
         return "created";
       });
     },
+    release: (hash, to, by) =>
+      db.runTransaction(async (tx) => {
+        const ref = returns.doc(hash.toUpperCase());
+        const r = (await tx.get(ref)).data() as ReturnRecord | undefined;
+        if (!r) return "missing";
+        if (r.status !== "kept") return "not-kept";
+        tx.update(ref, { status: "pending", to, releasedBy: by, releasedAt: Date.now() });
+        return "released";
+      }),
     async get(hash) {
       const d = await returns.doc(hash.toUpperCase()).get();
       return d.exists ? (d.data() as ReturnRecord) : null;

package/src/index.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { nanoPrefix } from "./address.js";
 import { sendOnce } from "./sendOnce.js";
 import { LockLost, type BlockInfo, type ReturnStore, type Rpc, type Signer } from "./types.js";
@@ -20,7 +21,10 @@ export { publicKeyOf } from "./address.js";
 //   checkouts can still claim the amount (isClaimable);
 // - never one sent by an address in `never` (your own wallets, an admin who
 //   tops the wallet up);
-// - at most `perRun` new returns per run and `perDay` per day.
+// - at most `perRun` new returns per run and `perDay` per day;
+// - with `perSenderPerDay` (off by default): at most that many returns per
+//   sender per day. Later payments from that sender that day are kept: recorded
+//   as "kept", marked used, not sent, until you release one (releaseKept).
 //
 // Each return is recorded together with a "used" mark for the payment, so a
 // late claim can't also take it. The wallet then receives exactly that
@@ -47,6 +51,14 @@ export type LateReturnOptions = {
   perRun?: number;
   /** New returns per day (UTC). Default 30. */
   perDay?: number;
+  /**
+   * Returns per sender per day (UTC). Off by default (no limit). When set, a
+   * sender's later payments that day are kept: recorded with status "kept"
+   * and reason "limit", marked used, never sent unless you call releaseKept().
+   * Kept payments don't count toward `perDay`. Needs a store with
+   * `senderLimit` (memoryStore and firestoreStore have it).
+   */
+  perSenderPerDay?: number;
   /**
    * Also look at the wallet's recent receives, not only its waiting payments.
    * Turn on if something else receives into this wallet (a payout run does).
@@ -100,6 +112,8 @@ export async function findLateReturns(o: LateReturnOptions): Promise<number> {
   const d = defaults(o);
   const never = new Set([o.signer.address, ...(o.never ?? [])].map(nanoPrefix));
   const day = { key: new Date(d.now).toISOString().slice(0, 10), max: d.perDay };
+  const perSender = o.perSenderPerDay;
+  if (perSender !== undefined && !o.store.senderLimit) throw new Error("perSenderPerDay needs a store with senderLimit (memoryStore and firestoreStore have it)");
   let made = 0;
   for (const [hash, amount] of await candidates(o, d.minRaw)) {
     if (made >= d.perRun) break;
@@ -112,13 +126,32 @@ export async function findLateReturns(o: LateReturnOptions): Promise<number> {
     const seenAt = Number(info.local_timestamp ?? 0) * 1000;
     if (!seenAt || d.now - seenAt < d.minAgeSec * 1000) continue;
     if (await o.isClaimable({ hash, amount, from, seenAt })) continue;
-    const res = await o.store.record({ hash, amount, to: from, by: "auto" }, day);
+    const res = await o.store.record({ hash, amount, to: from, by: "auto" }, day, perSender === undefined ? undefined : { key: senderKey(day.key, from), max: perSender });
     if (res === "limit") break;
     if (res === "created") made++;
   }
   return made;
 }
 
+/** A sender's counter for a day: the day and a hash of the address (the address itself is not stored in it). */
+export const senderKey = (day: string, address: string) => `${day}-${createHash("sha256").update(nanoPrefix(address)).digest("hex").slice(0, 32)}`;
+
+/**
+ * Releases a kept payment: it goes back to its sender with the next run
+ * (exactly once, like any return). The sender is read again from your node
+ * (block_info), so this works even if your site replaced the stored address.
+ * `by` records who released it. A payment that isn't kept is left alone.
+ */
+export async function releaseKept(o: Pick<LateReturnOptions, "rpc" | "store">, hash: string, by: string): Promise<"released" | "not-kept" | "missing"> {
+  if (!o.store.release) throw new Error("this store can't release kept payments (it has no release())");
+  const H = hash.toUpperCase();
+  const r = await o.store.get(H);
+  if (!r) return "missing";
+  if (r.status !== "kept") return "not-kept";
+  const info = await o.rpc<BlockInfo>({ action: "block_info", hash: H, json_block: "true" });
+  return o.store.release(H, nanoPrefix(info.block_account), by);
+}
+
 /** Sends the pending returns back, each exactly once. Returns how many it sent. Needs the lock. */
 export async function settleReturns(o: LateReturnOptions, lock: ReturnType<ReturnStore["lock"]>): Promise<number> {
   const d = defaults(o);

package/src/memoryStore.ts

@@ -9,12 +9,16 @@ import { LockLost, type Lock, type RecordResult, type ReturnRecord, type ReturnS
 export function memoryStore(used: Set<string> = new Set()) {
   const returns = new Map<string, ReturnRecord>();
   const days = new Map<string, number>();
+  /** Returns per sender per day (key: senderKey()). */
+  const senders = new Map<string, number>();
   let held: { owner: string; until: number } | null = null;
 
-  const store: ReturnStore & { returns: Map<string, ReturnRecord>; used: Set<string>; days: Map<string, number>; expireLock: () => void } = {
+  const store: ReturnStore & { returns: Map<string, ReturnRecord>; used: Set<string>; days: Map<string, number>; senders: Map<string, number>; expireLock: () => void } = {
     returns,
     used,
     days,
+    senders,
+    senderLimit: true,
     /** Tests only: makes the current lock expire now. */
     expireLock: () => {
       if (held) held.until = 0;
@@ -22,17 +26,31 @@ export function memoryStore(used: Set<string> = new Set()) {
     async isUsed(hash) {
       return used.has(hash.toUpperCase());
     },
-    async record(r, day): Promise<RecordResult> {
+    async record(r, day, sender): Promise<RecordResult> {
       const hash = r.hash.toUpperCase();
       if (returns.has(hash)) return "exists";
       if (used.has(hash)) return "used";
+      const s = sender ? (senders.get(sender.key) ?? 0) : 0;
+      if (sender && s >= sender.max) {
+        used.add(hash);
+        returns.set(hash, { ...r, hash, status: "kept", reason: "limit", day: day.key, createdAt: Date.now() });
+        return "kept";
+      }
       const n = days.get(day.key) ?? 0;
       if (n >= day.max) return "limit";
       used.add(hash);
       returns.set(hash, { ...r, hash, status: "pending", createdAt: Date.now() });
       days.set(day.key, n + 1);
+      if (sender) senders.set(sender.key, s + 1);
       return "created";
     },
+    async release(hash, to, by) {
+      const r = returns.get(hash.toUpperCase());
+      if (!r) return "missing";
+      if (r.status !== "kept") return "not-kept";
+      Object.assign(r, { status: "pending", to, releasedBy: by, releasedAt: Date.now() });
+      return "released";
+    },
     async get(hash) {
       const r = returns.get(hash.toUpperCase());
       return r ? structuredClone(r) : null;

package/src/types.ts

@@ -37,10 +37,17 @@ export type ReturnRecord = {
   amount: string;
   /** Where it goes back to: the payment's sender. */
   to: string;
-  status: "pending" | "returned";
+  /** "kept": over the sender's daily limit (perSenderPerDay); it waits, unsent, until releaseKept(). */
+  status: "pending" | "returned" | "kept";
   /** "auto" for the scan, or who asked (an admin). */
   by: string;
   createdAt: number;
+  /** Why a payment was kept ("limit"), and the UTC day it counted on. */
+  reason?: string | null;
+  day?: string | null;
+  /** Who released a kept payment, and when. */
+  releasedBy?: string | null;
+  releasedAt?: number | null;
   /** The receive of this payment, once the wallet has it ("earlier" when an earlier run received it). */
   recv?: string | null;
   send?: SendIntent | null;
@@ -49,7 +56,10 @@ export type ReturnRecord = {
   tries?: number;
 };
 
-export type RecordResult = "created" | "exists" | "used" | "limit";
+export type RecordResult = "created" | "exists" | "used" | "limit" | "kept";
+
+/** A sender's daily limit for record(): `key` names the sender and the day (it holds no address), `max` the returns it may have. */
+export type SenderLimit = { key: string; max: number };
 
 /** The wallet's lock: one run at a time. Every money write proves it still holds the lock. */
 export interface Lock {
@@ -71,8 +81,21 @@ export interface ReturnStore {
    * In one atomic step: unless a return exists for the hash, the payment is
    * used, or today's count reached `day.max`, create the pending return, mark
    * the payment used (so no checkout can claim it later) and count it.
+   *
+   * With `sender` (only when the store has `senderLimit`): a payment whose
+   * sender already has `sender.max` returns today is recorded as "kept"
+   * instead (marked used, not sent, not counted in `day`), and the result is
+   * "kept". Otherwise the sender's count goes up with the day's.
+   */
+  record(r: { hash: string; amount: string; to: string; by: string }, day: { key: string; max: number }, sender?: SenderLimit): Promise<RecordResult>;
+  /** True when record() takes a SenderLimit, and release() exists (perSenderPerDay needs both). */
+  senderLimit?: boolean;
+  /**
+   * A kept payment goes back after all: in one atomic step, a "kept" record
+   * becomes "pending" (sent by the next run), going to `to`. Anything else is
+   * left alone.
    */
-  record(r: { hash: string; amount: string; to: string; by: string }, day: { key: string; max: number }): Promise<RecordResult>;
+  release?(hash: string, to: string, by: string): Promise<"released" | "not-kept" | "missing">;
   get(hash: string): Promise<ReturnRecord | null>;
   pending(limit: number): Promise<ReturnRecord[]>;
   /** A lock for one run, held for `ttlMs` unless renewed. */