Feat/stellar testnet faucet (#62)

* fix(backend): repair boot-blocking dependency and file gaps from PR #49

PostgreSQL_persistence_layer merged code that requires `pg` and
`@testcontainers/postgresql` without adding them to package.json, and
referenced `./routes/internal` from app.js without ever committing that
file — so a fresh install can't boot the app or run the test suite at
all. Also bumps the Stellar SDK compat shim since installed 13.x
releases renamed `SorobanRpc` to `rpc`, breaking config/stellar.js on
load.

Reconstructs routes/internal.js (GET /api/v1/internal/db-stats) from
the existing (already-committed) test contract in internal.test.js.

* feat(stellar): add testnet friendbot funding endpoint and frontend integration

Adds POST /api/v1/stellar/fund so developers can fund a Testnet account
via Stellar Friendbot without leaving the app: blocked on Mainnet (403),
rate-limited to 1 request per IP per hour (429), and validated against
malformed public keys (400). The wallet page shows a "Fund with Testnet
XLM" button only when connected to Testnet with a 0 XLM balance, and
refreshes the balance automatically after funding.

Also adds Jest + React Testing Library to the frontend (previously had
no test tooling) to cover the new button's states.

Closes #33.

* chore(frontend): remove package-lock.json

Frontend now uses pnpm (frontend/pnpm-lock.yaml), making the npm
package-lock.json redundant. Per maintainer request on the PR.

Author: Bolajiomo99

.github/workflows/frontend.yml

@@ -33,5 +33,8 @@ jobs:
       - name: Run lint
         run: npm run lint
 
+      - name: Run tests
+        run: npm test
+
       - name: Run build
         run: npm run build

backend/README.md

@@ -37,8 +37,10 @@ npm run dev
 | `GET` | `/api/v1/streams/:id` | Get stream by ID |
 | `POST` | `/api/v1/streams` | Index a stream |
 | `GET` | `/api/v1/stellar/account/:publicKey` | Horizon account info |
+| `GET` | `/api/v1/stellar/account/:publicKey/transactions` | Paginated payment history |
 | `GET` | `/api/v1/stellar/network` | Network config |
 | `GET` | `/api/v1/stellar/fee` | Fee statistics |
+| `POST` | `/api/v1/stellar/fund` | Fund a Testnet account via Friendbot |
 
 ## Query Parameters — Assets
 

backend/src/__tests__/routes/stellar.test.js

@@ -10,6 +10,8 @@
 const request = require("supertest");
 const app = require("../../app");
 const { cacheClear } = require("../../services/transactionService");
+const stellarRouter = require("../../routes/stellar");
+const stellarConfig = require("../../config/stellar");
 
 // ── Mock the Horizon server ───────────────────────────────────────────────────
 
@@ -100,6 +102,8 @@ function mockHorizonSuccess(txs, ops) {
 beforeEach(() => {
   cacheClear();
   jest.clearAllMocks();
+  stellarRouter.resetFundRateLimiter();
+  stellarConfig.NETWORK = "testnet";
 });
 
 // ── Tests ─────────────────────────────────────────────────────────────────────
@@ -431,3 +435,105 @@ describe("GET /api/v1/stellar/account/:publicKey/transactions", () => {
     expect(res.body.meta.hasMore).toBe(false);
   });
 });
+
+describe("POST /api/v1/stellar/fund", () => {
+  const originalFetch = global.fetch;
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("funds a valid Testnet account", async () => {
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: true,
+      json: jest.fn().mockResolvedValue({ hash: "friendbot-tx-hash" }),
+    });
+
+    const res = await request(app)
+      .post("/api/v1/stellar/fund")
+      .send({ publicKey: VALID_KEY })
+      .expect(200);
+
+    expect(res.body).toEqual({
+      publicKey: VALID_KEY,
+      funded: true,
+      hash: "friendbot-tx-hash",
+    });
+    expect(global.fetch).toHaveBeenCalledWith(
+      expect.stringContaining(`addr=${VALID_KEY}`)
+    );
+  });
+
+  it("returns 400 when publicKey is missing", async () => {
+    const res = await request(app).post("/api/v1/stellar/fund").send({}).expect(400);
+    expect(res.body.error).toMatch(/publicKey is required/i);
+  });
+
+  it("returns 400 for a malformed publicKey", async () => {
+    const res = await request(app)
+      .post("/api/v1/stellar/fund")
+      .send({ publicKey: "not-a-real-key" })
+      .expect(400);
+    expect(res.body.error).toMatch(/valid Stellar public key/i);
+  });
+
+  it("returns 403 when the network is configured for Mainnet", async () => {
+    stellarConfig.NETWORK = "mainnet";
+    global.fetch = jest.fn();
+
+    const res = await request(app)
+      .post("/api/v1/stellar/fund")
+      .send({ publicKey: VALID_KEY })
+      .expect(403);
+
+    expect(res.body).toEqual({
+      error: "Friendbot is only available on Stellar Testnet.",
+    });
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it("returns a structured 500 error when Friendbot fails", async () => {
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: false,
+      status: 400,
+      json: jest.fn().mockResolvedValue({ detail: "createAccountAlreadyExist" }),
+    });
+
+    const res = await request(app)
+      .post("/api/v1/stellar/fund")
+      .send({ publicKey: VALID_KEY })
+      .expect(500);
+
+    expect(res.body).toHaveProperty("error");
+  });
+
+  it("returns a structured 500 error when Friendbot is unreachable", async () => {
+    global.fetch = jest.fn().mockRejectedValue(new Error("network down"));
+
+    const res = await request(app)
+      .post("/api/v1/stellar/fund")
+      .send({ publicKey: VALID_KEY })
+      .expect(500);
+
+    expect(res.body).toHaveProperty("error");
+  });
+
+  it("returns 429 after the per-IP limit (1 per hour) is exceeded", async () => {
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: true,
+      json: jest.fn().mockResolvedValue({ hash: "friendbot-tx-hash" }),
+    });
+
+    await request(app)
+      .post("/api/v1/stellar/fund")
+      .send({ publicKey: VALID_KEY })
+      .expect(200);
+
+    const res = await request(app)
+      .post("/api/v1/stellar/fund")
+      .send({ publicKey: VALID_KEY })
+      .expect(429);
+
+    expect(res.body).toHaveProperty("error");
+  });
+});

backend/src/config/stellar.js

@@ -37,7 +37,7 @@ const horizonUrl =
   HORIZON_URLS[NETWORK] ||
   HORIZON_URLS.testnet;
 
-const rpcServer = new SorobanRpc.Server(rpcUrl, { allowHttp: false });
+const rpcServer = new SorobanRpcNs.Server(rpcUrl, { allowHttp: false });
 const horizonServer = new Horizon.Server(horizonUrl);
 
 const CONTRACT_IDS = {

backend/src/routes/stellar.js

@@ -1,6 +1,7 @@
 const { Router } = require("express");
 const { body, query, param } = require("express-validator");
 const rateLimit = require("express-rate-limit");
+const { MemoryStore } = rateLimit;
 const validate = require("../middleware/validate");
 const { horizonServer, NETWORK, CONTRACT_IDS } = require("../config/stellar");
 const {
@@ -13,10 +14,24 @@ const {
   submitSignedTx,
 } = require("../services/listingService");
 const { getAccountTransactions } = require("../services/transactionService");
+const { fundAccount } = require("../services/friendbotService");
 const { isValidStellarAddress } = require("../utils/stellar");
 
 const router = Router();
 
+// ── Per-IP rate limiter for the Friendbot funding endpoint ────────────────────
+// 1 request per IP per 60-minute window. The store is kept as a standalone
+// reference so tests can reset it between cases.
+const fundLimiterStore = new MemoryStore();
+const fundRateLimiter = rateLimit({
+  windowMs: 60 * 60 * 1000,
+  max: 1,
+  store: fundLimiterStore,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: "Only one Friendbot request is allowed per IP per hour. Please try again later." },
+});
+
 // ── Per-key rate limiter for the transactions endpoint ────────────────────────
 // Keyed on the publicKey path param so each Stellar address gets its own quota.
 // 30 requests per 60-second window per key.
@@ -224,3 +239,6 @@ router.post(
 );
 
 module.exports = router;
+
+// Exposed so tests can clear the funding rate limiter between cases.
+module.exports.resetFundRateLimiter = () => fundLimiterStore.resetAll();

backend/src/services/friendbotService.js

@@ -0,0 +1,44 @@
+/**
+ * friendbotService.js
+ *
+ * Funds a Stellar Testnet account via Stellar Friendbot, the public faucet
+ * service for the test network. Only ever call this against Testnet — the
+ * caller (the /fund route) is responsible for the Mainnet restriction.
+ */
+
+const FRIENDBOT_URL = "https://friendbot.stellar.org";
+
+/**
+ * Request Friendbot funding for a Testnet account.
+ *
+ * @param {string} publicKey - Stellar G-address to fund
+ * @returns {Promise<{ publicKey: string, funded: boolean, hash: string|null }>}
+ */
+async function fundAccount(publicKey) {
+  let response;
+  try {
+    response = await fetch(`${FRIENDBOT_URL}?addr=${encodeURIComponent(publicKey)}`);
+  } catch {
+    throw new Error("Unable to reach Stellar Friendbot. Please try again later.");
+  }
+
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    // Friendbot did not return a JSON body; fall through with a generic message.
+  }
+
+  if (!response.ok) {
+    const detail = body?.detail || body?.title || "Friendbot funding request failed.";
+    throw new Error(detail);
+  }
+
+  return {
+    publicKey,
+    funded: true,
+    hash: body?.hash ?? null,
+  };
+}
+
+module.exports = { fundAccount, FRIENDBOT_URL };

frontend/README.md

@@ -66,6 +66,7 @@ http://localhost:3000
 | `npm run build` | Create a production build |
 | `npm run start` | Start the production server |
 | `npm run lint` | Run ESLint |
+| `npm test` | Run component tests (Jest + React Testing Library) |
 
 ---
 

frontend/jest.config.js

@@ -0,0 +1,15 @@
+const nextJest = require("next/jest");
+
+const createJestConfig = nextJest({ dir: "./" });
+
+/** @type {import('jest').Config} */
+const customJestConfig = {
+  testEnvironment: "jest-environment-jsdom",
+  setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"],
+  moduleNameMapper: {
+    "^@/(.*)$": "<rootDir>/src/$1",
+  },
+  testMatch: ["**/__tests__/**/*.test.[jt]s?(x)"],
+};
+
+module.exports = createJestConfig(customJestConfig);

frontend/jest.setup.ts

@@ -0,0 +1 @@
+import "@testing-library/jest-dom";

frontend/src/app/wallet/page.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import WalletFundingButton from "@/components/WalletFundingButton";
+
+interface Balance {
+  asset_type: string;
+  balance: string;
+}
+
+export default function WalletPage() {
+  const [publicKeyInput, setPublicKeyInput] = useState("");
+  const [publicKey, setPublicKey] = useState("");
+  const [network, setNetwork] = useState("");
+  const [balanceXLM, setBalanceXLM] = useState<number | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [notFound, setNotFound] = useState(false);
+
+  useEffect(() => {
+    fetch("http://localhost:4000/api/v1/stellar/network")
+      .then((res) => res.json())
+      .then((data) => setNetwork(data.network))
+      .catch(() => setNetwork(""));
+  }, []);
+
+  useEffect(() => {
+    if (publicKey) fetchBalance(publicKey);
+  }, [publicKey]);
+
+  async function fetchBalance(key: string) {
+    if (!key) return;
+    setLoading(true);
+    setNotFound(false);
+
+    try {
+      const res = await fetch(`http://localhost:4000/api/v1/stellar/account/${key}`);
+
+      if (res.status === 404) {
+        // Unfunded accounts don't exist on the network yet — treat as 0 XLM.
+        setNotFound(true);
+        setBalanceXLM(0);
+        return;
+      }
+
+      if (!res.ok) {
+        setBalanceXLM(null);
+        return;
+      }
+
+      const data = await res.json();
+      const native = (data.balances || []).find(
+        (b: Balance) => b.asset_type === "native"
+      );
+      setBalanceXLM(native ? parseFloat(native.balance) : 0);
+    } catch {
+      setBalanceXLM(null);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <main className="min-h-screen bg-black text-white pt-12 px-6 pb-12">
+      <div className="max-w-xl mx-auto space-y-8">
+        <div>
+          <h1 className="text-3xl font-bold mb-2">Wallet</h1>
+          <p className="text-zinc-400 text-sm">
+            View your account balance and fund it on Testnet for development.
+          </p>
+        </div>
+
+        <div className="bg-zinc-900 border border-zinc-800 rounded-lg p-6 space-y-4">
+          <div>
+            <label className="block text-sm font-semibold mb-2">
+              Stellar Public Key
+            </label>
+            <div className="flex gap-2">
+              <input
+                type="text"
+                value={publicKeyInput}
+                onChange={(e) => setPublicKeyInput(e.target.value)}
+                placeholder="G..."
+                className="flex-1 px-4 py-2 bg-zinc-800 border border-zinc-700 rounded-lg text-white placeholder-zinc-500 focus:outline-none focus:border-purple-500 text-sm"
+              />
+              <button
+                onClick={() => setPublicKey(publicKeyInput.trim())}
+                className="px-4 py-2 bg-zinc-800 hover:bg-zinc-700 border border-zinc-700 rounded-lg text-sm font-semibold transition-colors"
+              >
+                Connect
+              </button>
+            </div>
+          </div>
+
+          {publicKey && (
+            <div className="pt-4 border-t border-zinc-800 space-y-4">
+              <div className="flex justify-between items-center">
+                <span className="text-zinc-400 text-sm">Balance</span>
+                <span className="font-semibold">
+                  {loading
+                    ? "Loading…"
+                    : balanceXLM !== null
+                    ? `${balanceXLM} XLM`
+                    : "Unable to load balance"}
+                </span>
+              </div>
+
+              {notFound && (
+                <p className="text-xs text-zinc-500">
+                  This account doesn&apos;t exist on the network yet — fund it
+                  to activate it.
+                </p>
+              )}
+
+              {balanceXLM !== null && (
+                <WalletFundingButton
+                  publicKey={publicKey}
+                  network={network}
+                  balanceXLM={balanceXLM}
+                  onFunded={() => fetchBalance(publicKey)}
+                />
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+    </main>
+  );
+}