On-chain habit tracking with accountability on Stacks
- What is AhhbitTracker?
- How It Works
- Tech Stack
- Getting Started
- Contract Reference
- Security
- Documentation
- Contributing
- License
AhhbitTracker is a habit-building app that uses the psychological power of loss aversion to keep you committed. By staking a small deposit of STX (a digital token secured by Bitcoin) on a daily habit, you create real financial accountability.
Here is the simple 30-second loop:
- Set a Habit & Deposit: Choose a daily habit (e.g. "Read 10 pages", "Workout", "Drink 3L Water") and lock in a small commitment deposit (as low as 0.02 STX).
- Check In Daily: Verify your habit completion every 16 to 32 hours.
- Maintain your Streak: Hit a 7-day streak to unlock and reclaim your deposit.
- Claim Bonus Payouts: Consistent users earn additional bonus payouts from a shared reward pool built from penalties of users who missed their habits!
- Miss a Day, Take a Penalty: If you miss a check-in window, a 10% penalty of your staked deposit is forfeited to the shared reward pool.
Live contracts:
- Main Tracker:
SP1N3809W9CBWWX04KN3TCQHP8A9GN520BD4JMP8Z.habit-tracker-v3 - Accountability:
SP1N3809W9CBWWX04KN3TCQHP8A9GN520BD4JMP8Z.habit-accountability-group-v3 - Streak Rewards:
SP1N3809W9CBWWX04KN3TCQHP8A9GN520BD4JMP8Z.habit-streak-reward-v3
- Stake — Create a habit and deposit ≥ 0.02 STX as your commitment
- Check In — Record daily completion within the 16-32 hour window (96-192 blocks)
- Streak — Maintain a 7-day streak to unlock withdrawal
- Withdraw — Reclaim your stake and claim your share of the bonus pool
- Refer — Register a referrer once; successful referrals boost future bonus shares
Missed windows forfeit 10% per missed window to the shared pool, distributed as rewards to users who complete their streaks.
| Layer | Technology |
|---|---|
| Smart Contract | Clarity 2.0 on Stacks Mainnet |
| Frontend | React 18 · TypeScript · Vite 5 · Tailwind CSS |
| State | @tanstack/react-query |
| Blockchain Read Sync | Layered read-through caching + transaction-aware invalidation |
| Wallet | @stacks/connect (Leather · Xverse · Asigna) |
| Testing | Vitest + Clarinet SDK |
| Deployment | Vercel |
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:3000If you want to verify the system locally, you can run the test suite:
npm test # Run unit tests
cd frontend && npm test # Run frontend testsThe project relies on these specialized packages for the Stacks ecosystem:
stx-utils: Zero-dependency utility library for Stacks (formatting, block math, address helpers)ahhbit-tracker-sdk: Typed SDK for the contract (transactions, queries, post-conditions)defikit: DeFi utility toolkit for basis points and fee math
| Function | Description |
|---|---|
register-referrer |
Register a referrer for bonus boosts |
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 |
get-unclaimed-completed-habits |
View pending bonus claimant count |
get-estimated-bonus-share |
View next estimated bonus share |
get-referral-boost |
View current referral bonus weight |
Full reference → docs/API_REFERENCE.md
- 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.
| Document | Description |
|---|---|
| User Guide | End-user walkthrough |
| API Reference | Contract functions and error codes |
| Architecture | System design and data flow |
| Mobile Architecture | Mobile app design and setup |
| FAQ | Common questions |
| Security | Security model |
Pull requests are welcome. See CONTRIBUTING.md.