@zerc20/kohaku-plugin 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zERC20
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @zerc20/kohaku-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+zERC20 as a [Kohaku](https://github.com/ethereum/kohaku) privacy plugin: a wallet built on `@kohaku-eth/plugins` shields
+into zERC20, pays privately and unshields, through the `Host` it already has.
+
+```sh
+npm install @zerc20/kohaku-plugin @kohaku-eth/plugins viem
+```
+
+```ts
+import { createZerc20Broadcaster, createZerc20Plugin } from '@zerc20/kohaku-plugin';
+import { networkFromJson } from '@zerc20/wallet-sdk';
+
+const network = networkFromJson(await (await fetch('https://v2.zerc20.io/network.json')).text());
+const plugin = await createZerc20Plugin(host, { network, accountIndex: 0 });
+const usdc = { __type: 'erc20', contract: '0xA0b8…eB48' } as const;
+
+const { txns } = await plugin.prepareShield({ asset: usdc, amount }); // sent in order, before the next shield's
+await plugin.balance([usdc]); // spendable, then `pending` (screening, or awaiting a root)
+const op = await plugin.prepareTransfer({ asset: usdc, amount }, 'zerc20id1…');
+await createZerc20Broadcaster(plugin).broadcast(op);
+```
+
+Assets are named by their underlying ERC20 (ETH as `0xeeee…eeee`): a shield wraps it, an unshield pays it out. Named
+by the zERC20 token itself, they move as they are.
+
+## Why it looks like this
+
+- **One plugin per chain.** Kohaku gives a plugin one provider, and a zERC20 account keeps a state of its own on each
+  chain, so a host opens a plugin per chain, side by side.
+- **The host's network covers everything.** Chain reads go through `host.provider`, and every server request (the
+  relayer, the attester, the storage canister, the circuits) through `host.network.fetch`: a host's proxy or Tor
+  covers them all.
+- **Keys come from the host's keystore**, below `m/31333'/1'/{accountIndex}'` only, so the host's mnemonic restores
+  the account. It is not the account wallet.zerc20.io opens with a passkey.
+- **Preparing spends nothing.** `prepareTransfer` and `prepareUnshield` quote the fee and check that one JoinSplit pays
+  it; the broadcaster proves on the device, has the relayer submit, and returns once final. An interrupted broadcast
+  resumes at the next `sync()`.
+- **The wallet underneath is `plugin.wallet`** (`@zerc20/wallet-sdk`), for receive codes, consolidation, rage exits,
+  history and view keys. `plugin.wallet.close()` lets the account go.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import { type AssetAmount, type ERC20AssetId, type Host, type PluginInstance, type PrivateOperation, type PublicOperation } from '@kohaku-eth/plugins';
+import type { Broadcaster } from '@kohaku-eth/plugins/broadcaster';
+import { type Network, type Token, Wallet } from '@zerc20/wallet-sdk';
+import { type Address, type Hex } from 'viem';
+/** The keystore subtree zERC20 keys come from ("ze" in ASCII as the purpose, as Kohaku's own plugins name theirs): the
+ * plugin derives nothing outside it. */
+export declare const ZERC20_KEYSTORE_PREFIX = "m/31333'/1'";
+export interface Zerc20PluginParameters {
+    /** The zERC20 deployment, as `networkFromJson` reads its network.json. */
+    network: Network;
+    /** Which account of the keystore's: each index is an account of its own. */
+    accountIndex: number;
+    /** Where an account with no saved state starts looking on chain: the block its key was first used at, or roughly
+     * when. Without it, an account that registered before is looked for from the chain's start, and a new one from now. */
+    birthday?: bigint | Date;
+}
+/** An amount of a token of the plugin's chain, named by its underlying ERC20 (ETH as `0xeeee…eeee`, as Kohaku's other
+ * plugins name it), which a shield wraps and an unshield pays out, or by the zERC20 itself, which moves as it is. */
+export type Zerc20AssetAmount<Tag extends string | undefined = undefined> = AssetAmount<ERC20AssetId, bigint, Tag>;
+/** The transactions a shield takes, for the host to sign and send in order before it prepares another shield of the same
+ * asset: an ERC20's approval of the amount first, which a later one would replace, then the wrap. */
+export interface Zerc20PublicOperation extends PublicOperation {
+    txns: {
+        to: Address;
+        data: Hex;
+        value: bigint;
+    }[];
+}
+/** A payment or a withdrawal as quoted: nothing is spent until a broadcaster sends it. */
+export interface Zerc20PrivateOperation extends PrivateOperation {
+    kind: 'send' | 'withdraw';
+    token: Token;
+    /** A send's recipient: a zERC20 ID, an address that opened a zERC20 wallet, or a receive code. A withdrawal's: any
+     * address. */
+    to: string;
+    amount: bigint;
+    /** The fee quoted, the most the payment may cost on top of `amount`. */
+    maxFee: bigint;
+    /** A withdrawal's payout in the underlying asset rather than the zERC20. */
+    unwrap: boolean;
+}
+export type Zerc20Instance = PluginInstance<string, {
+    features: {
+        prepareShield: true;
+        prepareTransfer: true;
+        prepareUnshield: true;
+    };
+    assetAmounts: {
+        input: Zerc20AssetAmount;
+        internal: Zerc20AssetAmount;
+        output: Zerc20AssetAmount;
+        /** Each asset's spendable amount, then what is on its way (screening, or awaiting a root) tagged `pending`. */
+        read: Zerc20AssetAmount<'pending'>;
+    };
+    publicOp: Zerc20PublicOperation;
+    privateOp: Zerc20PrivateOperation;
+    extras: {
+        /** Brings the account up to date with the chain and the servers, and moves operations under way along. Every call
+         * that reads the account does it first. */
+        sync(): Promise<void>;
+        /** The zERC20 wallet underneath, for what Kohaku has no call for: receive codes, consolidation, rage exits,
+         * history, a view key. `close()` lets the account go, for another plugin on the same chain. */
+        wallet: Wallet;
+    };
+}>;
+/** What a broadcast did: the operation's id in the wallet, and the transactions it sent. */
+export interface Zerc20BroadcastResult {
+    id: string;
+    txHashes: Hex[];
+}
+export type Zerc20Broadcaster = Broadcaster<Zerc20PrivateOperation, Zerc20BroadcastResult>;
+/** Opens account `accountIndex` of the host's keystore on the chain of its provider; the first time, it registers the
+ * account for payments. Its state lives in the host's storage, encrypted by the wallet, under the deployment's storage
+ * canister and verifier as well: the same keys on another deployment of the chain have a state of their own. An earlier
+ * plugin of the same account and chain, here or in another tab, stops: Kohaku has no call to close one, and the two
+ * would spend the same notes. */
+export declare function createZerc20Plugin(host: Host, params: Zerc20PluginParameters): Promise<Zerc20Instance>;
+/** Sends what `plugin` prepared: proves the JoinSplit here, has the relayer submit it, and returns once it is final.
+ * Interrupted, it resumes at the plugin's next sync. */
+export declare function createZerc20Broadcaster(plugin: Zerc20Instance): Zerc20Broadcaster;

package/dist/index.js

@@ -0,0 +1,126 @@
+// @zerc20/kohaku-plugin: zERC20 as a Kohaku privacy plugin. A wallet built on @kohaku-eth/plugins shields into zERC20,
+// pays privately and unshields through the host it already has, as it does with the other protocols.
+//
+//   const plugin = await createZerc20Plugin(host, { network: networkFromJson(json), accountIndex: 0 });
+//   const { txns } = await plugin.prepareShield({ asset: { __type: 'erc20', contract: usdc }, amount }); // the host signs
+//   const op = await plugin.prepareTransfer({ asset, amount }, 'zerc20id1…');
+//   await createZerc20Broadcaster(plugin).broadcast(op);
+//
+// One plugin is one zERC20 account on the chain of the host's provider: Kohaku gives a plugin one provider, and the
+// account's wallet on each chain keeps a state of its own, so a host opens one plugin per chain, side by side. Every
+// chain read goes through that provider and every server request through the host's `network.fetch`, so a host's proxy
+// or Tor covers the relayer, the attester and the storage canister too.
+import { InsufficientBalanceError, InvalidAddressError, PluginError, UnsupportedAssetError, UnsupportedChainError, scopeKeystore, } from '@kohaku-eth/plugins';
+import { base64 } from '@scure/base';
+import { Wallet, WalletError, accountId, accountKey } from '@zerc20/wallet-sdk';
+import { custom, hexToBytes, isAddress, isAddressEqual } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+/** The keystore subtree zERC20 keys come from ("ze" in ASCII as the purpose, as Kohaku's own plugins name theirs): the
+ * plugin derives nothing outside it. */
+export const ZERC20_KEYSTORE_PREFIX = "m/31333'/1'";
+/** Opens account `accountIndex` of the host's keystore on the chain of its provider; the first time, it registers the
+ * account for payments. Its state lives in the host's storage, encrypted by the wallet, under the deployment's storage
+ * canister and verifier as well: the same keys on another deployment of the chain have a state of their own. An earlier
+ * plugin of the same account and chain, here or in another tab, stops: Kohaku has no call to close one, and the two
+ * would spend the same notes. */
+export async function createZerc20Plugin(host, params) {
+    const chainId = await host.provider.getChainId();
+    const config = params.network.chains.find((c) => c.chainId === chainId);
+    if (!config)
+        throw new UnsupportedChainError(chainId);
+    const keystore = scopeKeystore(host.keystore, { prefixes: [ZERC20_KEYSTORE_PREFIX] });
+    // the key is the seed of every zERC20 key of the account: asked for whenever the wallet spends, and let go after
+    const seed = async () => hexToBytes(await keystore.deriveAt(`${ZERC20_KEYSTORE_PREFIX}/${params.accountIndex}'`));
+    const key = `zerc20-state:${params.network.storage.canisterId}:${chainId}:${config.verifier}:${params.accountIndex}`;
+    const request = (({ method, params }) => host.provider.request({ method, params }));
+    const wallet = await Wallet.open({
+        network: { ...params.network, chains: [config] },
+        account: privateKeyToAccount(accountKey(await seed())),
+        seed,
+        persist: {
+            load: async () => {
+                const saved = await host.storage.get(key);
+                return saved === null ? null : base64.decode(saved);
+            },
+            save: (bytes) => host.storage.set(key, base64.encode(bytes)),
+        },
+        birthday: params.birthday,
+        take: true,
+        transport: () => custom({ request }),
+        fetch: (input, init) => host.network.fetch(input, init),
+    });
+    const tokenOf = (asset) => {
+        for (const token of wallet.tokens()) {
+            if (isAddressEqual(token.underlying, asset.contract))
+                return { token, wrapped: false };
+            if (isAddressEqual(token.address, asset.contract))
+                return { token, wrapped: true };
+        }
+        throw new UnsupportedAssetError(asset);
+    };
+    /** A payment's fee now, which also checks that one JoinSplit pays it from what is spendable. */
+    const quote = async (kind, { asset, amount }, to) => {
+        await wallet.sync();
+        const { token, wrapped } = tokenOf(asset);
+        try {
+            const { fee } = await wallet.fees({ kind, token, amount });
+            return { __type: 'privateOperation', kind, token, to, amount, maxFee: fee, unwrap: !wrapped };
+        }
+        catch (e) {
+            // as Kohaku's other plugins report it; settling funds and fragmented notes keep the wallet's own codes
+            if (!(e instanceof WalletError) || e.code !== 'insufficient-funds')
+                throw e;
+            throw new InsufficientBalanceError(asset, amount, (await wallet.maxAmount({ kind, token })).amount);
+        }
+    };
+    return {
+        wallet,
+        sync: () => wallet.sync(),
+        instanceId: async () => accountId(wallet.address),
+        async balance(assets) {
+            await wallet.sync();
+            const balances = wallet.balances();
+            const rows = assets
+                ? assets.map((asset) => ({ asset, token: tokenOf(asset).token }))
+                : balances.map((b) => ({ asset: { __type: 'erc20', contract: b.token.underlying }, token: b.token }));
+            return rows.flatMap(({ asset, token }) => {
+                const b = balances.find((b) => b.token.tokenId === token.tokenId);
+                const pending = b?.pending.reduce((sum, p) => sum + p.amount, 0n) ?? 0n;
+                return [
+                    { asset, amount: b?.spendable ?? 0n },
+                    { asset, amount: pending, tag: 'pending' },
+                ];
+            });
+        },
+        async prepareShield({ asset, amount }, to) {
+            await wallet.sync();
+            const { token, wrapped } = tokenOf(asset);
+            return { __type: 'publicOperation', txns: await wallet.depositTransactions({ token, amount, to, wrapped }) };
+        },
+        prepareTransfer: (asset, to) => quote('send', asset, to),
+        async prepareUnshield(asset, to, options) {
+            // a withdrawal pays one address and calls nothing after
+            if (options?.tailCalls)
+                throw new PluginError('a zERC20 withdrawal takes no tail calls');
+            if (!isAddress(to))
+                throw new InvalidAddressError(to);
+            return quote('withdraw', asset, to);
+        },
+    };
+}
+/** Sends what `plugin` prepared: proves the JoinSplit here, has the relayer submit it, and returns once it is final.
+ * Interrupted, it resumes at the plugin's next sync. */
+export function createZerc20Broadcaster(plugin) {
+    return {
+        async broadcast(op) {
+            const { wallet } = plugin;
+            const { token, amount, maxFee } = op;
+            const sent = op.kind === 'send'
+                ? await wallet.send({ to: op.to, token, amount, maxFee })
+                : await wallet.withdraw({ to: op.to, token, amount, maxFee, unwrap: op.unwrap });
+            await sent.wait();
+            return { id: sent.id, txHashes: [...sent.txHashes] };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@zerc20/kohaku-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "zERC20 as a Kohaku privacy plugin: shield, private transfers and unshield for wallets built on @kohaku-eth/plugins.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerc20io/zERC20v2.git",
+    "directory": "wallet/kohaku"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --config vitest.config.ts",
+    "test:e2e": "scripts/e2e.sh"
+  },
+  "dependencies": {
+    "@scure/base": "^2.4.0",
+    "@zerc20/wallet-sdk": "^"
+  },
+  "peerDependencies": {
+    "@kohaku-eth/plugins": "^0.0.1-alpha.20",
+    "viem": "^2.57.7"
+  },
+  "devDependencies": {
+    "@kohaku-eth/plugins": "0.0.1-alpha.20",
+    "@kohaku-eth/provider": "0.1.0-alpha.14",
+    "@types/node": "24.19.2",
+    "typescript": "6.0.3",
+    "viem": "2.57.7",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "overrides": {
+    "underscore": "1.13.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,215 @@
+// @zerc20/kohaku-plugin: zERC20 as a Kohaku privacy plugin. A wallet built on @kohaku-eth/plugins shields into zERC20,
+// pays privately and unshields through the host it already has, as it does with the other protocols.
+//
+//   const plugin = await createZerc20Plugin(host, { network: networkFromJson(json), accountIndex: 0 });
+//   const { txns } = await plugin.prepareShield({ asset: { __type: 'erc20', contract: usdc }, amount }); // the host signs
+//   const op = await plugin.prepareTransfer({ asset, amount }, 'zerc20id1…');
+//   await createZerc20Broadcaster(plugin).broadcast(op);
+//
+// One plugin is one zERC20 account on the chain of the host's provider: Kohaku gives a plugin one provider, and the
+// account's wallet on each chain keeps a state of its own, so a host opens one plugin per chain, side by side. Every
+// chain read goes through that provider and every server request through the host's `network.fetch`, so a host's proxy
+// or Tor covers the relayer, the attester and the storage canister too.
+
+import {
+  type AssetAmount,
+  type ERC20AssetId,
+  type Host,
+  InsufficientBalanceError,
+  InvalidAddressError,
+  PluginError,
+  type PluginInstance,
+  type PrivateOperation,
+  type PublicOperation,
+  type UnshieldOptions,
+  UnsupportedAssetError,
+  UnsupportedChainError,
+  scopeKeystore,
+} from '@kohaku-eth/plugins';
+import type { Broadcaster } from '@kohaku-eth/plugins/broadcaster';
+import { base64 } from '@scure/base';
+import { type Network, type Token, Wallet, WalletError, accountId, accountKey } from '@zerc20/wallet-sdk';
+import { type Address, type EIP1193RequestFn, type Hex, custom, hexToBytes, isAddress, isAddressEqual } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+
+/** The keystore subtree zERC20 keys come from ("ze" in ASCII as the purpose, as Kohaku's own plugins name theirs): the
+ * plugin derives nothing outside it. */
+export const ZERC20_KEYSTORE_PREFIX = "m/31333'/1'";
+
+export interface Zerc20PluginParameters {
+  /** The zERC20 deployment, as `networkFromJson` reads its network.json. */
+  network: Network;
+  /** Which account of the keystore's: each index is an account of its own. */
+  accountIndex: number;
+  /** Where an account with no saved state starts looking on chain: the block its key was first used at, or roughly
+   * when. Without it, an account that registered before is looked for from the chain's start, and a new one from now. */
+  birthday?: bigint | Date;
+}
+
+/** An amount of a token of the plugin's chain, named by its underlying ERC20 (ETH as `0xeeee…eeee`, as Kohaku's other
+ * plugins name it), which a shield wraps and an unshield pays out, or by the zERC20 itself, which moves as it is. */
+export type Zerc20AssetAmount<Tag extends string | undefined = undefined> = AssetAmount<ERC20AssetId, bigint, Tag>;
+
+/** The transactions a shield takes, for the host to sign and send in order before it prepares another shield of the same
+ * asset: an ERC20's approval of the amount first, which a later one would replace, then the wrap. */
+export interface Zerc20PublicOperation extends PublicOperation {
+  txns: { to: Address; data: Hex; value: bigint }[];
+}
+
+/** A payment or a withdrawal as quoted: nothing is spent until a broadcaster sends it. */
+export interface Zerc20PrivateOperation extends PrivateOperation {
+  kind: 'send' | 'withdraw';
+  token: Token;
+  /** A send's recipient: a zERC20 ID, an address that opened a zERC20 wallet, or a receive code. A withdrawal's: any
+   * address. */
+  to: string;
+  amount: bigint;
+  /** The fee quoted, the most the payment may cost on top of `amount`. */
+  maxFee: bigint;
+  /** A withdrawal's payout in the underlying asset rather than the zERC20. */
+  unwrap: boolean;
+}
+
+export type Zerc20Instance = PluginInstance<
+  string,
+  {
+    features: { prepareShield: true; prepareTransfer: true; prepareUnshield: true };
+    assetAmounts: {
+      input: Zerc20AssetAmount;
+      internal: Zerc20AssetAmount;
+      output: Zerc20AssetAmount;
+      /** Each asset's spendable amount, then what is on its way (screening, or awaiting a root) tagged `pending`. */
+      read: Zerc20AssetAmount<'pending'>;
+    };
+    publicOp: Zerc20PublicOperation;
+    privateOp: Zerc20PrivateOperation;
+    extras: {
+      /** Brings the account up to date with the chain and the servers, and moves operations under way along. Every call
+       * that reads the account does it first. */
+      sync(): Promise<void>;
+      /** The zERC20 wallet underneath, for what Kohaku has no call for: receive codes, consolidation, rage exits,
+       * history, a view key. `close()` lets the account go, for another plugin on the same chain. */
+      wallet: Wallet;
+    };
+  }
+>;
+
+/** What a broadcast did: the operation's id in the wallet, and the transactions it sent. */
+export interface Zerc20BroadcastResult {
+  id: string;
+  txHashes: Hex[];
+}
+
+export type Zerc20Broadcaster = Broadcaster<Zerc20PrivateOperation, Zerc20BroadcastResult>;
+
+/** Opens account `accountIndex` of the host's keystore on the chain of its provider; the first time, it registers the
+ * account for payments. Its state lives in the host's storage, encrypted by the wallet, under the deployment's storage
+ * canister and verifier as well: the same keys on another deployment of the chain have a state of their own. An earlier
+ * plugin of the same account and chain, here or in another tab, stops: Kohaku has no call to close one, and the two
+ * would spend the same notes. */
+export async function createZerc20Plugin(host: Host, params: Zerc20PluginParameters): Promise<Zerc20Instance> {
+  const chainId = await host.provider.getChainId();
+  const config = params.network.chains.find((c) => c.chainId === chainId);
+  if (!config) throw new UnsupportedChainError(chainId);
+  const keystore = scopeKeystore(host.keystore, { prefixes: [ZERC20_KEYSTORE_PREFIX] });
+  // the key is the seed of every zERC20 key of the account: asked for whenever the wallet spends, and let go after
+  const seed = async () => hexToBytes(await keystore.deriveAt(`${ZERC20_KEYSTORE_PREFIX}/${params.accountIndex}'`));
+  const key = `zerc20-state:${params.network.storage.canisterId}:${chainId}:${config.verifier}:${params.accountIndex}`;
+  const request = (({ method, params }) => host.provider.request({ method, params })) as EIP1193RequestFn;
+  const wallet = await Wallet.open({
+    network: { ...params.network, chains: [config] },
+    account: privateKeyToAccount(accountKey(await seed())),
+    seed,
+    persist: {
+      load: async () => {
+        const saved = await host.storage.get(key);
+        return saved === null ? null : base64.decode(saved);
+      },
+      save: (bytes) => host.storage.set(key, base64.encode(bytes)),
+    },
+    birthday: params.birthday,
+    take: true,
+    transport: () => custom({ request }),
+    fetch: (input, init) => host.network.fetch(input, init),
+  });
+
+  const tokenOf = (asset: ERC20AssetId): { token: Token; wrapped: boolean } => {
+    for (const token of wallet.tokens()) {
+      if (isAddressEqual(token.underlying, asset.contract)) return { token, wrapped: false };
+      if (isAddressEqual(token.address, asset.contract)) return { token, wrapped: true };
+    }
+    throw new UnsupportedAssetError(asset);
+  };
+
+  /** A payment's fee now, which also checks that one JoinSplit pays it from what is spendable. */
+  const quote = async (
+    kind: 'send' | 'withdraw',
+    { asset, amount }: Zerc20AssetAmount,
+    to: string,
+  ): Promise<Zerc20PrivateOperation> => {
+    await wallet.sync();
+    const { token, wrapped } = tokenOf(asset);
+    try {
+      const { fee } = await wallet.fees({ kind, token, amount });
+      return { __type: 'privateOperation', kind, token, to, amount, maxFee: fee, unwrap: !wrapped };
+    } catch (e) {
+      // as Kohaku's other plugins report it; settling funds and fragmented notes keep the wallet's own codes
+      if (!(e instanceof WalletError) || e.code !== 'insufficient-funds') throw e;
+      throw new InsufficientBalanceError(asset, amount, (await wallet.maxAmount({ kind, token })).amount);
+    }
+  };
+
+  return {
+    wallet,
+    sync: () => wallet.sync(),
+    instanceId: async () => accountId(wallet.address),
+
+    async balance(assets) {
+      await wallet.sync();
+      const balances = wallet.balances();
+      const rows = assets
+        ? assets.map((asset) => ({ asset, token: tokenOf(asset).token }))
+        : balances.map((b) => ({ asset: { __type: 'erc20', contract: b.token.underlying } as const, token: b.token }));
+      return rows.flatMap(({ asset, token }) => {
+        const b = balances.find((b) => b.token.tokenId === token.tokenId);
+        const pending = b?.pending.reduce((sum, p) => sum + p.amount, 0n) ?? 0n;
+        return [
+          { asset, amount: b?.spendable ?? 0n },
+          { asset, amount: pending, tag: 'pending' as const },
+        ];
+      });
+    },
+
+    async prepareShield({ asset, amount }, to) {
+      await wallet.sync();
+      const { token, wrapped } = tokenOf(asset);
+      return { __type: 'publicOperation', txns: await wallet.depositTransactions({ token, amount, to, wrapped }) };
+    },
+
+    prepareTransfer: (asset, to) => quote('send', asset, to),
+
+    async prepareUnshield(asset, to, options?: UnshieldOptions) {
+      // a withdrawal pays one address and calls nothing after
+      if (options?.tailCalls) throw new PluginError('a zERC20 withdrawal takes no tail calls');
+      if (!isAddress(to)) throw new InvalidAddressError(to);
+      return quote('withdraw', asset, to);
+    },
+  };
+}
+
+/** Sends what `plugin` prepared: proves the JoinSplit here, has the relayer submit it, and returns once it is final.
+ * Interrupted, it resumes at the plugin's next sync. */
+export function createZerc20Broadcaster(plugin: Zerc20Instance): Zerc20Broadcaster {
+  return {
+    async broadcast(op) {
+      const { wallet } = plugin;
+      const { token, amount, maxFee } = op;
+      const sent =
+        op.kind === 'send'
+          ? await wallet.send({ to: op.to, token, amount, maxFee })
+          : await wallet.withdraw({ to: op.to as Address, token, amount, maxFee, unwrap: op.unwrap });
+      await sent.wait();
+      return { id: sent.id, txHashes: [...sent.txHashes] };
+    },
+  };
+}