Vaulta MVP

Vaulta is a private custody operations console built with React + TypeScript. It demonstrates an end-to-end workflow:

• Live demo: https://vaulta-theta.vercel.app/

• enter the console

• view portfolio balances

• create outbound transfers with policy checks

• approve 2-of-3 to move a transfer through its lifecycle to completion

• see an activity feed for audit-style events

Evaluate this repo in 2 minutes

• Locally (recommended):

pnpm install
pnpm run validate

pnpm run validate is the single quality gate: unit tests + lint + build + Playwright E2E.

Tech stack

• React + TypeScript + Vite
• React Router
• TanStack Query
• Tailwind + shadcn/ui primitives
• Vitest unit tests (policy + lifecycle contracts)
• Playwright E2E (golden path)
• decimal.js for precise money/amount handling

Prerequisites

• Node.js + pnpm

What’s mocked vs real

• Simulated: custody provider API, persistence, auth, on-chain execution, monitoring/alerting.
• In-repo contracts: policy evaluation outputs, transfer lifecycle/state machine, number-handling discipline.

Getting started

pnpm install
pnpm dev

Vite will print the local dev URL (typically http://localhost:5173).

Common scripts

pnpm dev
pnpm test
pnpm lint
pnpm build
pnpm preview
pnpm test:e2e
pnpm run validate

pnpm run validate runs unit tests + lint + build + Playwright.

What’s “done” in the MVP (current state)

• Connect flow (/ → /dashboard)
• Dashboard: balances/portfolio primitives
• Transfers: create + policy preview + transfer details + approvals
• Activity: audit events, including transfer_completed
• Deterministic E2E golden path: e2e/golden-path.spec.ts

More detail: docs/PROJECT-STATUS.md.

Key engineering decisions

• Policy engine is a pure module with explicit pass/warn/fail outputs (src/lib/custody/policy-engine.ts) and unit tests to lock behavior.
• Transfer lifecycle is a state machine that guards impossible transitions (src/lib/custody/transfer-machine.ts) with unit tests as a contract.
• Single quality gate: pnpm run validate is the “green means shippable” contract.
• Deterministic E2E: stable selectors + deterministic scheduler settings in Playwright config.
• No float money math: uses decimal.js and documents number handling (docs/NUMBER-HANDLING.md).

Terminology (canonical)

• Policy: rules that evaluate a transfer and return pass/warn/fail outcomes (some failures block).
• Approvals: multi-party authorization to progress a transfer (simulated 2-of-3 in this MVP).
• Audit / Activity: the event trail for session + transfer lifecycle events (UI surface: Activity feed).
• Transfer lifecycle: the state machine that governs valid/invalid status transitions.

Manual smoke test (fast)

1. pnpm dev
2. Open the app and enter the console.
3. Create a transfer (Destination + Asset + Amount) and review policy checks.
4. Approve with any 2 distinct roles → transfer should reach Completed.
5. Verify the transfer appears in Transfers table and Activity feed.

Architecture (brief, with file pointers)

• Routing: src/app/router.tsx (Connect, Dashboard, Transfers, Activity, Settings)
• Mock custody backend: src/lib/custody/mock-api.ts
  • policy gating: src/lib/custody/policy-engine.ts
  • workflow timings + state transitions: src/lib/custody/transfer-machine.ts
• Number handling (authoritative): docs/NUMBER-HANDLING.md
• Golden path E2E: e2e/golden-path.spec.ts

More context (2-minute read): docs/PROJECT-STATUS.md.

Engineering notes

• This repo intentionally uses a simulated custody API and seeded data so reviewers can run the full workflow locally.
• The end-to-end workflow is locked by Playwright in e2e/ and a single command (pnpm run validate).

Engineering rules (core)

• shadcn/ui over custom components: if a UI primitive/component is needed and it’s not already in src/components/ui/, install it via shadcn instead of hand-rolling a custom one (unless there is a clear blocker).
• Don’t break E2E selectors: keep data-testid stable for e2e/golden-path.spec.ts.
• Numeric correctness matters: follow docs/NUMBER-HANDLING.md (no JS floats for money logic).

Documentation (source of truth)

• Product thesis: docs/PRODUCT-THESIS.md
• Project status: docs/PROJECT-STATUS.md
• Project rules: docs/RULES.md
• Architecture: docs/ARCHITECTURE.md
• Decisions (ADRs): docs/decisions/

Editor rules (Cursor)

This repo uses Cursor rules in .cursor/rules/:

• Core always-on rules: .cursor/rules/00-core.mdc
• File-scoped rules: .cursor/rules/react-typescript.mdc, .cursor/rules/ui-shadcn.mdc, .cursor/rules/testing.mdc