@zerc20/wallet-sdk 0.3.0 → 0.5.0

package/src/core.ts

@@ -28,21 +28,22 @@ export interface Burn {
 
 /** The `index`-th burn address of `publicKey` on a chain and token, and its salt, from `burnKey`: the wallet's own burn
  * key, or a point of sale's (`wallet_keys::derive_burn_address`). About 2^16 hashes, spread over the device's cores
- * (Web Workers in a browser, worker threads in Node) so that the app stays responsive; `signal` stops the search. */
+ * (Web Workers in a browser, worker threads in Node) so that the app stays responsive; `signal` stops the search. One
+ * that nobody waits for, made ahead, is `urgent: false`: it gives way to those someone waits for. */
 export const burnAddress = (
   burnKey: Uint8Array,
   chainId: bigint,
   tokenId: number,
   index: number,
   publicKey: Hex,
-  signal?: AbortSignal,
-): Promise<Burn> => search({ burnKey, chainId, tokenId, index, publicKey }, signal);
+  opts: { signal?: AbortSignal; urgent?: boolean } = {},
+): Promise<Burn> => search({ burnKey, chainId, tokenId, index, publicKey }, opts.urgent ?? true, opts.signal);
 
 /** A burn address of someone else's `publicKey` (one they published to be paid), with a random salt that has the proof
  * of work: about 2^16 hashes too, searched the same way. Only who holds the salt finds it: the payer, and the owner once
  * told (`planSend` with `burn`). */
 export const burnAddressFor = (chainId: bigint, publicKey: Hex, signal?: AbortSignal): Promise<Burn> =>
-  search({ chainId, publicKey }, signal);
+  search({ chainId, publicKey }, true, signal);
 
 export type BurnSearch =
   | { burnKey: Uint8Array; chainId: bigint; tokenId: number; index: number; publicKey: Hex }
@@ -60,16 +61,27 @@ export interface BurnBlock {
 
 export type BurnAnswer = { burn: Burn | null } | { error: string };
 
-/** The address a block holds, if any. Its salts count up from a start: one the burn key derives, or for someone else's
- * key a random one below 2^253, so that every salt is a field element. */
-export function runBlock({ search: s, from, to }: BurnBlock): Burn | null {
-  let burn: unknown;
-  if ('burnKey' in s) burn = core.burnBlock(s.burnKey, s.chainId, s.tokenId, s.index, s.publicKey, from, to);
-  else {
-    const start = crypto.getRandomValues(new Uint8Array(32));
-    start[0] = start[0] & 0x1f;
-    burn = core.burnBlockFor(s.chainId, s.publicKey, bytesToHex(start), to - from + 1);
-  }
+/** What a block asks of the protocol code: `burnBlock`'s arguments, or `burnBlockFor`'s. */
+export type BurnCall =
+  | { burnKey: Uint8Array; chainId: bigint; tokenId: number; index: number; publicKey: Hex; from: number; to: number }
+  | { chainId: bigint; publicKey: Hex; start: Hex; count: number };
+
+/** A block's call. Its salts count up from a start: one the burn key derives, or for someone else's key a random one
+ * below 2^253, so that every salt is a field element. */
+export function blockCall({ search: s, from, to }: BurnBlock): BurnCall {
+  if ('burnKey' in s) return { ...s, from, to };
+  const start = crypto.getRandomValues(new Uint8Array(32));
+  start[0] = start[0] & 0x1f;
+  return { chainId: s.chainId, publicKey: s.publicKey, start: bytesToHex(start), count: to - from + 1 };
+}
+
+/** The address a block holds, if any. */
+export function runBlock(b: BurnBlock): Burn | null {
+  const c = blockCall(b);
+  const burn: unknown =
+    'burnKey' in c
+      ? core.burnBlock(c.burnKey, c.chainId, c.tokenId, c.index, c.publicKey, c.from, c.to)
+      : core.burnBlockFor(c.chainId, c.publicKey, c.start, c.count);
   return (burn as Burn | undefined) ?? null;
 }
 
@@ -155,8 +167,17 @@ type NodeWorker = new (url: URL) => {
   terminate(): Promise<number>;
 };
 
-/** Searches in progress, oldest first: blocks go to the oldest that has one to hand out. */
-const searches: Search[] = [];
+/** Searches in progress by owner (the burn key, or the key paid): those someone waits for, and those made ahead. Each
+ * owner in turn gets a block of its oldest search that has one, so that one owner's many searches hold up no other's,
+ * and each address it waits for comes as soon as its cores allow. */
+// ponytail: fair per owner, so per point of sale; a merchant opening many accounts gets many turns, so cap each
+// merchant's sales if that happens
+const queues = { urgent: new Map<string, Search[]>(), later: new Map<string, Search[]>() };
+/** One block in this many goes to the searches made ahead while some are waited for: a flood of urgent searches slows
+ * the making ahead, which keeps everyone else's sales from waiting, but does not stop it. */
+const LATER_EVERY = 4;
+/** Urgent blocks handed out in a row. */
+let urgentRun = 0;
 let threads: Thread[] | null = null;
 let starting = false;
 /** Workers do not run here (a page whose CSP forbids them, a bundler that left burnWorker.js out, tests run from
@@ -167,27 +188,51 @@ let idle: ReturnType<typeof setTimeout> | undefined;
 /** An idle pool stops after this long, freeing a wasm instance per core. */
 const IDLE_MS = 30_000;
 
-async function search(s: BurnSearch, signal?: AbortSignal): Promise<Burn> {
+async function search(s: BurnSearch, urgent: boolean, signal?: AbortSignal): Promise<Burn> {
   await initCore();
   signal?.throwIfAborted();
+  const queue = urgent ? queues.urgent : queues.later;
+  const owner = 'burnKey' in s ? bytesToHex(s.burnKey) : s.publicKey;
   return new Promise((resolve, reject) => {
     const abort = () => one.fail(signal!.reason);
     const one = new Search(s, (r) => {
       signal?.removeEventListener('abort', abort);
-      searches.splice(searches.indexOf(one), 1);
+      const mine = queue.get(owner)!;
+      mine.splice(mine.indexOf(one), 1);
+      if (!mine.length) queue.delete(owner);
       if ('burn' in r) resolve(r.burn);
       else reject(r.error);
     });
     signal?.addEventListener('abort', abort, { once: true });
-    searches.push(one);
+    const mine = queue.get(owner);
+    if (mine) mine.push(one);
+    else queue.set(owner, [one]);
     dispatch();
   });
 }
 
 function nextJob(): Job | null {
-  for (const search of searches) {
-    const block = search.take();
-    if (block !== undefined) return { search, block };
+  const order = urgentRun >= LATER_EVERY - 1 ? [queues.later, queues.urgent] : [queues.urgent, queues.later];
+  for (const queue of order) {
+    const job = takeFrom(queue);
+    if (!job) continue;
+    urgentRun = queue === queues.urgent ? urgentRun + 1 : 0;
+    return job;
+  }
+  return null;
+}
+
+/** A block of the first owner in line that has one, from its oldest search that does; that owner then goes to the back
+ * of the line. */
+function takeFrom(queue: Map<string, Search[]>): Job | null {
+  for (const [owner, mine] of queue) {
+    for (const search of mine) {
+      const block = search.take();
+      if (block === undefined) continue;
+      queue.delete(owner);
+      queue.set(owner, mine);
+      return { search, block };
+    }
   }
   return null;
 }
@@ -203,9 +248,49 @@ function deliver({ search, block }: Job, a: BurnAnswer) {
   else search.finish(block, a.burn);
 }
 
-/** Hands blocks to idle threads, starting the pool if it is not running. */
+/** Runs blocks somewhere other than this module's wasm: a server's native process, say. */
+export interface BurnRunner {
+  /** How many blocks it runs at once. */
+  slots: number;
+  run(call: BurnCall): Promise<Burn | null>;
+}
+
+let runner: BurnRunner | null = null;
+/** Blocks the runner has and has not answered. */
+const onRunner = new Set<Job>();
+
+/** Runs every block from now on on `r`, or with null in this module's wasm again. The blocks the runner had are handed
+ * out again, and what it answers for them later is dropped. */
+export function runBurnsOn(r: BurnRunner | null): void {
+  for (const job of onRunner) job.search.drop(job.block);
+  onRunner.clear();
+  runner = r;
+  dispatch();
+}
+
+function feed(r: BurnRunner) {
+  while (onRunner.size < r.slots) {
+    const job = nextJob();
+    if (!job) return;
+    onRunner.add(job);
+    void r
+      .run(blockCall(blockOf(job)))
+      .then(
+        (burn): BurnAnswer => ({ burn }),
+        (e: unknown): BurnAnswer => ({ error: e instanceof Error ? e.message : String(e) }),
+      )
+      .then((a) => {
+        if (!onRunner.delete(job)) return; // handed out again when the runner was taken away
+        deliver(job, a);
+        dispatch();
+      });
+  }
+}
+
+/** Hands blocks to the runner, or to idle threads, starting the pool if it is not running. */
 function dispatch() {
   clearTimeout(idle);
+  if (runner) return feed(runner);
   if (here) return void runHere();
   if (!threads) return void start();
   for (const t of threads) {
@@ -216,7 +301,7 @@ function dispatch() {
     t.busy(true);
     t.send(blockOf(job));
   }
-  if (!searches.length && threads.every((t) => !t.job)) {
+  if (!queues.urgent.size && !queues.later.size && threads.every((t) => !t.job)) {
     idle = setTimeout(stop, IDLE_MS);
     (idle as { unref?: () => void }).unref?.(); // a process need not stay up for it
   }

package/src/errors.ts

@@ -23,6 +23,8 @@ export type ErrorCode =
   | 'user-rejected'
   /** The wallet is open in another tab or window: close it there (`close()`), then open it here. */
   | 'wallet-in-use'
+  /** This wallet watches its account by its view key (`Wallet.watch`): it spends and writes nothing. */
+  | 'read-only'
   /** This wallet object was closed (`close()`): open the wallet again to go on. */
   | 'wallet-closed'
   /** A server answered something that does not match the chain. */

package/src/index.ts

@@ -5,13 +5,25 @@
 //   wallet.balances();                       // spendable, and what is pending and why
 //   await (await wallet.deposit({ token, amount })).wait();
 //   const q = await wallet.fees({ kind: 'send', token, amount });
-//   await (await wallet.send({ to: '0x…', token, amount, maxFee: q.fee })).wait();
+//   await (await wallet.send({ to: 'zerc20id1…', token, amount, maxFee: q.fee })).wait();
+//   const watching = await Wallet.watch({ network, viewKey: wallet.viewKey(), persist }); // elsewhere, spends nothing
 //
 // Nothing secret leaves the device unencrypted: JoinSplit proofs are made here, a merge's by the merge prover, and the
 // attester and the prover get the witness sealed to an enclave whose measurement the wallet checks. Servers are only
 // ever asked for what every wallet downloads.
 
-export { Chain, type Referrer, type Token, MAX_REFERRAL_BPS, NATIVE, UNWRAP_INTENT } from './chain.js';
+export { accountId, idAccount } from './accountId.js';
+export {
+  Chain,
+  type Referrer,
+  type Refund,
+  type Token,
+  MAX_REFERRAL_BPS,
+  NATIVE,
+  UNWRAP_INTENT,
+  rpcTransport,
+} from './chain.js';
+export { type Burn, type BurnCall, type BurnRunner, runBurnsOn } from './core.js';
 export { type ErrorCode, WalletError } from './errors.js';
 export {
   type AttesterTrust,
@@ -24,18 +36,22 @@ export {
 } from './network.js';
 export { type Payment, PointOfSale, type PosToken, type Sale, type SaleStatus } from './pos.js';
 export { accountKey, seedFromSignature } from './seed.js';
+export { viewKeyAccount } from './viewKey.js';
 export {
   type Activity,
   type Balance,
   type CoinInfo,
   type CoinState,
+  type DepositAddressInfo,
   type DepositInfo,
   type DepositStep,
   type FeeQuote,
+  type MaxAmount,
   type OpenOptions,
   type Operation,
   type OperationKind,
   type OperationStatus,
   type PendingReason,
   Wallet,
+  type WatchOptions,
 } from './wallet.js';