Getting Started

Production onboarding path for FlowVault, from first install to validated deposit flow, including a handoff format for AI-assisted implementation.

Audience: Web3 engineers and AI coding agentsMode: Implementation

Overview

FlowVault combines Clarity contracts with a typed TypeScript SDK and wallet-first frontend architecture. Every write operation is executed on-chain and client layers are responsible for validation and UX.

Goal: complete one verified cycle: configure routing rules, deposit, read state, and withdraw unlocked balance.

Workspace Architecture

Package	Responsibility	Entry Action
flowvault-contracts	On-chain routing behavior, lock mechanics, transfer invariants.	`clarinet check` and `npm test`
flowvault-sdk	Typed interface for write/read calls and parsing of Clarity values.	`npm run build` and integration tests
flowvault-frontend	Wallet connection, transaction approval UX, and state polling.	`npm run dev` with testnet env vars

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-v2
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.

Rule: keep contract and token principals from the same network. Mixed testnet/mainnet pairs are invalid.

Smoke Test

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

AI Handoff Packet

When delegating implementation to an AI assistant, provide this minimum context package in one message.

Project: FlowVault integration
Network: testnet
Contract: STD7QG84VQQ0C35SZM2EYTHZV4M8FQ0R7YNSQWPD.flowvault-v2
Token: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx
Wallet mode: @stacks/connect request("stx_callContract")
Required flows: setRoutingRules, deposit, getVaultState, withdraw
Validation: enforce STX address only, future lock block, split rules
Output required: TS code, env config, and runbook commands