FlowVault SDK

Installation

npm install flowvault-sdk@0.1.1

Pin exact version in production apps when contract interfaces are tightly controlled, then upgrade intentionally after testnet checks.

Initialization

Backend signer mode

import { FlowVault } from "flowvault-sdk";

const vault = new FlowVault({
  network: "testnet",
  contractAddress: "STD7QG84VQQ0C35SZM2EYTHZV4M8FQ0R7YNSQWPD",
  contractName: "flowvault",
  tokenContractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
  tokenContractName: "usdcx",
  senderKey: process.env.STACKS_PRIVATE_KEY,
});

Browser wallet mode

import { request } from "@stacks/connect";
import { FlowVault } from "flowvault-sdk";

const walletVault = new FlowVault({
  network: "testnet",
  contractAddress: "STD7QG84VQQ0C35SZM2EYTHZV4M8FQ0R7YNSQWPD",
  contractName: "flowvault",
  tokenContractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
  tokenContractName: "usdcx",
  senderAddress: "ST...",
  contractCallExecutor: async (call) => request("stx_callContract", {
    contract: call.contractAddress + "." + call.contractName,
    functionName: call.functionName,
    functionArgs: call.functionArgs,
    network: call.network,
    postConditionMode: "allow",
    postConditions: call.postConditions,
  }),
});

Write Calls

await vault.setRoutingRules({
  lockAmount: "1000000",
  lockUntilBlock: 3905000,
  splitAddress: null,
  splitAmount: "0",
});

await vault.deposit("5000000");
await vault.withdraw("1000000");
await vault.clearRoutingRules();

All writes return normalized transaction result data, including tx id, so callers can immediately link to explorer state or queue retries.

Read Calls

const state = await vault.getVaultState("ST...");
const rules = await vault.getRoutingRules("ST...");
const hasLock = await vault.hasLockedFunds("ST...");
const block = await vault.getCurrentBlockHeight("ST...");

Read methods parse Clarity values into stable TypeScript shapes, which avoids duplicated parsing logic in UI components.

Production Practices

• Validate network and contract principals at process startup.
• Use wallet executor mode for browser clients, never sender keys.
• Poll read-only state after writes until expected balance transition appears.
• Surface typed SDK errors directly for better support diagnostics.
• Store token amounts as strings or bigint, never floating numbers.

Error Handling

SDK exposes typed errors: InvalidAmountError, InvalidAddressError, InvalidRoutingRuleError, InvalidConfigurationError, ContractCallError, NetworkError, and ParsingError.

try {
  await vault.deposit("250000");
} catch (error) {
  if (error?.name === "InvalidAddressError") {
    // prompt user to reconnect wallet and fetch STX principal again
  }
  throw error;
}