@zerc20/wallet-sdk 0.3.0 → 0.4.0

package/src/wallet.ts

@@ -10,6 +10,7 @@ import {
   encodeCode,
   lookupRecipient,
   nextPosLane,
+  notifyKey,
   planDeposit,
   planPosLane,
   posKey,
@@ -23,13 +24,25 @@ import {
   type WalletClient,
   bytesToHex,
   formatUnits,
+  getAddress,
   hexToBytes,
   isAddress,
   numberToHex,
   zeroAddress,
 } from 'viem';
+import { toAccount } from 'viem/accounts';
 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 {
+  type ChainCtx,
+  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';
@@ -79,6 +92,7 @@ import {
   topUpBurns,
   unusedBurn,
 } from './sync.js';
+import { decodeViewKey, encodeViewKey } from './viewKey.js';
 
 /** The ledger's bound outside an emergency. */
 const NO_BOUND = 2n ** 64n - 1n;
@@ -106,6 +120,11 @@ export interface OpenOptions {
   referrer?: Referrer;
 }
 
+export interface WatchOptions extends Pick<OpenOptions, 'network' | 'persist' | 'birthday'> {
+  /** The account's view key, from its wallet's `viewKey()`. */
+  viewKey: string;
+}
+
 /** What a deposit, or a deposit address, waits on: for an app to show while it does. */
 export type DepositStep =
   /** Behind another call of this wallet: a sync, or another operation. */
@@ -253,6 +272,7 @@ export class Wallet {
   #release = () => {};
   #referrer: Referrer | undefined;
   readonly #unlock: (() => Promise<Uint8Array>) | undefined;
+  #readOnly = false;
   #closed = new AbortController();
 
   private constructor(ctx: Ctx, unlock?: () => Promise<Uint8Array>) {
@@ -272,6 +292,18 @@ export class Wallet {
     return this.#ctx.address;
   }
 
+  /** The account's view key, for `watch` to follow it with on another device: whoever holds it sees what this wallet
+   * shows, except the private payments to receive codes, and can spend none of it. Checksummed text (bech32m,
+   * `zerc20view1…`). */
+  viewKey(): string {
+    return encodeViewKey(this.#ctx.view, owner(this.#ctx)!);
+  }
+
+  /** Whether this wallet only watches its account (`watch`): it shows what the account holds and spends nothing. */
+  get readOnly(): boolean {
+    return this.#readOnly;
+  }
+
   /** Opens the wallet. The first time on this address, registers it for payments: one signature. */
   static async open(opts: OpenOptions): Promise<Wallet> {
     checkNetwork(opts.network);
@@ -301,12 +333,7 @@ export class 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,
-      chain: new Chain(config),
-      indexer: new Indexer(config.indexer),
-      asp: new Asp(config.asp),
-    }));
+    const chains = chainsOf(opts.network);
     const code = await chains[0]?.chain.client.getCode({ address });
     // an EIP-7702 delegated account is still an EOA that signs
     if (code && code !== '0x' && !code.startsWith('0xef0100'))
@@ -327,39 +354,99 @@ export class Wallet {
     const restoring =
       !saved?.length && opts.birthday === undefined && !!(await storage.registration(hexToBytes(address)));
     const view = await registeredViewKey(storage, seed, signer, hexToBytes(address), publicKey);
-    const key = stateKey(seed);
+    const wallet = await Wallet.#begin(
+      {
+        network: opts.network,
+        seed,
+        owners: new Map(),
+        address,
+        account,
+        walletClient: opts.walletClient ?? null,
+        storage,
+        view,
+        chains,
+      },
+      { persist: opts.persist, saved, key: stateKey(seed), from: restoring ? 0n : opts.birthday },
+      typeof opts.seed === 'function' ? opts.seed : undefined,
+    );
+    wallet.#release = release;
+    wallet.#referrer = opts.referrer;
+    return wallet;
+  }
+
+  /** Opens an account to follow by its view key (`viewKey()`): its balances, coins and history as its own wallet shows
+   * them, less the private payments to its receive codes, whose keys only the seed derives. It spends and writes
+   * nothing: a call that would fails with `read-only`. The key must be the account's current one on this network. */
+  static async watch(opts: WatchOptions): Promise<Wallet> {
+    checkNetwork(opts.network);
+    await initCore();
+    const { view, owner } = decodeViewKey(opts.viewKey) ?? fail('invalid', 'not a view key');
+    const address = getAddress(bytesToHex(view.address));
+    const release = await lockWallet(address, 'view');
+    try {
+      const storage = await CanisterClient.connect(opts.network.storage.host, opts.network.storage.canisterId);
+      // what the account signed: a nullifying key that is not the account's would show spent coins as unspent
+      const r = await lookupRecipient(storage, view.address);
+      if (!r || bytesToHex(r.publicKey) !== owner.publicKey || bytesToHex(r.notifyKey) !== bytesToHex(notifyKey(view)))
+        fail('invalid', `not ${address}'s view key on ${opts.network.name}, or one it has replaced`);
+      const wallet = await Wallet.#begin(
+        {
+          network: opts.network,
+          seed: null,
+          owners: new Map([['', owner]]),
+          address,
+          // signs nothing: every call that would send is refused first
+          account: toAccount(address),
+          walletClient: null,
+          storage,
+          view,
+          chains: chainsOf(opts.network),
+        },
+        // registered, so its past is looked for
+        {
+          persist: opts.persist,
+          saved: await opts.persist.load(),
+          key: stateKey(view.seed),
+          from: opts.birthday ?? 0n,
+        },
+      );
+      wallet.#release = release;
+      wallet.#readOnly = true;
+      return wallet;
+    } catch (e) {
+      release();
+      throw e;
+    }
+  }
+
+  /** The wallet over `base`, its state opened from what `persist` saved, with `key`, or started `from` a block or date. */
+  static async #begin(
+    base: Omit<Ctx, 'state' | 'save' | 'lastFullRefreshMs'>,
+    {
+      persist,
+      saved,
+      key,
+      from,
+    }: { persist: OpenOptions['persist']; saved: Uint8Array | null | undefined; key: Uint8Array; from?: bigint | Date },
+    unlock?: () => Promise<Uint8Array>,
+  ): Promise<Wallet> {
     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(
         'invalid',
-        'the saved state does not open with this seed (another seed, a newer version, or damaged): clear it to start over, which finds what it held again',
+        'the saved state does not open with this key (another seed or view key, a newer version, or damaged): clear it to start over, which finds what it held again',
       );
     }
-    if (loaded && loaded.address.toLowerCase() !== address.toLowerCase())
+    if (loaded && loaded.address.toLowerCase() !== base.address.toLowerCase())
       fail('invalid', `the saved state is ${loaded.address}'s: keep one per address`);
-    const state: WalletState = loaded ?? emptyWalletState(address);
-    const ctx: Ctx = {
-      network: opts.network,
-      seed,
-      owners: new Map(),
-      address,
-      account,
-      walletClient: opts.walletClient ?? null,
-      storage,
-      view,
-      chains,
-      state,
-      save: () => opts.persist.save(sealState(key, state)),
-      lastFullRefreshMs: 0,
-    };
-    if (!loaded) await start(ctx, restoring ? 0n : opts.birthday);
-    const wallet = new Wallet(ctx, typeof opts.seed === 'function' ? opts.seed : undefined);
-    wallet.#release = release;
-    wallet.#referrer = opts.referrer;
+    const state: WalletState = loaded ?? emptyWalletState(base.address);
+    const ctx: Ctx = { ...base, state, save: () => persist.save(sealState(key, state)), lastFullRefreshMs: 0 };
+    if (!loaded) await start(ctx, from);
+    const wallet = new Wallet(ctx, unlock);
     // 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()]);
+    const [tokens] = await Promise.all([Promise.all(ctx.chains.map((c) => c.chain.tokens())), wallet.#readRoots()]);
     wallet.#tokens = tokens.flat();
     keyAll(ctx, wallet.#tokens);
     return wallet;
@@ -391,10 +478,16 @@ export class Wallet {
    * 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> {
+    this.#writable();
     if (needs && !this.#ctx.seed) this.#hold(await this.#unlock!());
     return this.#exclusive(f);
   }
 
+  /** Refuses a call that spends or writes to storage, in a wallet that watches. */
+  #writable(): void {
+    if (this.#readOnly) fail('read-only', 'this wallet watches its account by its view key: open it with its seed');
+  }
+
   /** 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++;
@@ -435,8 +528,9 @@ export class Wallet {
     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
+        // still this task's: a deposit queued meanwhile finds the one recorded ahead, rather than writing at handout;
+        // tried again after the next sync. A wallet that watches records none, as it writes nothing.
+        if (!this.#readOnly) await topUpBurns(this.#ctx, this.#closed.signal).catch(() => {});
         this.#dropSeed();
       }).catch(reject); // closed before it ran
     });
@@ -818,6 +912,7 @@ export class Wallet {
    * addresses. */
   posKey(): Promise<Hex> {
     return this.#exclusive(async () => {
+      this.#writable();
       const ctx = this.#ctx;
       const tokens = await tokenIds(ctx);
       let n = 0;
@@ -951,6 +1046,7 @@ export class Wallet {
     from?: WalletClient;
     onStep?: (step: DepositStep) => void;
   }): Promise<Operation> {
+    this.#writable();
     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 ?? (() => {});
@@ -1091,6 +1187,7 @@ export class Wallet {
     const step = opts.onStep ?? (() => {});
     if (this.#busy > 0) step('queued');
     return this.#exclusive(async () => {
+      this.#writable();
       const c = chainCtx(this.#ctx, token.chainId);
       const record = await this.#burnAddress(token, null, () => step('burn-address'));
       const { depositAddress, fee } = await registerDeposit(
@@ -1315,15 +1412,25 @@ export class Wallet {
   }
 }
 
+/** Each chain of `network`, with its servers. */
+const chainsOf = (network: Network): ChainCtx[] =>
+  network.chains.map((config) => ({
+    config,
+    chain: new Chain(config),
+    indexer: new Indexer(config.indexer),
+    asp: new Asp(config.asp),
+  }));
+
 /** Holds `address`'s wallet until the returned function is called: two tabs on one wallet would each overwrite the
- * other's state and spend the same notes. Nothing where there are no Web Locks. */
-export async function lockWallet(address: Address): Promise<() => void> {
+ * other's state and spend the same notes. A wallet that watches it (`view`) is held apart, as its state is its own.
+ * Nothing where there are no Web Locks. */
+export async function lockWallet(address: Address, kind: 'wallet' | 'view' = 'wallet'): Promise<() => void> {
   const locks = (globalThis as { navigator?: Navigator }).navigator?.locks;
   if (!locks) return () => {};
   let release = () => {};
   const held = new Promise<void>((r) => (release = r));
   const got = await new Promise<boolean>((resolve) => {
-    void locks.request(`zerc20-wallet:${address.toLowerCase()}`, { ifAvailable: true }, (lock) => {
+    void locks.request(`zerc20-${kind}:${address.toLowerCase()}`, { ifAvailable: true }, (lock) => {
       resolve(lock !== null);
       return lock ? held : undefined;
     });

package/wasm/zerc20_wallet_core.d.ts

@@ -73,6 +73,12 @@ export function path(i: bigint, n: bigint, chunk_leaves: Uint8Array, page_chunks
  */
 export function pathRoot(leaf: string, i: bigint, siblings: string[]): string;
 
+/**
+ * The public key a signing key's hash and a nullifying key make: how a view key's holder checks that the nullifying
+ * key it was given is the one the account's notes commit to.
+ */
+export function publicKey(auth_key_hash: string, nullifying_key: string): string;
+
 /**
  * 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.
@@ -138,6 +144,7 @@ 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 publicKey: (a: number, b: number, c: number, d: number) => [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];

package/wasm/zerc20_wallet_core.js

@@ -324,6 +324,36 @@ export function pathRoot(leaf, i, siblings) {
     }
 }
 
+/**
+ * The public key a signing key's hash and a nullifying key make: how a view key's holder checks that the nullifying
+ * key it was given is the one the account's notes commit to.
+ * @param {string} auth_key_hash
+ * @param {string} nullifying_key
+ * @returns {string}
+ */
+export function publicKey(auth_key_hash, nullifying_key) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const ptr0 = passStringToWasm0(auth_key_hash, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(nullifying_key, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.publicKey(ptr0, len0, ptr1, len1);
+        var ptr3 = ret[0];
+        var len3 = ret[1];
+        if (ret[3]) {
+            ptr3 = 0; len3 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
+    } finally {
+        wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
+    }
+}
+
 /**
  * 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.

package/wasm/zerc20_wallet_core_bg.wasm.d.ts

@@ -14,6 +14,7 @@ export const noteTag: (a: number, b: number, c: number) => [number, number, numb
 export const nullifier: (a: bigint, b: bigint, c: number, d: number) => [number, number, number, number];
 export const 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];
 export const pathRoot: (a: number, b: number, c: bigint, d: number, e: number) => [number, number, number, number];
+export const publicKey: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const sealMergeWitness: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
 export const sealWitness: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
 export const signMerge: (a: number, b: number, c: number, d: number) => [number, number, number, number];