AI Integration

Production-grade guide for using AI assistants to implement FlowVault correctly in a single prompt, with strict output contracts and validation gates.

Audience: AI coding agents and technical leadsMode: Automation

What It Does

AI Integration mode standardizes how an assistant generates FlowVault integration code. Instead of open-ended prompts, you provide one structured instruction packet that includes network, principals, required operations, and expected files.

This reduces implementation drift and prevents common mistakes such as wrong principals, missing validation, or wallet-unsafe signer usage.

Why Use It

Faster onboarding for new engineers and external implementation teams.
Consistent output format across different AI tools and models.
Lower risk of insecure browser patterns (private key leakage).
Built-in verification checklist that is easy to run in CI and local dev.
Reusable integration contract for future app surfaces and SDK updates.

Use this approach when: you want deterministic, reviewable generated code rather than conversational trial-and-error.

When To Use

Use this page when you want an AI assistant to implement FlowVault into a new or existing frontend with minimal back-and-forth. The prompt below gives enough context for production-shaped code.

Best practice: include exact network + contract principals in the same prompt message.

One Prompt Template

You are integrating FlowVault into a TypeScript frontend.

Use these values:
- network: testnet
- flowvault contract: STD7QG84VQQ0C35SZM2EYTHZV4M8FQ0R7YNSQWPD.flowvault-v2
- token contract: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx

Implement:
1) SDK setup in wallet mode using @stacks/connect request("stx_callContract")
2) Functions: setRoutingRules, deposit, getVaultState, withdraw
3) Input validation:
   - STX address only
   - lockUntilBlock must be in future when lockAmount > 0
   - splitAddress required when splitAmount > 0
4) UI state:
   - loading flags per operation
   - tx id result display
   - error mapping by SDK error name
5) Output files:
   - src/lib/flowvault.ts
   - src/hooks/useFlowVault.ts
   - .env.example
   - README integration section

Return code + run commands + smoke test steps.

Paste this prompt as-is, then replace principals or network values as needed for your deployment target.

Required Outputs

Compilable TypeScript files with strict typing (no any-based shortcuts).
Environment variables for network, contract, and token principals.
Wallet transaction executor wired to SDK contract call execution.
A short smoke test checklist that validates one full deposit cycle.
Error boundaries that map SDK errors into user-facing guidance.

Implementation Constraints

Never place private keys in browser runtime code.
Do not mix testnet and mainnet contract principals.
Treat token amounts as string or bigint values only.
Wait for write result, then refresh read state to confirm transitions.
Preserve tx ids for observability and support incident analysis.

Verification Commands

npm install
npm run build
npm run dev

# runtime checks
# 1) connect wallet
# 2) set routing rules
# 3) deposit
# 4) read vault state
# 5) withdraw unlocked amount

Release gate: do not approve generated code until all five runtime checks succeed with a real wallet on the target network.