AhhbitTracker

On-chain habit tracking with accountability on Stacks

---

Table of Contents

• What is AhhbitTracker?
• How It Works
• Tech Stack
• Getting Started
  • Testing
  • Packages
  • Production Build
• Deploy to Vercel
• Contract Reference
• Security
• Documentation
• Contributing
• License

---

What is AhhbitTracker?

AhhbitTracker is a decentralized habit-tracking dApp on the Stacks blockchain. Stake STX as a financial commitment to daily habits. Miss a day — your stake is forfeited to a shared pool. Complete a 7-day streak — reclaim your stake and earn bonuses from forfeited stakes.

Live contract: SP1N3809W9CBWWX04KN3TCQHP8A9GN520BD4JMP8Z.habit-tracker-v2

How It Works

1. Stake — Create a habit and deposit ≥ 0.02 STX as your commitment
2. Check In — Record daily completion within the 24-hour window (~144 blocks)
3. Streak — Maintain a 7-day streak to unlock withdrawal
4. Withdraw — Reclaim your stake and claim your share of the bonus pool

Missed check-ins forfeit your stake to the shared pool, distributed as rewards to users who complete their streaks.

Tech Stack

Layer	Technology
Smart Contract	Clarity 2.0 on Stacks Mainnet
Frontend	React 18 · TypeScript · Vite 5 · Tailwind CSS
State	@tanstack/react-query
Wallet	@stacks/connect (Leather · Xverse · Asigna)
Testing	Vitest + Clarinet SDK
Deployment	Vercel

Getting Started

Prerequisites: Node.js ≥ 18, Clarinet CLI

git clone https://github.com/Yusufolosun/AhhbitTracker.git
cd AhhbitTracker
npm install

cd frontend
cp .env.example .env.local
npm install
npm run dev                  # → http://localhost:3000

Testing

npm test              # Run contract + stx-utils tests (111 tests)
cd frontend && npm test   # Run frontend tests (30 tests)
clarinet check        # Validate Clarity syntax

Packages

Package	Description
stx-utils	Zero-dependency utility library for Stacks — formatting, validation, block math, address helpers
ahhbit-tracker-sdk	Typed SDK for the AhhbitTracker contract — transaction builders, read-only queries, post-conditions

Production Build

cd frontend
npm run build         # → frontend/dist/
npm run preview       # Preview locally

Deploy to Vercel

1. Import the repository in Vercel
2. Set Root Directory → frontend
3. Build settings are auto-detected from vercel.json
4. Optionally override VITE_CONTRACT_ADDRESS / VITE_CONTRACT_NAME

Contract Reference

Function	Description
create-habit	Create a habit with STX stake
check-in	Record daily check-in
withdraw-stake	Reclaim stake after 7-day streak
claim-bonus	Claim share of forfeited pool
get-habit	Read habit details
get-pool-balance	View total forfeited STX

Full reference → docs/API_REFERENCE.md

Security

• Post-condition validation on every STX transfer
• On-chain authorization — only habit owners can check in, withdraw, or claim
• Input validation enforced in the smart contract
• No private keys, mnemonics, or secrets in this repository

See docs/SECURITY.md for the full security model.

Documentation

Document	Description
User Guide	End-user walkthrough
API Reference	Contract functions and error codes
Architecture	System design and data flow
FAQ	Common questions
Security	Security model

Contributing

Pull requests are welcome. See CONTRIBUTING.md.

License

MIT