Appearance
v1.2 Protocol Admin Dashboard
Shipped: 2026-04-06 | Phases: 10 (14–23) | Plans: 36 | Git: 115 commits, 148 files, +32,702 lines
The largest milestone by phase count. v1.2 built the internal operations dashboard that gives protocol administrators visibility into billing health, merchant activity, and protocol state — with write operations gated by on-chain PDAs, not environment allowlists.
What Shipped
Phase 14: Admin Worker Scaffold + Auth
The foundation of the admin dashboard.
vela-adminCloudflare Worker — Standalone Worker at admin.velapay.io- SIWS wallet authentication — Gated to ProtocolConfig PDA admin field (no env allowlists, no hardcoded wallets)
- Audit log D1 table — Immutable audit trail for every admin action
- Service binding pattern — Admin Worker communicates with Dashboard Worker via internal service binding, no cross-origin complexity
- Wave-0 test stubs — 3 stub files with 3 pass, 8 todo, 0 fail, establishing the test-first discipline
Phase 15: Read-Only Monitoring
Protocol health visibility for admins.
- TVL, mandate counts, merchant stats — Real-time protocol metrics
- Keeper queue depth/health — Monitor the billing automation pipeline
- Traffic-light system health grid — Visual indicator for 5 subsystems (green/amber/red)
- ProtocolConfig/KeeperConfig PDA viewers — On-chain config with RPC staleness indicators
- TypeScript types for 10 API endpoints — Full type safety across admin API surface
- 7 TanStack Query hooks — All with
staleTime: Infinityfor admin data freshness control - 4 shared monitoring components — CSS traffic-light tokens for health visualization
Phase 16: Keeper Write Operations
Destructive admin actions with safety mechanisms.
- Force-retry failed billing schedules — Manually trigger retry for stuck pulls
- Merchant ban/suspend/restore — Status management with typed confirmation dialogs
- D1 migration — Added status column and audit trail for every admin action
- Simulation previews — Preview transaction before signing
- 7 shared components — ConfirmationDialog, SimulationPreview, TypedConfirmationInput, ActionToast, TxSignatureLink, PubkeyInput, MerchantStatusBadge
Phase 17: On-Chain Emergency Controls
Protocol-level emergency powers deployed to devnet.
- 3 new Anchor instructions:
pause_protocol,unpause_protocol,admin_cancel - Dashboard UI — Typed confirmation gates ("type PAUSE PROTOCOL to confirm")
- Protocol paused banner — Amber banner in merchant dashboard polls RPC every 60s
- SDK instruction builders — 3 emergency builders with VelaClient integration
- 8 LiteSVM E2E tests — Full emergency instruction coverage
Phase 18: Observability + Hardening
The monitoring and debugging layer.
- Real-time event stream — Live billing event feed
- Webhook pipeline health — Monitor Helius webhook delivery
- On-chain/D1 reconciliation — Cross-check on-chain state against D1 cache
- Vault invariant monitor — Verify vault balance ≥ mint supply
- Program deployment status — Track program deployment state
- Keeper cost tracking — SOL/day cost monitoring with sparkline charts
- Historical snapshots — Date comparison with delta calculation
- CSV export — Metrics, audit log, and merchant table export
Phases 19–23: Validation + Gap Closure
Five phases dedicated to closing validation debt and fixing gaps found during execution.
- Phase 19: Admin audit + write validation — Fixed merchant restore audit semantics, closed deferred test stubs
- Phase 20: Monitoring accuracy — Replaced merchant status placeholder, closed Phase 15 Nyquist gaps
- Phase 21: Emergency controls + typecheck cleanup — Closed Phase 17 validation debt, resolved TypeScript errors
- Phase 22: Observability validation — Phase 18 Nyquist coverage for activity, export, reconciliation flows
- Phase 23: Milestone gap closure — D1 snapshot migrations, EmergencyCancelButton refactored to derive credential accounts from on-chain PDA data
What Worked
Service Binding Pattern
Admin Worker → Dashboard Worker via env.BACKEND_WORKER.fetch() for D1 access. Zero cross-origin complexity, no exposed endpoints. This became the template for any Worker-to-Worker internal API.
Wave-0 Test Stub Discipline
Writing test stubs upfront in Phase 14/16 and closing them in Phase 19 worked well structurally. The stubs served as a tracking mechanism for deferred validation work.
Injectable Dependencies for Testing
The verifyAdminAccess(wallet, { _fetchAdmin }) pattern from Phase 14 made unit testing zero-network. Applied consistently across admin RPC modules.
On-Chain Source of Truth for Auth
ProtocolConfig PDA as the sole admin gate was clean. No env allowlists, no hardcoded wallets. Credential derivation moving fully on-chain in Phase 23 validated this philosophy.
Gap Closure Phases
Phases 20–23 as explicit debt retirement was effective. Kept main feature phases clean and surfaced validation gaps systematically.
What Was Inefficient
Phase Directory Fragmentation
Phases 20–22 were executed outside the workstream directory structure (.planning/phases/ vs .planning/workstreams/protocol-admin-dashboard/phases/). Required a manual sync pass at milestone completion. Future: run all phases within the active workstream directory.
Missing SUMMARY.md Files
Plans 19-03 and 19-04 were executed but summaries were never created. GSD tooling reported phase as in-progress. Stubs had to be created retroactively. Future: always write SUMMARY.md immediately after plan execution.
Audit File Stored Outside Workstream
v1.2-MILESTONE-AUDIT.md landed in .planning/ not .planning/workstreams/protocol-admin-dashboard/. Tooling couldn't find it automatically.
REQUIREMENTS.md Carry-Forward
DASH-01..08 (v1.0 merchant dashboard requirements) appeared unchecked in v1.2 REQUIREMENTS.md. Likely a copy issue from previous milestone.
Patterns Established
These patterns from v1.2 persisted through all subsequent milestones:
Service Binding RPC
Admin Worker calls Dashboard Worker via env.BACKEND_WORKER.fetch() for D1 access. Avoids direct D1 binding on admin Worker. Template for any Worker-to-Worker internal API.
Browser-Signs, Server-Logs
Admin transactions built in browser (Kit instruction builders), signed via wallet adapter, submitted via Helius RPC, then logged to audit trail with tx signature. The server never holds keys; it only records what happened.
Credential Derivation at Transaction Time
Never cache credential accounts in D1 for high-stakes operations. Derive from on-chain PDA bytes at getAccountInfo time. Established in Phase 23 after discovering that D1 cache coupling caused emergency cancel to fail for pre-migration subscribers.
Typed Confirmation Gates
Destructive admin actions require typing the exact action string ("PAUSE PROTOCOL", "BAN MERCHANT"). Implemented as TypedConfirmationInput component with disabled submit until match.
Key Lessons
- Workstream directory discipline matters — All phase artifacts must land in the workstream directory from the start. Post-hoc syncing is error-prone and confuses progress tracking.
- Write SUMMARY.md before closing a plan — The executor should always write the summary as the final step, even if brief. Missing summaries block tooling and require retroactive stub creation.
- Validation phases are worth planning explicitly — Phases 20–22 as dedicated validation/Nyquist closure phases were effective. Don't squeeze validation into feature phases — it gets deprioritized.
- On-chain derivation > cache for security-critical paths — Any operation that burns tokens or changes mandate state should derive accounts from on-chain data at call time. D1 is a UI cache, not an authoritative source.
Cost Observations
- Model mix: Opus 4.6 primary (quality profile), Sonnet for subagents
- Timeline: 4 days for 10 phases / 36 plans
- Velocity: ~9 plans/day average, accelerating through gap closure phases
- Notable: Gap closure phases (20–23) averaged 1 plan/phase vs 5–6 plans/phase for feature phases