Counter Smart Contract

A robust and simple counter smart contract built on the Stacks Blockchain using Clarity. This project demonstrates fundamental smart contract development patterns and serves as an educational example for blockchain developers.

🚀 Features

• Simple Counter Logic: Increment, decrement, and read counter values
• Blockchain Persistence: State stored immutably on the Stacks network
• Comprehensive Testing: Full test suite with Vitest
• Multi-Network Support: Configurations for Devnet, Testnet, and Mainnet
• Developer-Friendly: Built with Clarinet for easy development and deployment

📋 Table of Contents

• Installation
• Usage
• Testing
• Deployment
• API Reference
• Contributing
• License

🛠 Installation

Prerequisites

• Clarinet (latest version)
• Node.js 16+ and npm
• Git

Setup

1. Clone the repository

   git clone https://github.com/stx-labs/clarinet.git
   cd clarinet/counter-contract

2. Install dependencies

   npm install

3. Verify setup

   clarinet check

📖 Usage

Local Development

Start the Clarinet console for interactive testing:

clarinet console

Contract Functions

The contract provides three main functions:

• read-counter(): Returns the current counter value
• increment(): Increases the counter by 1
• decrement(): Decreases the counter by 1 (minimum value: 0)

Example Usage

;; Read current counter value
(read-counter)

;; Increment counter
(increment)

;; Decrement counter
(decrement)

🧪 Testing

Run the comprehensive test suite:

npm test

Run tests in watch mode:

npm run test:watch

View test coverage:

npm run test:coverage

🚀 Deployment

Local Devnet

1. Start Devnet:

   clarinet devnet start

2. Deploy contract:

   clarinet deployments generate --devnet
   clarinet deployments apply --devnet

Testnet/Mainnet

Update settings/Testnet.toml or settings/Mainnet.toml with your wallet information, then:

clarinet deployments generate --testnet
clarinet deployments apply --testnet

📚 API Reference

Public Functions

read-counter

Returns the current counter value.

Returns: uint - Current counter value

increment

Increments the counter by 1.

Returns: bool - Success status

decrement

Decrements the counter by 1 (if current value > 0).

Returns: bool - Success status

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Follow Clarity best practices
• Add tests for new functionality
• Update documentation as needed
• Ensure all tests pass before submitting PR

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

• 📧 Email: support@hirosystems.com
• 💬 Discord: Join our community
• 📖 Documentation: Stacks Docs
• 🐛 Issues: Report bugs

---

Built with ❤️ by the Stacks Community

⭐ Star us on GitHub • 📚 Learn More