move the wallet's chain source out of env and into the ui

WALLET_ESPLORA_URL was the one wallet setting an owner actually has to change — off a
public explorer that rate-limits and sees every address, onto their own indexer — and it
was the one they could only change with a shell and a restart. It now lives in
service_connections under 'esplora' and is edited at Wallet -> Settings -> Chain source,
probed against /blocks/tip/height before it is stored.

The URL joins the backend fingerprint, so re-pointing rebuilds every on-chain backend and
drops the gap-limit scan taken through the old endpoint. /_health probes what the wallets
actually use rather than the built-in default, and /_officer/config no longer reports a URL
it cannot know.

Also two receive-screen defects the Blockstream 429 exposed: a query error rendered as
"No address available", and the "new address" button called refetch() on the ?peek=true
query, so it re-fetched the same address instead of advancing the index.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/servers/sidecar/wallet/config.ts

@@ -0,0 +1,107 @@
+import { deleteServiceConnection, getServiceConnection, saveServiceConnection } from 'officerdb';
+import { invalidateAll } from './resolve';
+import { getChainSource, getConfig, invalidateChainSource, normalizeEsploraUrl } from './upstream';
+
+// `/_config` — which Esplora endpoint this owner's on-chain wallets read the chain from.
+//
+// This is the one wallet setting that is NOT per-wallet and NOT key material: an endpoint serves every
+// on-chain wallet the owner has, and it holds no secret, because Esplora is an unauthenticated read API.
+// It went from an env var to a row for one reason — it is the setting most likely to need changing, and
+// the reason to change it (a public explorer rate-limiting you, or seeing every address you own) shows
+// up long after the deployment that set it.
+//
+// PRIVACY, NOT CUSTODY. An Esplora endpoint learns which addresses you ask about, so pointing this at
+// your own indexer is a real privacy upgrade. It is never a custody risk: the endpoint sees no key, and
+// a hostile one can lie about balances but cannot move a coin.
+
+export type ChainProbe = { ok: boolean; blockHeight?: number | null; error?: string; ms?: number };
+
+/**
+ * Is there an Esplora API at this URL, and does it know the tip?
+ *
+ * `/blocks/tip/height` is the cheapest endpoint Esplora has and the one every implementation has — a
+ * bare number in the body. Anything else answering (a bitcoind RPC port, a mempool.space *web* root, an
+ * nginx default page) fails here rather than at the first address scan, which is the whole point: the
+ * owner finds out while looking at the form.
+ */
+export async function probe(baseUrl: string): Promise<ChainProbe> {
+  const started = Date.now();
+  try {
+    const res = await fetch(`${baseUrl}/blocks/tip/height`, {
+      headers: { Accept: 'text/plain' },
+      signal: AbortSignal.timeout(8_000),
+      redirect: 'manual',
+    });
+    const body = (await res.text()).trim();
+    if (!res.ok) {
+      return { ok: false, error: `endpoint returned ${res.status}: ${body.slice(0, 200)}`, ms: Date.now() - started };
+    }
+    const height = Number(body);
+    if (!Number.isFinite(height) || height <= 0) {
+      return {
+        ok: false,
+        error: `that URL answered, but not like an Esplora API (expected a block height, got "${body.slice(0, 60)}")`,
+        ms: Date.now() - started,
+      };
+    }
+    return { ok: true, blockHeight: height, ms: Date.now() - started };
+  } catch (err) {
+    return { ok: false, error: `could not reach the endpoint (${String(err)})`, ms: Date.now() - started };
+  }
+}
+
+const bad = (error: string, status = 400) => Response.json({ error }, { status });
+
+const isHttpUrl = (url: string): boolean => /^https?:\/\//i.test(url);
+
+/** The URL in use plus whether it is the owner's or the built-in default. No secrets exist here at all. */
+async function state(userId: number): Promise<Response> {
+  const connection = await getServiceConnection(userId, 'esplora');
+  const source = await getChainSource(userId);
+  return Response.json({
+    configured: !!connection,
+    connection,
+    esploraUrl: source.baseUrl,
+    custom: source.custom,
+    defaultUrl: getConfig().esploraUrl,
+    network: getConfig().network,
+  });
+}
+
+type ConfigBody = { url?: unknown };
+
+async function save(req: Request, userId: number): Promise<Response> {
+  const body = ((await req.json().catch(() => null)) as ConfigBody | null) ?? {};
+  const url = typeof body.url === 'string' ? normalizeEsploraUrl(body.url) : '';
+
+  if (!url) return bad('url is required');
+  if (!isHttpUrl(url)) return bad('url must start with http:// or https://');
+
+  const result = await probe(url);
+  if (!result.ok) return bad(result.error ?? 'that endpoint did not answer');
+
+  await saveServiceConnection({ userId, service: 'esplora', url });
+  invalidateChainSource(userId);
+  // Every on-chain backend holds an EsploraChain built from the old URL, and a cached gap-limit scan
+  // taken through it. Both are now wrong, so drop the instances rather than trying to patch them.
+  invalidateAll();
+
+  return Response.json({ ...(await state(userId).then((r) => r.json())), probe: result });
+}
+
+/** `/_config` — GET what is in use, PUT to change it, DELETE to fall back to the built-in default. */
+export async function handleConfigRoute(req: Request, userId: number, subpath: string): Promise<Response> {
+  if (subpath && subpath !== '/') return bad('not found', 404);
+
+  if (req.method === 'GET') return state(userId);
+  if (req.method === 'POST' || req.method === 'PUT') return save(req, userId);
+
+  if (req.method === 'DELETE') {
+    await deleteServiceConnection(userId, 'esplora');
+    invalidateChainSource(userId);
+    invalidateAll();
+    return state(userId);
+  }
+
+  return bad('method not allowed', 405);
+}

src/servers/sidecar/wallet/index.ts

@@ -1,7 +1,8 @@
 import type { SidecarCommand, SidecarEvent } from '../protocol';
 import { createSidecarConnector } from '../connect';
+import { handleConfigRoute } from './config';
 import { handleOfficerRoute } from './routes';
-import { getConfig, hasStoreKey } from './upstream';
+import { getChainSource, getConfig, hasStoreKey } from './upstream';
 import { lockAll } from './keys';
 import { invalidateAll } from './resolve';
 
@@ -30,7 +31,10 @@ import { invalidateAll } from './resolve';
 // HTTP CONTRACT — the platform strips its /api/wallet mount prefix before forwarding.
 //
 //   GET  /_health                                   ours. Reports network, chain reachability, store key.
-//   GET  /_officer/config                           network + esplora + unlock TTL + storeKeyConfigured
+//   GET    /_config                                 the owner's Esplora endpoint (or the built-in default)
+//   PUT    /_config                                 {url} — probed before it is stored
+//   DELETE /_config                                 fall back to the built-in default
+//   GET  /_officer/config                           network + unlock TTL + storeKeyConfigured
 //
 //   GET    /_officer/wallets                        list. Never includes secrets.
 //   POST   /_officer/wallets                        create. Seeded wallets return the mnemonic ONCE,
@@ -103,18 +107,42 @@ const server = Bun.serve({
   async fetch(req) {
     const url = new URL(req.url);
 
+    // `/_config` is the chain endpoint, which is per-owner — so unlike /_health it needs the header.
+    if (url.pathname === '/_config' || url.pathname.startsWith('/_config/')) {
+      const officerUser = req.headers.get('X-Officer-User');
+      const userId = Number(officerUser);
+      if (!officerUser || !Number.isInteger(userId) || userId <= 0) {
+        return Response.json({ error: 'missing or invalid X-Officer-User' }, { status: 401 });
+      }
+      try {
+        return await handleConfigRoute(req, userId, url.pathname.slice('/_config'.length));
+      } catch (err) {
+        console.error(`[wallet] ${req.method} ${url.pathname} failed`, err instanceof Error ? err.message : err);
+        return Response.json({ error: 'internal error' }, { status: 500 });
+      }
+    }
+
     if (url.pathname === '/_health') {
       const cfg = getConfig();
+      // Health has to probe the endpoint the wallets ACTUALLY use, not the built-in default — reporting
+      // the default green while the owner's own indexer is down would be worse than no health at all.
+      // The header is optional here (health predates it), so fall back rather than 401.
+      const healthUser = Number(req.headers.get('X-Officer-User'));
+      const chain =
+        Number.isInteger(healthUser) && healthUser > 0
+          ? await getChainSource(healthUser)
+          : { baseUrl: cfg.esploraUrl, custom: false };
       const started = Date.now();
       try {
-        const res = await fetch(`${cfg.esploraUrl}/blocks/tip/height`, {
+        const res = await fetch(`${chain.baseUrl}/blocks/tip/height`, {
           signal: AbortSignal.timeout(5_000),
         });
         const height = res.ok ? Number(await res.text()) : null;
         return Response.json({
           ok: res.ok,
           network: cfg.network,
-          esplora: cfg.esploraUrl,
+          esplora: chain.baseUrl,
+          custom: chain.custom,
           blockHeight: Number.isFinite(height) ? height : null,
           // Surfaced because wallet creation is refused without it, and that failure would otherwise
           // look like a bug rather than a missing config line.
@@ -126,7 +154,8 @@ const server = Bun.serve({
           {
             ok: false,
             network: cfg.network,
-            esplora: cfg.esploraUrl,
+            esplora: chain.baseUrl,
+            custom: chain.custom,
             error: String(err),
             storeKeyConfigured: hasStoreKey(),
             ms: Date.now() - started,
@@ -152,8 +181,8 @@ const server = Bun.serve({
   },
 });
 
-const cfg = getConfig();
-console.log(`[wallet] listening on 127.0.0.1:${port} — network=${cfg.network} esplora=${cfg.esploraUrl}`);
+// No esplora URL in the banner: it is per-owner state read from the database now, not a boot constant.
+console.log(`[wallet] listening on 127.0.0.1:${port} — network=${getConfig().network}`);
 if (!hasStoreKey()) {
   console.warn('[wallet] VAULT_STORE_KEY is unset — wallet creation will be refused until it is configured');
 }

src/servers/sidecar/wallet/resolve.ts

@@ -14,7 +14,7 @@ import { LndHubBackend } from './backends/lndhub';
 import { NwcBackend } from './backends/nwc';
 import { OnchainBackend } from './backends/onchain';
 import { sessionFor } from './keys';
-import { getConfig } from './upstream';
+import { getChainSource } from './upstream';
 import { BackendError, BIP_ADDRESS_TYPE, type AddressType, type BitcoinNetwork, type WalletBackend } from './types';
 
 // Turns a stored wallet row into a live backend instance. This is the one place that knows the mapping
@@ -38,8 +38,8 @@ export function invalidateAll(): void {
 }
 
 /** A stable fingerprint of the inputs a backend was built from, so a stale instance is detected. */
-function versionOf(wallet: WalletSummary, config: Record<string, unknown> | null): string {
-  return JSON.stringify([wallet.kind, wallet.network, wallet.defaultBip, wallet.xpubs, config]);
+function versionOf(wallet: WalletSummary, config: Record<string, unknown> | null, esploraUrl: string): string {
+  return JSON.stringify([wallet.kind, wallet.network, wallet.defaultBip, wallet.xpubs, config, esploraUrl]);
 }
 
 export type Resolved = { wallet: WalletSummary; backend: WalletBackend };
@@ -50,12 +50,15 @@ export async function resolveBackend(userId: number, walletId: number): Promise<
 
   const secrets = await getWalletSecrets(userId, walletId);
   const config = secrets?.config ?? null;
-  const version = versionOf(wallet, config);
+  // Read per resolve rather than per build: the URL is in the fingerprint, so pointing the owner at a
+  // different indexer rebuilds every backend and drops the scan taken through the old one.
+  const { baseUrl: esploraUrl } = await getChainSource(userId);
+  const version = versionOf(wallet, config, esploraUrl);
 
   const hit = cache.get(walletId);
   if (hit && hit.configVersion === version) return { wallet, backend: hit.backend };
 
-  const backend = build(wallet, config);
+  const backend = build(wallet, config, esploraUrl);
   cache.set(walletId, { backend, configVersion: version });
   return { wallet, backend };
 }
@@ -81,7 +84,7 @@ function required(config: Record<string, unknown> | null, key: string, kind: str
   return v;
 }
 
-function build(wallet: WalletSummary, config: Record<string, unknown> | null): WalletBackend {
+function build(wallet: WalletSummary, config: Record<string, unknown> | null, esploraUrl: string): WalletBackend {
   const network = wallet.network as BitcoinNetwork;
 
   switch (wallet.kind) {
@@ -123,7 +126,6 @@ function build(wallet: WalletSummary, config: Record<string, unknown> | null): W
       if (Object.keys(accountXpub).length === 0) {
         throw new BackendError('wallet has no account xpubs', 500, 'BAD_CONFIG');
       }
-      const { esploraUrl } = getConfig();
       return new OnchainBackend({
         chain: new EsploraChain({ baseUrl: esploraUrl, network }),
         network,

src/servers/sidecar/wallet/routes.ts

@@ -116,12 +116,17 @@ export async function handleOfficerRoute(req: Request, url: URL): Promise<Respon
   }
 }
 
-/** Non-secret deployment facts the UI needs before any wallet exists. */
+/**
+ * Non-secret deployment facts the UI needs before any wallet exists.
+ *
+ * No esplora URL: that is per-owner now and lives at `/_config`, which is also the only place that can
+ * say whether it is the owner's endpoint or the fallback. Reporting the default here would have shown
+ * the wrong URL to anyone who had set their own.
+ */
 function handleConfig(): Response {
   const cfg = getConfig();
   return json({
     network: cfg.network,
-    esploraUrl: cfg.esploraUrl,
     unlockTtlSec: cfg.unlockTtlSec,
     // The UI blocks wallet creation on this rather than letting the first write fail on a crypto error.
     storeKeyConfigured: hasStoreKey(),

src/servers/sidecar/wallet/upstream.ts

@@ -1,9 +1,15 @@
 import type { BitcoinNetwork } from './types';
+import { getServiceCredentials } from 'officerdb';
 
 // The ONLY reader of WALLET_* env in the tree. Everything else — node URLs, macaroons, runes, LNDHub
 // credentials, NWC URIs — is per-wallet configuration the owner enters at runtime and lives encrypted in
 // Postgres (databases/officer_db/src/schema/wallet.ts), not here. Env holds only what is genuinely
-// deployment-wide: which chain we're on and where to get chain data.
+// deployment-wide: which chain we're on.
+//
+// WHERE CHAIN DATA COMES FROM IS NOT ENV. It used to be WALLET_ESPLORA_URL, which meant the one setting
+// an owner actually has to change — off the public explorer, onto their own indexer — was the one
+// setting they could only change with a shell and a restart. It now lives in `service_connections`
+// under 'esplora' and is edited from Wallet → Settings; see getChainSource below.
 
 const NETWORKS: readonly BitcoinNetwork[] = ['bitcoin', 'testnet', 'signet', 'regtest'];
 
@@ -33,17 +39,54 @@ export function getConfig(): WalletConfig {
     warned = true;
   }
 
-  const esploraUrl = process.env.WALLET_ESPLORA_URL?.trim().replace(/\/+$/, '') || DEFAULT_ESPLORA[network];
   const ttl = Number(process.env.WALLET_UNLOCK_TTL_SEC ?? 900);
 
   return {
     network,
-    esploraUrl,
+    /** The built-in default, used until the owner stores one. `getChainSource` is the real answer. */
+    esploraUrl: DEFAULT_ESPLORA[network],
     // Clamp: a zero TTL makes the wallet unusable, and an unbounded one defeats auto-lock entirely.
     unlockTtlSec: Number.isFinite(ttl) ? Math.min(Math.max(ttl, 30), 86_400) : 900,
   };
 }
 
+export type ChainSource = {
+  /** Esplora API root, no trailing slash. */
+  baseUrl: string;
+  /** True when this is the owner's stored endpoint rather than the built-in public default. */
+  custom: boolean;
+};
+
+/** Short TTL: a save invalidates explicitly, so this only bounds how stale a *concurrent* reader can be. */
+const CHAIN_TTL_MS = 60_000;
+const chainCache = new Map<number, { source: ChainSource; at: number }>();
+
+export const normalizeEsploraUrl = (url: string): string => url.trim().replace(/\/+$/, '');
+
+/**
+ * Where to read the chain, for this owner.
+ *
+ * Falls back to the public default rather than failing: a wallet with no stored endpoint is still a
+ * working watch-only wallet, just one pointed at an explorer that rate-limits and can see every address
+ * it asks about. The default is a starting point, not a destination.
+ */
+export async function getChainSource(userId: number): Promise<ChainSource> {
+  const hit = chainCache.get(userId);
+  if (hit && Date.now() - hit.at < CHAIN_TTL_MS) return hit.source;
+
+  const creds = await getServiceCredentials(userId, 'esplora');
+  const source: ChainSource = creds?.url
+    ? { baseUrl: normalizeEsploraUrl(creds.url), custom: true }
+    : { baseUrl: getConfig().esploraUrl, custom: false };
+
+  chainCache.set(userId, { source, at: Date.now() });
+  return source;
+}
+
+export function invalidateChainSource(userId: number): void {
+  chainCache.delete(userId);
+}
+
 /**
  * Whether VAULT_STORE_KEY is present. The sidecar can serve a locked, watch-only view without it, but
  * every write path that touches an encrypted column will throw, so /_health reports it explicitly rather