@orangecheck/chat-core 0.1.0 → 0.2.0

package/src/channel.ts

@@ -69,7 +69,8 @@ export type ChannelError =
 export type IsBound = (pubkey: string, principal: string) => Promise<boolean>;
 
 /** Does this utxo-floor write proof match current chain state: an unspent output
- *  of `address` with exactly the proof's value, height and block hash (§8.3.3)? */
+ *  of `address` with exactly the proof's value, height and block hash (§8.3.3)?
+ *  A reader that could not tell throws UnansweredReadError, not false. */
 export type VerifyOnChain = (proof: WriteProof, address: string) => Promise<boolean>;
 
 export type WritePolicy = 'utxo-floor' | 'allowlist' | 'founder' | 'open';
@@ -425,8 +426,10 @@ export async function verifyDescriptor(
 }
 
 export interface VerifyPostOpts {
-    /** Reader's current tip height (one read per render batch). */
-    tipHeight: number;
+    /** Reader's current tip height (one read per render batch), or 'unanswered'
+     *  when it could not be read: a utxo-floor post that needs it then throws
+     *  UnansweredReadError rather than being refused. */
+    tipHeight: number | 'unanswered';
     /** BIP-322 by author_address over post_id — REQUIRED for utxo-floor. */
     controlSig?: string;
     /** The full writer-address list for an allowlist channel (membership proof). */
@@ -441,7 +444,8 @@ export interface VerifyPostOpts {
     /** A non-empty recipients[] on a chat-channel envelope is E_CHANNEL_RECIPIENTS. */
     recipients?: unknown[];
     /** utxo-floor: binds the write_proof to real chain state (io.ts has one
-     *  over an esplora API). Fail-closed: false drops the post. */
+     *  over an esplora API). Fail-closed: false drops the post; a read that got
+     *  no answer throws UnansweredReadError. */
     verifyOnChain: VerifyOnChain;
 }
 
@@ -556,6 +560,10 @@ async function checkWritePermission(
             if (!content.write_proof) return 'E_CHAN_FLOOR';
             if (!opts.controlSig) return 'E_CHAN_FLOOR';
             if (!isBitcoinAddress(content.author_address)) return 'E_CHAN_FLOOR';
+            // With no tip read, the age cannot be told: not a refusal (§8.3.3).
+            if (opts.tipHeight === 'unanswered') {
+                throw new UnansweredReadError('the chain tip could not be read');
+            }
             // Cheap offline gates first (no network): the floor arithmetic + the
             // control_sig (author controls the address, over post_id).
             const v = evaluateWriteProof(content.write_proof, w, opts.tipHeight);
@@ -979,9 +987,13 @@ export async function readChannelVersions(
         });
         const fresh = add(res);
         for (const e of res.events ?? []) until = Math.min(until ?? Infinity, e.created_at);
-        // A full page that brought something new may have more behind it.
-        if ((res.events ?? []).length < VERSION_PAGE_LIMIT || fresh === 0) break;
-        if (page === VERSION_MAX_PAGES - 1) truncated = true;
+        // A full page may have more behind it. One that brought nothing new is
+        // stuck on a second it cannot page past: the read stops there, cut off.
+        if ((res.events ?? []).length < VERSION_PAGE_LIMIT) break;
+        if (fresh === 0 || page === VERSION_MAX_PAGES - 1) {
+            truncated = true;
+            break;
+        }
     }
     add(await legacy);
 
@@ -1094,6 +1106,18 @@ export interface ChannelPost {
     event: NostrEvent;
 }
 
+export interface ChannelPosts {
+    /** The posts that verify, removals applied, in feed order. */
+    posts: ChannelPost[];
+    /** Posts that could not be checked (a binding, coin or tip read with no
+     *  answer): never shown, and counted so a reader can say so and try again
+     *  (§8.3.3). A post shown from another copy is not counted. */
+    unchecked: number;
+    /** False when a removal could not be checked, so a post it names may be
+     *  on show. */
+    removalsChecked: boolean;
+}
+
 /**
  * Deterministic public-feed order (§8.3.2). A public multi-author channel has no
  * single hash-chain (independent broadcasters), so order is the event-level
@@ -1114,24 +1138,36 @@ export function orderChannelPosts(posts: ChannelPost[]): ChannelPost[] {
  * each one authored by a bound key and through the write gate, removal
  * tombstones applied (forward-effective, §8.3.5), copies of one post_id kept
  * once at their lowest created_at, in feed order. A post that fails MUST NOT
- * render, so it is left out.
+ * render, so it is left out. A post whose binding, coin or tip read got no
+ * answer (UnansweredReadError) is not shown either, and is counted unchecked
+ * rather than refused; the rest of the feed still verifies.
  */
 export async function verifyChannelPosts(
     events: readonly NostrEvent[],
     descriptor: DescriptorContent,
     opts: Pick<VerifyPostOpts, 'tipHeight' | 'verifyBip322' | 'verifyOnChain'> & { isBound: IsBound }
-): Promise<ChannelPost[]> {
+): Promise<ChannelPosts> {
     const removed = new Set<string>();
     const byPostId = new Map<string, ChannelPost>();
+    const unchecked = new Set<string>();
+    let removalsUnread = false;
     for (const ev of events) {
         const content = parsePost(ev);
         if (!content || content.channel_id !== descriptor.channel_id) continue;
         const controlSig = ev.tags.find((t) => t[0] === 'control_sig')?.[1];
-        const v = await verifyPost(content, descriptor, {
-            ...opts,
-            event: ev,
-            ...(controlSig ? { controlSig } : {}),
-        });
+        let v: PostVerify;
+        try {
+            v = await verifyPost(content, descriptor, {
+                ...opts,
+                event: ev,
+                ...(controlSig ? { controlSig } : {}),
+            });
+        } catch (e) {
+            if (!(e instanceof UnansweredReadError)) throw e;
+            unchecked.add(postId(content));
+            if (typeof content.removes === 'string') removalsUnread = true;
+            continue;
+        }
         if (!v.ok) continue;
         if (v.isTombstone && content.removes) {
             removed.add(content.removes);
@@ -1142,5 +1178,9 @@ export async function verifyChannelPosts(
             byPostId.set(v.postId, { post: content, postId: v.postId, event: ev });
         }
     }
-    return orderChannelPosts([...byPostId.values()].filter((a) => !removed.has(a.postId)));
+    return {
+        posts: orderChannelPosts([...byPostId.values()].filter((a) => !removed.has(a.postId))),
+        unchecked: [...unchecked].filter((id) => !byPostId.has(id)).length,
+        removalsChecked: !removalsUnread,
+    };
 }

package/src/io.test.ts

@@ -1,9 +1,11 @@
-// The on-chain leg of the utxo-floor gate (SPEC §8.3.3), over a stubbed Esplora.
+// The on-chain leg of the utxo-floor gate (SPEC §8.3.3 (1)), over a stubbed
+// Esplora: the coin a proof names is read on its own, its transaction and then
+// its outspend, so a wallet of any size can be checked.
 
 import { describe, expect, it } from 'vitest';
 
 import type { WriteProof } from './channel';
-import { esploraWriteProofCheck, verifyWriteProofOnChain } from './io';
+import { esploraWriteProofCheck, readOutpoint, verifyWriteProofOnChain, writeProofOnChain } from './io';
 import { UnansweredReadError } from './read';
 
 const AUTHOR = 'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4';
@@ -13,76 +15,120 @@ const PROOF: WriteProof = {
     anchor_block_height: 800000,
     anchor_block_hash: '00000000000000000002a7c4c1e48d76c5a37902165a270156b7a8d72728a054',
 };
-const [TXID, VOUT] = PROOF.outpoint.split(':') as [string, string];
-/** The author's UTXO set as Esplora returns it. */
-const coin = {
-    txid: TXID,
-    vout: Number(VOUT),
-    value: PROOF.value_sats,
-    status: { confirmed: true, block_height: PROOF.anchor_block_height, block_hash: PROOF.anchor_block_hash },
-};
-const serving = (utxos: unknown, seen?: string[]) =>
-    (async (url: string) => {
-        seen?.push(url);
-        return { ok: true, json: async () => utxos } as unknown as Response;
-    }) as unknown as typeof fetch;
+const [TXID] = PROOF.outpoint.split(':') as [string, string];
 
-describe('verifyWriteProofOnChain', () => {
-    it('accepts a proof matching an unspent output of the address, exact in value, height and hash', async () => {
-        expect(await verifyWriteProofOnChain(PROOF, AUTHOR, { fetch: serving([coin]) })).toBe(true);
-    });
+/** The coin as Esplora holds it, and how each of its two reads answers. */
+interface Coin {
+    address?: string;
+    value?: number;
+    confirmed?: boolean;
+    height?: number;
+    hash?: string;
+    spent?: boolean;
+    /** No output at vout 0. */
+    noVout?: boolean;
+    txStatus?: number;
+    spendStatus?: number;
+}
 
-    it('refuses a value the coin does not carry', async () => {
-        const forged = { ...PROOF, value_sats: PROOF.value_sats + 1 };
-        expect(await verifyWriteProofOnChain(forged, AUTHOR, { fetch: serving([coin]) })).toBe(false);
+function explorer(coin: Coin = {}) {
+    const calls: string[] = [];
+    const f = async (url: string | URL) => {
+        const u = String(url);
+        calls.push(u.replace(/^.*\/api/, ''));
+        // A large wallet: Esplora will not list the address's set at all.
+        if (u.includes('/address/')) return new Response('Too many unspent transaction outputs (>500).', { status: 400 });
+        if (u.endsWith('/outspend/0')) {
+            if (coin.spendStatus) return new Response('', { status: coin.spendStatus });
+            return Response.json({ spent: coin.spent ?? false });
+        }
+        if (coin.txStatus) return new Response('', { status: coin.txStatus });
+        return Response.json({
+            vout: coin.noVout ? [] : [{ scriptpubkey_address: coin.address ?? AUTHOR, value: coin.value ?? PROOF.value_sats }],
+            status: {
+                confirmed: coin.confirmed ?? true,
+                block_height: coin.height ?? PROOF.anchor_block_height,
+                block_hash: coin.hash ?? PROOF.anchor_block_hash,
+            },
+        });
+    };
+    return { f: f as unknown as typeof fetch, calls };
+}
+
+describe('writeProofOnChain reads the one coin a proof names', () => {
+    it('verifies it for a wallet too big for the explorer to list, with the transaction and its outspend only', async () => {
+        const { f, calls } = explorer();
+        expect(await writeProofOnChain(PROOF, AUTHOR, { fetch: f })).toBe(true);
+        expect(calls).toEqual([`/tx/${TXID}`, `/tx/${TXID}/outspend/0`]);
     });
 
-    it('refuses an outpoint not in the address UTXO set (not owned, or spent)', async () => {
-        expect(await verifyWriteProofOnChain(PROOF, AUTHOR, { fetch: serving([]) })).toBe(false);
+    it('compares the address in normal form: a bech32 author in capitals is the same address', async () => {
+        expect(await writeProofOnChain(PROOF, AUTHOR.toUpperCase(), { fetch: explorer().f })).toBe(true);
+        expect(await writeProofOnChain(PROOF, AUTHOR, { fetch: explorer({ address: AUTHOR.toUpperCase() }).f })).toBe(true);
     });
 
-    it('refuses another anchor height or block hash', async () => {
-        const f = serving([coin]);
-        expect(await verifyWriteProofOnChain({ ...PROOF, anchor_block_height: 799995 }, AUTHOR, { fetch: f })).toBe(false);
-        expect(await verifyWriteProofOnChain({ ...PROOF, anchor_block_hash: '0'.repeat(64) }, AUTHOR, { fetch: f })).toBe(false);
+    it.each<[string, Coin, Partial<WriteProof>?]>([
+        ['a spent coin (a mempool spend included)', { spent: true }],
+        ['another address', { address: 'bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq' }],
+        ['another value', { value: PROOF.value_sats + 1 }],
+        ['an unconfirmed coin', { confirmed: false }],
+        ['another anchor height', {}, { anchor_block_height: 799995 }],
+        ['another block hash', {}, { anchor_block_hash: '0'.repeat(64) }],
+        ['no such transaction (404)', { txStatus: 404 }],
+        ['no such output to spend (404 on the outspend)', { spendStatus: 404 }],
+        ['a vout the transaction does not have', { noVout: true }],
+    ])('refuses %s', async (_name, coin, proof = {}) => {
+        expect(await writeProofOnChain({ ...PROOF, ...proof }, AUTHOR, { fetch: explorer(coin).f })).toBe(false);
     });
 
-    it('refuses an unconfirmed coin', async () => {
-        const pending = { ...coin, status: { ...coin.status, confirmed: false } };
-        expect(await verifyWriteProofOnChain(PROOF, AUTHOR, { fetch: serving([pending]) })).toBe(false);
+    it.each<[string, Coin]>([
+        ['a 429 on the transaction', { txStatus: 429 }],
+        ['a 503 on the outspend', { spendStatus: 503 }],
+    ])('answers no-answer for %s, and does not keep it', async (_name, coin) => {
+        const cache = new Map();
+        expect(await writeProofOnChain(PROOF, AUTHOR, { fetch: explorer(coin).f, cache })).toBe('no-answer');
+        await Promise.resolve();
+        expect(cache.size).toBe(0);
+        // The next read gets an answer: nothing unanswered was kept.
+        expect(await writeProofOnChain(PROOF, AUTHOR, { fetch: explorer().f, cache })).toBe(true);
     });
 
-    it('is false when the explorer does not answer', async () => {
-        const down = (async () => ({ ok: false }) as unknown as Response) as unknown as typeof fetch;
+    it('a thrown fetch or a body that does not parse is unanswered', async () => {
         const throws = (async () => {
             throw new Error('offline');
         }) as unknown as typeof fetch;
-        expect(await verifyWriteProofOnChain(PROOF, AUTHOR, { fetch: down })).toBe(false);
-        expect(await verifyWriteProofOnChain(PROOF, AUTHOR, { fetch: throws })).toBe(false);
+        const garbled = (async () => new Response('<html>busy</html>')) as unknown as typeof fetch;
+        expect(await readOutpoint(PROOF.outpoint, { fetch: throws })).toBe('unanswered');
+        expect(await readOutpoint(PROOF.outpoint, { fetch: garbled })).toBe('unanswered');
     });
 
-    it('reads each address once per batch', async () => {
-        const seen: string[] = [];
-        const check = esploraWriteProofCheck({ baseUrl: 'https://esplora.test/api/', fetch: serving([coin], seen) });
-        expect(await check(PROOF, AUTHOR)).toBe(true);
-        expect(await check({ ...PROOF, value_sats: 1 }, AUTHOR)).toBe(false);
-        expect(seen).toEqual([`https://esplora.test/api/address/${AUTHOR}/utxo`]);
+    it('verifyWriteProofOnChain is fail-closed: false when the explorer does not answer', async () => {
+        expect(await verifyWriteProofOnChain(PROOF, AUTHOR, { fetch: explorer({ txStatus: 503 }).f })).toBe(false);
+        expect(await verifyWriteProofOnChain(PROOF, AUTHOR, { fetch: explorer().f })).toBe(true);
     });
 });
 
-describe('esploraWriteProofCheck on a read that gets no answer', () => {
-    const down = (async () => {
-        throw new Error('offline');
-    }) as unknown as typeof fetch;
-
-    it('is false by default, so a feed hides the post', async () => {
-        expect(await esploraWriteProofCheck({ fetch: down })(PROOF, AUTHOR)).toBe(false);
+describe('esploraWriteProofCheck', () => {
+    it('reads each coin once per batch, at the base it is given', async () => {
+        const seen: string[] = [];
+        const f = (async (url: string) => {
+            seen.push(url);
+            return explorer().f(url);
+        }) as unknown as typeof fetch;
+        const check = esploraWriteProofCheck({ baseUrl: 'https://esplora.test/api/', fetch: f });
+        expect(await check(PROOF, AUTHOR)).toBe(true);
+        expect(await check({ ...PROOF, value_sats: 1 }, AUTHOR)).toBe(false);
+        expect(seen).toEqual([`https://esplora.test/api/tx/${TXID}`, `https://esplora.test/api/tx/${TXID}/outspend/0`]);
     });
 
-    it('throws UnansweredReadError when asked to, and still answers false for a coin that does not match', async () => {
-        await expect(esploraWriteProofCheck({ fetch: down, unanswered: 'throw' })(PROOF, AUTHOR)).rejects.toBeInstanceOf(
+    it('throws UnansweredReadError on a read that gets no answer, so a verifier never reads silence as "no"', async () => {
+        await expect(esploraWriteProofCheck({ fetch: explorer({ txStatus: 429 }).f })(PROOF, AUTHOR)).rejects.toBeInstanceOf(
             UnansweredReadError
         );
-        expect(await esploraWriteProofCheck({ fetch: serving([]), unanswered: 'throw' })(PROOF, AUTHOR)).toBe(false);
+        expect(await esploraWriteProofCheck({ fetch: explorer({ spent: true }).f })(PROOF, AUTHOR)).toBe(false);
+    });
+
+    it("is false instead with unanswered: 'false', for a caller that only needs fail-closed", async () => {
+        expect(await esploraWriteProofCheck({ fetch: explorer({ txStatus: 429 }).f, unanswered: 'false' })(PROOF, AUTHOR)).toBe(false);
     });
 });

package/src/io.ts

@@ -1,76 +1,119 @@
 // Readers over a public Esplora API (mempool.space by default) for the checks
 // chat-core leaves to its caller. Public chain data only.
 
+import { normalizeAddress } from '@orangecheck/bip322';
+
 import type { VerifyOnChain, WriteProof } from './channel';
 import { UnansweredReadError } from './read';
 
-/** One output from Esplora's /address/<addr>/utxo. */
-export interface MempoolUtxo {
-    txid: string;
-    vout: number;
-    value?: number;
-    status?: { confirmed?: boolean; block_height?: number; block_hash?: string };
+/** The coin a write proof names, as the explorer holds it. */
+export interface OutpointRead {
+    /** The output's scriptpubkey_address; null for a script with none. */
+    address: string | null;
+    value: number | null;
+    confirmed: boolean;
+    height: number | null;
+    hash: string | null;
+    /** Spent, a spend still in the mempool included. */
+    spent: boolean;
 }
 
-/** One address→UTXO-set read per distinct author for a batch of posts. */
-export type WriteProofUtxoCache = Map<string, Promise<MempoolUtxo[] | null>>;
+/**
+ * One read per outpoint for a batch of posts: two posts naming one coin read it
+ * once. A read that got no answer is not kept, so the next asks again.
+ */
+export type WriteProofCache = Map<string, Promise<OutpointRead | 'missing' | 'unanswered'>>;
 
 export interface EsploraOptions {
     /** Esplora API base; default https://mempool.space/api. */
     baseUrl?: string;
     fetch?: typeof fetch;
     /** Share one cache across the posts of a feed. */
-    utxoCache?: WriteProofUtxoCache;
+    cache?: WriteProofCache;
 }
 
-async function addressUtxos(
-    address: string,
-    base: string,
-    f: typeof fetch,
-    cache?: WriteProofUtxoCache
-): Promise<MempoolUtxo[] | null> {
-    const hit = cache?.get(address);
+/**
+ * The one coin a write proof names (§8.3.3 (1)): GET /tx/<txid> for the output
+ * at vout, then GET /tx/<txid>/outspend/<vout>. A 404 from either, or a vout the
+ * transaction does not have, is 'missing'. A 429, a 5xx, a timeout or a body
+ * that does not parse is 'unanswered'. Reading the coin rather than the
+ * address's whole UTXO set holds for any wallet: Esplora refuses to list an
+ * address past a few hundred UTXOs, and anyone can send an author dust.
+ */
+export async function readOutpoint(
+    outpoint: string,
+    opts: EsploraOptions = {}
+): Promise<OutpointRead | 'missing' | 'unanswered'> {
+    const hit = opts.cache?.get(outpoint);
     if (hit) return hit;
-    const p = (async () => {
+    const base = (opts.baseUrl ?? 'https://mempool.space/api').replace(/\/+$/, '');
+    const f = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const p = (async (): Promise<OutpointRead | 'missing' | 'unanswered'> => {
+        const sep = outpoint.lastIndexOf(':');
+        const txid = outpoint.slice(0, sep);
+        const vout = Number(outpoint.slice(sep + 1));
+        if (sep <= 0 || !/^[0-9a-f]{64}$/i.test(txid) || !Number.isInteger(vout) || vout < 0) {
+            return 'missing';
+        }
         try {
-            const res = await f(`${base}/address/${encodeURIComponent(address)}/utxo`);
-            if (!res.ok) return null;
-            return (await res.json()) as MempoolUtxo[];
+            const txRes = await f(`${base}/tx/${txid}`);
+            if (txRes.status === 404) return 'missing';
+            if (!txRes.ok) return 'unanswered';
+            const tx = (await txRes.json()) as {
+                vout?: { scriptpubkey_address?: string; value?: number }[];
+                status?: { confirmed?: boolean; block_height?: number; block_hash?: string };
+            };
+            const out = tx.vout?.[vout];
+            if (!out) return 'missing';
+            const spendRes = await f(`${base}/tx/${txid}/outspend/${vout}`);
+            if (spendRes.status === 404) return 'missing';
+            if (!spendRes.ok) return 'unanswered';
+            const spend = (await spendRes.json()) as { spent?: unknown };
+            if (typeof spend.spent !== 'boolean') return 'unanswered';
+            return {
+                address: out.scriptpubkey_address ?? null,
+                value: typeof out.value === 'number' ? out.value : null,
+                confirmed: tx.status?.confirmed === true,
+                height: tx.status?.block_height ?? null,
+                hash: tx.status?.block_hash ?? null,
+                spent: spend.spent,
+            };
         } catch {
-            return null;
+            return 'unanswered';
         }
     })();
-    cache?.set(address, p);
+    opts.cache?.set(outpoint, p);
+    void p.then((r) => {
+        if (r === 'unanswered' && opts.cache?.get(outpoint) === p) opts.cache.delete(outpoint);
+    });
     return p;
 }
 
 /**
- * Does a utxo-floor write proof match current chain state (§8.3.3), the
- * Bitcoin-load-bearing leg: the proof's outpoint is an unspent output of the
- * author's address with exactly the value, confirmation height and block hash
- * the proof states? 'no-answer' when the address's outputs could not be read.
+ * Does a utxo-floor write proof match current chain state (§8.3.3 (1)), the
+ * Bitcoin-load-bearing leg: the proof's outpoint pays the author's address
+ * (both in normal form, so a bech32 address in capitals is the same address)
+ * exactly the value, confirmed at the height and block hash the proof states,
+ * and is unspent (a spend still in the mempool counts as spent)? 'no-answer'
+ * when the explorer did not answer; false when the coin is missing or differs.
  */
 export async function writeProofOnChain(
     proof: WriteProof,
     authorAddress: string,
     opts: EsploraOptions = {}
 ): Promise<boolean | 'no-answer'> {
-    const base = (opts.baseUrl ?? 'https://mempool.space/api').replace(/\/+$/, '');
-    const f = opts.fetch ?? globalThis.fetch.bind(globalThis);
-    const utxos = await addressUtxos(authorAddress, base, f, opts.utxoCache);
-    if (!utxos) return 'no-answer';
-    const sep = proof.outpoint.lastIndexOf(':');
-    if (sep <= 0) return false;
-    const txid = proof.outpoint.slice(0, sep);
-    const vout = Number.parseInt(proof.outpoint.slice(sep + 1), 10);
-    return utxos.some(
-        (u) =>
-            u.txid === txid &&
-            u.vout === vout &&
-            u.status?.confirmed === true &&
-            u.value === proof.value_sats &&
-            u.status?.block_height === proof.anchor_block_height &&
-            u.status?.block_hash === proof.anchor_block_hash
+    const coin = await readOutpoint(proof.outpoint, opts);
+    if (coin === 'unanswered') return 'no-answer';
+    if (coin === 'missing') return false;
+    const owner = coin.address === null ? null : normalizeAddress(coin.address);
+    return (
+        owner !== null &&
+        owner === normalizeAddress(authorAddress) &&
+        coin.value === proof.value_sats &&
+        coin.confirmed &&
+        coin.height === proof.anchor_block_height &&
+        coin.hash === proof.anchor_block_hash &&
+        !coin.spent
     );
 }
 
@@ -84,19 +127,21 @@ export async function verifyWriteProofOnChain(
 }
 
 /**
- * A VerifyOnChain over Esplora, with one cache for the batch it is made for. An
- * unanswered read is false (a feed hides the post), or with `unanswered: 'throw'`
- * an UnansweredReadError, for a verifier that must say it could not tell.
+ * A VerifyOnChain over Esplora, with one cache for the batch it is made for. A
+ * read that gets no answer throws UnansweredReadError, so a verifier says it
+ * could not tell rather than read the silence as "no" (verifyChannelPosts
+ * counts the post unchecked). `unanswered: 'false'` makes it false instead, for
+ * a caller that only needs fail-closed.
  */
 export function esploraWriteProofCheck(
-    opts: EsploraOptions & { unanswered?: 'false' | 'throw' } = {}
+    opts: EsploraOptions & { unanswered?: 'throw' | 'false' } = {}
 ): VerifyOnChain {
-    const utxoCache = opts.utxoCache ?? new Map();
+    const cache = opts.cache ?? new Map();
     return async (proof, address) => {
-        const r = await writeProofOnChain(proof, address, { ...opts, utxoCache });
+        const r = await writeProofOnChain(proof, address, { ...opts, cache });
         if (r === 'no-answer') {
-            if (opts.unanswered === 'throw') throw new UnansweredReadError('the chain could not be read');
-            return false;
+            if (opts.unanswered === 'false') return false;
+            throw new UnansweredReadError('the chain could not be read');
         }
         return r;
     };