🕰️ TimeFi Protocol

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

🏗️ Project Structure

timefi-protocol/ ├── contracts/ # Clarity smart contracts ├── frontend/ # React-based web dashboard ├── sdk/ # JavaScript/TypeScript SDK ├── scripts/ # Deployment and maintenance scripts ├── settings/ # Network configuration ├── tests/ # Contract testing suite └── docs/ # Additional documentation

✨ Features

🔒 Smart Contract Features

• Create Vaults - Deposit STX with a time-lock
• Withdraw Requests - Queue withdrawals once the lock matures
• Custodian Processing - Let the deployer process mature withdrawal payouts
• Bot Approval - Approve automated bot principals directly
• Fee Collection - 0.5% protocol 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 package manager (npm ci preferred for clean installs)
• Access to a Stacks node API for the target network (mainnet by default)
• Ensure wallet network matches the configured API target before running write flows

🛠️ 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

# Start devnet
clarinet devnet start

# Run frontend (Vite)
npm run frontend:dev

# Build SDK package
npm run sdk:build

SDK Integration

The @timefi/sdk provides a clean interface for interacting with the protocol:

import { TimeFiClient } from './sdk/src/client.js';

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

🛠️ Tech Stack

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

📝 Contract Functions

Before opening a PR or pushing to main, run the checks that match the area you touched. Ensure frontend dependencies are installed first with npm --prefix frontend ci.

npm run check
npm run frontend:build
npm run sdk:build

For a single production-facing gate, run:

npm run verify:production

💻 Frontend Dashboard

npm --prefix frontend ci
npm run frontend:dev

📦 SDK Library

npm --prefix sdk ci
npm run sdk: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
revoke-bot	(bot principal)	Remove an approved 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
get-tvl	—	Get total value locked in microSTX
get-vault-count	—	Get total number of vaults created
get-total-fees	—	Get accumulated protocol fees

⚙️ 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

• Audit Status: Internal audit v1.0 complete (external review pending).
• Security Bounty: Bug bounty program coming Q2 2026.
• Emergency Pause: The protocol can be paused by multisig in the event of a critical vulnerability.
• Formal Verification: Clarity contracts are being verified using TLA+.

🌐 Network API Endpoints

• Mainnet: https://api.mainnet.hiro.so
• Testnet: https://api.testnet.hiro.so

⚙️ Deployment Settings

• Clarinet Settings: Clarinet.toml

🗳️ Governance

TimeFi Protocol is governed by its community. Future governance proposals will be handled via the on-chain governance module (currently under active development).

👥 Community

• 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: microSTX 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, which is approximately 1 hour on mainnet.

🗺️ Roadmap 2026

• Q1 2026: Mobile Wallet Support & SDK v2
• Q2 2026: Multi-sig Vaults & Fee Sharing
• Q3 2026: Cross-chain integrations and L3 experimentation
• Q4 2026: Decentralized Frontend & DAO Governance

📖 Operations Docs

• Contribution guide: CONTRIBUTING.md
• Mainnet testing and funding flows: MAINNET_TESTING.md
• API reference: API.md
• Security policy: SECURITY.md
• Code of conduct: CODE_OF_CONDUCT.md

📦 SDK Package Metadata

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

🤝 Acknowledgments

• Stacks Foundation: For the Clarity 4 development tools and ecosystem support.
• Hiro Systems: For the Stacks/Transactions library and API infrastructure.

👤 Contributors

• AdekunleBamz: Lead Developer & Maintainer

📄 License

• License
• Security Policy

MIT License - Copyright (c) 2026 TimeFi Protocol Team

---

Made with care by the TimeFi Team