feat: show what is actually at each payout address (dv6 tier 2) (#275)

Tier 1 answered "where does my money go?". This answers "and what is there?".

/api/payout-balances is a SEPARATE endpoint from /api/payout-registry on
purpose. The registry is a local join and answers instantly; these are network
reads against public RPCs that can take seconds or time out. Folding them
together would make the whole payout table hostage to the slowest chain, so the
page renders the table first and fills the column in afterwards.

Only addresses we actually hold are queried. An internal, minted or unknown
service has no address, and putting a public RPC to work on nothing is both
pointless and rude to infrastructure we do not pay for.

THE RULE, one level down from the address column: "could not check" must never
render like "the balance is zero". Three distinct looks --

  known         the amount and its symbol, 0 included, because a real zero IS a fact
  unreachable   "could not check", italic, with the reason on hover
  nothing asked an em dash, because there was no address to ask about

Decimal is serialised as a STRING. A float at this last step would undo exactly
the precision the reader uses Decimal to preserve.

The harness now runs balanceCell for real and was mutation-tested: making
unreachable render as 0 fails 2 checks and exits 1. The endpoint's address
filter was mutation-tested too -- removing the supported-chain condition fails
2 tests.

4159 passed, 95.56%, all six render harnesses green.

Author: GeiserX

app/main.py

@@ -47,6 +47,7 @@
     metrics,
     net_activity,
     notify,
+    onchain,
     payout_registry,
     payouts,
     power,
@@ -3072,6 +3073,49 @@ async def api_payout_registry(request: Request) -> dict[str, Any]:
     return await payout_registry.registry()
 
 
+@app.get("/api/payout-balances")
+async def api_payout_balances(request: Request) -> dict[str, Any]:
+    """What is actually AT each payout address (CashPilot-dv6, tier 2).
+
+    OWNER-ONLY, same reasoning as the registry it builds on.
+
+    A SEPARATE endpoint from /api/payout-registry on purpose. The registry is a
+    local join and answers instantly; these are network reads against public
+    RPCs that can take seconds or time out. Folding them together would make the
+    whole payout table hostage to the slowest chain, so the page renders the
+    table first and fills these in afterwards.
+
+    Only addresses we actually hold are queried -- an `internal`, `minted` or
+    `unknown` service has no address, and asking a public RPC about nothing is
+    both pointless and rude.
+    """
+    _require_owner(request)
+    registry = await payout_registry.registry()
+
+    wanted = [
+        row
+        for row in registry["entries"]
+        if row.get("model") == "external" and row.get("address") and row.get("chain") in onchain.CHAINS
+    ]
+    results = await onchain.balances([(row["chain"], row["address"]) for row in wanted])
+
+    balances: dict[str, Any] = {}
+    for row, result in zip(wanted, results, strict=True):
+        # Decimal does not survive JSON. str() keeps every digit, which is the
+        # whole reason the reader uses Decimal in the first place -- a float here
+        # would undo it at the last step.
+        amount = result.get("amount")
+        balances[row["slug"]] = {**result, "amount": None if amount is None else str(amount)}
+
+    return {
+        "balances": balances,
+        # Named so the UI can say "3 of 5 addresses could not be checked"
+        # instead of quietly showing fewer rows than it did a moment ago.
+        "checked": len(wanted),
+        "unreadable": sum(1 for r in results if r.get("state") != onchain.KNOWN),
+    }
+
+
 @app.get("/api/update-status")
 async def api_update_status(request: Request) -> dict[str, Any]:
     """Whether a newer CashPilot has been released (CashPilot-w0ss).

app/static/css/style.css

@@ -2134,3 +2134,21 @@ img { max-width: 100%; }
 .payout-row-actionable {
   background: var(--warning-soft, rgba(245, 158, 11, 0.08));
 }
+
+/* On-chain balance column (CashPilot-dv6 tier 2).
+   "could not check" must not read as a balance, and must not read as the
+   em dash used for "there was nothing to ask". Three distinct looks. */
+.payout-balance {
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-size: 0.82rem;
+  white-space: nowrap;
+  color: var(--text-primary);
+}
+/* Not an error and not a zero: we simply do not know right now. */
+.payout-unchecked {
+  color: var(--text-muted);
+  font-size: 0.8rem;
+  font-style: italic;
+  border-bottom: 1px dotted var(--border-color);
+  cursor: help;
+}

app/templates/payouts.html

@@ -102,6 +102,33 @@ <h3 class="card-title">All services</h3>
     return '<span class="payout-na">Not classified yet</span>';
   }
 
+  // What is actually AT the address (CashPilot-dv6 tier 2).
+  //
+  // The same rule as the address column, one level down: "we could not check"
+  // must NEVER render like "the balance is zero". Zero is a fact about an
+  // address; unreachable is a fact about us, and a public RPC rate-limiting us
+  // is not news about the user's money.
+  //
+  // A row we never queried (internal, minted, unknown, or no address) gets an
+  // em dash, because there was nothing to ask.
+  function balanceCell(result) {
+    if (!result) return '<span class="payout-na">&mdash;</span>';
+    if (result.state === 'known') {
+      return '<span class="payout-balance">' + esc(result.amount)
+           + (result.symbol ? ' ' + esc(result.symbol) : '') + '</span>';
+    }
+    if (result.state === 'unreachable') {
+      return '<span class="payout-unchecked" title="' + esc(result.detail || '')
+           + '">could not check</span>';
+    }
+    if (result.state === 'invalid') {
+      return '<span class="payout-missing">address not valid</span>';
+    }
+    // unsupported: we have no keyless endpoint for that chain. Not the user's
+    // problem and not an error about their money.
+    return '<span class="payout-na">&mdash;</span>';
+  }
+
   function payoutRow(entry) {
     var chain = entry.chain ? esc(entry.chain) : '<span class="payout-na">&mdash;</span>';
     var deployed = entry.deployed
@@ -116,6 +143,8 @@ <h3 class="card-title">All services</h3>
       + '<td><span class="badge badge-category">' + esc(entry.model || 'unknown') + '</span></td>'
       + '<td>' + chain + '</td>'
       + '<td>' + payoutAddressCell(entry) + '</td>'
+      + '<td class="payout-balance-cell" data-slug="' + esc(entry.slug) + '">'
+      + balanceCell(_balances[entry.slug]) + '</td>'
       + '</tr>';
   }
 
@@ -125,12 +154,14 @@ <h3 class="card-title">All services</h3>
     }
     return '<div style="overflow-x:auto;"><table class="breakdown-table"><thead><tr>'
       + '<th>Service</th><th>Status</th><th>Payout model</th><th>Chain</th><th>Address</th>'
+      + '<th>On-chain</th>'
       + '</tr></thead><tbody>'
       + entries.map(payoutRow).join('')
       + '</tbody></table></div>';
   }
 
   var _entries = [];
+  var _balances = {};
 
   function applyFilter() {
     var q = (document.getElementById('payout-filter').value || '').trim().toLowerCase();
@@ -163,6 +194,7 @@ <h3 class="card-title">All services</h3>
       }
 
       applyFilter();
+      loadBalances();
     } catch (err) {
       // Say the registry could not be read. Never render an empty table, which
       // would look like "no services pay you anything".
@@ -171,6 +203,23 @@ <h3 class="card-title">All services</h3>
     }
   }
 
+  // Deliberately fired after the table exists. These are network reads against
+  // public RPCs; making the page wait on them would mean a rate-limited chain
+  // shows the user a blank screen instead of their addresses.
+  async function loadBalances() {
+    try {
+      var data = await CP.api('/api/payout-balances');
+      _balances = data.balances || {};
+    } catch (err) {
+      // Leave every cell as it was. Inventing zeroes here would be the exact
+      // failure this column is built to avoid.
+      return;
+    }
+    document.querySelectorAll('.payout-balance-cell').forEach(function (cell) {
+      cell.innerHTML = balanceCell(_balances[cell.dataset.slug]);
+    });
+  }
+
   document.addEventListener('DOMContentLoaded', function () {
     if (document.body.dataset.page !== 'payouts') return;
     document.getElementById('payout-filter').addEventListener('input', applyFilter);

scripts/payout_registry_check.mjs

@@ -40,9 +40,11 @@ function extract(name) {
 // Evaluate the real esc/payoutAddressCell/payoutRow together, since they call
 // one another. A stub for esc() here would let escaping break while this stayed
 // green — exactly the failure these harnesses exist to catch.
-const src = [extract('esc'), extract('payoutAddressCell'), extract('payoutRow')].join('\n');
-const {payoutAddressCell, payoutRow} = new Function(
-  `${src}; return {payoutAddressCell, payoutRow};`
+const src = [extract('esc'), extract('payoutAddressCell'), extract('balanceCell'), extract('payoutRow')].join('\n');
+// payoutRow reads the module-level _balances map, so give it an empty one --
+// the balance cell is exercised directly below.
+const {payoutAddressCell, payoutRow, balanceCell} = new Function(
+  `const _balances = {}; ${src}; return {payoutAddressCell, payoutRow, balanceCell};`
 )();
 
 let failures = 0;
@@ -135,6 +137,43 @@ check(
   payoutAddressCell({})
 );
 
+// ---------------------------------------------------------------------------
+// The on-chain column (dv6 tier 2). Same rule, one level down.
+// ---------------------------------------------------------------------------
+const bKnown = balanceCell({state: 'known', amount: '1.5', symbol: 'ETH'});
+const bZero = balanceCell({state: 'known', amount: '0', symbol: 'ETH'});
+const bUnreachable = balanceCell({state: 'unreachable', detail: 'timeout'});
+const bUnsupported = balanceCell({state: 'unsupported'});
+const bInvalid = balanceCell({state: 'invalid'});
+const bNone = balanceCell(undefined);
+
+check('a known balance is shown with its symbol', bKnown.includes('1.5') && bKnown.includes('ETH'), bKnown);
+check('a real zero balance IS shown as 0', bZero.includes('0'), bZero);
+
+check(
+  'THE ONE THAT MATTERS: unreachable does not render as a number',
+  !/\d/.test(bUnreachable.replace(/[^>]*>/g, '')) && /could not check/i.test(bUnreachable),
+  bUnreachable
+);
+check(
+  'unreachable and a zero balance look different',
+  bUnreachable !== bZero && !bUnreachable.includes('payout-balance"'),
+  `unreachable=${bUnreachable}\n      zero=${bZero}`
+);
+check(
+  'a row that was never queried is an em dash, not "could not check"',
+  bNone.includes('—') && !/could not check/i.test(bNone),
+  bNone
+);
+check('unsupported is also an em dash, not an error', bUnsupported.includes('—'), bUnsupported);
+check('an invalid address says so', /not valid/i.test(bInvalid), bInvalid);
+
+check(
+  'CONTROL: a hostile amount is escaped in the balance cell',
+  !balanceCell({state: 'known', amount: '<script>x</script>', symbol: 'E'}).includes('<script>'),
+  balanceCell({state: 'known', amount: '<script>x</script>', symbol: 'E'})
+);
+
 if (failures) {
   console.error(`\n${failures} payout-registry render check(s) failed`);
   process.exit(1);