Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
128 lines (101 loc) · 3.34 KB

ARCHITECTURE.md

File metadata and controls

128 lines (101 loc) · 3.34 KB

CircleCare Architecture

Overview

CircleCare is built on a modular architecture leveraging Clarity 4 smart contracts on the Stacks blockchain. The system transforms traditional expense sharing into a care-centered model where communities operate in circles of mutual support.

System Components

Smart Contracts Layer

Circle Factory Contract (circle-factory.clar)

  • Purpose: Creates and manages care circles
  • Clarity Version: 4.0
  • Key Features:
    • Circle creation with configurable parameters
    • Member management and permissions
    • Circle metadata and settings

Circle Treasury Contract (circle-treasury.clar)

  • Purpose: Handles expense tracking and settlements
  • Clarity Version: 4.0
  • Key Features:
    • Expense creation and tracking
    • Settlement calculations
    • STX transfers and balances

Data Architecture

Circle Structure

Circle {
  id: uint,
  name: string-ascii,
  creator: principal,
  members: list of principals,
  treasury-balance: uint,
  created-at: uint
}

Expense Structure

Expense {
  id: uint,
  circle-id: uint,
  amount: uint,
  description: string-ascii,
  payer: principal,
  participants: list of principals,
  settled: bool,
  created-at: uint
}

Clarity 4 Features Integration

Contract Integrity (contract-hash?)

  • Verifies contract authenticity before interactions
  • Prevents malicious contract substitution
  • Ensures users interact with verified implementations

Asset Protection (restrict-assets?)

  • Protects user funds during settlement operations
  • Prevents unauthorized asset movements
  • Automatic rollback on failed transactions

Time-Based Logic (stacks-block-time)

  • Expense expiration timestamps
  • Time-locked settlements
  • Automated resolution scheduling

Enhanced Serialization (to-ascii?)

  • Convert data for cross-chain compatibility
  • Human-readable transaction logs
  • Improved event emission

Security Model

Access Control

  • Circle creators have administrative privileges
  • Members can create expenses and participate in settlements
  • Non-members cannot access circle data or functions

Fund Protection

  • Treasury funds are protected by multi-signature requirements
  • Settlement amounts are validated against actual balances
  • Emergency pause functionality for critical issues

Data Integrity

  • All state changes are atomic
  • Input validation on all public functions
  • Overflow protection on arithmetic operations

Scalability Considerations

Gas Optimization

  • Efficient data structures to minimize storage costs
  • Batched operations where possible
  • Lazy evaluation for complex calculations

State Management

  • Minimal on-chain storage
  • Event-driven architecture for off-chain indexing
  • Pagination for large data sets

Integration Points

Frontend Integration

  • Contract interaction through Stacks.js
  • Real-time updates via event listening
  • Wallet integration for transaction signing

External Services

  • Block explorer integration for transaction history
  • Notification services for expense updates
  • Analytics and reporting dashboards

Deployment Architecture

Development Environment

  • Local Clarinet development
  • Automated testing with Vitest
  • Contract simulation and debugging

Production Environment

  • Stacks mainnet deployment
  • Multi-environment configuration
  • Monitoring and alerting systems