Policy-controlled Bitcoin treasury for AI agents — a deterministic policy engine (auto-approve / escalate / reject), Gemini for agent missions and in-app help, and Lightning-style settlement using real SHA-256 preimage / payment_hash primitives, plus internal vs competitor transaction views.

flowchart LR
  subgraph ui [Next.js]
    D[Dashboard]
    A[Agents / Approvals]
    T[Transactions]
  end
  subgraph api [Hono API :4000]
    PE[Policy engine]
    AG[Gemini + fallback]
    LN[SHA-256 / HTLC-style]
  end
  DB[(Supabase Postgres)]
  ui --> api
  PE --> DB
  AG --> PE
  LN --> DB

This repo is one Eclipse application: a Next.js UI and a Hono API that share one product surface. They live in two npm packages for clarity and deployment.

From the repo root, npm run dev starts both; see Run locally below.

Architecture (diagrams + API inventory): ARCHITECTURE.md.

Deploy (Vercel frontend + separate API host): DEPLOY.md.

Configure backend in eclipse-backend/.env (copy from eclipse-backend/.env.example):

• Required: SUPABASE_SERVICE_ROLE_KEY, NEXT_PUBLIC_SUPABASE_URL
• Optional: NEXT_PUBLIC_SUPABASE_ANON_KEY (server), GEMINI_API_KEY (live missions, synthesis, Eclipse Help chat; fallbacks work without it), GEMINI_MODEL (defaults to gemini-2.5-flash-lite with quota fallbacks), DATABASE_URL, TREASURY_INITIAL_SATS, TREASURY_WIF (real testnet spends when funded)

Configure frontend in eclipse-frontend/.env.local (copy from eclipse-frontend/.env.example):

• NEXT_PUBLIC_API_URL — optional; defaults to http://localhost:4000

Treasury math: TREASURY_INITIAL_SATS (default 1.5M) + sum(treasury_topups) − sum(settled transactions). Header balance follows ledger vs on-chain rules described in the API (/api/treasury/balance).

1. Prefer DATABASE_URL in eclipse-backend/.env so npm run migrate (or API startup) applies supabase/migrations/*.sql in order.
2. If npm run migrate fails with EHOSTUNREACH, use the Session pooler URI from Supabase → Connect → Session pooler, then migrate again.
3. Alternative: run eclipse-backend/supabase/FULL_SCHEMA.sql once in the Supabase SQL Editor on an empty project.

Without tables, the UI may show missing-table errors until the schema exists.

1. Copy eclipse-backend/.env.example → eclipse-backend/.env and eclipse-frontend/.env.example → eclipse-frontend/.env.local; fill Supabase (and optional Gemini) from your dashboard.
2. Repo root: npm install && npm run dev (API + web). Or run npm run dev inside eclipse-backend and eclipse-frontend in two terminals.
3. Open http://localhost:3000
4. Judge path: Run Demo in the sidebar → http://localhost:3000/demo

GitHub Actions (.github/workflows/ci.yml) on main: backend tsc + tests, frontend lint + tests + production build.

• Backend: cd eclipse-backend && npm test — policy engine, Lightning settlement helpers, Gemini mission (mocked).
• Frontend: cd eclipse-frontend && npm test — helpers and CSV export.
• Root: npm run ci — full pipeline.

• curl http://127.0.0.1:4000/health → {"ok":true}
• With schema: curl http://127.0.0.1:4000/api/dashboard → summary + recent_activity

MIT — see LICENSE.