@zerc20/wallet-sdk 0.0.0-stage → 0.2.0

package/dist/context.js

@@ -0,0 +1,40 @@
+// Everything an open wallet works with, shared by sync and the operations.
+import { publicActions } from 'viem';
+import { core } from './core.js';
+const keys = new WeakMap();
+/** The key that owns this seed's notes and deposits on every chain and token, or with `code`, the notes paid to that
+ * receive code. */
+export function spendKey(ctx, code) {
+    let bySeed = keys.get(ctx.seed);
+    if (!bySeed)
+        keys.set(ctx.seed, (bySeed = new Map()));
+    const id = code ? `${code.chainId}:${code.tokenId}:${code.index}` : '';
+    let key = bySeed.get(id);
+    if (!key) {
+        key = (code ? core.codeKey(ctx.seed, code.chainId, code.tokenId, code.index) : core.spendKey(ctx.seed));
+        bySeed.set(id, key);
+    }
+    return key;
+}
+export function chainCtx(ctx, chainId) {
+    const c = ctx.chains.find((c) => c.config.chainId === chainId);
+    if (!c)
+        throw new Error(`chain ${chainId} is not in this network`);
+    return c;
+}
+export function chainState(ctx, chainId) {
+    let s = ctx.state.chains.find((c) => c.chainId === chainId);
+    if (!s)
+        ctx.state.chains.push((s = { chainId, samples: [], burnNext: {} }));
+    return s;
+}
+/** Waits until the wallet's own node has a transaction mined on ours too: the wallet simulates the next one there, and
+ * where blocks are fast that node lags ours now and then, so the next one would show as reverting. A wallet that does
+ * not answer is not waited on. */
+export async function walletSees(wc, hash) {
+    await wc
+        .extend(publicActions)
+        .waitForTransactionReceipt({ hash, pollingInterval: 1_000, timeout: 30_000 })
+        .catch(() => { });
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAG3E,OAAO,EAA+B,aAAa,EAAE,MAAM,MAAM,CAAC;AAElE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAmCjC,MAAM,IAAI,GAAG,IAAI,OAAO,EAAqC,CAAC;AAS9D;mBACmB;AACnB,MAAM,UAAU,QAAQ,CAAC,GAAQ,EAAE,IAAa;IAC9C,IAAI,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM;QAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC,CAAC,CAAC;IACxE,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,IAAI,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAa,CAAC;QACpH,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAQ,EAAE,OAAe;IAChD,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;IAC/D,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,SAAS,OAAO,yBAAyB,CAAC,CAAC;IACnE,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAQ,EAAE,OAAe;IAClD,IAAI,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;IAC5D,IAAI,CAAC,CAAC;QAAE,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC5E,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;kCAEkC;AAClC,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,EAAgB,EAAE,IAAS;IAC1D,MAAM,EAAE;SACL,MAAM,CAAC,aAAa,CAAC;SACrB,yBAAyB,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;SAC5E,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AACrB,CAAC"}

package/dist/core.d.ts

@@ -0,0 +1,43 @@
+import { type Address, type Hex } from 'viem';
+import * as wasm from '../wasm/zerc20_wallet_core.js';
+/** Loads the wasm. A browser (or a bundler) fetches the file next to this module; Node reads it from disk. */
+export declare function initCore(): Promise<void>;
+export declare const core: typeof wasm;
+export interface Burn {
+    salt: Hex;
+    address: Address;
+}
+/** A seed's `index`-th burn address of a token, with its salt: about 2^16 hashes, up to tens of seconds on a phone.
+ * Searched off the main thread (a Web Worker in a browser, a worker thread in Node), so that the app stays
+ * responsive; `signal` stops the search. */
+export declare const burnAddress: (seed: Uint8Array, chainId: bigint, tokenId: number, index: number, signal?: AbortSignal) => Promise<Burn>;
+/** The `k`-th burn address a point of sale holding `laneKey` makes for its owner's `publicKey` on a chain and token
+ * (`keys::pos_burn`), with its salt: about 2^16 hashes too, searched the same way. */
+export declare const posBurnAddress: (laneKey: Uint8Array, chainId: bigint, tokenId: number, k: number, publicKey: Hex, signal?: AbortSignal) => Promise<Burn>;
+/** 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 declare const burnAddressFor: (chainId: bigint, publicKey: Hex, signal?: AbortSignal) => Promise<Burn>;
+export type BurnSearch = {
+    seed: Uint8Array;
+    chainId: bigint;
+    tokenId: number;
+    index: number;
+} | {
+    laneKey: Uint8Array;
+    chainId: bigint;
+    tokenId: number;
+    k: number;
+    publicKey: Hex;
+} | {
+    chainId: bigint;
+    publicKey: Hex;
+};
+/** A search, where it runs: a seed's index, or a point of sale's counter, derives its salts; someone else's key takes
+ * random ones. */
+export declare function searchHere(s: BurnSearch): Burn;
+export type BurnAnswer = {
+    burn: Burn;
+} | {
+    error: string;
+};

package/dist/core.js

@@ -0,0 +1,106 @@
+// The wallet's protocol computations (wallet/core: the Rust the circuits, the attester and the backend share,
+// compiled to wasm). `initCore` loads it once; everything else here waits for it.
+import { bytesToHex } from 'viem';
+import init, * as wasm from '../wasm/zerc20_wallet_core.js';
+let ready;
+/** Loads the wasm. A browser (or a bundler) fetches the file next to this module; Node reads it from disk. */
+export function initCore() {
+    ready ??= (async () => {
+        const url = new URL('../wasm/zerc20_wallet_core_bg.wasm', import.meta.url);
+        if (url.protocol !== 'file:')
+            return init({ module_or_path: url });
+        // a variable, so that bundlers for the browser leave Node's module alone
+        const fs = 'node:fs/promises';
+        const { readFile } = (await import(/* @vite-ignore */ fs));
+        return init({ module_or_path: await readFile(url) });
+    })();
+    return ready.then(() => undefined);
+}
+export const core = wasm;
+/** A seed's `index`-th burn address of a token, with its salt: about 2^16 hashes, up to tens of seconds on a phone.
+ * Searched off the main thread (a Web Worker in a browser, a worker thread in Node), so that the app stays
+ * responsive; `signal` stops the search. */
+export const burnAddress = (seed, chainId, tokenId, index, signal) => search({ seed, chainId, tokenId, index }, signal);
+/** The `k`-th burn address a point of sale holding `laneKey` makes for its owner's `publicKey` on a chain and token
+ * (`keys::pos_burn`), with its salt: about 2^16 hashes too, searched the same way. */
+export const posBurnAddress = (laneKey, chainId, tokenId, k, publicKey, signal) => search({ laneKey, chainId, tokenId, k, publicKey }, 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, publicKey, signal) => search({ chainId, publicKey }, signal);
+/** A search, where it runs: a seed's index, or a point of sale's counter, derives its salts; someone else's key takes
+ * random ones. */
+export function searchHere(s) {
+    if ('seed' in s)
+        return core.burnAddress(s.seed, s.chainId, s.tokenId, s.index);
+    if ('laneKey' in s)
+        return core.posBurnAddress(s.laneKey, s.chainId, s.tokenId, s.k, s.publicKey);
+    for (;;) {
+        const bytes = crypto.getRandomValues(new Uint8Array(32));
+        bytes[0] = bytes[0] & 0x1f; // below 2^253: a canonical field element
+        const salt = bytesToHex(bytes);
+        const address = core.burnAddressOf(s.chainId, s.publicKey, salt);
+        if (address)
+            return { salt, address };
+    }
+}
+/** Starts `s` in a worker, which hands `done` its answer, or null if it did not run; returns how to stop it, or null
+ * where no worker starts. */
+// ponytail: a worker per search, each compiling the wasm; a pool of availableParallelism() workers if a server makes many
+async function spawn(s, done) {
+    if (typeof Worker !== 'undefined') {
+        const worker = new Worker(new URL('./burnWorker.js', import.meta.url), { type: 'module' });
+        worker.onmessage = ({ data }) => done(data);
+        // a worker that does not start (a bundler that left it out) costs responsiveness only
+        worker.onerror = (e) => {
+            e.preventDefault();
+            done(null);
+        };
+        worker.postMessage(s);
+        return () => worker.terminate();
+    }
+    // variables, so that bundlers for the browser leave Node's module and a second copy of the worker alone
+    const [threads, file] = ['node:worker_threads', './burnWorker.js'];
+    const { Worker: Thread } = (await import(/* @vite-ignore */ threads).catch(() => ({})));
+    if (!Thread)
+        return null;
+    const thread = new Thread(new URL(file, import.meta.url), { workerData: s });
+    thread.once('message', done);
+    thread.once('error', () => done(null)); // run from source, as tests are, there is no burnWorker.js
+    return () => void thread.terminate();
+}
+async function search(s, signal) {
+    signal?.throwIfAborted();
+    await initCore();
+    return new Promise((resolve, reject) => {
+        let stop = null;
+        let settled = false;
+        const settle = (f) => {
+            if (settled)
+                return;
+            settled = true;
+            stop?.();
+            signal?.removeEventListener('abort', abort);
+            f();
+        };
+        const here = () => settle(() => {
+            try {
+                resolve(searchHere(s));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        const abort = () => settle(() => reject(signal.reason));
+        signal?.addEventListener('abort', abort, { once: true });
+        spawn(s, (a) => a === null ? here() : settle(() => ('burn' in a ? resolve(a.burn) : reject(new Error(a.error))))).then((stopIt) => {
+            if (!stopIt)
+                here();
+            else if (settled)
+                stopIt();
+            else
+                stop = stopIt;
+        }, here);
+    });
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+export type ErrorCode = 
+/** Not enough value for the amount and its fees, even counting what is still settling. */
+'insufficient-funds'
+/** No single JoinSplit pays it, but merging the spendable notes and deposits first would: `consolidate`, then pay.
+ * `fees({ kind: 'consolidate' })` tells how many rounds that takes. */
+ | 'needs-consolidation'
+/** What is spendable now does not pay it, but notes or deposits are still settling (screening, awaiting
+ * a root, or the change of an operation in flight): pay again once `balances()` shows them spendable. */
+ | 'funds-settling'
+/** The fees are above the `maxFee` the caller allowed. */
+ | 'fee-too-high'
+/** The address never registered for private payments: pay it publicly or ask for a receive code. */
+ | 'recipient-not-registered'
+/** The withdrawal's recipient (or a merge's fee recipient) fails the attester's AML screening: withdraw elsewhere. */
+ | 'recipient-refused'
+/** A contract account: it cannot sign the messages a wallet needs. */
+ | 'unsupported-account'
+/** The user declined a signature or a transaction in their wallet. */
+ | 'user-rejected'
+/** The wallet is open in another tab or window: close it there (`close()`), then open it here. */
+ | 'wallet-in-use'
+/** 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. */
+ | 'indexer-mismatch'
+/** The attester's (or the merge prover's) enclave did not prove it is the published release. */
+ | 'attester-unverified'
+/** A service did not answer, or refused. The operation can be resumed. */
+ | 'unavailable'
+/** Bad input from the caller. */
+ | 'invalid';
+export declare class WalletError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+}
+export declare const fail: (code: ErrorCode, message: string) => never;
+/** Maps a declined wallet prompt to `user-rejected`, also where viem wraps it (a transaction's, in an execution error). */
+export declare function guard<T>(p: Promise<T>): Promise<T>;

package/dist/errors.js

@@ -0,0 +1,26 @@
+// What can go wrong, by code, so that an app can tell the user what to do.
+import { BaseError, UserRejectedRequestError } from 'viem';
+export class WalletError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WalletError';
+    }
+}
+export const fail = (code, message) => {
+    throw new WalletError(code, message);
+};
+const declined = (e) => e instanceof UserRejectedRequestError || e?.code === 4001;
+/** Maps a declined wallet prompt to `user-rejected`, also where viem wraps it (a transaction's, in an execution error). */
+export async function guard(p) {
+    try {
+        return await p;
+    }
+    catch (e) {
+        if (declined(e) || (e instanceof BaseError && e.walk(declined)))
+            throw new WalletError('user-rejected', 'declined in the wallet');
+        throw e;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAE3E,OAAO,EAAE,SAAS,EAAE,wBAAwB,EAAE,MAAM,MAAM,CAAC;AAkC3D,MAAM,OAAO,WAAY,SAAQ,KAAK;IAEzB;IADX,YACW,IAAe,EACxB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,SAAI,GAAJ,IAAI,CAAW;QAIxB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,IAAe,EAAE,OAAe,EAAS,EAAE;IAC9D,MAAM,IAAI,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC,CAAC;AAEF,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAE,EAAE,CAC9B,CAAC,YAAY,wBAAwB,IAAK,CAA8B,EAAE,IAAI,KAAK,IAAI,CAAC;AAE1F,2HAA2H;AAC3H,MAAM,CAAC,KAAK,UAAU,KAAK,CAAI,CAAa;IAC1C,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,CAAC;IACjB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,SAAS,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC7D,MAAM,IAAI,WAAW,CAAC,eAAe,EAAE,wBAAwB,CAAC,CAAC;QACnE,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Chain, type Referrer, type Token, MAX_REFERRAL_BPS, NATIVE, UNWRAP_INTENT } from './chain.js';
+export { type ErrorCode, WalletError } from './errors.js';
+export { type AttesterTrust, type ChainConfig, type Circuit, type Network, NITRO_ROOT_SHA256, checkNetwork, networkFromJson, } from './network.js';
+export { type Payment, PointOfSale, type PosToken, type Sale, type SaleStatus } from './pos.js';
+export { seedFromSignature } from './seed.js';
+export { type Activity, type Balance, type CoinInfo, type CoinState, type DepositInfo, type DepositStep, type FeeQuote, type OpenOptions, type Operation, type OperationKind, type OperationStatus, type PendingReason, Wallet, } from './wallet.js';

package/dist/index.js

@@ -0,0 +1,19 @@
+// @zerc20/wallet-sdk: a zERC20 wallet for browsers and Node.
+//
+//   const wallet = await Wallet.open({ network, walletClient, seed, persist });
+//   await wallet.sync();                     // or wallet.autoSync(render)
+//   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();
+//
+// 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, MAX_REFERRAL_BPS, NATIVE, UNWRAP_INTENT } from './chain.js';
+export { WalletError } from './errors.js';
+export { NITRO_ROOT_SHA256, checkNetwork, networkFromJson, } from './network.js';
+export { PointOfSale } from './pos.js';
+export { seedFromSignature } from './seed.js';
+export { Wallet, } from './wallet.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,gFAAgF;AAChF,2EAA2E;AAC3E,uFAAuF;AACvF,4DAA4D;AAC5D,kEAAkE;AAClE,mFAAmF;AACnF,EAAE;AACF,uHAAuH;AACvH,qHAAqH;AACrH,8CAA8C;AAE9C,OAAO,EAAE,KAAK,EAA6B,gBAAgB,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACvG,OAAO,EAAkB,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAKL,iBAAiB,EACjB,YAAY,EACZ,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAgB,WAAW,EAA6C,MAAM,UAAU,CAAC;AAChG,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAaL,MAAM,GACP,MAAM,aAAa,CAAC"}

package/dist/network.d.ts

@@ -0,0 +1,66 @@
+import type { Address } from 'viem';
+/** A proving key set: the circuit's wasm and zkey, pinned by SHA-256 (from the setup's `setup.json`). */
+export interface Circuit {
+    wasm: string;
+    zkey: string;
+    wasmSha256: string;
+    zkeySha256: string;
+}
+/** How to trust an enclave's key: the attester's, or the merge prover's. */
+export type AttesterTrust = 
+/** A Nitro Enclave: the document must chain to the root with this SHA-256 and measure this PCR0 (hex). */
+{
+    pcr0: string;
+    rootSha256: string;
+}
+/** A development attester, which has no document: its key is taken at its word. Never on a real network. */
+ | {
+    development: true;
+};
+/** The AWS Nitro Enclaves root certificate (G1), SHA-256 over its DER. */
+export declare const NITRO_ROOT_SHA256 = "641a0321a3e244efe456463195d606317ed7cdcc3c1756e09893f3c68f79bb5b";
+export interface ChainConfig {
+    chainId: bigint;
+    /** Used for every read and for waiting on receipts, never the wallet's own RPC. */
+    rpcUrl: string;
+    verifier: Address;
+    depositAddressFactory: Address;
+    indexer: string;
+    asp: string;
+    attester: string;
+    attesterTrust: AttesterTrust;
+    transactRelayer: string;
+    depositRelayer: string;
+    /** The native currency, which its native zERC20 is named after; ETH if absent. For a chain an app does not know. */
+    nativeCurrency?: {
+        name: string;
+        symbol: string;
+    };
+}
+export interface Network {
+    name: string;
+    chains: ChainConfig[];
+    /** The note storage canister on the Internet Computer. */
+    storage: {
+        host: string;
+        canisterId: string;
+    };
+    circuits: {
+        joinsplit: Circuit;
+        rageexit: Circuit;
+    };
+    /** The merge prover (`backend/merge-prover`), one shared by every chain, and how to trust its enclave, which sees each
+     * merge's witness while it proves it. Without it the wallet cannot consolidate. */
+    mergeProver?: {
+        url: string;
+        trust: AttesterTrust;
+    };
+}
+/** A `Network` from JSON, where chain ids are strings (JSON has no bigints), as scripts/dev-stack.sh writes it. */
+export declare function networkFromJson(json: string): Network;
+/** The local chain development settings are for. */
+export declare const LOCAL_CHAIN_ID = 31337n;
+/** Throws on settings that only a local development network may have: servers over plain HTTP (anyone on the path
+ * could swap a deposit address or a fee), a development attester or merge prover (its host would read every witness,
+ * the openings of what it spends included), or a Nitro trust that does not pin the AWS root and a real enclave. */
+export declare function checkNetwork(n: Network): void;

package/dist/network.js

@@ -0,0 +1,55 @@
+// Where a wallet finds everything: per chain, its contracts, servers and artifacts. Apps pass one of these to
+// `Wallet.open`; nothing here is secret.
+import { fail } from './errors.js';
+/** The AWS Nitro Enclaves root certificate (G1), SHA-256 over its DER. */
+export const NITRO_ROOT_SHA256 = '641a0321a3e244efe456463195d606317ed7cdcc3c1756e09893f3c68f79bb5b';
+/** A `Network` from JSON, where chain ids are strings (JSON has no bigints), as scripts/dev-stack.sh writes it. */
+export function networkFromJson(json) {
+    const n = JSON.parse(json);
+    return { ...n, chains: n.chains.map((c) => ({ ...c, chainId: BigInt(c.chainId) })) };
+}
+/** The local chain development settings are for. */
+export const LOCAL_CHAIN_ID = 31337n;
+const local = (url) => ['localhost', '127.0.0.1', '[::1]'].includes(new URL(url).hostname);
+/** Throws on settings that only a local development network may have: servers over plain HTTP (anyone on the path
+ * could swap a deposit address or a fee), a development attester or merge prover (its host would read every witness,
+ * the openings of what it spends included), or a Nitro trust that does not pin the AWS root and a real enclave. */
+export function checkNetwork(n) {
+    const bad = (what) => fail('invalid', `network ${n.name}: ${what}`);
+    const servers = (urls) => {
+        for (const u of urls)
+            if (new URL(u).protocol !== 'https:' && !local(u))
+                bad(`${u} is not https`);
+    };
+    servers([n.storage.host]);
+    // artifacts are pinned by SHA-256, and Node reads them from disk
+    for (const c of [n.circuits.joinsplit, n.circuits.rageexit]) {
+        for (const u of [c.wasm, c.zkey])
+            if (!u.startsWith('file:'))
+                servers([u]);
+    }
+    const trusted = (chains, what, t) => {
+        if ('development' in t) {
+            for (const c of chains)
+                if (c.chainId !== LOCAL_CHAIN_ID)
+                    bad(`a development ${what} on chain ${c.chainId}`);
+        }
+        else {
+            if (t.rootSha256.toLowerCase() !== NITRO_ROOT_SHA256)
+                bad(`the ${what} trust does not pin the AWS Nitro root`);
+            // a debug enclave measures all zeros
+            const pcr0 = t.pcr0.replace(/^0x/i, '');
+            if (!/^[0-9a-f]{96}$/i.test(pcr0) || /^0+$/.test(pcr0))
+                bad(`PCR0 ${t.pcr0} is not a release enclave's`);
+        }
+    };
+    for (const c of n.chains) {
+        servers([c.rpcUrl, c.indexer, c.asp, c.attester, c.transactRelayer, c.depositRelayer]);
+        trusted([c], 'attester', c.attesterTrust);
+    }
+    if (n.mergeProver) {
+        servers([n.mergeProver.url]);
+        trusted(n.chains, 'merge prover', n.mergeProver.trust);
+    }
+}
+//# sourceMappingURL=network.js.map

package/dist/network.js.map

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

package/dist/pos.d.ts

@@ -0,0 +1,93 @@
+import { type Address, type Hex } from 'viem';
+import { type Token } from './chain.js';
+import { type Network } from './network.js';
+/** 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'>;
+export interface Sale {
+    /** Its burn address, which no other sale has. */
+    id: Address;
+    chainId: bigint;
+    tokenId: number;
+    token: Address;
+    /** Paid in the token by a transfer here. */
+    burnAddress: Address;
+    /** Paid in the underlying asset here, which the deposit relayer then wraps into the burn address: once one is
+     * registered (`registerDeposit`). */
+    depositAddress: Address | null;
+    /** What the deposit relayer takes out of each payment to `depositAddress`: ask for `amount` plus it. */
+    depositFee: bigint | null;
+    /** Where `depositAddress` sends back what it cannot wrap, and what a rage exit returns: the payer's, or the
+     * merchant's. On chain for anyone to read once the address is first flushed. */
+    refundTo: Address | null;
+    /** What was asked, if anything: the point of sale's alone, never sent anywhere. */
+    amount: bigint | null;
+    createdMs: number;
+}
+export interface Payment {
+    amount: bigint;
+    /** Who paid the burn address: the payer, or for a payment through `depositAddress` the deposit address itself. */
+    sender: Address;
+    /** `confirming` until final (a reorg may still drop it), then `screening` until the ASP decides. `rejected` goes back
+     * to its sender by the merchant's rage exit, or to `refundTo` from a deposit address. */
+    state: 'confirming' | 'screening' | 'approved' | 'rejected';
+    /** The transaction that paid the burn address, once the chain shows it: the payer's, or for a payment through
+     * `depositAddress` the deposit relayer's. */
+    txHash: Hex | null;
+}
+export interface SaleStatus {
+    sale: Sale;
+    payments: Payment[];
+    /** What is final: every payment but the confirming ones. */
+    received: bigint;
+}
+export declare class PointOfSale {
+    #private;
+    private constructor();
+    /** 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. */
+    static open(opts: {
+        network: Network;
+        persist: {
+            load(): Promise<Uint8Array | null | undefined>;
+            save(bytes: Uint8Array): Promise<void>;
+        };
+        refillWithinMs?: number;
+    }): Promise<PointOfSale>;
+    get connected(): boolean;
+    /** Takes the key `merchant`'s wallet made for it (`Wallet.posKey`), and the public key `merchant` registered in
+     * storage, which every address it makes is under: whoever hands it a key cannot point sales at a key of its own. The
+     * same key again changes nothing. Another one starts over in that lane; the sales made so far are still followed. */
+    connect(merchant: Address, laneKey: Hex): Promise<void>;
+    /** 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;
+    /** How many addresses of `token` are recorded and wait for a sale. */
+    ready(token: PosToken): number;
+    /** A new sale of `token`, at an address no sale has had: one recorded ahead, or, when none is left, one recorded
+     * now. With `via: 'deposit'` it also registers a deposit address in front of it (`registerDeposit`). */
+    next(opts: {
+        via: 'burn' | 'deposit';
+        token: PosToken;
+        amount?: bigint;
+        refundTo?: Address;
+    }): Promise<Sale>;
+    /** Registers a deposit address in front of sale `id`, for the underlying asset; the deposit relayer watches it for 7
+     * days. What it cannot wrap (too little, another token) and a rage exit go back to `refundTo`, the merchant's
+     * account if absent: name the payer's, so that neither the merchant's account is on chain nor a payment the ASP
+     * rejects comes back to the merchant. A sale has one: asked again with the same `refundTo`, it is the same. */
+    registerDeposit(id: Address, opts?: {
+        refundTo?: Address;
+    }): Promise<Sale>;
+    sales(): Sale[];
+    /** 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. */
+    refresh(ids: Address[]): Promise<{
+        sales: SaleStatus[];
+        errors: unknown[];
+    }>;
+    /** What reached sale `id`, and how much is final. */
+    status(id: Address): Promise<SaleStatus>;
+    /** What reached sale `id` as of the last `refresh`, asking no server. */
+    lastStatus(id: Address): SaleStatus;
+}