feat: auto-refund for failed renders (blocked/empty pages) via Stellar USDC transfer

.env.example

@@ -1,4 +1,6 @@
-# Stellar testnet secret key (starts with S...)
-STELLAR_PRIVATE_KEY=
 # Stellar testnet public key to receive payments (starts with G...)
 PAY_TO=
+# Stellar testnet secret key for the server — used to send refunds (starts with S...)
+SERVER_SECRET=
+# Client's Stellar testnet secret key — for demo-client.js only (starts with S...)
+STELLAR_PRIVATE_KEY=

Dockerfile

@@ -16,7 +16,7 @@ RUN npm ci --omit=dev
 # Install Playwright Chromium
 RUN npx playwright install chromium
 
-COPY server.js renderer.js ./
+COPY server.js renderer.js refund.js ./
 
 USER node
 ENV PORT=7860

refund.js

@@ -0,0 +1,91 @@
+import {
+  Keypair,
+  Networks,
+  TransactionBuilder,
+  Operation,
+  Asset,
+  Horizon,
+} from "@stellar/stellar-sdk";
+
+const USDC_ISSUER = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5";
+const USDC = new Asset("USDC", USDC_ISSUER);
+const HORIZON_URL = "https://horizon-testnet.stellar.org";
+
+const BLOCKED_PATTERNS = [
+  "you've been blocked",
+  "you have been blocked",
+  "blocked by network security",
+  "access denied",
+  "please log in",
+  "log in to",
+  "sign in to",
+  "enable javascript",
+  "just a moment...",
+  "checking your browser",
+  "performing security verification",
+  "ray id:",
+  "cloudflare",
+  "attention required",
+  "please verify you are a human",
+  "this page doesn't exist",
+];
+
+export function isFailedRender(content, title) {
+  if (!content || content.length < 100) return "empty_content";
+
+  const lower = content.toLowerCase();
+  const titleLower = (title || "").toLowerCase();
+
+  // Check title for block signals
+  if (titleLower === "just a moment..." || titleLower === "blocked") {
+    return "blocked_page";
+  }
+
+  // Check content for block/login patterns
+  for (const pattern of BLOCKED_PATTERNS) {
+    // Only flag if the blocked pattern is a large portion of the content
+    // (avoid false positives on pages that mention "log in" in a nav bar)
+    if (lower.includes(pattern) && content.length < 500) {
+      return "blocked_page";
+    }
+  }
+
+  return null; // render is good
+}
+
+export async function sendRefund(payerAddress, amount, memo) {
+  const serverSecret = process.env.SERVER_SECRET;
+  if (!serverSecret) {
+    console.error("SERVER_SECRET not set — cannot send refund");
+    return null;
+  }
+
+  try {
+    const server = new Horizon.Server(HORIZON_URL);
+    const keypair = Keypair.fromSecret(serverSecret);
+    const account = await server.loadAccount(keypair.publicKey());
+
+    const tx = new TransactionBuilder(account, {
+      fee: "100",
+      networkPassphrase: Networks.TESTNET,
+    })
+      .addOperation(
+        Operation.payment({
+          destination: payerAddress,
+          asset: USDC,
+          amount: amount,
+        }),
+      )
+      .addMemo(TransactionBuilder.memo("text", memo || "RenderGate refund"))
+      .setTimeout(30)
+      .build();
+
+    tx.sign(keypair);
+    const result = await server.submitTransaction(tx);
+    console.log(`Refund sent to ${payerAddress}: ${result.hash}`);
+    return result.hash;
+  } catch (err) {
+    console.error(`Refund failed for ${payerAddress}:`, err.message);
+    return null;
+  }
+}

server.js

@@ -4,6 +4,7 @@ import { paymentMiddlewareFromConfig } from "@x402/express";
 import { HTTPFacilitatorClient } from "@x402/core/server";
 import { ExactStellarScheme } from "@x402/stellar/exact/server";
 import { renderUrl, closeBrowser } from "./renderer.js";
+import { isFailedRender, sendRefund } from "./refund.js";
 
 const PORT = process.env.PORT || 3001;
 const PRICE = "$0.001";
@@ -89,6 +90,18 @@ app.use(
   ),
 );
 
+// Extract payer address from the PAYMENT-RESPONSE header set by x402 middleware
+function getPayerFromResponse(res) {
+  try {
+    const header = res.getHeader("PAYMENT-RESPONSE");
+    if (!header) return null;
+    const decoded = JSON.parse(Buffer.from(header, "base64").toString());
+    return decoded?.payer || null;
+  } catch {
+    return null;
+  }
+}
+
 // Protected render endpoint
 app.get("/render", async (req, res) => {
   const decoded = req.decodedUrl;
@@ -99,6 +112,26 @@ app.get("/render", async (req, res) => {
     const result = await renderUrl(decoded);
     const elapsed = Date.now() - start;
 
+    // Check if the render actually succeeded
+    const failReason = isFailedRender(result.content, result.title);
+    const payerAddress = getPayerFromResponse(res);
+    if (failReason && payerAddress) {
+      console.log(`Bad render (${failReason}) for ${decoded} — refunding ${payerAddress}`);
+      const refundHash = await sendRefund(payerAddress, "0.001", `refund:${failReason}`);
+
+      return res.json({
+        ...result,
+        renderTimeMs: elapsed,
+        payment: { price: PRICE, network: NETWORK },
+        refund: {
+          reason: failReason,
+          transaction: refundHash,
+          amount: "0.001 USDC",
+          message: "Page was blocked or empty — payment refunded",
+        },
+      });
+    }
+
     res.json({
       ...result,
       renderTimeMs: elapsed,