@zerc20/wallet-sdk 0.4.0 → 0.5.0

package/src/pos.ts

@@ -3,7 +3,7 @@
 // every wallet downloads. Stolen, it gives away which addresses are the merchant's, and nothing else: the merchant's
 // wallet alone spends what they receive, merges it and withdraws it.
 
-import { BURN_BLOCK, CanisterClient, lookupRecipient, writePosBlock } from '@zerc20/storage-sdk';
+import { BURN_BLOCK, CanisterClient, MAX_POS_BLOCKS, lookupRecipient, writePosBlocks } from '@zerc20/storage-sdk';
 import {
   type Address,
   type Hex,
@@ -16,11 +16,11 @@ import {
   zeroAddress,
 } from 'viem';
 import { Chain, type Token } from './chain.js';
-import { burnAddress, core, initCore } from './core.js';
-import { fail } from './errors.js';
+import { type Burn, burnAddress, core, initCore } from './core.js';
+import { WalletError, fail } from './errors.js';
 import { type ChainConfig, type Network, checkNetwork } from './network.js';
 import { scan } from './scan.js';
-import { Asp, Indexer } from './servers.js';
+import { Asp, Indexer, type IndexerStatus } from './servers.js';
 import { registerDeposit } from './services.js';
 import type { DepositRecord } from './state.js';
 import { applyHits, commitmentFields, commitmentTx, dropReorged, readDecisions, readTransfers } from './sync.js';
@@ -28,6 +28,8 @@ import { applyHits, commitmentFields, commitmentTx, dropReorged, readDecisions,
 /** The longest a refill waits once a token's addresses run low: a write at a random time after the sale that drew
  * them down, not right after it, so that the write's time does not mark that sale. */
 const REFILL_WITHIN_MS = 10 * 60_000;
+/** How long what a pass over the chains read may go unsaved: lost, it is read from the chains again. */
+const PASS_SAVED_WITHIN_MS = 60_000;
 
 /** What a point of sale needs of a token: where it is, and its id for the burn addresses' derivation and tags. */
 export type PosToken = Pick<Token, 'chainId' | 'tokenId' | 'address'>;
@@ -74,6 +76,16 @@ export interface SaleStatus {
 
 type Watched = Pick<DepositRecord, 'address' | 'watches' | 'found'>;
 
+/** A token's addresses: made and recorded ahead of its sales. */
+interface Pool {
+  /** The next counter to derive. */
+  next: number;
+  /** Addresses made and not recorded yet, a block of counters `first..` each. */
+  made: { first: number; burns: Burn[] }[];
+  /** Addresses recorded in the lane that no sale has had. */
+  ready: Address[];
+}
+
 interface Connection {
   merchant: Address;
   /** The zERC20 public key the merchant registered in storage, which its burn addresses are under. */
@@ -81,8 +93,8 @@ interface Connection {
   laneKey: Hex;
   /** Per chain, the lane's first slot not known to be taken. */
   slots: Record<string, number>;
-  /** Per `chainId:tokenId`, the next counter to derive, and the addresses recorded in the lane that no sale has had. */
-  pools: Record<string, { next: number; ready: Address[] }>;
+  /** Per `chainId:tokenId`. */
+  pools: Record<string, Pool>;
 }
 
 interface Saved {
@@ -103,7 +115,29 @@ const decode = (b: Uint8Array): Saved =>
   ) as Saved;
 
 const same = (a: string, b: string) => a.toLowerCase() === b.toLowerCase();
-const pairOf = (token: PosToken) => `${token.chainId}:${token.tokenId}`;
+const pairOf = (token: Pick<PosToken, 'chainId' | 'tokenId'>) => `${token.chainId}:${token.tokenId}`;
+const madeOf = (pool: Pool) => pool.made.length * BURN_BLOCK;
+
+/** A chain's indexer as one pass reads it: its status, read once for every point of sale of the process that asks while
+ * it is read, and the tag pages they read after it, each once. The points of sale of a server run their passes side by
+ * side, so the indexer serves each page once a pass, not once a merchant; and a page read after the status is never
+ * older than it, which the scan needs. */
+interface Pass {
+  status: IndexerStatus;
+  tags: Map<number, Promise<Uint8Array>>;
+}
+const passes = new Map<string, Promise<Pass>>();
+
+function passOf(indexer: Indexer): Promise<Pass> {
+  let pass = passes.get(indexer.url);
+  if (!pass) {
+    const read = indexer.status().then((status) => ({ status, tags: new Map() }));
+    const done = () => void (passes.get(indexer.url) === read && passes.delete(indexer.url));
+    read.then(done, done);
+    passes.set(indexer.url, (pass = read));
+  }
+  return pass;
+}
 
 export class PointOfSale {
   readonly #network: Network;
@@ -111,12 +145,23 @@ export class PointOfSale {
   readonly #persist: { save(bytes: Uint8Array): Promise<void> };
   readonly #refillWithinMs: number;
   readonly #chains = new Map<bigint, Chain>();
-  /** The refill running for each token, and the one waiting to. */
-  readonly #fills = new Map<string, Promise<void>>();
+  /** Sales by lowercase id. */
+  readonly #byId = new Map<string, Sale>();
+  /** The block each token is making ahead: one at a time, beside those made for a sale that waits. */
+  readonly #making = new Map<string, Promise<void>>();
+  /** The write each token has under way: one at a time. */
+  readonly #recording = new Map<string, Promise<void>>();
+  /** The write each token waits to do, at a random time. */
   readonly #timers = new Map<string, ReturnType<typeof setTimeout>>();
+  /** How many sales of each token wait for an address. */
+  readonly #waiting = new Map<string, number>();
+  /** The searches of the lane connected now: another lane, or closing, stops them. */
+  #searches = new AbortController();
   #storage: Promise<CanisterClient> | undefined;
   #queue: Promise<unknown> = Promise.resolve();
   #saving: Promise<unknown> = Promise.resolve();
+  #passSave: ReturnType<typeof setTimeout> | undefined;
+  #closed = false;
 
   private constructor(
     network: Network,
@@ -128,10 +173,12 @@ export class PointOfSale {
     this.#state = state;
     this.#persist = persist;
     this.#refillWithinMs = refillWithinMs;
+    for (const s of state.sales) this.#byId.set(s.id.toLowerCase(), s);
   }
 
   /** Opens the point of sale's saved state. It keeps which addresses it handed out: lose that, and it may hand one out
-   * twice. One state, one point of sale: two open on it would hand out the same addresses. */
+   * twice. One state, one point of sale: two open on it would hand out the same addresses, so `close` the one before
+   * opening it again. */
   static async open(opts: {
     network: Network;
     persist: { load(): Promise<Uint8Array | null | undefined>; save(bytes: Uint8Array): Promise<void> };
@@ -141,6 +188,8 @@ export class PointOfSale {
     await initCore();
     const saved = await opts.persist.load();
     const state: Saved = saved?.length ? decode(saved) : { connection: null, sales: [], seen: {}, txs: {} };
+    // a state saved before addresses were made ahead
+    for (const pool of Object.values(state.connection?.pools ?? {})) pool.made ??= [];
     return new PointOfSale(opts.network, state, opts.persist, opts.refillWithinMs ?? REFILL_WITHIN_MS);
   }
 
@@ -159,9 +208,7 @@ export class PointOfSale {
       if (c && same(c.merchant, merchant) && same(c.laneKey, laneKey)) return;
       const recipient = await lookupRecipient(await this.#client(), hexToBytes(merchant));
       if (!recipient) fail('invalid', `${merchant} has not registered for private payments: open its wallet once`);
-      for (const t of this.#timers.values()) clearTimeout(t);
-      this.#timers.clear();
-      this.#fills.clear();
+      this.#stop();
       this.#state.connection = {
         merchant: getAddress(merchant),
         publicKey: bytesToHex(recipient!.publicKey),
@@ -173,11 +220,20 @@ export class PointOfSale {
     });
   }
 
+  /** Stops making and recording, then saves the state as it is: nothing is saved after, so the state may be opened
+   * again. A sale under way then fails rather than hand out an address it could not save. */
+  async close(): Promise<void> {
+    this.#stop();
+    const last = this.#save();
+    this.#closed = true;
+    await last;
+  }
+
   /** Readies addresses of `token` ahead of its sales: an app calls it for each token it takes, as it starts and after
    * sales. Nothing happens while enough are ready, or a refill is under way or due. */
   prepare(token: PosToken): void {
     chainOf(this.#network, token.chainId);
-    this.#topUp(token);
+    this.#supply(token);
   }
 
   /** How many addresses of `token` are recorded and wait for a sale. */
@@ -191,9 +247,19 @@ export class PointOfSale {
     const { token } = opts;
     const c = chainOf(this.#network, token.chainId);
     this.#connection();
-    const { commitmentsFinal: from } = await new Indexer(c.indexer).status();
+    const pair = pairOf(token);
+    // counted from the start, so that the sales that come at once have their addresses made at once
+    this.#waiting.set(pair, (this.#waiting.get(pair) ?? 0) + 1);
     let burnAddress: Address | undefined;
-    while (!(burnAddress = this.#connection().pools[pairOf(token)]?.ready.shift())) await this.#fill(token);
+    let from: number;
+    try {
+      ({ commitmentsFinal: from } = await new Indexer(c.indexer).status());
+      while (!(burnAddress = this.#pool(token).ready.shift())) await this.#record(token);
+    } finally {
+      const left = this.#waiting.get(pair)! - 1;
+      if (left) this.#waiting.set(pair, left);
+      else this.#waiting.delete(pair);
+    }
     // saved as taken before the deposit relayer is asked: a sale that fails half-way never hands it out again
     const sale: Sale = {
       id: burnAddress,
@@ -209,9 +275,10 @@ export class PointOfSale {
     };
     const watch = { key: tag(token.tokenId, burnAddress), from, scannedTo: from };
     this.#state.sales.push(sale);
+    this.#byId.set(burnAddress.toLowerCase(), sale);
     this.#state.seen[burnAddress] = { address: burnAddress, watches: [{ tokenId: token.tokenId, watch }], found: [] };
     await this.#save();
-    this.#topUp(token);
+    this.#supply(token);
     return opts.via === 'deposit' ? this.#exclusive(() => this.#register(sale, opts.refundTo)) : sale;
   }
 
@@ -231,7 +298,9 @@ export class PointOfSale {
       if (same(sale.refundTo!, to)) return sale;
       return fail('invalid', `sale ${sale.id} already has a deposit address, refunding to ${sale.refundTo}`);
     }
-    const { depositAddress, fee } = await registerDeposit(this.#chain(sale.chainId), sale.token, sale.burnAddress, to);
+    const { depositAddress, fee } = await registerDeposit(this.#chain(sale.chainId), sale.token, sale.burnAddress, {
+      address: to,
+    });
     Object.assign(sale, { depositAddress, depositFee: fee, refundTo: to });
     await this.#save();
     return sale;
@@ -241,6 +310,11 @@ export class PointOfSale {
     return [...this.#state.sales];
   }
 
+  /** Sale `id`. */
+  sale(id: Address): Sale {
+    return this.#sale(id);
+  }
+
   /** What reached each of sales `ids`: every transfer to its burn address, with where each stands. One pass per chain
    * for them all, reading only what every wallet downloads, so no server learns which addresses it asks about. A chain
    * that fails keeps what was read before, and its error is returned. */
@@ -257,7 +331,7 @@ export class PointOfSale {
           ).catch((e: unknown) => void errors.push(e)),
         ),
       );
-      await this.#save();
+      this.#saveSoon();
       return { sales: sales.map((s) => this.#statusOf(s)), errors };
     });
   }
@@ -278,9 +352,14 @@ export class PointOfSale {
     const c = chainOf(this.#network, chainId);
     const indexer = new Indexer(c.indexer);
     const seen = sales.map((s) => this.#state.seen[s.id]);
-    const status = await indexer.status();
+    const { status, tags } = await passOf(indexer);
+    const page = (p: number) => {
+      let read = tags.get(p);
+      if (!read) tags.set(p, (read = indexer.page('tags', p)));
+      return read;
+    };
     const watches = seen.flatMap((r) => r.watches.map((w) => w.watch));
-    const hits = await scan(watches, 4, (p) => indexer.page('tags', p), status.commitmentsFinal, status.commitments);
+    const hits = await scan(watches, 4, page, status.commitmentsFinal, status.commitments);
     applyHits([], seen, hits);
     dropReorged(seen, status.commitmentsFinal);
     await readTransfers(commitmentFields(indexer), seen);
@@ -314,67 +393,156 @@ export class PointOfSale {
     return { sale, payments, received };
   }
 
-  /** Refills `token`'s addresses once they run low: right away when none is left, otherwise at a random time within
-   * `refillWithinMs`. */
-  #topUp(token: PosToken): void {
+  /** How many addresses of a token to keep made, and recorded, ahead: twice its sales of the last `refillWithinMs`, so
+   * that they last through the wait for a refill as sales pick up; in whole blocks, at least one, at most one write. */
+  #low(pair: string): number {
+    const sales = this.#state.sales;
+    const since = Date.now() - this.#refillWithinMs;
+    let recent = 0;
+    // sales are kept in the order they were made
+    for (let i = sales.length - 1; i >= 0 && sales[i].createdMs >= since; i--) if (pairOf(sales[i]) === pair) recent++;
+    return BURN_BLOCK * Math.min(MAX_POS_BLOCKS, Math.max(1, Math.ceil((2 * recent) / BURN_BLOCK)));
+  }
+
+  /** Keeps `token` supplied. Its addresses are recorded once fewer than `#low` are ready: right away when none is,
+   * otherwise at a random time within `refillWithinMs`, so that the time of a write does not mark the sale that drew
+   * them down. They are made ahead, which shows nobody anything, until `#low` are made. */
+  #supply(token: PosToken): void {
+    if (!this.#state.connection || this.#closed) return;
     const pair = pairOf(token);
-    const left = this.#state.connection?.pools[pair]?.ready.length ?? 0;
-    if (!this.#state.connection || left >= BURN_BLOCK || this.#fills.has(pair) || this.#timers.has(pair)) return;
-    // a refill that fails is tried again by the next sale, which tells why
-    const fill = () => void this.#fill(token).catch(() => undefined);
-    if (left === 0) return fill();
-    const timer = setTimeout(() => {
-      this.#timers.delete(pair);
-      fill();
-    }, Math.random() * this.#refillWithinMs);
-    (timer as { unref?: () => void }).unref?.(); // a process need not stay up for it
-    this.#timers.set(pair, timer);
+    const pool = this.#pool(token);
+    const low = this.#low(pair);
+    if (pool.ready.length < low && !this.#recording.has(pair) && !this.#timers.has(pair)) {
+      // a write that fails is tried again by the next sale, which tells why
+      if (pool.ready.length === 0) void this.#record(token).catch(() => undefined);
+      else this.#later(token);
+    }
+    if (madeOf(pool) < low) void this.#ahead(token).catch(() => undefined);
   }
 
-  /** Makes `BURN_BLOCK` more addresses of `token`, records them in the lane, then adds them to its pool: one refill at
-   * a time per token. One that fails changes nothing. */
-  #fill(token: PosToken): Promise<void> {
+  /** The block `token` is making ahead, begun if there is none; the next follows while fewer than `#low` are made. */
+  #ahead(token: PosToken): Promise<void> {
     const pair = pairOf(token);
-    const running = this.#fills.get(pair);
+    const running = this.#making.get(pair);
+    if (running) return running;
+    const run: Promise<void> = this.#make(token, false).finally(() => {
+      if (this.#making.get(pair) === run) this.#making.delete(pair);
+    });
+    this.#making.set(pair, run);
+    // one that fails is made again by the next sale, or the next pass's `prepare`
+    run.then(
+      () => this.#supply(token),
+      () => undefined,
+    );
+    return run;
+  }
+
+  /** Makes `token`'s next block of addresses. Its counters are taken as it starts, so that blocks made side by side
+   * never share one; a block that fails, or ends after the lane changed, leaves a gap in the counters, which no reader
+   * minds. What is made is saved with the next save: lost, it is made again from the same counters, to the same
+   * addresses, none of which a sale has had. */
+  async #make(token: PosToken, urgent: boolean): Promise<void> {
+    const c = this.#connection();
+    const pool = this.#pool(token);
+    const first = pool.next;
+    pool.next += BURN_BLOCK;
+    const laneKey = hexToBytes(c.laneKey);
+    const signal = this.#searches.signal;
+    const burns = await Promise.all(
+      Array.from({ length: BURN_BLOCK }, (_, i) =>
+        burnAddress(laneKey, token.chainId, token.tokenId, first + i, c.publicKey, { signal, urgent }),
+      ),
+    );
+    if (this.#state.connection !== c) return;
+    pool.made.push({ first, burns });
+    this.#saveSoon();
+  }
+
+  /** Records made addresses of `token` in the lane, in one write, and readies them: as many blocks as the sales that
+   * wait and the low mark ask for. One write at a time per token: a sale that finds none ready waits for the one under
+   * way. A pool with none ready has the blocks its waiting sales need, one at least, made side by side and ahead of
+   * every search made ahead, since the next sale waits for them. A timer that finds none made waits again: writing
+   * right after the making would mark the sale that began it. */
+  #record(token: PosToken): Promise<void> {
+    const pair = pairOf(token);
+    const running = this.#recording.get(pair);
     if (running) return running;
     clearTimeout(this.#timers.get(pair));
     this.#timers.delete(pair);
     const run: Promise<void> = (async () => {
       const c = this.#connection();
-      const pool = (c.pools[pair] ??= { next: 0, ready: [] });
-      const k = pool.next;
-      const laneKey = hexToBytes(c.laneKey);
-      const burns = await Promise.all(
-        Array.from({ length: BURN_BLOCK }, (_, i) =>
-          burnAddress(laneKey, token.chainId, token.tokenId, k + i, c.publicKey),
-        ),
-      );
-      const block = {
-        chainId: token.chainId,
-        tokenId: token.tokenId,
-        first: k,
-        salts: burns.map((b) => hexToBytes(b.salt)),
-      };
+      const pool = this.#pool(token);
+      const waiting = Math.ceil((this.#waiting.get(pair) ?? 0) / BURN_BLOCK);
+      if (pool.ready.length === 0) {
+        const short = Math.max(waiting, 1) - pool.made.length;
+        await Promise.all(Array.from({ length: Math.max(0, short) }, () => this.#make(token, true)));
+      } else if (pool.made.length === 0) return this.#later(token);
+      if (this.#state.connection !== c) return;
+      const short = Math.ceil((this.#low(pair) - pool.ready.length) / BURN_BLOCK);
+      const blocks = pool.made.slice(0, Math.min(MAX_POS_BLOCKS, Math.max(waiting, short, 1)));
+      if (!blocks.length) return;
       const chain = `${token.chainId}`;
-      const slot = await writePosBlock(await this.#client(), laneKey, block, c.slots[chain] ?? 0);
-      if (this.#state.connection !== c) return; // connected to another lane meanwhile
+      const slot = await writePosBlocks(
+        await this.#client(),
+        hexToBytes(c.laneKey),
+        blocks.map((b) => ({
+          chainId: token.chainId,
+          tokenId: token.tokenId,
+          first: b.first,
+          salts: b.burns.map((burn) => hexToBytes(burn.salt)),
+        })),
+        c.slots[chain] ?? 0,
+      );
+      if (this.#state.connection !== c) return;
       c.slots[chain] = Math.max(c.slots[chain] ?? 0, slot);
-      pool.ready.push(...burns.map((b) => b.address));
-      pool.next = k + BURN_BLOCK;
+      // what is made is only ever added to, after these
+      pool.made.splice(0, blocks.length);
+      pool.ready.push(...blocks.flatMap((b) => b.burns.map((burn) => burn.address)));
       await this.#save();
     })().finally(() => {
-      if (this.#fills.get(pair) === run) this.#fills.delete(pair);
+      if (this.#recording.get(pair) === run) this.#recording.delete(pair);
     });
-    this.#fills.set(pair, run);
+    this.#recording.set(pair, run);
+    // what was made ahead is recorded now: make the next, and record again if still short
+    run.then(
+      () => this.#supply(token),
+      () => undefined,
+    );
     return run;
   }
 
+  /** Records `token`'s addresses at a random time within `refillWithinMs`. */
+  #later(token: PosToken): void {
+    const pair = pairOf(token);
+    const timer = setTimeout(() => {
+      this.#timers.delete(pair);
+      void this.#record(token).catch(() => undefined);
+    }, Math.random() * this.#refillWithinMs);
+    (timer as { unref?: () => void }).unref?.(); // a process need not stay up for it
+    this.#timers.set(pair, timer);
+  }
+
+  /** Stops the searches, timers and writes of the lane connected now. Those under way finish, and drop what they
+   * bring, since the lane is no longer the one connected or the point of sale is closed. */
+  #stop(): void {
+    this.#searches.abort();
+    this.#searches = new AbortController();
+    for (const t of this.#timers.values()) clearTimeout(t);
+    this.#timers.clear();
+    this.#making.clear();
+    this.#recording.clear();
+  }
+
   #connection(): Connection {
     return this.#state.connection ?? fail('invalid', "not connected: connect the merchant's wallet first");
   }
 
+  #pool(token: PosToken): Pool {
+    return (this.#connection().pools[pairOf(token)] ??= { next: 0, made: [], ready: [] });
+  }
+
   #sale(id: Address): Sale {
-    return this.#state.sales.find((s) => same(s.id, id)) ?? fail('invalid', `no sale ${id}`);
+    return this.#byId.get(id.toLowerCase()) ?? fail('invalid', `no sale ${id}`);
   }
 
   #chain(chainId: bigint): Chain {
@@ -400,12 +568,23 @@ export class PointOfSale {
   }
 
   /** Saves the state as it is when the save runs, after every save asked for before: an older state never lands last,
-   * which would hand out again an address taken since. */
+   * which would hand out again an address taken since. Closed, it saves nothing and fails. */
   #save(): Promise<void> {
+    if (this.#closed) return Promise.reject(new WalletError('unavailable', 'the point of sale is closed'));
+    clearTimeout(this.#passSave);
+    this.#passSave = undefined;
     const run = this.#saving.then(() => this.#persist.save(encode(this.#state)));
     this.#saving = run.catch(() => undefined);
     return run;
   }
+
+  /** Saves within `PASS_SAVED_WITHIN_MS`, for what can be read or made again: a pass's findings, addresses made. */
+  // ponytail: the whole state on every save; split it once a merchant has some 10k sales
+  #saveSoon(): void {
+    if (this.#passSave || this.#closed) return;
+    this.#passSave = setTimeout(() => void this.#save().catch(() => undefined), PASS_SAVED_WITHIN_MS);
+    (this.#passSave as { unref?: () => void }).unref?.(); // a process need not stay up for it
+  }
 }
 
 function chainOf(network: Network, chainId: bigint): ChainConfig {