@zerc20/wallet-sdk 0.1.0 → 0.3.0

package/src/wallet.ts

@@ -19,15 +19,17 @@ import {
   type Account,
   type Address,
   type Hex,
+  type LocalAccount,
   type WalletClient,
   bytesToHex,
   formatUnits,
   hexToBytes,
   isAddress,
   numberToHex,
+  zeroAddress,
 } from 'viem';
-import { Chain, NATIVE, type Token, erc20Abi, tokenAbi } from './chain.js';
-import { type Ctx, type SpendKey, chainCtx, chainState, spendKey, walletSees } from './context.js';
+import { Chain, MAX_REFERRAL_BPS, NATIVE, type Referrer, type Token, erc20Abi, tokenAbi } from './chain.js';
+import { type Ctx, type SpendKey, chainCtx, chainState, owner, switched, walletOn, walletSees } from './context.js';
 import { burnAddressFor, core, initCore } from './core.js';
 import { type ErrorCode, WalletError, fail, guard } from './errors.js';
 import { type Network, checkNetwork } from './network.js';
@@ -61,10 +63,14 @@ import {
   emptyWalletState,
   openState,
   sealState,
+  stateKey,
+  unspent,
 } from './state.js';
 import {
   WAIT_MS,
   commitmentTx,
+  keyAll,
+  nextBurn,
   recordBurn,
   storageState,
   syncAll,
@@ -74,21 +80,30 @@ import {
   unusedBurn,
 } from './sync.js';
 
-const DAY_MS = 86_400_000;
 /** The ledger's bound outside an emergency. */
 const NO_BOUND = 2n ** 64n - 1n;
 
 export interface OpenOptions {
   network: Network;
-  /** The user's wallet (MetaMask, WalletConnect, ...) as a viem client with its account. */
-  walletClient: WalletClient;
-  /** The 32-byte root of every key. See `seedFromSignature`. */
-  seed: Uint8Array;
+  /** The account's key, held by the app as a viem local account (a private key's, or `accountKey`'s): the wallet sends
+   * its transactions through each chain's RPC. Give this or `walletClient`. */
+  account?: LocalAccount;
+  /** The user's wallet (MetaMask, WalletConnect, ...) as a viem client with its account, which the wallet switches to
+   * each chain it sends on. */
+  walletClient?: WalletClient;
+  /** The 32-byte root of every key (see `seedFromSignature`), held while the wallet is open. Or a function that gives
+   * it, a passkey's say, to hold the seed only while it is needed: asked as the wallet opens, and again to pay,
+   * withdraw, consolidate or exit, or for a receive code past those derived ahead, each time before the call waits on
+   * anything (a browser shows a passkey prompt only in the click that asked). The seed goes at the end of a sync that
+   * nothing waits behind, once nothing in flight signs again. */
+  seed: Uint8Array | (() => Promise<Uint8Array>);
   /** Where the encrypted state lives between sessions. */
   persist: { load(): Promise<Uint8Array | null | undefined>; save(bytes: Uint8Array): Promise<void> };
   /** Where a wallet with no saved state starts looking: the block its seed was first used at, or roughly when. Without
    * it, an address registered before is looked for from the chain's start, and a new one from now on. */
   birthday?: bigint | Date;
+  /** The app opening the wallet, when it takes a share of what reaches the deposit addresses it hands out. */
+  referrer?: Referrer;
 }
 
 /** What a deposit, or a deposit address, waits on: for an app to show while it does. */
@@ -105,7 +120,7 @@ export type DepositStep =
 
 /** Why an amount is not spendable yet. */
 export type PendingReason =
-  /** Announced by the payer, and not yet read on chain. */
+  /** A note this device's payment, withdrawal or merge under way is making, not yet read on chain. */
   | 'incoming'
   /** Waiting for a proved root that covers it (minutes). */
   | 'awaiting-root'
@@ -154,7 +169,7 @@ export interface Activity {
   txHash: Hex | null;
   /** `done` once on chain (in a block: a reorg may still take it back until final), `failed` for a payment or
    * withdrawal that cannot land, shown only on the device that tried it. What is not on chain yet is not activity:
-   * an operation under way is in `operations()`, a note only announced is `incoming` in `balances()`. */
+   * an operation under way is in `operations()`, and the note it is making `incoming` in `balances()`. */
   status: 'done' | 'failed';
 }
 
@@ -236,10 +251,13 @@ export class Wallet {
   /** Calls running or queued. */
   #busy = 0;
   #release = () => {};
+  #referrer: Referrer | undefined;
+  readonly #unlock: (() => Promise<Uint8Array>) | undefined;
   #closed = new AbortController();
 
-  private constructor(ctx: Ctx) {
+  private constructor(ctx: Ctx, unlock?: () => Promise<Uint8Array>) {
     this.#ctx = ctx;
+    this.#unlock = unlock;
   }
 
   /** Lets this wallet open again: in another tab, or here for another account. This object is done with: what is
@@ -256,20 +274,32 @@ export class Wallet {
 
   /** Opens the wallet. The first time on this address, registers it for payments: one signature. */
   static async open(opts: OpenOptions): Promise<Wallet> {
-    await initCore();
     checkNetwork(opts.network);
-    if (opts.seed.length !== 32) fail('invalid', 'the seed is 32 bytes');
-    const account = opts.walletClient.account ?? fail('invalid', 'the wallet client has no account');
+    // the factory refuses these, which the relayer would report as its own failure
+    const r = opts.referrer;
+    if (r) {
+      if (!isAddress(r.address, { strict: false }) || r.address.toLowerCase() === zeroAddress)
+        fail('invalid', `the referrer ${r.address} is not an address to pay`);
+      if (!Number.isInteger(r.bps) || r.bps < 0 || r.bps > MAX_REFERRAL_BPS)
+        fail('invalid', `a referrer takes 0 to ${MAX_REFERRAL_BPS} bps, not ${r.bps}`);
+    }
+    if (!opts.account === !opts.walletClient) fail('invalid', 'give an account or a wallet client, one of the two');
+    const account = opts.account ?? opts.walletClient!.account ?? fail('invalid', 'the wallet client has no account');
+    // asked once the options are checked, and before anything is waited on: a browser shows a passkey prompt only in
+    // the click that opened
+    const seed = typeof opts.seed === 'function' ? await opts.seed() : opts.seed;
+    if (seed.length !== 32) fail('invalid', 'the seed is 32 bytes');
+    await initCore();
     const release = await lockWallet(account.address);
     try {
-      return await Wallet.#open(opts, account, release);
+      return await Wallet.#open(opts, seed, account, release);
     } catch (e) {
       release();
       throw e;
     }
   }
 
-  static async #open(opts: OpenOptions, account: Account, release: () => void): Promise<Wallet> {
+  static async #open(opts: OpenOptions, seed: Uint8Array, account: Account, release: () => void): Promise<Wallet> {
     const address = account.address;
     const chains = opts.network.chains.map((config) => ({
       config,
@@ -282,16 +312,23 @@ export class Wallet {
     if (code && code !== '0x' && !code.startsWith('0xef0100'))
       fail('unsupported-account', 'contract accounts cannot sign for a wallet');
     const signer: Signer = async (message) =>
-      hexToBytes(await guard(opts.walletClient.signMessage({ account, message })));
+      hexToBytes(
+        await guard(
+          account.type === 'local'
+            ? account.signMessage({ message })
+            : opts.walletClient!.signMessage({ account, message }),
+        ),
+      );
     const storage = await CanisterClient.connect(opts.network.storage.host, opts.network.storage.canisterId);
-    const publicKey = hexToBytes((core.spendKey(opts.seed) as SpendKey).publicKey);
+    const publicKey = hexToBytes((core.spendKey(seed) as SpendKey).publicKey);
     const saved = await opts.persist.load();
     // registered already: used before, here or on another device, so its past is looked for
     // ponytail: from genesis (~4 MB per million commitments); ask for a birthday once the chain has many
     const restoring =
       !saved?.length && opts.birthday === undefined && !!(await storage.registration(hexToBytes(address)));
-    const view = await registeredViewKey(storage, opts.seed, signer, hexToBytes(address), publicKey);
-    const loaded = saved?.length ? openState(opts.seed, saved) : null;
+    const view = await registeredViewKey(storage, seed, signer, hexToBytes(address), publicKey);
+    const key = stateKey(seed);
+    const loaded = saved?.length ? openState(key, saved) : null;
     // never started over in place: the first save would overwrite what it held, operations in flight included
     if (saved?.length && !loaded) {
       fail(
@@ -304,26 +341,60 @@ export class Wallet {
     const state: WalletState = loaded ?? emptyWalletState(address);
     const ctx: Ctx = {
       network: opts.network,
-      seed: opts.seed,
+      seed,
+      owners: new Map(),
       address,
-      walletClient: opts.walletClient,
+      account,
+      walletClient: opts.walletClient ?? null,
       storage,
       view,
       chains,
       state,
-      save: () => opts.persist.save(sealState(opts.seed, state)),
+      save: () => opts.persist.save(sealState(key, state)),
       lastFullRefreshMs: 0,
     };
     if (!loaded) await start(ctx, restoring ? 0n : opts.birthday);
-    const wallet = new Wallet(ctx);
+    const wallet = new Wallet(ctx, typeof opts.seed === 'function' ? opts.seed : undefined);
     wallet.#release = release;
+    wallet.#referrer = opts.referrer;
     // a saved state names its tokens by id, and its coins stand by the chains' roots: read both now, so balances, coins
     // and history work before the first sync
     const [tokens] = await Promise.all([Promise.all(chains.map((c) => c.chain.tokens())), wallet.#readRoots()]);
     wallet.#tokens = tokens.flat();
+    keyAll(ctx, wallet.#tokens);
     return wallet;
   }
 
+  /** Holds `seed`, asked of `#unlock`, once it is checked to be this wallet's. */
+  #hold(seed: Uint8Array): void {
+    if ((core.spendKey(seed) as SpendKey).publicKey !== owner(this.#ctx)!.publicKey)
+      fail('invalid', "the seed given is another wallet's");
+    this.#ctx.seed = seed;
+    keyAll(this.#ctx, this.#tokens);
+  }
+
+  /** Within a task: the seed held, asked of `#unlock` if need be. */
+  async #seed(): Promise<void> {
+    if (!this.#ctx.seed) this.#hold(await this.#unlock!());
+  }
+
+  /** At the end of a sync: lets the seed go when it was opened with a function for it, nothing waits behind the sync,
+   * and no payment, withdrawal or consolidation is in flight, as each may sign again (a JoinSplit that reverts is
+   * proved again, and every merge round is signed). */
+  #dropSeed(): void {
+    if (!this.#unlock || this.#busy > 1) return;
+    if (this.#ctx.state.ops.some((o) => o.status === 'pending' && o.kind !== 'deposit')) return;
+    this.#ctx.seed = null;
+  }
+
+  /** `#exclusive` for a call that `needs` the seed: held first, asked of `#unlock` if need be before the call waits on
+   * anything else (a browser shows a passkey prompt only in the click that asked), and queued in the step that took it,
+   * so that a sync ending meanwhile does not let it go. */
+  async #seeded<T>(f: () => Promise<T>, needs = true): Promise<T> {
+    if (needs && !this.#ctx.seed) this.#hold(await this.#unlock!());
+    return this.#exclusive(f);
+  }
+
   /** Runs `f` after everything queued before it: one state, changed by one task at a time. */
   #exclusive<T>(f: () => Promise<T>): Promise<T> {
     this.#busy++;
@@ -359,13 +430,14 @@ export class Wallet {
 
   /** Catches up: new notes, deposits, spends and roots, then advances every operation in flight. A chain or server that
    * fails holds back only what needs it, and the first error is thrown once the rest is done. Settles before the burn
-   * addresses are topped up, which can take a phone tens of seconds. */
+   * addresses are topped up, which can take a phone some seconds. */
   sync(): Promise<void> {
     return new Promise((resolve, reject) => {
       this.#exclusive(async () => {
         await this.#catchUp().then(resolve, reject);
         // still this task's: a deposit queued meanwhile finds the one recorded ahead, rather than writing at handout
         await topUpBurns(this.#ctx, this.#closed.signal).catch(() => {}); // tried again after the next sync
+        this.#dropSeed();
       }).catch(reject); // closed before it ran
     });
   }
@@ -411,7 +483,7 @@ export class Wallet {
     if (errors.length > 0) throw errors[0];
   }
 
-  /** Syncs on its own: every 15 s while something is under way, every 5 min otherwise. Returns a stop function. */
+  /** Syncs on its own: every 3 s while something is under way, every 10 s otherwise. Returns a stop function. */
   autoSync(onChange?: () => void, onError?: (e: unknown) => void): () => void {
     let stopped = false;
     let timer: ReturnType<typeof setTimeout> | undefined;
@@ -424,7 +496,7 @@ export class Wallet {
       }
       if (stopped || this.#closed.signal.aborted) return;
       const busy = this.#ctx.state.ops.some((o) => o.status === 'pending' && Date.now() - o.createdMs < WAIT_MS * 4);
-      timer = setTimeout(tick, busy ? 15_000 : 300_000);
+      timer = setTimeout(tick, busy ? 3_000 : 10_000);
     };
     void tick();
     return () => {
@@ -447,18 +519,22 @@ export class Wallet {
 
   balances(): Balance[] {
     const coins = this.coins();
+    // storage says which notes to look for, not that they come: a payer writes its notes there before its JoinSplit
+    // leaves, and one that never lands leaves them behind. So a note counts once it is a coin (its commitment read);
+    // before that, only a note this device's own operation under way is making counts, as incoming. A zero-value
+    // change, there to carry its payment's receipt, never counts
+    const making = new Set(
+      this.#ctx.state.ops.flatMap((o) =>
+        o.status === 'pending' && o.kind !== 'deposit' ? (o.data.changes ?? []) : [],
+      ),
+    );
     return this.#tokens.map((token) => {
       const { chainId, tokenId } = token;
       const b: Balance = { token, spendable: 0n, pending: [], blocked: 0n };
-      // a merge that never landed (another device spent an input first) stops counting after a day; a zero-value
-      // change, there to carry its payment's receipt, never counts. A note is a coin once its commitment is read, so
-      // until then it is incoming, as a payment's change is between its relay and the next sync
       for (const n of this.#ctx.state.notes.filter(
-        (n) => n.chainId === chainId && n.tokenId === tokenId && n.value > 0n,
+        (n) => n.chainId === chainId && n.tokenId === tokenId && n.value > 0n && making.has(n.salt),
       )) {
-        const stale =
-          n.receipt?.kind === 'merged' && n.atNs !== null && Date.now() - Number(n.atNs / 1_000_000n) > DAY_MS;
-        if (!n.found.some((f) => f.confirmed) && !stale) b.pending.push({ amount: n.value, reason: 'incoming' });
+        if (!n.found.some((f) => f.confirmed)) b.pending.push({ amount: n.value, reason: 'incoming' });
       }
       for (const c of coins.filter((c) => c.token === token)) {
         if (c.state === 'spendable') b.spendable += c.amount;
@@ -470,13 +546,14 @@ export class Wallet {
   }
 
   /** Every unspent note and deposit on chain, and where each stands, as of opening or the last sync. A note announced
-   * but not on chain yet is not one: `balances()` counts it as incoming. */
+   * but not read on chain yet is not one: `balances()` counts it as incoming if this device's operation is making it. */
   coins(): CoinInfo[] {
     const size = (chainId: bigint) => this.#status.get(chainId)?.latestRoot?.size ?? 0;
     const unproved = (chainId: bigint) => (this.#status.get(chainId)?.halted ? 'roots-halted' : 'awaiting-root');
     const spending = new Set(this.#ctx.state.ops.flatMap((o) => inputsOf(o).map((c) => `${o.chainId}:${c.index}`)));
-    // spent by a JoinSplit in a block, which waits only to be final: gone, as activity() counts it (a reorg that drops
-    // it brings them back as spending, and the operation relays it again)
+    // spent by a JoinSplit in a block, which waits only to be final: gone, as activity() counts it. Sync sees it by its
+    // nullifier (`unspent`); this device's own is gone already from its relay on (a reorg that drops it brings them
+    // back as spending, and the operation relays it again)
     const landed = new Set(
       this.#ctx.state.ops.flatMap((o) =>
         o.kind !== 'deposit' && o.data.step?.stage === 'relayed'
@@ -487,7 +564,7 @@ export class Wallet {
     const out: CoinInfo[] = [];
     // a zero-value change carries its payment's receipt, and is no coin
     for (const n of this.#ctx.state.notes.filter((n) => n.value > 0n)) {
-      for (const f of n.found.filter((f) => !f.spent)) {
+      for (const f of n.found.filter(unspent)) {
         const id = `${n.chainId}:${f.index}`;
         // a 4-byte tag alone matches someone else's now and then: a coin once its commitment is read
         if (!f.confirmed || landed.has(id)) continue;
@@ -505,7 +582,7 @@ export class Wallet {
     }
     for (const d of this.#ctx.state.deposits) {
       // a coin once its commitment is read, which names the amount
-      for (const f of d.found.filter((f) => !f.spent && f.amount !== null)) {
+      for (const f of d.found.filter((f) => unspent(f) && f.amount !== null)) {
         const id = `${d.chainId}:${f.index}`;
         if (landed.has(id)) continue;
         const state =
@@ -755,7 +832,7 @@ export class Wallet {
   /** Refunds deposit `id` to its sender without the ASP, the attester or a proved root: for a deposit the ASP
    * rejected, or when those services stop. The account's wallet sends the transactions and pays their gas. */
   rageExit(id: string): Promise<Hex[]> {
-    return this.#exclusive(async () => {
+    return this.#seeded(async () => {
       const [chain, index] = id.split(':');
       const record =
         this.#ctx.state.deposits.find((d) => `${d.chainId}` === chain && d.found.some((f) => `${f.index}` === index)) ??
@@ -861,22 +938,26 @@ export class Wallet {
    * With `wrapped`, it pays from the account's zERC20 itself, as a withdrawal pays out, rather than its underlying
    * asset: a plain transfer into the burn address, with no wrap and no approval.
    *
+   * With `from`, another wallet of the user's (a browser wallet) pays instead of the account: its balance is checked,
+   * it approves and wraps, and an exit refunds it there. The account pays nothing and signs nothing.
+   *
    * Returns once the wrap is sent: the operation is done once it is mined, which `wait()` or the next sync finds.
    * `onStep` hears what it waits on meanwhile, for an app to show. */
-  deposit(opts: {
+  async deposit(opts: {
     token: Token;
     amount: bigint;
     to?: Address;
     wrapped?: boolean;
+    from?: WalletClient;
     onStep?: (step: DepositStep) => void;
   }): Promise<Operation> {
+    if (opts.amount <= 0n) fail('invalid', 'the amount must be positive');
+    const payer = opts.from ? (opts.from.account ?? fail('invalid', 'the wallet client has no account')) : null;
     const step = opts.onStep ?? (() => {});
     if (this.#busy > 0) step('queued');
     return this.#exclusive(async () => {
       const { token, amount } = opts;
-      if (amount <= 0n) fail('invalid', 'the amount must be positive');
-      const wc = this.#ctx.walletClient;
-      const account = wc.account!;
+      const account = payer ?? this.#ctx.account;
       const client = chainCtx(this.#ctx, token.chainId).chain.client;
       const { wrapped } = opts;
       const native = !wrapped && token.underlying.toLowerCase() === NATIVE.toLowerCase();
@@ -893,7 +974,7 @@ export class Wallet {
         const of = wrapped ? token.symbol : `${token.symbol}'s underlying asset`;
         fail(
           'insufficient-funds',
-          `the account holds ${formatUnits(held, token.decimals)} of ${of}, less than ${formatUnits(amount, token.decimals)}`,
+          `${payer ? 'the wallet' : 'the account'} holds ${formatUnits(held, token.decimals)} of ${of}, less than ${formatUnits(amount, token.decimals)}`,
         );
       }
       const address = opts.to
@@ -907,8 +988,7 @@ export class Wallet {
       );
       await this.#ctx.save();
       try {
-        if ((await wc.getChainId()) !== Number(token.chainId))
-          await guard(wc.switchChain({ id: Number(token.chainId) }));
+        const wc = opts.from ? await switched(opts.from, token.chainId) : await walletOn(this.#ctx, token.chainId);
         if (!native && !wrapped) {
           const allowance = await client.readContract({
             address: token.underlying,
@@ -1002,8 +1082,8 @@ export class Wallet {
 
   /** An address that takes `token`'s underlying asset from anywhere (an exchange withdrawal, another wallet) and
    * deposits it privately, less `fee` (in the underlying's base units) to the deposit relayer each time: what arrives
-   * must exceed it. Watched for 7 days by the deposit relayer; refunds go back to this account. `onStep` hears what it
-   * waits on (`queued`, `burn-address`). */
+   * must exceed it. A wallet opened with a `referrer` also pays it its `bps` of the rest. Watched for 7 days by the
+   * deposit relayer; refunds go back to this account. `onStep` hears what it waits on (`queued`, `burn-address`). */
   depositAddress(
     token: Token,
     opts: { onStep?: (step: DepositStep) => void } = {},
@@ -1013,7 +1093,13 @@ export class Wallet {
     return this.#exclusive(async () => {
       const c = chainCtx(this.#ctx, token.chainId);
       const record = await this.#burnAddress(token, null, () => step('burn-address'));
-      const { depositAddress, fee } = await registerDeposit(c.chain, token.address, record.address, this.address);
+      const { depositAddress, fee } = await registerDeposit(
+        c.chain,
+        token.address,
+        record.address,
+        this.address,
+        this.#referrer,
+      );
       record.depositAddress = depositAddress;
       // for the wallet's other devices, to show what comes through it: written by the next sync
       const burnAddress = record.address.toLowerCase() as Hex;
@@ -1037,19 +1123,21 @@ export class Wallet {
    * nothing; it names neither this address nor its public key. Anyone who gets the code can pay it, and see what its
    * other payers paid privately: give each payer its own. It is checksummed text (bech32m, `zerc201…`). */
   receiveCode(token: Token): Promise<string> {
-    return this.#exclusive(async () => {
-      const ctx = this.#ctx;
+    const ctx = this.#ctx;
+    const code = (index: number) => ({ chainId: token.chainId, tokenId: token.tokenId, index });
+    // the seed is asked for only past the codes derived ahead
+    const derived = !!owner(ctx, code(nextBurn(ctx, token.chainId, token.tokenId)));
+    return this.#seeded(async () => {
       const { burnIndex, address } = await this.#burnAddress(token);
+      if (!owner(ctx, code(burnIndex))) await this.#seed(); // calls queued before took the next ones
       return encodeCode({
         chainId: token.chainId,
         tokenId: token.tokenId,
         burnAddress: hexToBytes(address),
-        publicKey: hexToBytes(
-          spendKey(ctx, { chainId: token.chainId, tokenId: token.tokenId, index: burnIndex }).publicKey,
-        ),
+        publicKey: hexToBytes(owner(ctx, code(burnIndex))!.publicKey),
         key: codeKey(ctx.view.seed, token.chainId, token.tokenId, burnIndex),
       });
-    });
+    }, !derived);
   }
 
   /** What a send or withdrawal of `amount` would cost now, or a consolidation of what the wallet holds. A send or
@@ -1134,10 +1222,11 @@ export class Wallet {
    * what is spendable now, or it fails here: `needs-consolidation`, `funds-settling` or `insufficient-funds`.
    * `amount` is what the recipient gets, and `maxFee` caps what it pays on top, `fees({ kind: 'send' }).fee`: the
    * relayer names its fee, so a quote the user saw is the cap. */
-  send(opts: { to: string; token: Token; amount: bigint; maxFee: bigint }): Promise<Operation> {
-    return this.#exclusive(async () => {
-      const { token, amount } = opts;
-      if (amount <= 0n) fail('invalid', 'the amount must be positive');
+  async send(opts: { to: string; token: Token; amount: bigint; maxFee: bigint }): Promise<Operation> {
+    const { token, amount } = opts;
+    if (amount <= 0n) fail('invalid', 'the amount must be positive');
+    // the JoinSplit is proved by a later sync, which holds the seed until the payment is done
+    return this.#seeded(async () => {
       let to: Destination;
       if (isAddress(opts.to)) {
         const recipient = await lookupRecipient(this.#ctx.storage, hexToBytes(opts.to));
@@ -1169,7 +1258,7 @@ export class Wallet {
    * touched; one still settling is waited for. `maxFee` caps the fees of every merge together,
    * `fees({ kind: 'consolidate' }).fee`. */
   consolidate(opts: { token: Token; coins?: string[]; maxFee: bigint }): Promise<Operation> {
-    return this.#exclusive(async () => {
+    return this.#seeded(async () => {
       if (!this.#ctx.network.mergeProver) fail('invalid', 'this network has no merge prover');
       const to: Destination = { kind: 'self' };
       const data: SpendData = { to, maxFee: opts.maxFee, step: null, paid: 0n };
@@ -1196,10 +1285,16 @@ export class Wallet {
   /** Withdraws `amount` publicly to `to`, as zERC20 or with `unwrap` the underlying asset itself, so `to` needs no gas
    * to unwrap. One JoinSplit, as `send`, and as there `to` gets all of `amount` and `maxFee` caps what is paid on top
    * (`fees({ kind: 'withdraw' }).fee`). */
-  withdraw(opts: { to: Address; token: Token; amount: bigint; maxFee: bigint; unwrap?: boolean }): Promise<Operation> {
-    return this.#exclusive(async () => {
-      if (!isAddress(opts.to)) fail('invalid', `${String(opts.to)} is not an address`);
-      if (opts.amount <= 0n) fail('invalid', 'the amount must be positive');
+  async withdraw(opts: {
+    to: Address;
+    token: Token;
+    amount: bigint;
+    maxFee: bigint;
+    unwrap?: boolean;
+  }): Promise<Operation> {
+    if (!isAddress(opts.to)) fail('invalid', `${String(opts.to)} is not an address`);
+    if (opts.amount <= 0n) fail('invalid', 'the amount must be positive');
+    return this.#seeded(async () => {
       const to: Destination = { kind: 'public', address: opts.to, unwrap: opts.unwrap };
       return this.#newPayment('withdraw', opts.token, opts.amount, { to, maxFee: opts.maxFee, step: null, paid: 0n });
     });

package/wasm/zerc20_wallet_core.d.ts

@@ -7,18 +7,27 @@
  */
 export function aspLeaves(bitmap: Uint8Array, first: bigint, count: number): Uint8Array;
 
+export function burnAddressOf(chain_id: bigint, public_key: string, salt: string): string | undefined;
+
 /**
- * A seed's `index`-th burn address for one chain and token, with its salt: `{salt, address}`. About 2^16 hashes.
+ * The `index`-th burn address of `public_key` on one chain and token from `burn_key`, and its salt, if the salt's
+ * counter is in `from..=to`: `{salt, address}` or `undefined`. Searched in blocks of counters from 0, the result is
+ * the first block's hit.
  */
-export function burnAddress(seed: Uint8Array, chain_id: bigint, token_id: number, index: number): any;
+export function burnBlock(burn_key: Uint8Array, chain_id: bigint, token_id: number, index: number, public_key: string, from: number, to: number): any;
 
-export function burnAddressOf(chain_id: bigint, public_key: string, salt: string): string | undefined;
+/**
+ * A burn address of someone else's `public_key` on a chain, with its salt: the first of the `count` salts from
+ * `start` that has the proof of work, `{salt, address}`, or `undefined`. A random `start` makes the salt
+ * unguessable.
+ */
+export function burnBlockFor(chain_id: bigint, public_key: string, start: string, count: number): any;
 
 /**
  * The key that owns the notes paid to a seed's `index`-th receive code for one chain and token, shaped like
  * `spendKey`.
  */
-export function codeKey(seed: Uint8Array, chain_id: bigint, token_id: number, index: number): any;
+export function codeSpendKey(seed: Uint8Array, chain_id: bigint, token_id: number, index: number): any;
 
 /**
  * `CommitmentLedger`'s hash chain after appending a commitment with `fields` to `prev`.
@@ -64,12 +73,6 @@ export function path(i: bigint, n: bigint, chunk_leaves: Uint8Array, page_chunks
  */
 export function pathRoot(leaf: string, i: bigint, siblings: string[]): string;
 
-/**
- * The `k`-th burn address a point of sale holding `lane_key` makes for `public_key` on one chain and token, with its
- * salt: `{salt, address}`. About 2^16 hashes.
- */
-export function posBurnAddress(lane_key: Uint8Array, chain_id: bigint, token_id: number, k: number, public_key: string): any;
-
 /**
  * Seals a merge witness (JSON) to the merge prover's key, padded with spaces to `pad_to` bytes. Take the key from
  * `verifyAttestation`, as for the attester's.
@@ -123,9 +126,10 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly aspLeaves: (a: number, b: number, c: bigint, d: number) => [number, number, number, number];
-    readonly burnAddress: (a: number, b: number, c: bigint, d: number, e: number) => [number, number, number];
     readonly burnAddressOf: (a: bigint, b: number, c: number, d: number, e: number) => [number, number, number, number];
-    readonly codeKey: (a: number, b: number, c: bigint, d: number, e: number) => [number, number, number];
+    readonly burnBlock: (a: number, b: number, c: bigint, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number, number];
+    readonly burnBlockFor: (a: bigint, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+    readonly codeSpendKey: (a: number, b: number, c: bigint, d: number, e: number) => [number, number, number];
     readonly hashChain: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly leaf: (a: number, b: number) => [number, number, number, number];
     readonly leaves: (a: number, b: number) => [number, number, number, number];
@@ -134,7 +138,6 @@ export interface InitOutput {
     readonly nullifier: (a: bigint, b: bigint, c: number, d: number) => [number, number, number, number];
     readonly path: (a: bigint, b: bigint, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number) => [number, number, number, number];
     readonly pathRoot: (a: number, b: number, c: bigint, d: number, e: number) => [number, number, number, number];
-    readonly posBurnAddress: (a: number, b: number, c: bigint, d: number, e: number, f: number, g: number) => [number, number, number];
     readonly sealMergeWitness: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly sealWitness: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly signMerge: (a: number, b: number, c: number, d: number) => [number, number, number, number];