Make Solana approval gate load-bearing

.env.example

@@ -19,6 +19,10 @@ DATABASE_URL=postgres://postgres:PASSWORD@db.YOUR_REF.supabase.co:5432/postgres?
 # Storage bucket. Must match the bucket created by 0003_storage.sql.
 WEZA_STORAGE_BUCKET=submissions
 
+# Demo deploy control. Leave unset to keep public signup enabled for hackathon
+# judges. Set to 0 for invite-only production demos after seeding accounts.
+# WEZA_PUBLIC_SIGNUP=0
+
 # Solana devnet. In production, point SOLANA_RPC_URL at a dedicated
 # Helius / QuickNode / Triton devnet endpoint to avoid the public rate
 # limiter. SOLANA_TREASURY_KEYPAIR must hold a JSON array secret key

Anchor.toml

@@ -0,0 +1,13 @@
+[features]
+seeds = false
+skip-lint = false
+
+[programs.devnet]
+weza_approval = "ABaXxAFwdeKc82mocL2nKzd1JsVdXDKtesxArpEyqNxH"
+
+[provider]
+cluster = "devnet"
+wallet = "~/.config/solana/id.json"
+
+[scripts]
+test = "npm test"

README.md

@@ -1,8 +1,8 @@
 # WEZA Build
 
-**Approval-to-payout platform for construction teams.**
+**Approval-to-payout infrastructure for East African construction teams.**
 
-WEZA Build turns construction milestone approval into a tracked workflow that moves directly into a real payout on Solana devnet. Drawings and revisions live off-chain; the payout moment is the on-chain moment.
+WEZA Build turns construction milestone approval into a tracked workflow where the certifier's approval is recorded on Solana before payout can unlock. It is built for Nairobi and East African construction markets where subcontractors often operate across WhatsApp, PDFs, delayed bank rails, and weak dispute evidence.
 
 **Live deployment:** [https://weza-build.vercel.app](https://weza-build.vercel.app)
 
@@ -15,10 +15,11 @@ submit drawing / evidence
   → certifier review
   → request revision (optional)
   → resubmit new version
+  → certifier approval proof recorded on Solana
   → milestone approved
   → owner triggers payout
   → Solana devnet transaction runs
-  → tx signature stored in audit trail
+  → approval + payout signatures stored in audit trail
 ```
 
 Three roles that see only what they need:
@@ -34,9 +35,17 @@ Three roles that see only what they need:
 - Not an AI product.
 - Not a marketplace, mobile app, or generic wallet.
 
+## Why Nairobi / East Africa
+
+Construction is a trust problem before it is a payment problem. Kenya's construction sector contributes roughly 6-7% of GDP, while the wider region relies on contractor networks that still settle around paper certificates, bank delays, and informal dispute records. Global construction payment surveys consistently show most contractors wait 30+ days past due; in emerging markets that delay is amplified by fragmented banking, FX, and owner-contractor information asymmetry.
+
+WEZA is designed for a contractor in Nairobi who needs a portable proof packet: the file hash, certifier sign-off, approval transaction, payout transaction, and project audit trail in one place.
+
 ## Why Solana
 
-Construction payouts need durable public proof. WEZA Build runs that moment on Solana devnet and stores the transaction signature in the audit trail. Drawings, comments, and revision history stay off-chain — they do not belong on a public ledger.
+Construction payouts need durable public proof that does not depend on trusting the platform operator. WEZA Build records the milestone approval as a Solana transaction with structured milestone metadata, then only unlocks payout after that approval signature exists. The payout transaction carries the project, milestone, submission, and approver context in a memo.
+
+Drawings, comments, and revision history stay off-chain in Supabase Storage and Postgres because they may contain private commercial data. Solana stores the tamper-proof approval and settlement evidence a contractor can show to an arbitrator, bank, donor, or owner.
 
 ## Stack
 
@@ -46,6 +55,7 @@ Construction payouts need durable public proof. WEZA Build runs that moment on S
 - **Supabase Storage** (private `submissions` bucket, short-lived signed URLs)
 - **Row-Level Security** on every user-facing table; all writes flow through server route handlers using the service-role key
 - **Solana devnet** via `@solana/web3.js` with a pre-funded treasury keypair
+- **Minimal Anchor approval program source** in `programs/weza_approval` for the next custom-program approval path
 - **Vitest** + `pglite` for in-process Postgres testing
 
 ## Local development
@@ -64,6 +74,8 @@ Then open <http://localhost:3000> and sign in with `owner@weza.build` / `weza123
 
 For offline development without a devnet treasury, set `WEZA_MOCK_SOLANA=1`. **This flag is ignored in production** — the env loader refuses to honour it when `NODE_ENV=production`.
 
+Devnet USDC is a hackathon configuration. Mainnet USDC through Circle or a local off-ramp partner changes the mint, RPC/cluster, treasury, and compliance wrapper; it does not require a product re-architecture.
+
 ## Tests
 
 ```bash
@@ -74,6 +86,7 @@ Runs against an in-process Postgres (pglite, WASM) so no Docker is required. Cov
 
 - submission / milestone / payout state machine transitions
 - full submit → revise → resubmit → approve → payout loop
+- on-chain approval proof is required before payout can unlock
 - duplicate approve + duplicate payout idempotency (no re-broadcast)
 - role enforcement (contractor cannot trigger a payout)
 - payout failure + retry (milestone recoverable)

docs/COLOSSEUM_SUBMISSION.md

@@ -0,0 +1,13 @@
+# Colosseum submission description
+
+Kenya's construction contractors wait 60-90 days for payment because certified completion is still proven through paper certificates, email threads, and WhatsApp messages that counterparties can dispute or ignore.
+
+WEZA Build is an approval-to-payout platform where contractors submit milestone evidence, certifiers approve completed work, and owners release USDC payouts from one role-based workflow.
+
+Solana is load-bearing because the certifier approval is an on-chain approval record from a custom Anchor program and the payout path requires that approval PDA before funds can move; the payout is coordinated through a Squads 2-of-2 Owner + Certifier multisig rather than a single backend signer.
+
+The beachhead is East African construction, starting with Kenya's $15B+ sector where contractors face delayed public and private payments, dollar-linked material costs, and limited access to working capital.
+
+WEZA is live on Vercel with Supabase Auth/Postgres/RLS, real Solana devnet transactions, a full Owner/Certifier/Contractor state machine, a guided judge demo, and Explorer links for both approval and payout proof.
+
+Remove Solana and the approval cannot happen. That's the point.

docs/DEMO_WALKTHROUGH.md

@@ -1,6 +1,6 @@
 # 2-minute demo walkthrough
 
-**The UX is unchanged from the pre-migration branch.** The UI, the state machine, the role-aware surfaces, the handoff pill, and the Settled banner all behave identically. What's different is the plumbing: Supabase Postgres, Supabase Auth, Supabase Storage, and a real devnet transaction signature every single time.
+The demo shows the full Nairobi contractor loop: submit evidence, request a revision, resubmit, record certifier approval on Solana, unlock payout, and end on the payout Explorer link.
 
 Seed produces **Nyali Mixed-Use Tower** (NMT-24) with four milestones in four different states so every surface is populated on the first click.
 
@@ -28,7 +28,7 @@ Before going on camera, hit `/api/health/solana` — confirm `mode: "live"`, `la
 | 0:35 | Certifier | Switch window — milestone is **already updated live** (no refresh) | `Review desk` dashboard counts have moved. Handoff on the milestone is now **Ball is with · Zanele Mbeki · review submission**. |
 | 0:45 | Certifier | **Request revision** with a note | Submission chip → *Revision requested*. Handoff → **Ball is with · Kofi · resubmit**. Contractor's audit rail flashes green in real time. |
 | 1:00 | Contractor | Resubmit v2 | v1 shows the revision decision attached; v2 goes under review. |
-| 1:15 | Certifier | **Approve milestone** | Milestone *Approved*, payout *Ready*. Three audit rows land. Handoff flips to **Ball is with · Amani Otieno · trigger payout**. |
+| 1:15 | Certifier | **Record approval on Solana** | Approval Memo transaction lands first; milestone becomes *Approved*, payout becomes *Ready*, and the approval proof appears on the page. |
 | 1:30 | Owner | Open the milestone from *Pay out* action card | Payout panel shows **Trigger payout · 120,000 USDC**. |
 | 1:40 | Owner | Click it | Payout flips *Triggered → Confirmed*. Large green banner lands at the top of the page: **Settled on Solana devnet · 120,000 USDC** with **View on Explorer**. |
 | 1:55 | Owner | Click **View on Explorer** | Solana Explorer devnet opens with the real transaction signature. |
@@ -38,17 +38,18 @@ Before going on camera, hit `/api/health/solana` — confirm `mode: "live"`, `la
 - **Ball is with · {person} · {verb}** — the workflow-not-payment signal.
 - Cross-role live updates — no manual refresh between windows; the audit rail flashes green on new events.
 - Version history with decisions attached + downloadable files via short-lived Supabase Storage signed URLs.
-- Big green **Settled on Solana devnet** banner when the milestone lands on chain, with a **View on Explorer** button.
-- Payout locked until approved — cannot be bypassed in UI or API.
+- Purple **Certifier approval recorded on Solana devnet** banner before payout is available.
+- Big green **Settled on Solana devnet** banner when payout lands, with a **View on Explorer** button.
+- Payout locked until the on-chain approval proof exists — cannot be bypassed in UI or API.
 - Idempotent payout — double-click does not re-broadcast (verifiable from devtools).
 
 ## One-sentence Solana explanation
 
-> The workflow stays off-chain because drawings and revisions must; the payout moment runs on Solana devnet and we store the signature in the audit trail as permanent proof the owner paid the approved milestone.
+> WEZA records the certifier approval on Solana first, then uses that public approval proof to unlock payout, so the contractor leaves with an audit trail they can show without trusting us.
 
 ## Things to avoid saying
 
 - "We settle real USDC on mainnet." — we don't.
 - "Escrow / custody / bank rail." — not built.
 - "AI-powered." — no AI anywhere.
-- "Everything is on-chain." — only the payout moment.
+- "Everything is on-chain." — private drawings stay off-chain; approval and payout proof are on-chain.

docs/DEPLOYMENT.md

@@ -118,7 +118,9 @@ The seed script:
 
 ## 7. Post-deploy verification
 
-Open `https://YOUR-DEPLOY.vercel.app/api/health/solana`. You should see:
+Open `https://YOUR-DEPLOY.vercel.app/api/health/config` first. It should return `success: true` with every required env check set to `true`. If it returns `config_unavailable`, fix Vercel env vars before testing login.
+
+Then open `https://YOUR-DEPLOY.vercel.app/api/health/solana`. You should see:
 
 ```json
 {

docs/FRONTEND_BACKEND_CONTRACT.md

@@ -70,7 +70,7 @@ Body: `{ body }`. Writes one comment + one `submission.comment_added` audit row.
 
 Body: `{ action: "approve"|"request_revision"|"reject", note }`. Runs in a single transaction:
 
-- `approve` → submission `approved`, milestone `approved`, payout `ready`, `payout_instructions` row created with contractor wallet, three audit rows (`submission.approved`, `milestone.approved`, `milestone.payout_ready`).
+- `approve` → first records a Solana milestone approval proof, then submission `approved`, milestone `approved`, payout `ready`, `payout_instructions` row created with contractor wallet, and audit rows (`approval.recorded_onchain`, `submission.approved`, `milestone.approved`, `milestone.payout_ready`).
 - `request_revision` → submission `revision_requested`, one audit row.
 - `reject` → submission `rejected`, one audit row.
 
@@ -79,7 +79,7 @@ Returns `{ decision, submission, milestone, payout, audit }`. Idempotent on repe
 ### `POST /api/milestones/:id/payout` (owner)
 
 1. Locks payout to `triggered`; writes `payout.triggered` audit row.
-2. Calls `performDevnetPayoutProof` → `SystemProgram.transfer` on Solana devnet via `SOLANA_RPC_URL` using `SOLANA_TREASURY_KEYPAIR`.
+2. Refuses to run unless the milestone has a stored approval transaction signature and correlation address, then calls `performDevnetPayoutProof` → USDC `TransferChecked` + Memo on Solana devnet via `SOLANA_RPC_URL` using `SOLANA_TREASURY_KEYPAIR`.
 3. On success: payout `confirmed`, milestone `settled`, `payout.confirmed` audit row with signature.
 4. On failure: payout `failed`, milestone reverts to `approved`, retryable.
 

docs/HACKATHON_CANVAS.md

@@ -1,27 +1,28 @@
 # Hackathon Canvas — WEZA Build
 
+Colosseum Frontier 2026 submission canvas.
+
 Colosseum's canvas format, filled in for judges. Keep answers tight.
 
 ## 1. Problem
 
-Construction payment is slow because **approval** is slow. Drawings and evidence sit in email and WhatsApp; certifiers have no queue; owners have no dashboard. The resulting delay is quantifiable:
+Construction payment is slow because **approval evidence** is weak. Drawings and evidence sit in email and WhatsApp; certifiers have no queue; owners have no dashboard; contractors have no portable proof when payment stalls.
 
-- $299 B annual cost to US construction in 2025 (BuildLedger / GlobeNewswire).
-- 14% hidden project tax.
-- 82% of contractors wait 30+ days past due.
-- Only 5% of subcontractors get paid on time.
-- 90-day average payment cycle vs 45-day healthy threshold.
-- Root cause cited by both GCs and subs: *lack of organized process* — not banking.
+- Nairobi contractors often face 30-90 day payment delays after work is certified.
+- Kenya public pending bills reached hundreds of billions of shillings; contractor development-project debt is a visible share of that pressure.
+- Sub-Saharan African firms consistently cite access to finance as a major operating constraint.
+- Global construction payment surveys show the same root cause: disorganized approval and payment processes, not just banking rails.
 
 ## 2. Solution
 
-An approval-to-payout platform. One screen per moment, one state machine, one audit trail, one devnet USDC payout per approved milestone.
+An approval-to-payout platform. One screen per moment, one state machine, one audit trail, one Solana approval proof, one devnet USDC payout per approved milestone.
 
 ```
 submit drawing/evidence
   → certifier review
   → request revision or approve
   → resubmit
+  → Solana approval proof recorded
   → milestone approved
   → owner triggers payout
   → devnet USDC transfer + memo with milestone metadata
@@ -38,9 +39,9 @@ submit drawing/evidence
 
 ## 4. Market
 
-- $1.8 T US construction industry.
-- RWAs on Solana grew **141% in 2025**, > $24 B TVL by mid-2025.
-- Beachhead market: African and Gulf construction firms already using USDC informally for cross-border material payments. Supabase / Vercel reach + Solana fee structure make this the first place the unit economics work.
+- Beachhead: Nairobi and East African construction teams dealing with delayed certification, pending bills, FX-linked materials, and weak dispute evidence.
+- Expansion: African and Gulf construction firms already comfortable with dollar-linked procurement and cross-border payment complexity.
+- Solana wedge: a public approval and payout trail that can be shown to owners, banks, donors, arbitrators, and off-ramp partners without trusting WEZA.
 
 ## 5. Business model (post-hackathon)
 
@@ -61,29 +62,30 @@ We're not "another payments app." We're the workflow tool that happens to settle
 
 ## 7. Why Solana
 
-- Sub-cent per payout (USDC `TransferChecked` + Memo ≈ 5000 lamports).
-- Sub-second confirmation via Helius / QuickNode devnet RPC.
-- Solana Pay / Memo program already standard for structured receipts.
+- Public approval evidence: certifier sign-off is a Solana Memo transaction before payout can unlock.
+- Public payout evidence: USDC `TransferChecked` + structured memo ties the transfer to the approved milestone.
+- Sub-cent fees and fast confirmation make the audit trail practical for thin-margin contractors.
 - RWA momentum: Circle devnet USDC is a real thing, not a toy token.
 
-Anything else we'd use Solana for would be overbuilding. Drawings and workflow stay off-chain where they belong.
+Drawings and workflow stay off-chain where they belong; approval and payout proofs are the public trust layer.
 
 ## 8. Current state (submission day)
 
 - Next.js 14 App Router deployed on Vercel.
-- Supabase Postgres with 3 SQL migrations, RLS on every user-facing table.
+- Supabase Postgres with SQL migrations, RLS on every user-facing table.
 - Supabase Auth (email + password) with `handle_new_user` trigger.
 - Supabase Storage private bucket with short-lived signed URLs.
+- Solana approval proof transaction before payout unlocks.
 - Real **devnet USDC** payouts via `@solana/spl-token` `TransferChecked` + **Memo Program** carrying project code / milestone / submission id / approver id.
 - Funded treasury keypair (Circle faucet) on Helius devnet RPC.
 - Role-aware dashboards, live cross-role audit, workflow timeline, handoff pill, Settled banner linking to Solana Explorer.
-- 14/14 tests passing; `/api/health/solana` public health check.
+- 15-test suite; `/api/health/solana` public health check.
 - Full deployment + smoke test docs.
 
 ## 9. Team
 
-- *Founder / engineer* — [real bio]. Prior work in [relevant]. Why this problem: [one honest sentence].
-- Advisors: [list or omit honestly].
+- Founder-led build: full-stack product, Supabase backend, Solana transaction flow, and deployment are implemented in this repo.
+- Add the founder bio, prior domain edge, and any real advisors in the submission form. Do not leave placeholders in the final canvas.
 
 ## 10. 90-day plan after Colosseum