Getting Started

Quickstart

Get RegVault Protocol running locally or deployed to devnet in minutes.

Prerequisites

Node.js 20+ and pnpm 9+
Rust toolchain (for program builds)
Solana CLI 1.18+
Anchor 0.32+

Tip

Install the full toolchain with: pnpm toolchain:install

Option 1: Localnet (Recommended for Development)

Step 1: Install Dependencies

pnpm install

Step 2: Run the One-Command Demo

This starts a local validator, deploys programs, initializes the vault, and seeds demo data:

pnpm demo:local

What happens automatically

Starts solana-test-validator with programs deployed
Creates mock USDC mint and rvUSDC share mint with Transfer Hook
Initializes vault config with role assignments
Creates demo entities, wallets, and attestations
Starts the Next.js dev server on port 3000

Step 3: Verify Installation

Run the release check to validate the entire stack:

pnpm release:check

Step 4: Open the Dashboard

Visit http://localhost:3000 and explore:

Connect a wallet to see role badges
Check Transfer Hook health status
View the Withdrawal Queue
Browse Immutable Receipts
Run operator simulations

Option 2: Devnet Deployment

Step 1: Deploy Programs

pnpm deploy:devnet

Step 2: Initialize Protocol

pnpm init:devnet

Funding required

Devnet deployment requires SOL for program deployment and initialization. If airdrops fail, fund the printed keypairs from the devnet faucet and re-run pnpm init:devnet.

Step 3: Configure Environment

Copy the printed environment variables from the init output into apps/web/.env.local:

Variable	Description
NEXT_PUBLIC_RPC_URL	Solana RPC endpoint
NEXT_PUBLIC_CLUSTER	localnet \| devnet
NEXT_PUBLIC_REGVAULT_PROGRAM_ID	Regvault program ID
NEXT_PUBLIC_SHARE_HOOK_PROGRAM_ID	Share hook program ID
NEXT_PUBLIC_VAULT_CONFIG	Vault config PDA
NEXT_PUBLIC_DEPOSIT_MINT	USDC mint address
NEXT_PUBLIC_SHARE_MINT	rvUSDC share mint
NEXT_PUBLIC_ADMIN	Admin wallet pubkey
NEXT_PUBLIC_COMPLIANCE	Compliance role pubkey
NEXT_PUBLIC_OPERATOR	Operator role pubkey

Step 4: Deploy to Vercel

Import your repo into Vercel
Set project root to apps/web
Add all environment variables from above
Use build command: pnpm -w build
Deploy and verify /dashboard shows healthy hook wiring

Troubleshooting

Airdrop Failures

Devnet airdrops can be rate-limited. If initialization fails with insufficient funds, visit the Solana Faucet and fund the printed wallet addresses manually, then re-run the init command.

RPC Rate Limits

For production deployments, use a dedicated RPC endpoint like Helius or QuickNode. Update NEXT_PUBLIC_RPC_URL in your environment config.

Hook Wiring Errors

If the dashboard shows "Attention required" for Transfer Hook health, verify:

Share mint has Transfer Hook extension configured
ExtraAccountMetaList PDA exists and is owned by share_hook program
Environment variables match deployed program IDs

Next: Architecture →