timefi-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AdekunleBamz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# timefi-sdk
+
+The official JavaScript SDK for interacting with the **TimeFi Protocol** on the Stacks blockchain.
+
+[![npm version](https://img.shields.io/npm/v/timefi-sdk.svg)](https://www.npmjs.com/package/timefi-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🚀 Features
+
+- **Protocol Client**: Easy-to-use `TimeFiClient` for read and write interactions.
+- **On-chain Data**: Fetch TVL, vault status, and lock durations directly from smart contracts.
+- **Formatting Utilities**: Standardized formatting for STX (microSTX to STX), addresses, and dates.
+- **Mainnet/Testnet Support**: Unified interface for both networks.
+
+## 📦 Installation
+
+```bash
+npm install timefi-sdk
+```
+
+## 🛠️ Quick Start
+
+### Fetch Protocol Stats
+
+```javascript
+import { TimeFiClient, formatSTX } from '@timefi/sdk';
+
+// Initialize for Stacks Mainnet
+const client = new TimeFiClient('mainnet');
+
+// Get Total Value Locked
+const tvl = await client.getTVL();
+console.log(`Current TVL: ${formatSTX(tvl)} STX`);
+```
+
+### Format a Stacks Address
+
+```javascript
+import { formatAddress } from '@timefi/sdk';
+
+const shortAddress = formatAddress('SP3...XYZ123');
+console.log(shortAddress); // SP3...Z123
+```
+
+## 📖 Documentation
+
+The SDK provides the following exports:
+
+- `TimeFiClient`: Core class for blockchain interactions.
+- `formatSTX(microStx)`: Converts microSTX to a human-readable STX string.
+- `formatAddress(address)`: Truncates addresses for UI display.
+- `CONTRACT_ADDRESS`: The main TimeFi Protocol contract address on Stacks.
+
+## 📄 License
+
+MIT © [AdekunleBamz](https://github.com/AdekunleBamz)

package/dist/index.esm.js

@@ -0,0 +1,111 @@
+import { callReadOnlyFunction as u, cvToValue as s, uintCV as o, PostConditionMode as c, AnchorMode as l } from "@stacks/transactions";
+import { AnchorMode as k, PostConditionMode as D, bufferCV as E, noneCV as _, principalCV as v, responseErrorCV as S, responseOkCV as L, someCV as F, stringAsciiCV as G, stringUtf8CV as P, uintCV as H } from "@stacks/transactions";
+import { StacksMainnet as d, StacksTestnet as f } from "@stacks/network";
+const m = "SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N", i = {
+  VAULT: "timefi-vault-v-A2",
+  REWARDS: "timefi-rewards-v-A2",
+  GOVERNANCE: "timefi-governance-v-A2",
+  EMERGENCY: "timefi-emergency-v-A2"
+}, g = {
+  MONTH_1: { label: "1 Month", blocks: 4320, apy: 1 },
+  MONTH_3: { label: "3 Months", blocks: 12960, apy: 3 },
+  MONTH_6: { label: "6 Months", blocks: 25920, apy: 6 },
+  MONTH_9: { label: "9 Months", blocks: 38880, apy: 9 },
+  YEAR_1: { label: "1 Year", blocks: 52560, apy: 12 }
+}, M = 0.01, C = 1e6, w = (t) => {
+  if (t == null) return "0.000000";
+  try {
+    const n = typeof t == "object" && t !== null && "value" in t ? t.value : t;
+    return (Number(n) / 1e6).toLocaleString(void 0, {
+      minimumFractionDigits: 0,
+      maximumFractionDigits: 6
+    });
+  } catch (n) {
+    return console.error("Error formatting STX:", n), "0.000000";
+  }
+}, N = (t, n = 4, r = 4) => t ? t.length <= n + r ? t : `${t.slice(0, n + 2)}...${t.slice(-r)}` : "", T = (t) => t == null ? "0" : Number(t).toLocaleString(), p = (t, n = 2) => t == null ? "0%" : (t * 100).toFixed(n) + "%", h = (t) => t ? new Date(t).toLocaleDateString(void 0, {
+  year: "numeric",
+  month: "short",
+  day: "numeric"
+}) : "--", O = (t) => {
+  if (!t) return "--";
+  const n = /* @__PURE__ */ new Date(), r = new Date(t), e = Math.floor((n - r) / 1e3);
+  return e < 60 ? "just now" : e < 3600 ? `${Math.floor(e / 60)}m ago` : e < 86400 ? `${Math.floor(e / 3600)}h ago` : e < 604800 ? `${Math.floor(e / 86400)}d ago` : h(t);
+};
+class R {
+  constructor(n = "mainnet") {
+    this.network = n === "mainnet" ? new d() : new f(), this.contractAddress = m;
+  }
+  // --- Read-only Methods ---
+  async callReadOnly(n, r = [], e) {
+    const a = await u({
+      contractAddress: this.contractAddress,
+      contractName: i.VAULT,
+      functionName: n,
+      functionArgs: r,
+      network: this.network,
+      senderAddress: e || this.contractAddress
+    });
+    return a.type === 7 || a.type === 8 ? s(a.value) : s(a);
+  }
+  async getVault(n) {
+    return this.callReadOnly("get-vault", [o(n)]);
+  }
+  async getTimeRemaining(n) {
+    return this.callReadOnly("get-time-remaining", [o(n)]);
+  }
+  async canWithdraw(n) {
+    return this.callReadOnly("can-withdraw", [o(n)]);
+  }
+  async getTVL() {
+    return this.callReadOnly("get-tvl", []);
+  }
+  // --- Transaction Signing Options Helpers ---
+  getCreateVaultOptions(n, r) {
+    return {
+      contractAddress: this.contractAddress,
+      contractName: i.VAULT,
+      functionName: "create-vault",
+      functionArgs: [o(n * 1e6), o(r)],
+      network: this.network,
+      anchorMode: l.Any,
+      postConditionMode: c.Deny
+    };
+  }
+  getWithdrawOptions(n) {
+    return {
+      contractAddress: this.contractAddress,
+      contractName: i.VAULT,
+      functionName: "request-withdraw",
+      functionArgs: [o(n)],
+      network: this.network,
+      anchorMode: l.Any,
+      postConditionMode: c.Deny
+    };
+  }
+}
+export {
+  k as AnchorMode,
+  m as CONTRACT_ADDRESS,
+  i as CONTRACT_NAMES,
+  g as LOCK_PERIODS,
+  C as MAX_DEPOSIT,
+  M as MIN_DEPOSIT,
+  D as PostConditionMode,
+  R as TimeFiClient,
+  E as bufferCV,
+  N as formatAddress,
+  h as formatDate,
+  T as formatNumber,
+  p as formatPercent,
+  O as formatRelativeTime,
+  w as formatSTX,
+  _ as noneCV,
+  v as principalCV,
+  S as responseErrorCV,
+  L as responseOkCV,
+  F as someCV,
+  G as stringAsciiCV,
+  P as stringUtf8CV,
+  H as uintCV
+};

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("@stacks/transactions"),s=require("@stacks/network"),c="SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N",a={VAULT:"timefi-vault-v-A2",REWARDS:"timefi-rewards-v-A2",GOVERNANCE:"timefi-governance-v-A2",EMERGENCY:"timefi-emergency-v-A2"},l={MONTH_1:{label:"1 Month",blocks:4320,apy:1},MONTH_3:{label:"3 Months",blocks:12960,apy:3},MONTH_6:{label:"6 Months",blocks:25920,apy:6},MONTH_9:{label:"9 Months",blocks:38880,apy:9},YEAR_1:{label:"1 Year",blocks:52560,apy:12}},d=.01,f=1e6,m=e=>{if(e==null)return"0.000000";try{const t=typeof e=="object"&&e!==null&&"value"in e?e.value:e;return(Number(t)/1e6).toLocaleString(void 0,{minimumFractionDigits:0,maximumFractionDigits:6})}catch(t){return console.error("Error formatting STX:",t),"0.000000"}},C=(e,t=4,o=4)=>e?e.length<=t+o?e:`${e.slice(0,t+2)}...${e.slice(-o)}`:"",b=e=>e==null?"0":Number(e).toLocaleString(),g=(e,t=2)=>e==null?"0%":(e*100).toFixed(t)+"%",u=e=>e?new Date(e).toLocaleDateString(void 0,{year:"numeric",month:"short",day:"numeric"}):"--",A=e=>{if(!e)return"--";const t=new Date,o=new Date(e),r=Math.floor((t-o)/1e3);return r<60?"just now":r<3600?`${Math.floor(r/60)}m ago`:r<86400?`${Math.floor(r/3600)}h ago`:r<604800?`${Math.floor(r/86400)}d ago`:u(e)};class y{constructor(t="mainnet"){this.network=t==="mainnet"?new s.StacksMainnet:new s.StacksTestnet,this.contractAddress=c}async callReadOnly(t,o=[],r){const i=await n.callReadOnlyFunction({contractAddress:this.contractAddress,contractName:a.VAULT,functionName:t,functionArgs:o,network:this.network,senderAddress:r||this.contractAddress});return i.type===7||i.type===8?n.cvToValue(i.value):n.cvToValue(i)}async getVault(t){return this.callReadOnly("get-vault",[n.uintCV(t)])}async getTimeRemaining(t){return this.callReadOnly("get-time-remaining",[n.uintCV(t)])}async canWithdraw(t){return this.callReadOnly("can-withdraw",[n.uintCV(t)])}async getTVL(){return this.callReadOnly("get-tvl",[])}getCreateVaultOptions(t,o){return{contractAddress:this.contractAddress,contractName:a.VAULT,functionName:"create-vault",functionArgs:[n.uintCV(t*1e6),n.uintCV(o)],network:this.network,anchorMode:n.AnchorMode.Any,postConditionMode:n.PostConditionMode.Deny}}getWithdrawOptions(t){return{contractAddress:this.contractAddress,contractName:a.VAULT,functionName:"request-withdraw",functionArgs:[n.uintCV(t)],network:this.network,anchorMode:n.AnchorMode.Any,postConditionMode:n.PostConditionMode.Deny}}}Object.defineProperty(exports,"AnchorMode",{enumerable:!0,get:()=>n.AnchorMode});Object.defineProperty(exports,"PostConditionMode",{enumerable:!0,get:()=>n.PostConditionMode});Object.defineProperty(exports,"bufferCV",{enumerable:!0,get:()=>n.bufferCV});Object.defineProperty(exports,"noneCV",{enumerable:!0,get:()=>n.noneCV});Object.defineProperty(exports,"principalCV",{enumerable:!0,get:()=>n.principalCV});Object.defineProperty(exports,"responseErrorCV",{enumerable:!0,get:()=>n.responseErrorCV});Object.defineProperty(exports,"responseOkCV",{enumerable:!0,get:()=>n.responseOkCV});Object.defineProperty(exports,"someCV",{enumerable:!0,get:()=>n.someCV});Object.defineProperty(exports,"stringAsciiCV",{enumerable:!0,get:()=>n.stringAsciiCV});Object.defineProperty(exports,"stringUtf8CV",{enumerable:!0,get:()=>n.stringUtf8CV});Object.defineProperty(exports,"uintCV",{enumerable:!0,get:()=>n.uintCV});exports.CONTRACT_ADDRESS=c;exports.CONTRACT_NAMES=a;exports.LOCK_PERIODS=l;exports.MAX_DEPOSIT=f;exports.MIN_DEPOSIT=d;exports.TimeFiClient=y;exports.formatAddress=C;exports.formatDate=u;exports.formatNumber=b;exports.formatPercent=g;exports.formatRelativeTime=A;exports.formatSTX=m;

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "timefi-sdk",
+    "version": "0.1.0",
+    "description": "Core SDK for interacting with TimeFi Protocol on Stacks",
+    "main": "dist/index.js",
+    "module": "dist/index.esm.js",
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/AdekunleBamz/TimeFi-Protocol.git"
+    },
+    "bugs": {
+        "url": "https://github.com/AdekunleBamz/TimeFi-Protocol/issues"
+    },
+    "homepage": "https://github.com/AdekunleBamz/TimeFi-Protocol#readme",
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "vite build",
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "stacks",
+        "bitcoin",
+        "clarity",
+        "defi",
+        "time-lock"
+    ],
+    "author": "AdekunleBamz",
+    "license": "MIT",
+    "dependencies": {
+        "@stacks/network": "^6.13.0",
+        "@stacks/transactions": "^6.14.0"
+    },
+    "devDependencies": {
+        "vite": "^5.0.0"
+    }
+}