faucet: validate address and show readable dispense errors

Author: Gmin2

faucet/app/page.tsx

@@ -17,7 +17,13 @@ import type { GetTransactionResponse } from "@/gen/bitcoin/bitcoind/v1alpha/bitc
 import { FaucetService } from "@/gen/faucet/v1/faucet_pb";
 import { timestampToDate } from "@/lib/api";
 import { clientTransport } from "@/lib/client-api";
-import { blockExplorerUrl, exampleAddressForNetwork } from "@/lib/utils";
+import { dispenseErrorMessage } from "@/lib/errors";
+import {
+  blockExplorerUrl,
+  exampleAddressForNetwork,
+  instanceNetwork,
+  isPlausibleAddress,
+} from "@/lib/utils";
 
 export default function Home() {
   const [address, setAddress] = useState("");
@@ -35,6 +41,11 @@ export default function Home() {
   const handleDispense = async () => {
     if (!address || !amount) return;
 
+    if (!isPlausibleAddress(address)) {
+      setError(`That doesn't look like a valid ${instanceNetwork()} address.`);
+      return;
+    }
+
     setLoading(true);
     setError(null);
     setTxid(null);
@@ -45,7 +56,7 @@ export default function Home() {
       setTxid(response.txid);
       fetchClaims(); // Refresh claims list
     } catch (err) {
-      setError(`Failed to dispense coins: ${err}`);
+      setError(dispenseErrorMessage(err));
     } finally {
       setLoading(false);
     }

faucet/lib/errors.ts

@@ -0,0 +1,21 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+import { instanceNetwork } from "@/lib/utils";
+
+// Turns the backend's raw dispense errors into something a user can act on.
+// The Bitcoin Core node stays the source of truth, this just makes its
+// messages readable instead of dumping "[internal] dispense coins: -5: ...".
+export function dispenseErrorMessage(err: unknown): string {
+  const connectErr = ConnectError.from(err);
+  const raw = connectErr.rawMessage.toLowerCase();
+
+  if (raw.includes("address") || raw.includes("checksum")) {
+    return `That doesn't look like a valid ${instanceNetwork()} address. Double-check it and try again.`;
+  }
+  if (raw.includes("amount")) {
+    return "Amount must be greater than 0 and at most 5 BTC.";
+  }
+  if (connectErr.code === Code.ResourceExhausted || raw.includes("insufficient")) {
+    return "The faucet is temporarily out of funds or rate-limited. Please try again later.";
+  }
+  return "Could not dispense coins. Please try again.";
+}

faucet/lib/utils.ts

@@ -14,6 +14,17 @@ export function instanceNetwork(): string {
   return network;
 }
 
+// Loose sanity check to catch empty or obviously typo'd input before we hit
+// the node. Intentionally does not verify the checksum or network, the faucet's
+// Bitcoin Core node is the source of truth, so this stays permissive to avoid
+// rejecting a valid address.
+export function isPlausibleAddress(address: string): boolean {
+  const addr = address.trim();
+  const bech32 = /^(bc|tb|bcrt)1[a-z0-9]{6,87}$/i;
+  const base58 = /^[123mn][1-9A-HJ-NP-Za-km-z]{24,38}$/;
+  return bech32.test(addr) || base58.test(addr);
+}
+
 export function exampleAddressForNetwork(): string {
   switch (instanceNetwork()) {
     case "signet":