QuaiVault Frontend
Multisig wallet management UI for Quai Network, powered by QuaiVault smart contracts with Zodiac IAvatar compatibility.
Related Repositories
Key Features
- Decentralized-First — All core functionality works directly via RPC without backend dependencies
- Real-Time Updates — Supabase subscriptions with automatic polling fallback
- Hybrid Data Fetching — Indexer for fast reads, blockchain for writes, automatic fallback when indexer is unavailable
- Transaction Management — Propose, approve, execute, cancel, and revoke approvals with configurable timelocks and expiration
- Multi-Asset Support — Native QUAI, ERC-20 tokens, ERC-721 NFTs, and ERC-1155 semi-fungibles
- Owner Management — Add/remove owners and change approval thresholds via multisig proposals
- Social Recovery — Guardian-based vault recovery via the SocialRecoveryModule
- Message Signing — EIP-1271 message signing and unsigning with browsable history
- Contract Interaction — ABI auto-fetch, function selector, and custom calldata builder
- Modern UI — Dark vault theme with responsive design, toast notifications, and accessibility features
Tech Stack
| Category | Libraries |
|---|
| Framework | React 18, TypeScript, Vite |
| Blockchain | quais.js (Quai SDK), viem, wagmi |
| Wallet Connect | Reown AppKit, WalletConnect |
| Data Fetching | TanStack React Query |
| State Management | Zustand (persisted) |
| Styling | TailwindCSS (custom vault theme) |
| Backend | Supabase (indexer, real-time subscriptions) |
| Validation | Zod, React Hook Form |
| Testing | Vitest, Testing Library |
Quick Start
Prerequisites
- Node.js 18+
- npm or yarn
- Pelagus wallet browser extension (or WalletConnect-compatible wallet)
Installation
npm install
Environment Configuration
Copy the environment template and configure:
cp .env.example .env
Required environment variables:
# Network
VITE_RPC_URL=https://orchard.rpc.quai.network
VITE_CHAIN_ID=15000
# Mainnet: https://explorer.qu.ai
VITE_BLOCK_EXPLORER_URL=https://orchard.quaiscan.io
# Contract addresses (from quaivault-contracts deployment)
VITE_QUAIVAULT_IMPLEMENTATION=0x...
VITE_QUAIVAULT_FACTORY=0x...
VITE_SOCIAL_RECOVERY_MODULE=0x...
VITE_MULTISEND=0x...
# Indexer (optional — enables real-time updates and fast queries)
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key
VITE_NETWORK_SCHEMA=dev
VITE_INDEXER_URL=https://index.devnet.quaivault.org
# DAO Ships metadata (optional; defaults to the indexer settings above)
VITE_DAOSHIPS_SUPABASE_URL=https://your-project.supabase.co
VITE_DAOSHIPS_SUPABASE_ANON_KEY=your-anon-key
VITE_DAOSHIPS_NETWORK_SCHEMA=testnet
VITE_DAOSHIPS_APP_URL=https://testnet.daoships.org
# WalletConnect
VITE_WC_PROJECT_ID=your-walletconnect-project-id
# NFT metadata resolution
VITE_IPFS_GATEWAY=https://ipfs.qu.ai
VITE_NFT_IPFS_GATEWAY=https://ipfs.io
# Site metadata
VITE_SITE_URL=https://testnet.quaivault.org
VITE_GITHUB_URL=https://github.com/Quai-Vault/quaivault-frontend
See .env.example for defaults and all options.
Development
npm run dev
The app runs at http://localhost:5173.
Build
npm run build # Type-check + production build → dist/
npm run preview # Preview the production build locally
Project Structure
src/
├── components/ # UI components
│ ├── transaction/ # Transaction forms (SendToken, SendNft, SignMessage, etc.)
│ ├── Modal.tsx # Accessible modal with focus trap
│ ├── OwnerManagement.tsx # Owner list and management
│ ├── ModuleManagement.tsx # Module configuration panel
│ ├── WalletCard.tsx # Vault card for dashboard
│ ├── Layout.tsx # App shell (sidebar + content)
│ └── ... # 36 components total
├── pages/ # Route pages
│ ├── Dashboard.tsx # Vault list (owned + guardian)
│ ├── WalletDetail.tsx # Vault overview, pending txs, owners, modules
│ ├── CreateWallet.tsx # Vault deployment wizard
│ ├── NewTransaction.tsx # Propose transaction (6 modes)
│ ├── TransactionHistory.tsx
│ └── LookupTransaction.tsx
├── services/ # Blockchain and data services
│ ├── core/ # WalletService, TransactionService, OwnerService
│ ├── modules/ # SocialRecoveryModuleService
│ ├── indexer/ # Supabase indexer queries, subscriptions, health
│ ├── utils/ # Gas estimation, error handling, metadata, verification
│ └── MultisigService.ts # Facade — indexer-first with blockchain fallback
├── hooks/ # 17 custom React hooks
├── store/ # Zustand stores (wallet, theme)
├── config/ # Chain config, ABIs, provider, Supabase client
├── types/ # TypeScript type definitions
├── utils/ # Formatting, validation, clipboard
└── test/ # Test setup and mocks
Routes
| Path | Page | Purpose |
|---|
/ | Dashboard | Lists owned vaults and guardian-only vaults |
/create | CreateWallet | Deploy a new multisig vault |
/wallet/:address | WalletDetail | Balance, pending transactions, owners, modules, assets |
/wallet/:address/transaction/new | NewTransaction | Propose a transaction (send QUAI, tokens, NFTs, contract calls, message signing) |
/wallet/:address/history | TransactionHistory | Executed, cancelled, expired, and failed transactions |
/wallet/:address/lookup | LookupTransaction | Search for a specific transaction by hash |
Architecture
Service Layer
The service layer follows a facade + fallback pattern:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
