Skip to content

README.md

Latest commit

 

History

History
289 lines (226 loc) · 10.1 KB

README.md

File metadata and controls

289 lines (226 loc) · 10.1 KB

CircleCare - Next Generation Care Circles on Stacks

A complete rebuild leveraging Clarity 4 features for enhanced security, performance, and user experience

Clarity Version Stacks License

Overview

CircleCare transforms expense sharing from tracking debts into flowing care. Instead of "you owe Alice $50," we recognize that communities operate in circles of mutual care—everyone contributes when they can, everyone receives when they need, and support comes full circle.

This is a ground-up rebuild of CircleCare, architected from the start to leverage Clarity 4's powerful new features including:

  • contract-hash? for contract integrity verification
  • restrict-assets? for enhanced asset protection
  • to-ascii? for improved data serialization
  • stacks-block-time for time-based logic
  • secp256r1-verify for passkey authentication readiness

Why This Rebuild?

The original CircleCare prototype demonstrated the concept. This rebuild takes it to production-ready standards:

Smart Contract Improvements (Clarity 4)

  • Enhanced Security: Leveraging restrict-assets? to prevent unauthorized asset movements
  • Contract Verification: Using contract-hash? to ensure contract integrity
  • Time-Based Features: Implementing stacks-block-time for expiring expenses and automated settlements
  • Better Data Handling: Using to-ascii? for improved serialization and cross-chain readiness
  • Future-Ready Auth: Foundation laid for secp256r1-verify passkey authentication

Frontend Modernization

  • Complete UI Redesign: Fresh color palette while maintaining CircleCare's warm, flowing philosophy
  • Enhanced UX: Improved wallet connection, transaction feedback, and error handling
  • Performance Optimizations: Better state management and data fetching strategies
  • Accessibility: WCAG 2.1 AA compliance from the ground up
  • Mobile-First: Responsive design optimized for all device sizes

Project Structure

circlecare/
├── contracts/                   # Clarity 4 smart contracts
│   ├── contracts/
│   │   ├── circle-factory.clar     # Circle creation and management
│   │   └── circle-treasury.clar    # Expense and settlement logic
│   ├── tests/                      # Comprehensive contract tests
│   └── Clarinet.toml               # Clarity 4 configuration
│
├── frontend/                    # Next.js 15 application
│   ├── app/                     # App router pages
│   ├── components/              # Reusable UI components
│   ├── lib/                     # Contract interactions & utilities
│   └── types/                   # TypeScript definitions
│
└── docs/                        # Documentation
    ├── ARCHITECTURE.md          # Technical architecture
    ├── CLARITY_4_FEATURES.md    # How we use Clarity 4
    └── DEPLOYMENT.md            # Deployment guide

Tech Stack

Smart Contracts

  • Clarity 4: Latest version with enhanced features
  • Clarinet 2.x: Development and testing framework
  • Vitest: Unit testing with clarinet-sdk

Frontend

  • Next.js 15: React framework with App Router
  • React 19: Latest React features
  • TypeScript 5.x: Type safety throughout
  • Tailwind CSS 4: Modern utility-first CSS
  • Stacks.js: Web3 integration
  • TanStack Query: Data fetching and caching

Getting Started

Prerequisites

Installation

  1. Clone the repository

    git clone https://github.com/ThinkLikeAFounder/circlecare.git
cd circlecare

  2. Install contract dependencies

    cd contracts
npm install

  3. Install frontend dependencies

    cd ../frontend
npm install

Development

Smart Contracts

cd contracts
clarinet test              # Run contract tests
clarinet console           # Interactive REPL
clarinet check             # Syntax checking

Frontend

cd frontend
npm run dev                # Start development server
npm run build              # Production build
npm run type-check         # TypeScript validation

Clarity 4 Feature Implementation

1. Contract Integrity Verification (contract-hash?)

We use contract-hash? to verify that interacting contracts match expected implementations, preventing malicious contract substitution.

2. Asset Protection (restrict-assets?)

Settlement operations are wrapped with restrict-assets? to ensure:

  • Users can only transfer amounts they actually owe
  • Contract funds remain protected during external calls
  • Automatic rollback on unauthorized transfers

3. Time-Based Logic (stacks-block-time)

Expenses can now have:

  • Expiration timestamps for automatic resolution
  • Time-locked settlements
  • Scheduled recurring contributions

4. Enhanced Serialization (to-ascii?)

Convert principals, amounts, and other data to ASCII for:

  • Better logging and events
  • Cross-chain message formatting
  • Human-readable receipts

Key Features

For Users

  • Create Care Circles: Organize your community
  • Track Contributions: Transparent expense sharing
  • Settle Debts: Simple STX transfers
  • Time-Based Expenses: Set expiration dates
  • Verified Contracts: Know you're interacting with authentic code

For Developers

  • Clarity 4 Native: Built for the latest Clarity features
  • Comprehensive Tests: Full test coverage
  • Type-Safe: TypeScript throughout the stack
  • Well-Documented: Clear code and documentation
  • Extensible: Easy to build on top of

Testing

Smart Contracts

cd contracts
npm test                   # Run all tests
npm run test:watch         # Watch mode
npm run test:coverage      # Coverage report

Frontend

cd frontend
npm run test              # Unit tests
npm run test:e2e          # End-to-end tests

Deployment

Smart Contracts

See DEPLOYMENT.md for detailed instructions.

cd contracts
clarinet deployments generate --testnet
clarinet deployments apply --testnet

Frontend

Deploy to Vercel, Netlify, or any static hosting:

cd frontend
npm run build

Documentation

Comprehensive documentation is available in the /docs directory:

📚 Complete Documentation

🚀 User Resources

🏗️ Developer Resources

🔧 Technical Resources

Contributing

We welcome contributions! Please see our Contributing Guide for detailed guidelines:

  1. Check existing issues or create a new one
  2. Fork the repository
  3. Create a feature branch
  4. Make your changes with tests
  5. Submit a pull request

For quick contributions:

  • 🐛 Bug Reports: Use GitHub Issues
  • 💡 Feature Requests: Create detailed GitHub Issues
  • 📝 Documentation: Improve our docs
  • 🔧 Code: Follow our development guidelines

Roadmap

Phase 1: Foundation (Current)

  • Core Clarity 4 contracts with all new features
  • Modern frontend with improved UX
  • Comprehensive test coverage
  • Documentation

Phase 2: Enhanced Features

  • Recurring contributions
  • Multi-token support (sBTC, other SIP-010 tokens)
  • Passkey authentication using secp256r1-verify
  • Mobile app (React Native)

Phase 3: Advanced

  • Cross-chain bridges
  • DAO governance
  • Analytics dashboard
  • API for third-party integrations

License

MIT License - see LICENSE file for details

Acknowledgments

Support & Community

📖 Documentation & Help

🤝 Community & Support

🛠️ Developer Resources

CircleCare - Where care comes full circle, powered by Clarity 4 on Stacks