Getting Started

End-to-end setup for contracts, SDK, and frontend, including required checks before your first successful vault deposit.

Overview

FlowVault provides deterministic stablecoin routing via Clarity smart contracts and a typed TypeScript SDK. In a normal workflow you deploy contracts, configure environment variables, connect a wallet, configure routing rules, then execute deposits and withdrawals.

The stack is split into three independently deployable packages:flowvault-contracts, flowvault-sdk, andflowvault-frontend. This separation lets you upgrade UI logic without changing on-chain behavior.

Prerequisites

  • Node.js 18+
  • Clarinet 3.13+
  • Stacks wallet (Leather, Xverse, Hiro)
  • Testnet STX and USDCx test liquidity
  • A deployment account with sufficient STX for fees

Quick Path

1) Contract workspace

cd flowvault-contracts
npm install
clarinet check
npm test

Ensure all tests pass before deployment. Failed tests usually mean routing math or lock timing logic changed.

2) Frontend workspace

cd flowvault-frontend
npm install
npm run dev

Start in development mode first so you can verify wallet connection and read-only calls before sending transactions.

3) SDK workspace

cd flowvault-sdk
npm install
npm test
npm run build

Keep SDK and frontend versions aligned. If frontend behavior differs from docs, check your installed SDK version.

Environment Setup

NEXT_PUBLIC_FLOWVAULT_NETWORK=testnet
NEXT_PUBLIC_FLOWVAULT_CONTRACT_ADDRESS=STD7QG84VQQ0C35SZM2EYTHZV4M8FQ0R7YNSQWPD
NEXT_PUBLIC_FLOWVAULT_CONTRACT_NAME=flowvault
NEXT_PUBLIC_FLOWVAULT_TOKEN_CONTRACT_ADDRESS=ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
NEXT_PUBLIC_FLOWVAULT_TOKEN_CONTRACT_NAME=usdcx

For mainnet migration, switch both contract principals together. Mixed environments are the most common source of failed transfers.

Smoke Test

  1. Connect wallet and confirm an STX address is detected.
  2. Call read methods: getVaultState and getRoutingRules.
  3. Set routing rules with no split and a short lock duration.
  4. Deposit a small amount and confirm tx id is returned.
  5. Refresh state and verify unlocked or locked balances changed.