🕰️ TimeFi Protocol

A time-locked vault protocol built on the Stacks blockchain using Clarity smart contract features.

🏗️ Project Structure

TimeFi-Protocol/
 - 📂 `contracts/` — Clarity smart contracts
 - 📂 `frontend/` — React-based web dashboard
 - 📂 `sdk/` — JavaScript/TypeScript SDK
 - 📂 `deployments/` — Clarinet deployment plans
 - 📂 `settings/` — Network configuration
 - 📂 `tests/regressions/` — Regression and edge-case suites
 - 📂 `tests/` — Contract testing suite
 - 📂 `docs/` — Additional documentation

🏛️ Architecture Overview

The TimeFi Protocol is designed as a modular system for security and scalability:

• Smart Contracts (Clarity 4): Core logic managing vault states and time-locks on Stacks.
• Protocol SDK (JS/TS): Abstraction layer simplifying contract interactions and CV conversions.
• Web Dashboard (React): Professional UI for vault management and protocol monitoring.

🌟 Features

🔒 Smart Contract Features

• Create Vaults - Deposit STX with time-lock
• Withdraw Requests - Queue withdrawals once the lock has matured
• Custodian Processing - Let the deployer process mature withdrawal payouts
• Bot Approval - Approve automated bot principals directly
• Fee Collection - 0.5% fee on deposits

📜 Clarity 4 Functions Used

• tenure-height - For block-based lock timing
• stx-transfer? - For deposit and withdrawal settlement

🚀 Getting Started

📋 Prerequisites

• Clarinet installed
• Node.js 18+ (LTS recommended)
• npm or yarn package manager
• Access to a Stacks node API for the network you are targeting (mainnet by default)
• Wallet/provider network should match the configured API target before running write flows

Windows-Specific Setup

For Windows developers:

1. Install Windows Subsystem for Linux (WSL2) for optimal Clarinet experience
2. Use Git Bash or WSL terminal for running commands
3. Ensure Node.js is added to system PATH
4. May need to run terminal as Administrator for global installations

🛠️ Development

For detailed contribution guidelines, please see CONTRIBUTING.md.

# Install dependencies
npm ci

# Check contracts
npm run contracts:check

# Validate with project script
npm run check

# Open Clarinet console
npm run contracts:console

# Run tests
npm run test

# Run tests with coverage + costs
npm run test:report

# Run frontend tests from root
npm run frontend:test

# Start devnet
clarinet devnet start

# Run frontend (Vite)
npm run frontend:dev

# Build SDK package
npm run sdk:build

💻 Frontend Dashboard

cd frontend
npm ci
npm run dev

📦 SDK Library

cd sdk
npm ci
npm run build

🔗 SDK Library Integration

The timefi-sdk package provides a clean interface for interacting with the protocol:

import { TimeFiClient } from 'timefi-sdk';

const client = new TimeFiClient('testnet');
const vault = await client.getVault(1);
const tvl = await client.getTVL();

🔧 Tech Stack

• Smart Contracts: Clarity 4 (Stacks Blockchain)
• Frontend: React + Vite + Vanilla CSS
• SDK: JavaScript / @stacks/transactions
• Tooling: Clarinet, Vitest

🧾 Contract Functions

🔓 Public Contract Functions

Function	Parameters	Description
create-vault	(amount uint) (lock-blocks uint)	Create a new time-locked vault
request-withdraw	(id uint)	Queue a withdrawal after maturity
process-withdraw	(id uint)	Settle a mature withdrawal as deployer
approve-bot	(bot principal)	Approve a bot principal

🔍 Read-Only Contract Functions

Function	Parameters	Description
get-vault	(id uint)	Get vault details
is-active	(id uint)	Check if vault is active
get-time-remaining	(id uint)	Get blocks remaining to unlock
can-withdraw	(id uint)	Check withdrawal readiness
is-bot	(sender principal)	Check if sender is approved bot

⚙️ Configuration

🔢 Protocol Constants

MIN_DEPOSIT: 10,000 microSTX (0.01 STX)
MIN_LOCK: 6 blocks (~1 hour)
MAX_LOCK: 52,560 blocks (~1 year)
FEE_BPS: 50 (0.5%)

🧱 Infrastructure

• Mainnet testing and funding flows: docs/MAINNET_TESTING.md
• Audit Status: [Internal Audit v1.0] (Pending External Review)
• Security Bounty: Bug bounty program coming Q2 2026.
• Emergency Pause: Protocol can be paused by multisig in case of critical vulnerability.
• Formal Verification: Clarity contracts are being verified using TLA+.

🌐 Network API Endpoints

• Mainnet: https://stacks-node-api.mainnet.stacks.co
• Testnet: https://stacks-node-api.testnet.stacks.co

⚙️ Deployment Settings

• Clarinet Settings: settings/Clarinet.toml
• Mainnet Plan: deployments/default.mainnet-plan.yaml
• Testnet Plan: deployments/default.testnet-plan.yaml

🗳️ Governance

TimeFi Protocol is governed by its community. Future proposals will be handled via the on-chain governance module.

👥 Community

• Discord: Join our Discord
• Twitter: @TimeFiProtocol
• GitHub: AdekunleBamz

🪐 Ecosystem

• Mainnet Explorer: View on Stacks Explorer
• Testnet Explorer: View on Stacks Explorer
• Console.xyz: Community discussions and governance

❓ FAQ

Q: What is microSTX? A: It is the smallest unit of STX. 1 STX = 1,000,000 microSTX.

Q: What is the minimum lock period? A: The minimum lock period is 6 Stacks blocks, or about 1 hour.

🗺️ Roadmap 2026

• Q1 2026: Mobile Wallet Support & SDK v2
• Q2 2026: Multi-sig Vaults & Fee Sharing
• Q3 2026: L2 Integrations (Starknet/Arbitrum) & L3 Hyperchains
• Q4 2026: Decentralized Frontend & DAO Governance

📖 Operations Docs

• Mainnet testing and funding flows: MAINNET_TESTING.md
• Technical Specification: TECHNICAL_SPEC.md

📦 Package Metadata

• Name: timefi-sdk
• Version: 0.1.0
• Architecture: ES Modules
• License: MIT

🤝 Acknowledgments

• Stacks Foundation: For the Clarity 4 development tools.
• Hiro Systems: For the Stacks/Transactions library.

👤 Contributors

• adekunlebamz: Lead Developer & Maintainer

📄 License

• Security Policy
• Code of Conduct

MIT License - Copyright (c) 2026 TimeFi Protocol Team

---

Made with ❤️ by the TimeFi Team