stx-vault-sdk 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish SDK to npm
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,7 @@
+MIT License
+
+Copyright (c) 2026 Oluwafemi Olagoke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files to deal in the Software
+without restriction.

package/README.md

@@ -0,0 +1,180 @@
+ STX Vault SDK
+
+   
+
+
+---
+
+Overview
+
+STX Vault SDK is a production-ready JavaScript/TypeScript SDK for building STX vaults and time-lock applications on the Stacks blockchain.
+
+It allows developers to:
+
+Lock STX in smart contract vaults
+
+Withdraw funds after the unlock period
+
+Create new vaults (multi-pool support)
+
+Track real-time vault events
+
+Get vault analytics & TVL
+
+Connect wallets like Xverse and Leather
+
+Use React hooks for front-end apps
+
+Interact via CLI commands
+
+
+
+
+
+---
+
+Installation
+
+npm install stx-vault-sdk
+
+
+---
+
+Quick Start
+
+Connect Wallet
+
+import { connectWallet } from "stx-vault-sdk"
+
+await connectWallet()
+
+
+---
+
+Lock STX
+
+import { lockSTX } from "stx-vault-sdk"
+
+await lockSTX(
+  100000000,          // Amount in micro-STX
+  900000,             // Unlock block
+  PRIVATE_KEY,        // Your private key
+  CONTRACT_ADDRESS,   // Smart contract address
+  "stx-vault"        // Contract name
+)
+
+
+---
+
+Withdraw STX
+
+import { withdrawSTX } from "stx-vault-sdk"
+
+await withdrawSTX(
+  PRIVATE_KEY,
+  CONTRACT_ADDRESS,
+  "stx-vault"
+)
+
+
+---
+
+Create Vault
+
+import { createVault } from "stx-vault-sdk"
+
+await createVault(
+  900000,             // Unlock block
+  PRIVATE_KEY,
+  CONTRACT_ADDRESS,
+  "stx-vault"
+)
+
+
+---
+
+Get Vault Balance
+
+import { getVaultBalance } from "stx-vault-sdk"
+
+const balance = await getVaultBalance(
+  USER_ADDRESS,
+  CONTRACT_ADDRESS,
+  "stx-vault"
+)
+console.log("Vault Balance:", balance)
+
+
+---
+
+React Hook Example
+
+import { useVault } from "stx-vault-sdk"
+
+const { balance, refresh } = useVault(USER_ADDRESS, CONTRACT_ADDRESS, "stx-vault")
+
+
+---
+
+CLI Usage
+
+After installing and building the SDK:
+
+npx stx-vault connect
+npx stx-vault lock -a 1000000 -b 900000 -k YOUR_KEY -c SPXXXX -n stx-vault
+npx stx-vault withdraw -k YOUR_KEY -c SPXXXX -n stx-vault
+npx stx-vault create -b 900000 -k YOUR_KEY -c SPXXXX -n stx-vault
+
+
+---
+
+Analytics & TVL
+
+import { getVaultStats, getVaultTVL } from "stx-vault-sdk"
+
+const stats = await getVaultStats("https://api.yourvault.com")
+const tvl = await getVaultTVL("https://api.yourvault.com")
+
+
+---
+
+Real-time Vault Events
+
+import { watchVaultEvents } from "stx-vault-sdk"
+
+const events = await watchVaultEvents(
+  "https://api.mainnet.hiro.so",
+  "SPXXXX.stx-vault"
+)
+console.log(events)
+
+
+---
+
+Supported Wallets
+
+Xverse Wallet 
+
+Leather Wallet 
+
+
+
+---
+
+Badges & Ecosystem
+
+Works on Stacks Mainnet
+
+Supports mobile-first wallets
+
+TypeScript-ready for front-end & back-end apps
+
+Fully DeFi protocol-ready SDK
+
+
+
+---
+
+License
+
+MIT

package/examples/react-demo/app.js

@@ -0,0 +1,15 @@
+import { connectWallet, lockSTX } from "stx-vault-sdk"
+
+async function start() {
+  await connectWallet()
+
+  await lockSTX(
+    100000000,
+    900000,
+    PRIVATE_KEY,
+    CONTRACT_ADDRESS,
+    "stx-vault"
+  )
+}
+
+start()

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "stx-vault-sdk",
+  "version": "1.0.0",
+  "description": "Production SDK for STX vault and time-lock applications on the Stacks blockchain, with CLI, React hooks, analytics, and wallet support.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "stacks",
+    "stx",
+    "vault",
+    "defi",
+    "web3",
+    "time-lock",
+    "stacks-sdk",
+    "cli",
+    "react-hook",
+    "analytics"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/investorphem/stx-vault-sdk"
+  },
+  "author": "Oluwafemi Olagoke",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts src/cli.ts --watch",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@stacks/connect": "^7.0.1",
+    "@stacks/network": "^7.0.1",
+    "@stacks/transactions": "^7.0.1",
+    "commander": "^11.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^7.2.0",
+    "typescript": "^5.3.3"
+  },
+  "bin": {
+    "stx-vault": "./dist/cli.js"
+  }
+}

package/src/analytics/tvl.ts

@@ -0,0 +1,4 @@
+export async function getVaultTVL(apiUrl: string) {
+  const res = await fetch(`${apiUrl}/vault/tvl`)
+  return res.json()
+}

package/src/analytics/vault-stats.ts

@@ -0,0 +1,4 @@
+export async function getVaultStats(apiUrl: string) {
+  const res = await fetch(`${apiUrl}/vault/stats`)
+  return res.json()
+}

package/src/cli.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { program } from "commander"
+import { lockSTX, withdrawSTX, createVault } from "./vault"
+import { connectWallet } from "./wallet/connect"
+
+program.version("1.0.0").description("STX Vault CLI - interact with STX vaults")
+
+// LOCK STX
+program
+  .command("lock")
+  .description("Lock STX into a vault")
+  .requiredOption("-a, --amount <number>", "Amount of STX to lock (in micro-STX)")
+  .requiredOption("-b, --unlockBlock <number>", "Unlock block height")
+  .requiredOption("-k, --key <string>", "Your private key")
+  .requiredOption("-c, --contractAddress <string>", "Contract address")
+  .requiredOption("-n, --contractName <string>", "Contract name")
+  .action(async (opts) => {
+    console.log("Locking STX...")
+    const tx = await lockSTX(
+      Number(opts.amount),
+      Number(opts.unlockBlock),
+      opts.key,
+      opts.contractAddress,
+      opts.contractName
+    )
+    console.log("Transaction:", tx)
+  })
+
+// WITHDRAW STX
+program
+  .command("withdraw")
+  .description("Withdraw STX from your vault")
+  .requiredOption("-k, --key <string>", "Your private key")
+  .requiredOption("-c, --contractAddress <string>", "Contract address")
+  .requiredOption("-n, --contractName <string>", "Contract name")
+  .action(async (opts) => {
+    console.log("Withdrawing STX...")
+    const tx = await withdrawSTX(
+      opts.key,
+      opts.contractAddress,
+      opts.contractName
+    )
+    console.log("Transaction:", tx)
+  })
+
+// CREATE VAULT
+program
+  .command("create")
+  .description("Create a new vault with a specific unlock block")
+  .requiredOption("-b, --unlockBlock <number>", "Unlock block height")
+  .requiredOption("-k, --key <string>", "Your private key")
+  .requiredOption("-c, --contractAddress <string>", "Contract address")
+  .requiredOption("-n, --contractName <string>", "Contract name")
+  .action(async (opts) => {
+    console.log("Creating vault...")
+    const tx = await createVault(
+      Number(opts.unlockBlock),
+      opts.key,
+      opts.contractAddress,
+      opts.contractName
+    )
+    console.log("Vault created:", tx)
+  })
+
+// WALLET CONNECT (optional CLI)
+program
+  .command("connect")
+  .description("Connect a wallet")
+  .action(async () => {
+    console.log("Connecting wallet...")
+    await connectWallet()
+    console.log("Wallet connected!")
+  })
+
+program.parse(process.argv)

package/src/events/vault-events.ts

@@ -0,0 +1,4 @@
+export async function watchVaultEvents(apiUrl: string, contractId: string) {
+  const res = await fetch(`${apiUrl}/extended/v1/contract/${contractId}/events`)
+  return res.json()
+}

package/src/react/useVault.ts

@@ -0,0 +1,13 @@
+import { useState } from "react"
+import { getVaultBalance } from "../vault/balance"
+
+export function useVault(address: string, contractAddress: string, contractName: string) {
+  const [balance, setBalance] = useState<number | null>(null)
+
+  async function refresh() {
+    const result = await getVaultBalance(address, contractAddress, contractName)
+    setBalance(result)
+  }
+
+  return { balance, refresh }
+}

package/src/utils/network.ts

@@ -0,0 +1,3 @@
+import { StacksMainnet } from "@stacks/network"
+
+export const network = new StacksMainnet()

package/src/vault/balance.ts

@@ -0,0 +1,17 @@
+import { callReadOnlyFunction } from "@stacks/transactions"
+import { network } from "../utils/network"
+
+export async function getVaultBalance(
+  userAddress: string,
+  contractAddress: string,
+  contractName: string
+) {
+  return callReadOnlyFunction({
+    contractAddress,
+    contractName,
+    functionName: "get-balance",
+    functionArgs: [],
+    senderAddress: userAddress,
+    network
+  })
+}

package/src/vault/create-vault.ts

@@ -0,0 +1,18 @@
+import { makeContractCall, uintCV } from "@stacks/transactions"
+import { network } from "../utils/network"
+
+export async function createVault(
+  unlockBlock: number,
+  senderKey: string,
+  contractAddress: string,
+  contractName: string
+) {
+  return makeContractCall({
+    contractAddress,
+    contractName,
+    functionName: "create-vault",
+    functionArgs: [uintCV(unlockBlock)],
+    senderKey,
+    network
+  })
+}

package/src/vault/history.ts

@@ -0,0 +1,4 @@
+export async function getVaultHistory(apiUrl: string, address: string) {
+  const res = await fetch(`${apiUrl}/extended/v1/address/${address}/transactions`)
+  return res.json()
+}

package/src/vault/lock.ts

@@ -0,0 +1,22 @@
+import { makeContractCall, uintCV } from "@stacks/transactions"
+import { network } from "../utils/network"
+
+export async function lockSTX(
+  amount: number,
+  unlockBlock: number,
+  senderKey: string,
+  contractAddress: string,
+  contractName: string
+) {
+  return makeContractCall({
+    contractAddress,
+    contractName,
+    functionName: "lock-stx",
+    functionArgs: [
+      uintCV(amount),
+      uintCV(unlockBlock)
+    ],
+    senderKey,
+    network
+  })
+}

package/src/vault/withdraw.ts

@@ -0,0 +1,17 @@
+import { makeContractCall } from "@stacks/transactions"
+import { network } from "../utils/network"
+
+export async function withdrawSTX(
+  senderKey: string,
+  contractAddress: string,
+  contractName: string
+) {
+  return makeContractCall({
+    contractAddress,
+    contractName,
+    functionName: "withdraw",
+    functionArgs: [],
+    senderKey,
+    network
+  })
+}

package/src/wallet/connect.ts

@@ -0,0 +1,16 @@
+import { AppConfig, UserSession, showConnect } from "@stacks/connect"
+
+const appConfig = new AppConfig(["store_write"])
+
+export const userSession = new UserSession({ appConfig })
+
+export function connectWallet() {
+  showConnect({
+    userSession,
+    appDetails: {
+      name: "STX Vault",
+      icon: "/logo.png"
+    },
+    onFinish: () => window.location.reload()
+  })
+}

package/src/wallet/session.ts

@@ -0,0 +1,11 @@
+import { AppConfig, UserSession } from "@stacks/connect"
+
+const appConfig = new AppConfig(["store_write"])
+
+export const userSession = new UserSession({ appConfig })
+
+export function getUserData() {
+  if (userSession.isUserSignedIn()) {
+    return userSession.loadUserData()
+  }
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}