timefi-sdk 0.1.4 → 0.2.0

package/README.md

@@ -10,7 +10,8 @@ The official JavaScript SDK for interacting with the **TimeFi Protocol** on the
 
 - 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.
+- Formatting Utilities: Standardized formatting for STX (microSTX to STX), addresses, dates, and timestamps.
+- Shared Helpers: Utility helpers and protocol models from the old `timefi-utils` and `timefi-types` packages are now included directly in `timefi-sdk`.
 - Mainnet/Testnet Support: Unified interface for both networks.
 
 ## Installation
@@ -51,6 +52,20 @@ const shortAddress = formatAddress('SP3F1234567890ABCDEFG1234567890XYZ123');
 console.log(shortAddress);
 ```
 
+### Use Integrated Utilities and Protocol Helpers
+
+```javascript
+import {
+  calculateTimeRemaining,
+  getProtocolConfig,
+  validateAddress,
+} from 'timefi-sdk';
+
+const config = getProtocolConfig();
+const remaining = calculateTimeRemaining(Date.now() + 60_000);
+const isValid = validateAddress('SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N');
+```
+
 ## Running Tests
 
 ```bash
@@ -64,6 +79,20 @@ The SDK exports:
 - `TimeFiClient`
 - `formatSTX(microStx)`
 - `formatAddress(address)`
+- `formatTimestamp(timestamp)`
+- `calculateTimeRemaining(endTime)`
+- `validateAddress(address)`
+- `validateAddressResult(address)`
+- `formatAmount(amount, decimals?)`
+- `parseAmount(amount)`
+- `generateId()`
+- `sleep(ms)`
+- `retry(fn, maxRetries?, delay?)`
+- `initializeProtocol(options?)`
+- `getProtocolVersion()`
+- `getProtocolConfig()`
+- `normalizeVault(vault)`
+- `normalizeTransaction(transaction)`
 - `formatNumber(value)`
 - `formatPercent(value)`
 - `formatDate(value)`

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("@stacks/transactions"),c=require("@stacks/network"),u="SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N",s={VAULT:"timefi-vault-v-A2",REWARDS:"timefi-rewards-v-A2",GOVERNANCE:"timefi-governance-v-A2",EMERGENCY:"timefi-emergency-v-A2"},f={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,m=1e6,g=t=>{if(t==null)return"0.000000";try{const e=typeof t=="object"&&t!==null&&"value"in t?t.value:t,r=Number(e);return isNaN(r)?"0.000000":(r/1e6).toLocaleString(void 0,{minimumFractionDigits:0,maximumFractionDigits:6})}catch(e){return console.error("Error formatting STX:",e),"0.000000"}},h=(t,e=4,r=4)=>t?t.length<=e+r?t:`${t.slice(0,e+2)}...${t.slice(-r)}`:"",b=t=>{if(t==null)return"0";const e=Number(t);return isNaN(e)?"0":e.toLocaleString()},C=(t,e=2)=>{if(t==null)return"0%";const r=Number(t);return isNaN(r)?"0%":(r*100).toFixed(e)+"%"},l=t=>{if(!t)return"--";const e=new Date(t);return isNaN(e.getTime())?"--":e.toLocaleDateString(void 0,{year:"numeric",month:"short",day:"numeric"})},A=t=>{if(!t)return"--";const e=new Date,r=new Date(t),o=Math.floor((e-r)/1e3);if(o<-1){const i=Math.abs(o);return i<60?"in a few seconds":i<3600?`in ${Math.floor(i/60)}m`:i<86400?`in ${Math.floor(i/3600)}h`:`in ${Math.floor(i/86400)}d`}return o<5?"just now":o<60?`${o}s ago`:o<3600?`${Math.floor(o/60)}m ago`:o<86400?`${Math.floor(o/3600)}h ago`:o<604800?`${Math.floor(o/86400)}d ago`:l(t)};function a(t,e){if(!Number.isInteger(t)||t<=0)throw new Error(`${e} must be a positive integer.`)}function w(t){if(t==null)throw new Error("amountSTX is required");const e=String(t).trim();if(!/^\d+(\.\d+)?$/.test(e))throw new Error("amountSTX must be a valid positive number.");const[r,o=""]=e.split(".");if(o.length>6)throw new Error("amountSTX supports at most 6 decimal places.");const i=BigInt(r)*1000000n+BigInt((o+"000000").slice(0,6));if(i<=0n)throw new Error("amountSTX must be greater than 0.");return i}class M{constructor(e="mainnet"){if(!["mainnet","testnet"].includes(e))throw new Error(`Invalid networkType "${e}". Use "mainnet" or "testnet".`);this.networkType=e,this.network=e==="mainnet"?new c.StacksMainnet:new c.StacksTestnet,this.contractAddress=u}async callReadOnly(e,r=[],o){const i=await n.callReadOnlyFunction({contractAddress:this.contractAddress,contractName:s.VAULT,functionName:e,functionArgs:r,network:this.network,senderAddress:o||this.contractAddress});return i.type===7||i.type===8?n.cvToValue(i.value):n.cvToValue(i)}async getVault(e){return a(e,"vaultId"),this.callReadOnly("get-vault",[n.uintCV(e)])}async getTimeRemaining(e){return a(e,"vaultId"),this.callReadOnly("get-time-remaining",[n.uintCV(e)])}async canWithdraw(e){return a(e,"vaultId"),this.callReadOnly("can-withdraw",[n.uintCV(e)])}async getTVL(){return this.callReadOnly("get-tvl",[])}getCreateVaultOptions(e,r){return a(r,"lockDurationBlocks"),{contractAddress:this.contractAddress,contractName:s.VAULT,functionName:"create-vault",functionArgs:[n.uintCV(w(e)),n.uintCV(r)],network:this.network,anchorMode:n.AnchorMode.Any,postConditionMode:n.PostConditionMode.Allow}}getWithdrawOptions(e){return a(e,"vaultId"),{contractAddress:this.contractAddress,contractName:s.VAULT,functionName:"request-withdraw",functionArgs:[n.uintCV(e)],network:this.network,anchorMode:n.AnchorMode.Any,postConditionMode:n.PostConditionMode.Allow}}}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=u;exports.CONTRACT_NAMES=s;exports.LOCK_PERIODS=f;exports.MAX_DEPOSIT=m;exports.MIN_DEPOSIT=d;exports.TimeFiClient=M;exports.formatAddress=h;exports.formatDate=l;exports.formatNumber=b;exports.formatPercent=C;exports.formatRelativeTime=A;exports.formatSTX=g;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("@stacks/transactions"),f=require("@stacks/network"),d="SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N",u={VAULT:"timefi-vault-v-A2",REWARDS:"timefi-rewards-v-A2",GOVERNANCE:"timefi-governance-v-A2",EMERGENCY:"timefi-emergency-v-A2"},p={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}},y=.01,M=1e6,V=e=>{if(e==null)return"0.000000";try{const t=typeof e=="object"&&e!==null&&"value"in e?e.value:e,r=Number(t);return isNaN(r)?"0.000000":(r/1e6).toLocaleString(void 0,{minimumFractionDigits:0,maximumFractionDigits:6})}catch(t){return console.error("Error formatting STX:",t),"0.000000"}},E=(e,t=4,r=4)=>e?e.length<=t+r?e:`${e.slice(0,t+2)}...${e.slice(-r)}`:"",P=e=>{if(e==null)return"0";const t=Number(e);return isNaN(t)?"0":t.toLocaleString()},R=(e,t=2)=>{if(e==null)return"0%";const r=Number(e);return isNaN(r)?"0%":(r*100).toFixed(t)+"%"},m=e=>{if(!e)return"--";const t=new Date(e);return isNaN(t.getTime())?"--":t.toLocaleDateString(void 0,{year:"numeric",month:"short",day:"numeric"})},_=e=>{if(!e)return"--";const t=new Date,r=new Date(e),n=Math.floor((t-r)/1e3);if(n<-1){const i=Math.abs(n);return i<60?"in a few seconds":i<3600?`in ${Math.floor(i/60)}m`:i<86400?`in ${Math.floor(i/3600)}h`:`in ${Math.floor(i/86400)}d`}return n<5?"just now":n<60?`${n}s ago`:n<3600?`${Math.floor(n/60)}m ago`:n<86400?`${Math.floor(n/3600)}h ago`:n<604800?`${Math.floor(n/86400)}d ago`:m(e)},D=/^S[PTMN][A-Z0-9]{38,40}$/i;function v(e){const t=Number(e);return!Number.isInteger(t)||t<0?6:t}function k(e){const t=e instanceof Date?e:new Date(e);return Number.isNaN(t.getTime())?"Invalid Date":t.toLocaleString()}function I(e){const t=e instanceof Date?e.getTime():Number(e),r=Number.isFinite(t)?t-Date.now():0;if(r<=0)return{days:0,hours:0,minutes:0,seconds:0,total:0};const n=Math.floor(r/(1e3*60*60*24)),i=Math.floor(r%(1e3*60*60*24)/(1e3*60*60)),l=Math.floor(r%(1e3*60*60)/(1e3*60)),C=Math.floor(r%(1e3*60)/1e3);return{days:n,hours:i,minutes:l,seconds:C,total:r}}function g(e){if(typeof e!="string")return{valid:!1,error:"Address must be a string."};const t=e.trim().toUpperCase();return t?D.test(t)?{valid:!0,address:t}:{valid:!1,address:t,error:"Address must be a valid Stacks address."}:{valid:!1,error:"Address is required."}}function F(e){return g(e).valid}function L(e,t=6){const r=Number(e),n=v(t);return Number.isFinite(r)?r.toFixed(n):0 .toFixed(n)}function j(e){const t=Number.parseFloat(String(e).replace(/,/g,"").trim());return Number.isFinite(t)?t:0}function U(){return`${Date.now()}-${Math.random().toString(36).slice(2,11)}`}function T(e){const t=Number.isFinite(e)&&e>0?e:0;return new Promise(r=>setTimeout(r,t))}async function z(e,t=3,r=1e3){const n=Number.isInteger(t)&&t>0?t:1;for(let i=0;i<n;i+=1)try{return await e()}catch(l){if(i===n-1)throw l;await T(r)}throw new Error("Retry exhausted without executing the operation.")}const A="1.0.0",h=Object.freeze({timeLock:!0,vaults:!0,governance:!1,rewards:!1}),b=Object.freeze(["active","locked","withdrawn","failed"]),N=Object.freeze(["deposit","withdraw","create","fee"]),S=Object.freeze(["pending","confirmed","failed"]);function s(e,t=0){const r=Number(e);return Number.isFinite(r)?r:t}function $(e){return b.includes(e)?e:"active"}function G(e){return N.includes(e)?e:"deposit"}function X(e){return S.includes(e)?e:"pending"}function O(e={}){const t={...h,...e.features||{}};return{network:e.network||"mainnet",version:e.version||A,features:t,initialized:e.initialized??!0}}let c=O();function H(e={}){return c=O(e),w()}function q(){return c.version}function w(){return{...c,features:{...c.features}}}function Y(e={}){return{id:e.id?String(e.id):"",owner:e.owner?String(e.owner):"",amount:s(e.amount),lockTime:s(e.lockTime),unlockTime:s(e.unlockTime),status:$(e.status),fees:s(e.fees)}}function Z(e={}){return{hash:e.hash?String(e.hash):"",type:G(e.type),amount:s(e.amount),from:e.from?String(e.from):"",to:e.to?String(e.to):"",timestamp:s(e.timestamp),status:X(e.status)}}function a(e,t){if(!Number.isInteger(e)||e<=0)throw new Error(`${t} must be a positive integer.`)}function K(e){if(e==null)throw new Error("amountSTX is required");const t=String(e).trim();if(!/^\d+(\.\d+)?$/.test(t))throw new Error("amountSTX must be a valid positive number.");const[r,n=""]=t.split(".");if(n.length>6)throw new Error("amountSTX supports at most 6 decimal places.");const i=BigInt(r)*1000000n+BigInt((n+"000000").slice(0,6));if(i<=0n)throw new Error("amountSTX must be greater than 0.");return i}class B{constructor(t="mainnet"){if(!["mainnet","testnet"].includes(t))throw new Error(`Invalid networkType "${t}". Use "mainnet" or "testnet".`);this.networkType=t,this.network=t==="mainnet"?new f.StacksMainnet:new f.StacksTestnet,this.contractAddress=d}async callReadOnly(t,r=[],n){const i=await o.callReadOnlyFunction({contractAddress:this.contractAddress,contractName:u.VAULT,functionName:t,functionArgs:r,network:this.network,senderAddress:n||this.contractAddress});return i.type===7||i.type===8?o.cvToValue(i.value):o.cvToValue(i)}async getVault(t){return a(t,"vaultId"),this.callReadOnly("get-vault",[o.uintCV(t)])}async getTimeRemaining(t){return a(t,"vaultId"),this.callReadOnly("get-time-remaining",[o.uintCV(t)])}async canWithdraw(t){return a(t,"vaultId"),this.callReadOnly("can-withdraw",[o.uintCV(t)])}async getTVL(){return this.callReadOnly("get-tvl",[])}getCreateVaultOptions(t,r){return a(r,"lockDurationBlocks"),{contractAddress:this.contractAddress,contractName:u.VAULT,functionName:"create-vault",functionArgs:[o.uintCV(K(t)),o.uintCV(r)],network:this.network,anchorMode:o.AnchorMode.Any,postConditionMode:o.PostConditionMode.Allow}}getWithdrawOptions(t){return a(t,"vaultId"),{contractAddress:this.contractAddress,contractName:u.VAULT,functionName:"request-withdraw",functionArgs:[o.uintCV(t)],network:this.network,anchorMode:o.AnchorMode.Any,postConditionMode:o.PostConditionMode.Allow}}}Object.defineProperty(exports,"AnchorMode",{enumerable:!0,get:()=>o.AnchorMode});Object.defineProperty(exports,"PostConditionMode",{enumerable:!0,get:()=>o.PostConditionMode});Object.defineProperty(exports,"bufferCV",{enumerable:!0,get:()=>o.bufferCV});Object.defineProperty(exports,"noneCV",{enumerable:!0,get:()=>o.noneCV});Object.defineProperty(exports,"principalCV",{enumerable:!0,get:()=>o.principalCV});Object.defineProperty(exports,"responseErrorCV",{enumerable:!0,get:()=>o.responseErrorCV});Object.defineProperty(exports,"responseOkCV",{enumerable:!0,get:()=>o.responseOkCV});Object.defineProperty(exports,"someCV",{enumerable:!0,get:()=>o.someCV});Object.defineProperty(exports,"stringAsciiCV",{enumerable:!0,get:()=>o.stringAsciiCV});Object.defineProperty(exports,"stringUtf8CV",{enumerable:!0,get:()=>o.stringUtf8CV});Object.defineProperty(exports,"uintCV",{enumerable:!0,get:()=>o.uintCV});exports.CONTRACT_ADDRESS=d;exports.CONTRACT_NAMES=u;exports.DEFAULT_PROTOCOL_FEATURES=h;exports.LOCK_PERIODS=p;exports.MAX_DEPOSIT=M;exports.MIN_DEPOSIT=y;exports.PROTOCOL_VERSION=A;exports.TRANSACTION_STATUSES=S;exports.TRANSACTION_TYPES=N;exports.TimeFiClient=B;exports.VAULT_STATUSES=b;exports.calculateTimeRemaining=I;exports.formatAddress=E;exports.formatAmount=L;exports.formatDate=m;exports.formatNumber=P;exports.formatPercent=R;exports.formatRelativeTime=_;exports.formatSTX=V;exports.formatTimestamp=k;exports.generateId=U;exports.getProtocolConfig=w;exports.getProtocolVersion=q;exports.initializeProtocol=H;exports.normalizeTransaction=Z;exports.normalizeVault=Y;exports.parseAmount=j;exports.retry=z;exports.sleep=T;exports.validateAddress=F;exports.validateAddressResult=g;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./constants.js";
 export * from "./format.js";
+export * from "./utils.js";
+export * from "./protocol.js";
 export * from "./client.js";
 export { uintCV, principalCV, bufferCV, stringAsciiCV, stringUtf8CV, noneCV, someCV, responseOkCV, responseErrorCV, AnchorMode, PostConditionMode } from "@stacks/transactions";

package/dist/index.mjs

@@ -1,147 +1,283 @@
-import { callReadOnlyFunction as f, cvToValue as c, uintCV as i, PostConditionMode as u, AnchorMode as l } from "@stacks/transactions";
-import { AnchorMode as S, PostConditionMode as k, bufferCV as D, noneCV as _, principalCV as $, responseErrorCV as I, responseOkCV as L, someCV as F, stringAsciiCV as P, stringUtf8CV as G, uintCV as H } from "@stacks/transactions";
-import { StacksMainnet as d, StacksTestnet as m } from "@stacks/network";
-const h = "SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N", a = {
+import { callReadOnlyFunction as w, cvToValue as f, uintCV as i, PostConditionMode as d, AnchorMode as m } from "@stacks/transactions";
+import { AnchorMode as it, PostConditionMode as st, bufferCV as at, noneCV as ut, principalCV as ct, responseErrorCV as lt, responseOkCV as ft, someCV as dt, stringAsciiCV as mt, stringUtf8CV as ht, uintCV as gt } from "@stacks/transactions";
+import { StacksMainnet as A, StacksTestnet as N } from "@stacks/network";
+const T = "SP3FKNEZ86RG5RT7SZ5FBRGH85FZNG94ZH1MCGG6N", l = {
   VAULT: "timefi-vault-v-A2",
   REWARDS: "timefi-rewards-v-A2",
   GOVERNANCE: "timefi-governance-v-A2",
   EMERGENCY: "timefi-emergency-v-A2"
-}, M = {
+}, 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 }
-}, p = 0.01, T = 1e6, y = (n) => {
-  if (n == null) return "0.000000";
+}, $ = 0.01, z = 1e6, U = (t) => {
+  if (t == null) return "0.000000";
   try {
-    const t = typeof n == "object" && n !== null && "value" in n ? n.value : n, e = Number(t);
-    return isNaN(e) ? "0.000000" : (e / 1e6).toLocaleString(void 0, {
+    const e = typeof t == "object" && t !== null && "value" in t ? t.value : t, n = Number(e);
+    return isNaN(n) ? "0.000000" : (n / 1e6).toLocaleString(void 0, {
       minimumFractionDigits: 0,
       maximumFractionDigits: 6
     });
-  } catch (t) {
-    return console.error("Error formatting STX:", t), "0.000000";
+  } catch (e) {
+    return console.error("Error formatting STX:", e), "0.000000";
   }
-}, C = (n, t = 4, e = 4) => n ? n.length <= t + e ? n : `${n.slice(0, t + 2)}...${n.slice(-e)}` : "", b = (n) => {
-  if (n == null) return "0";
-  const t = Number(n);
-  return isNaN(t) ? "0" : t.toLocaleString();
-}, E = (n, t = 2) => {
-  if (n == null) return "0%";
-  const e = Number(n);
-  return isNaN(e) ? "0%" : (e * 100).toFixed(t) + "%";
-}, w = (n) => {
-  if (!n) return "--";
-  const t = new Date(n);
-  return isNaN(t.getTime()) ? "--" : t.toLocaleDateString(void 0, {
+}, G = (t, e = 4, n = 4) => t ? t.length <= e + n ? t : `${t.slice(0, e + 2)}...${t.slice(-n)}` : "", j = (t) => {
+  if (t == null) return "0";
+  const e = Number(t);
+  return isNaN(e) ? "0" : e.toLocaleString();
+}, H = (t, e = 2) => {
+  if (t == null) return "0%";
+  const n = Number(t);
+  return isNaN(n) ? "0%" : (n * 100).toFixed(e) + "%";
+}, b = (t) => {
+  if (!t) return "--";
+  const e = new Date(t);
+  return isNaN(e.getTime()) ? "--" : e.toLocaleDateString(void 0, {
     year: "numeric",
     month: "short",
     day: "numeric"
   });
-}, O = (n) => {
-  if (!n) return "--";
-  const t = /* @__PURE__ */ new Date(), e = new Date(n), r = Math.floor((t - e) / 1e3);
+}, X = (t) => {
+  if (!t) return "--";
+  const e = /* @__PURE__ */ new Date(), n = new Date(t), r = Math.floor((e - n) / 1e3);
   if (r < -1) {
     const o = Math.abs(r);
     return o < 60 ? "in a few seconds" : o < 3600 ? `in ${Math.floor(o / 60)}m` : o < 86400 ? `in ${Math.floor(o / 3600)}h` : `in ${Math.floor(o / 86400)}d`;
   }
-  return r < 5 ? "just now" : r < 60 ? `${r}s ago` : r < 3600 ? `${Math.floor(r / 60)}m ago` : r < 86400 ? `${Math.floor(r / 3600)}h ago` : r < 604800 ? `${Math.floor(r / 86400)}d ago` : w(n);
-};
-function s(n, t) {
-  if (!Number.isInteger(n) || n <= 0)
-    throw new Error(`${t} must be a positive integer.`);
+  return r < 5 ? "just now" : r < 60 ? `${r}s ago` : r < 3600 ? `${Math.floor(r / 60)}m ago` : r < 86400 ? `${Math.floor(r / 3600)}h ago` : r < 604800 ? `${Math.floor(r / 86400)}d ago` : b(t);
+}, S = /^S[PTMN][A-Z0-9]{38,40}$/i;
+function p(t) {
+  const e = Number(t);
+  return !Number.isInteger(e) || e < 0 ? 6 : e;
+}
+function Z(t) {
+  const e = t instanceof Date ? t : new Date(t);
+  return Number.isNaN(e.getTime()) ? "Invalid Date" : e.toLocaleString();
+}
+function Y(t) {
+  const e = t instanceof Date ? t.getTime() : Number(t), n = Number.isFinite(e) ? e - Date.now() : 0;
+  if (n <= 0)
+    return { days: 0, hours: 0, minutes: 0, seconds: 0, total: 0 };
+  const r = Math.floor(n / (1e3 * 60 * 60 * 24)), o = Math.floor(n % (1e3 * 60 * 60 * 24) / (1e3 * 60 * 60)), c = Math.floor(n % (1e3 * 60 * 60) / (1e3 * 60)), g = Math.floor(n % (1e3 * 60) / 1e3);
+  return { days: r, hours: o, minutes: c, seconds: g, total: n };
+}
+function M(t) {
+  if (typeof t != "string")
+    return { valid: !1, error: "Address must be a string." };
+  const e = t.trim().toUpperCase();
+  return e ? S.test(e) ? { valid: !0, address: e } : { valid: !1, address: e, error: "Address must be a valid Stacks address." } : { valid: !1, error: "Address is required." };
+}
+function q(t) {
+  return M(t).valid;
+}
+function B(t, e = 6) {
+  const n = Number(t), r = p(e);
+  return Number.isFinite(n) ? n.toFixed(r) : 0 .toFixed(r);
+}
+function K(t) {
+  const e = Number.parseFloat(String(t).replace(/,/g, "").trim());
+  return Number.isFinite(e) ? e : 0;
+}
+function W() {
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+function y(t) {
+  const e = Number.isFinite(t) && t > 0 ? t : 0;
+  return new Promise((n) => setTimeout(n, e));
+}
+async function x(t, e = 3, n = 1e3) {
+  const r = Number.isInteger(e) && e > 0 ? e : 1;
+  for (let o = 0; o < r; o += 1)
+    try {
+      return await t();
+    } catch (c) {
+      if (o === r - 1)
+        throw c;
+      await y(n);
+    }
+  throw new Error("Retry exhausted without executing the operation.");
+}
+const C = "1.0.0", O = Object.freeze({
+  timeLock: !0,
+  vaults: !0,
+  governance: !1,
+  rewards: !1
+}), E = Object.freeze(["active", "locked", "withdrawn", "failed"]), R = Object.freeze(["deposit", "withdraw", "create", "fee"]), V = Object.freeze(["pending", "confirmed", "failed"]);
+function s(t, e = 0) {
+  const n = Number(t);
+  return Number.isFinite(n) ? n : e;
+}
+function D(t) {
+  return E.includes(t) ? t : "active";
+}
+function k(t) {
+  return R.includes(t) ? t : "deposit";
+}
+function v(t) {
+  return V.includes(t) ? t : "pending";
+}
+function h(t = {}) {
+  const e = {
+    ...O,
+    ...t.features || {}
+  };
+  return {
+    network: t.network || "mainnet",
+    version: t.version || C,
+    features: e,
+    initialized: t.initialized ?? !0
+  };
+}
+let u = h();
+function J(t = {}) {
+  return u = h(t), _();
+}
+function Q() {
+  return u.version;
+}
+function _() {
+  return {
+    ...u,
+    features: { ...u.features }
+  };
+}
+function tt(t = {}) {
+  return {
+    id: t.id ? String(t.id) : "",
+    owner: t.owner ? String(t.owner) : "",
+    amount: s(t.amount),
+    lockTime: s(t.lockTime),
+    unlockTime: s(t.unlockTime),
+    status: D(t.status),
+    fees: s(t.fees)
+  };
+}
+function et(t = {}) {
+  return {
+    hash: t.hash ? String(t.hash) : "",
+    type: k(t.type),
+    amount: s(t.amount),
+    from: t.from ? String(t.from) : "",
+    to: t.to ? String(t.to) : "",
+    timestamp: s(t.timestamp),
+    status: v(t.status)
+  };
+}
+function a(t, e) {
+  if (!Number.isInteger(t) || t <= 0)
+    throw new Error(`${e} must be a positive integer.`);
 }
-function g(n) {
-  if (n == null)
+function F(t) {
+  if (t == null)
     throw new Error("amountSTX is required");
-  const t = String(n).trim();
-  if (!/^\d+(\.\d+)?$/.test(t))
+  const e = String(t).trim();
+  if (!/^\d+(\.\d+)?$/.test(e))
     throw new Error("amountSTX must be a valid positive number.");
-  const [e, r = ""] = t.split(".");
+  const [n, r = ""] = e.split(".");
   if (r.length > 6)
     throw new Error("amountSTX supports at most 6 decimal places.");
-  const o = BigInt(e) * 1000000n + BigInt((r + "000000").slice(0, 6));
+  const o = BigInt(n) * 1000000n + BigInt((r + "000000").slice(0, 6));
   if (o <= 0n)
     throw new Error("amountSTX must be greater than 0.");
   return o;
 }
-class R {
-  constructor(t = "mainnet") {
-    if (!["mainnet", "testnet"].includes(t))
-      throw new Error(`Invalid networkType "${t}". Use "mainnet" or "testnet".`);
-    this.networkType = t, this.network = t === "mainnet" ? new d() : new m(), this.contractAddress = h;
+class nt {
+  constructor(e = "mainnet") {
+    if (!["mainnet", "testnet"].includes(e))
+      throw new Error(`Invalid networkType "${e}". Use "mainnet" or "testnet".`);
+    this.networkType = e, this.network = e === "mainnet" ? new A() : new N(), this.contractAddress = T;
   }
   // --- Read-only Methods ---
-  async callReadOnly(t, e = [], r) {
-    const o = await f({
+  async callReadOnly(e, n = [], r) {
+    const o = await w({
       contractAddress: this.contractAddress,
-      contractName: a.VAULT,
-      functionName: t,
-      functionArgs: e,
+      contractName: l.VAULT,
+      functionName: e,
+      functionArgs: n,
       network: this.network,
       senderAddress: r || this.contractAddress
     });
-    return o.type === 7 || o.type === 8 ? c(o.value) : c(o);
+    return o.type === 7 || o.type === 8 ? f(o.value) : f(o);
   }
-  async getVault(t) {
-    return s(t, "vaultId"), this.callReadOnly("get-vault", [i(t)]);
+  async getVault(e) {
+    return a(e, "vaultId"), this.callReadOnly("get-vault", [i(e)]);
   }
-  async getTimeRemaining(t) {
-    return s(t, "vaultId"), this.callReadOnly("get-time-remaining", [i(t)]);
+  async getTimeRemaining(e) {
+    return a(e, "vaultId"), this.callReadOnly("get-time-remaining", [i(e)]);
   }
-  async canWithdraw(t) {
-    return s(t, "vaultId"), this.callReadOnly("can-withdraw", [i(t)]);
+  async canWithdraw(e) {
+    return a(e, "vaultId"), this.callReadOnly("can-withdraw", [i(e)]);
   }
   async getTVL() {
     return this.callReadOnly("get-tvl", []);
   }
   // --- Transaction Signing Options Helpers ---
-  getCreateVaultOptions(t, e) {
-    return s(e, "lockDurationBlocks"), {
+  getCreateVaultOptions(e, n) {
+    return a(n, "lockDurationBlocks"), {
       contractAddress: this.contractAddress,
-      contractName: a.VAULT,
+      contractName: l.VAULT,
       functionName: "create-vault",
-      functionArgs: [i(g(t)), i(e)],
+      functionArgs: [i(F(e)), i(n)],
       network: this.network,
-      anchorMode: l.Any,
-      postConditionMode: u.Allow
+      anchorMode: m.Any,
+      postConditionMode: d.Allow
     };
   }
-  getWithdrawOptions(t) {
-    return s(t, "vaultId"), {
+  getWithdrawOptions(e) {
+    return a(e, "vaultId"), {
       contractAddress: this.contractAddress,
-      contractName: a.VAULT,
+      contractName: l.VAULT,
       functionName: "request-withdraw",
-      functionArgs: [i(t)],
+      functionArgs: [i(e)],
       network: this.network,
-      anchorMode: l.Any,
-      postConditionMode: u.Allow
+      anchorMode: m.Any,
+      postConditionMode: d.Allow
     };
   }
 }
 export {
-  S as AnchorMode,
-  h as CONTRACT_ADDRESS,
-  a as CONTRACT_NAMES,
-  M as LOCK_PERIODS,
-  T as MAX_DEPOSIT,
-  p as MIN_DEPOSIT,
-  k as PostConditionMode,
-  R as TimeFiClient,
-  D as bufferCV,
-  C as formatAddress,
-  w as formatDate,
-  b as formatNumber,
-  E as formatPercent,
-  O as formatRelativeTime,
-  y as formatSTX,
-  _ as noneCV,
-  $ as principalCV,
-  I as responseErrorCV,
-  L as responseOkCV,
-  F as someCV,
-  P as stringAsciiCV,
-  G as stringUtf8CV,
-  H as uintCV
+  it as AnchorMode,
+  T as CONTRACT_ADDRESS,
+  l as CONTRACT_NAMES,
+  O as DEFAULT_PROTOCOL_FEATURES,
+  L as LOCK_PERIODS,
+  z as MAX_DEPOSIT,
+  $ as MIN_DEPOSIT,
+  C as PROTOCOL_VERSION,
+  st as PostConditionMode,
+  V as TRANSACTION_STATUSES,
+  R as TRANSACTION_TYPES,
+  nt as TimeFiClient,
+  E as VAULT_STATUSES,
+  at as bufferCV,
+  Y as calculateTimeRemaining,
+  G as formatAddress,
+  B as formatAmount,
+  b as formatDate,
+  j as formatNumber,
+  H as formatPercent,
+  X as formatRelativeTime,
+  U as formatSTX,
+  Z as formatTimestamp,
+  W as generateId,
+  _ as getProtocolConfig,
+  Q as getProtocolVersion,
+  J as initializeProtocol,
+  ut as noneCV,
+  et as normalizeTransaction,
+  tt as normalizeVault,
+  K as parseAmount,
+  ct as principalCV,
+  lt as responseErrorCV,
+  ft as responseOkCV,
+  x as retry,
+  y as sleep,
+  dt as someCV,
+  mt as stringAsciiCV,
+  ht as stringUtf8CV,
+  gt as uintCV,
+  q as validateAddress,
+  M as validateAddressResult
 };

package/dist/protocol.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @param {Partial<ProtocolConfig>} [options={}]
+ * @returns {ProtocolConfig}
+ */
+export function initializeProtocol(options?: Partial<ProtocolConfig>): ProtocolConfig;
+/**
+ * @returns {string}
+ */
+export function getProtocolVersion(): string;
+/**
+ * @returns {ProtocolConfig}
+ */
+export function getProtocolConfig(): ProtocolConfig;
+/**
+ * @param {Partial<Vault>} [vault={}]
+ * @returns {Vault}
+ */
+export function normalizeVault(vault?: Partial<Vault>): Vault;
+/**
+ * @param {Partial<Transaction>} [transaction={}]
+ * @returns {Transaction}
+ */
+export function normalizeTransaction(transaction?: Partial<Transaction>): Transaction;
+/**
+ * Protocol metadata and typed helpers for the TimeFi ecosystem.
+ */
+/** @typedef {{ timeLock: boolean, vaults: boolean, governance: boolean, rewards: boolean }} ProtocolFeatures */
+/** @typedef {{ network: string, version: string, features: ProtocolFeatures, initialized?: boolean }} ProtocolConfig */
+/** @typedef {'active' | 'locked' | 'withdrawn' | 'failed'} VaultStatus */
+/** @typedef {{ id: string, owner: string, amount: number, lockTime: number, unlockTime: number, status: VaultStatus, fees: number }} Vault */
+/** @typedef {'deposit' | 'withdraw' | 'create' | 'fee'} TransactionType */
+/** @typedef {'pending' | 'confirmed' | 'failed'} TransactionStatus */
+/** @typedef {{ hash: string, type: TransactionType, amount: number, from: string, to: string, timestamp: number, status: TransactionStatus }} Transaction */
+export const PROTOCOL_VERSION: "1.0.0";
+/** @type {Readonly<ProtocolFeatures>} */
+export const DEFAULT_PROTOCOL_FEATURES: Readonly<ProtocolFeatures>;
+/** @type {Readonly<VaultStatus[]>} */
+export const VAULT_STATUSES: Readonly<VaultStatus[]>;
+/** @type {Readonly<TransactionType[]>} */
+export const TRANSACTION_TYPES: Readonly<TransactionType[]>;
+/** @type {Readonly<TransactionStatus[]>} */
+export const TRANSACTION_STATUSES: Readonly<TransactionStatus[]>;
+export type ProtocolFeatures = {
+    timeLock: boolean;
+    vaults: boolean;
+    governance: boolean;
+    rewards: boolean;
+};
+export type ProtocolConfig = {
+    network: string;
+    version: string;
+    features: ProtocolFeatures;
+    initialized?: boolean;
+};
+export type VaultStatus = "active" | "locked" | "withdrawn" | "failed";
+export type Vault = {
+    id: string;
+    owner: string;
+    amount: number;
+    lockTime: number;
+    unlockTime: number;
+    status: VaultStatus;
+    fees: number;
+};
+export type TransactionType = "deposit" | "withdraw" | "create" | "fee";
+export type TransactionStatus = "pending" | "confirmed" | "failed";
+export type Transaction = {
+    hash: string;
+    type: TransactionType;
+    amount: number;
+    from: string;
+    to: string;
+    timestamp: number;
+    status: TransactionStatus;
+};

package/dist/utils.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @param {number | string | Date} timestamp
+ * @returns {string}
+ */
+export function formatTimestamp(timestamp: number | string | Date): string;
+/**
+ * @param {number | string | Date} endTime
+ * @returns {TimeRemaining}
+ */
+export function calculateTimeRemaining(endTime: number | string | Date): TimeRemaining;
+/**
+ * @param {string} address
+ * @returns {ValidationResult}
+ */
+export function validateAddressResult(address: string): ValidationResult;
+/**
+ * @param {string} address
+ * @returns {boolean}
+ */
+export function validateAddress(address: string): boolean;
+/**
+ * @param {number | string} amount
+ * @param {number} [decimals=6]
+ * @returns {string}
+ */
+export function formatAmount(amount: number | string, decimals?: number): string;
+/**
+ * @param {string | number} amountStr
+ * @returns {number}
+ */
+export function parseAmount(amountStr: string | number): number;
+/**
+ * @returns {string}
+ */
+export function generateId(): string;
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function sleep(ms: number): Promise<void>;
+/**
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @param {number} [maxRetries=3]
+ * @param {number} [delay=1000]
+ * @returns {Promise<T>}
+ */
+export function retry<T>(fn: () => Promise<T>, maxRetries?: number, delay?: number): Promise<T>;
+export type TimeRemaining = {
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    total: number;
+};
+export type ValidationResult = {
+    valid: boolean;
+    address?: string;
+    error?: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "timefi-sdk",
-    "version": "0.1.4",
+    "version": "0.2.0",
     "description": "Official JavaScript SDK for TimeFi Protocol - Time-locked vaults on Stacks blockchain",
     "main": "dist/index.cjs",
     "module": "dist/index.mjs",