deviant/scripts/lib/chipnet-safe.mjs

/**
 * chipnet-safe.mjs — safe chipnet UTXO selection + broadcast, hardened against a real, diagnosed bug.
 *
 * THE BUG (root-caused 2026-07-21). The cashscript `ElectrumNetworkProvider`'s default chipnet
 * electrum server returns a STALE UTXO index: it lists already-SPENT outpoints as unspent. Measured
 * on the operator wallet, the cashscript provider reported 94 UTXOs while mainnet-js (a fresher,
 * independent electrum server) reported 81 — a 14-outpoint difference, every one a CHANGE output from
 * an earlier genesis tx that had long since been spent (all confirmed-long-ago, vout 1). A driver that
 * builds a tx from that stale view can select a spent outpoint as an input; the node then rejects the
 * broadcast with **"Missing inputs" (bad-txns-inputs-missingorspent)**. Fragmentation raises the odds
 * of hitting a phantom, so the wallet looks permanently "stuck".
 *
 * THE FIX. Source wallet UTXO selection from **mainnet-js**, which returned the ACCURATE set (it had
 * already dropped the 14 phantoms). Convert to the cashscript UTXO shape the TransactionBuilder wants.
 * The cashscript provider is still fine for BROADCAST and for reading the covenant/token UTXOs (a
 * freshly-created controller is never a phantom); we just stop trusting its wallet-UTXO *listing*.
 * Belt-and-suspenders: `sendWithRetry` re-fetches and rebuilds if a broadcast still hits a stale-input
 * reject (e.g. mainnet-js momentarily lagging). Prefer confirmed inputs, but ACCEPT unconfirmed when
 * necessary (a fresh split output is real at 0-conf — 0-conf chaining is normal and safe here).
 */

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const STALE_INPUT = /Missing inputs|missingorspent|bad-txns-inputs|txn-mempool-conflict|txn-already-known/i;
const toCs = (x) => ({ txid: x.txid, vout: x.vout, satoshis: BigInt(x.satoshis), token: x.token });
const bySatsDesc = (a, b) => Number(BigInt(b.satoshis) - BigInt(a.satoshis));

/** The ACCURATE spendable UTXO set (from mainnet-js), in cashscript shape. `provider` is unused but
 *  kept in the signature so call sites read symmetrically and can be swapped later. */
export async function safeUtxos(_provider, wallet) {
  const mj = await wallet.getUtxos();
  return mj.map(toCs);
}

/** Largest-first BCH selection covering `need` sats from a pre-fetched set (non-token only). */
export function pickBch(utxos, need) {
  const p = []; let t = 0n;
  for (const x of utxos.filter((x) => !x.token).sort(bySatsDesc)) { p.push(x); t += BigInt(x.satoshis); if (t >= need) break; }
  if (t < need) throw new Error(`insufficient BCH: have ${t}, need ${need}`);
  return { p, t };
}

/**
 * A non-token UTXO at outpoint index 0 — required to genesis a CashToken whose category == that
 * outpoint's txid (CashTokens genesis rule: an input must spend a vout-0 output). Prefer a CONFIRMED
 * one; else use any; else split one into existence (send-to-self) and use the fresh (0-conf) output.
 */
export async function eligibleVout0(_provider, wallet, { splitSats = 3000n, waitMs = 14000 } = {}) {
  const pick0 = (arr) => arr.filter((x) => x.vout === 0 && !x.token).sort(bySatsDesc)[0];
  let mj = await wallet.getUtxos();
  let e = pick0(mj.filter((x) => Number(x.height ?? 0) > 0)) || pick0(mj);   // confirmed first, else any
  if (e) return toCs(e);
  await wallet.send([{ cashaddr: wallet.cashaddr, value: splitSats, unit: 'sat' }]);   // create a vout-0 output
  await sleep(waitMs);
  mj = await wallet.getUtxos();
  e = pick0(mj);                                                              // accept the fresh 0-conf output
  if (!e) throw new Error('could not obtain a vout-0 UTXO after split');
  return toCs(e);
}

/**
 * Run `buildAndSend` (an async thunk that RE-FETCHES its inputs, builds, and broadcasts), retrying on
 * the stale-input reject. The thunk must re-fetch each call so the retry uses fresh state.
 */
export async function sendWithRetry(buildAndSend, { retries = 3, backoffMs = 8000, onRetry } = {}) {
  for (let i = 0; ; i++) {
    try { return await buildAndSend(); }
    catch (e) {
      const msg = e?.message ?? String(e);
      if (i < retries && STALE_INPUT.test(msg)) { onRetry?.(i + 1, msg); await sleep(backoffMs); continue; }
      throw e;
    }
  }
}

/** Consolidate a wallet's UTXOs into one output (maintenance; reduces fragmentation). */
export async function consolidate(wallet) { return wallet.sendMax(wallet.cashaddr); }