strade-stx 1.0.0

package/README.md

@@ -0,0 +1,344 @@
+# Strade - Decentralized Marketplace on Stacks
+
+[![Stacks](https://img.shields.io/badge/Stacks-Blockchain-5546FF?style=flat&logo=stacks)](https://www.stacks.co/)
+[![Clarity](https://img.shields.io/badge/Clarity-4.0-blue?style=flat)](https://clarity-lang.org/)
+[![Next.js](https://img.shields.io/badge/Next.js-15-black?style=flat&logo=next.js)](https://nextjs.org/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Testnet](https://img.shields.io/badge/Testnet-Live-success)](https://explorer.hiro.so/address/STGEE2D7NV4RJC1MHK59AN83PEN0CBBEXNG4QQVF?chain=testnet)
+
+A secure, decentralized marketplace built on the Stacks blockchain, featuring smart contract-powered escrow, dispute resolution, and user reputation systems.
+
+##  Features
+
+### Core Marketplace
+- **Create Listings**: List items for sale with customizable pricing and duration
+- **Browse & Search**: Discover active listings with real-time updates
+- **Direct Purchases**: Secure STX-based transactions with immediate confirmation
+- **Listing Management**: Update, cancel, or modify your listings anytime
+
+### Escrow Service
+- **Trustless Transactions**: Automated escrow holds funds until conditions are met
+- **7-Day Protection**: Standard escrow duration with automatic expiry handling
+- **Flexible Release**: Buyer-initiated or dispute-based fund releases
+- **Refund Mechanism**: Built-in refund system for failed transactions
+
+### Dispute Resolution
+- **Fair Arbitration**: Community-based voting system for dispute resolution
+- **24-Hour Voting Period**: Efficient dispute resolution process
+- **Multi-Arbitrator Support**: Minimum 3 votes required for decisions
+- **Transparent Process**: All dispute actions recorded on-chain
+
+### User Profiles & Reputation
+- **User Registration**: Create profiles with username, bio, and email
+- **Rating System**: 5-star rating system for buyers and sellers
+- **Reputation Score**: Calculated scores based on ratings and activity
+- **Authorization System**: Contract-based user permissions
+
+### BST Token (Strade Token)
+- **SIP-010 Compliant**: Standard fungible token implementation
+- **1 Trillion Supply**: Initial supply minted to deployer
+- **6 Decimals**: Precision for micro-transactions
+- **Pausable Contract**: Emergency pause functionality for security
+
+##  Architecture
+
+### Smart Contracts (Clarity 4)
+
+```
+contracts/
+├── CoreMarketPlace.clar      # Main marketplace logic
+├── EscrowService.clar         # Escrow management
+├── DisputeResolution_clar.clar # Arbitration system
+├── UserProfile.clar           # User management
+└── token.clar                 # BST token (SIP-010)
+```
+
+### Frontend (Next.js 15)
+
+```
+frontend/
+├── src/
+│   ├── app/                   # Next.js app router pages
+│   ├── components/            # React components
+│   ├── lib/                   # Stacks integration & utilities
+│   └── test/                  # Unit tests
+└── public/                    # Static assets
+```
+
+##  Getting Started
+
+### Prerequisites
+
+- Node.js 18+ and npm
+- [Clarinet](https://github.com/hirosystems/clarinet) for smart contract development
+- [Leather Wallet](https://leather.io/) for testnet interactions
+
+### Installation
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/yourusername/strade.git
+   cd strade
+   ```
+
+2. **Install dependencies**
+   ```bash
+   # Install Clarinet (if not already installed)
+   curl -L https://github.com/hirosystems/clarinet/releases/download/latest/clarinet-linux-x64.tar.gz | tar xz
+   
+   # Install frontend dependencies
+   cd frontend
+   npm install
+   ```
+
+3. **Configure environment**
+   ```bash
+   # Frontend configuration is in src/lib/stacks.ts
+   # Contract addresses are already configured for testnet
+   ```
+
+### Running Locally
+
+#### Smart Contracts
+
+```bash
+# Check contract syntax
+clarinet check
+
+# Run contract tests
+clarinet test
+
+# Start local console
+clarinet console
+```
+
+#### Frontend
+
+```bash
+cd frontend
+
+# Development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Start production server
+npm start
+
+# Run tests
+npm test
+```
+
+Visit `http://localhost:3000` to see the application.
+
+##  Testnet Deployment
+
+All contracts are deployed and verified on Stacks Testnet:
+
+| Contract | Address |
+|----------|---------|
+| CoreMarketPlace | `STGEE2D7NV4RJC1MHK59AN83PEN0CBBEXNG4QQVF.CoreMarketPlace` |
+| EscrowService | `STGEE2D7NV4RJC1MHK59AN83PEN0CBBEXNG4QQVF.EscrowService` |
+| UserProfile | `STGEE2D7NV4RJC1MHK59AN83PEN0CBBEXNG4QQVF.UserProfile` |
+| DisputeResolution | `STGEE2D7NV4RJC1MHK59AN83PEN0CBBEXNG4QQVF.DisputeResolution_clar` |
+| BST Token | `STGEE2D7NV4RJC1MHK59AN83PEN0CBBEXNG4QQVF.token` |
+
+**Deployer Address**: [STGEE2D7NV4RJC1MHK59AN83PEN0CBBEXNG4QQVF](https://explorer.hiro.so/address/STGEE2D7NV4RJC1MHK59AN83PEN0CBBEXNG4QQVF?chain=testnet)
+
+See [DEPLOYMENT_RESULTS.md](DEPLOYMENT_RESULTS.md) for detailed deployment information.
+
+##  Testing
+
+### Smart Contract Tests
+
+```bash
+# Run all contract tests
+npm test
+
+# Run with coverage
+clarinet test --coverage
+
+# Run specific test file
+npm test -- tests/CoreMarketPlace.test.ts
+```
+
+### Frontend Tests
+
+```bash
+cd frontend
+
+# Run unit tests
+npm test
+
+# Run with coverage
+npm test -- --coverage
+
+# Run in watch mode
+npm test -- --watch
+```
+
+### Test Coverage
+
+- ✅ CoreMarketPlace: 20 tests
+- ✅ Fuzz Testing: 13 tests
+- ✅ All contracts verified on testnet
+
+##  Security Features
+
+- **Input Validation**: All user inputs are validated on-chain
+- **Access Control**: Function-level permissions and ownership checks
+- **Escrow Protection**: Automatic fund locking and secure release mechanisms
+- **Dispute Resolution**: Multi-party arbitration prevents unilateral decisions
+- **Emergency Pause**: Contract owner can pause operations if needed
+- **Expiration Handling**: Automatic expiry for listings and escrow
+
+##  Documentation
+
+### For Users
+- [User Guide](docs/USER_GUIDE.md) - How to use Strade marketplace
+- [FAQ](docs/FAQ.md) - Frequently asked questions
+
+### For Developers
+- [Smart Contract API](docs/CONTRACT_API.md) - Contract functions and parameters
+- [Frontend Integration](docs/INTEGRATION.md) - How to integrate with Strade
+- [Development Guide](docs/DEVELOPMENT.md) - Contributing guidelines
+
+##  Roadmap
+
+### Phase 1: Core Functionality 
+- [x] Smart contract development
+- [x] Basic marketplace features
+- [x] Escrow system
+- [x] User profiles
+- [x] Testnet deployment
+
+### Phase 2: Enhanced Features 
+- [ ] Advanced search and filters
+- [ ] Image upload and IPFS integration
+- [ ] Mobile-responsive design improvements
+- [ ] Real-time notifications
+- [ ] Multi-currency support
+
+### Phase 3: Scaling & Security 
+- [ ] Professional security audit
+- [ ] Mainnet deployment
+- [ ] Performance optimization
+- [ ] Analytics dashboard
+- [ ] Community governance
+
+### Phase 4: Ecosystem Growth 
+- [ ] Mobile app (iOS/Android)
+- [ ] API for third-party integration
+- [ ] Multi-chain support
+- [ ] NFT marketplace integration
+- [ ] Advanced reputation algorithms
+
+##  Contributing
+
+We welcome contributions! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+Please ensure:
+- All tests pass (`npm test`)
+- Code follows existing style guidelines
+- Commit messages are clear and descriptive
+- Documentation is updated if needed
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+##  Smart Contract Details
+
+### CoreMarketPlace
+- **Purpose**: Main marketplace logic for listing management
+- **Key Functions**: `create-listing`, `update-listing`, `cancel-listing`, `purchase-listing`
+- **Features**: Time-based expiration, status tracking, event logging
+
+### EscrowService
+- **Purpose**: Secure fund holding during transactions
+- **Key Functions**: `create-escrow`, `release-funds`, `refund-buyer`
+- **Duration**: 1,008 blocks (~7 days)
+
+### DisputeResolution
+- **Purpose**: Fair dispute resolution through arbitration
+- **Key Functions**: `raise-dispute`, `vote-on-dispute`, `resolve-dispute`
+- **Voting Period**: 144 blocks (~24 hours)
+
+### UserProfile
+- **Purpose**: User identity and reputation management
+- **Key Functions**: `register-user`, `update-profile`, `rate-user`, `calculate-reputation`
+- **Features**: 5-star rating system, reputation scores
+
+### BST Token
+- **Standard**: SIP-010 Fungible Token
+- **Functions**: `transfer`, `mint`, `burn`, `get-balance`
+- **Supply**: 1,000,000,000,000 BST (1 trillion)
+
+##  Technology Stack
+
+### Blockchain
+- **Stacks Blockchain**: Layer-1 blockchain for Bitcoin
+- **Clarity 4**: Smart contract language with predictable behavior
+- **PoX Consensus**: Proof of Transfer for Bitcoin finality
+
+### Frontend
+- **Next.js 15**: React framework with App Router
+- **TypeScript**: Type-safe development
+- **Tailwind CSS**: Utility-first CSS framework
+- **shadcn/ui**: Beautiful component library
+- **Stacks.js**: Official Stacks JavaScript libraries
+
+### Development Tools
+- **Clarinet**: Local development and testing environment
+- **Vitest**: Fast unit testing framework
+- **ESLint**: Code linting and quality
+- **Prettier**: Code formatting
+
+##  Project Statistics
+
+- **Smart Contracts**: 5 deployed contracts
+- **Total Lines of Code**: ~1,500 Clarity + ~2,000 TypeScript
+- **Test Coverage**: 33 tests passing
+- **Deployment Cost**: 0.427 STX
+- **Clarity Version**: 4.0 (Epoch 3.0)
+
+##  License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+##  Acknowledgments
+
+- **Stacks Foundation** - For the amazing blockchain infrastructure
+- **Hiro Systems** - For development tools and APIs
+- **Clarity Language** - For secure smart contract development
+- **Open Source Community** - For inspiration and support
+
+##  Support & Community
+
+- **Website**: [strade.io](https://strade.io) (Coming Soon)
+- **Documentation**: [docs.strade.io](https://docs.strade.io) (Coming Soon)
+- **Discord**: [Join our community](https://discord.gg/strade) (Coming Soon)
+- **Twitter**: [@StradeMarket](https://twitter.com/StradeMarket) (Coming Soon)
+- **Email**: support@strade.io
+
+##  Disclaimer
+
+**TESTNET ONLY**: This project is currently deployed on Stacks Testnet. DO NOT use real assets or consider any transactions as having real-world value. The testnet can be reset at any time, and all data may be lost.
+
+Before mainnet deployment, a comprehensive security audit will be conducted. Use at your own risk.
+
+##  Star History
+
+If you find this project useful, please consider giving it a star ⭐
+
+---
+
+**Built on the Stacks Blockchain**
+
+*Empowering decentralized commerce, one transaction at a time.*
+

package/TODO.md

@@ -0,0 +1,34 @@
+# TODO.md - Git Activity Generator: Run 2000 More Commits
+
+## Plan Summary
+**Information Gathered:**
+- `scripts/git-activity-generator.ts`: Generates ~2000 git commits (7 PRs × 286 commits) via temp-commits/counter26XX.txt files (updates content, commits "chore: bump counter X"). Offset 2602, total files seen up to ~2753, .activity_counter=300 (likely tracks something else or reset).
+- Existing temp-commits/ has many files; will clean to avoid conflicts.
+- Uses `gh pr create` (assumes GitHub CLI auth'd).
+- `generate-activity.ts`/`auto-activity.sh`: On-chain tx generator, not git-related.
+
+**Plan:**
+1. Edit `scripts/git-activity-generator.ts`:
+   - Clean temp-commits/ fully on start.
+   - Set new offset = 2754 (next after visible files).
+   - Keep NUM_PRS=7, COMMITS_PER_PR=286 (~2000 total).
+   - Add progress logging, optional --count CLI arg for flexibility.
+   - Ensure safe git ops (stash if dirty, checkout main at end).
+2. No dependent files (self-contained).
+
+**Dependent Files to be edited:** None.
+
+**Followup steps:**
+1. Run dry-run: `npx tsx scripts/git-activity-generator.ts --dry-run`
+2. Ensure `gh auth status` (install/auth if needed).
+3. Execute: `npx tsx scripts/git-activity-generator.ts`
+4. Verify: `gh pr list`, `git log --oneline -10`
+5. Optional cleanup: rm -rf temp-commits/, git branch -D fake-activity-pr-*
+
+✅ Plan approved by user.
+
+## Progress
+- [x] Create TODO.md
+- [x] Step 1: Edit git-activity-generator.ts ✅ (offset 2754, --total CLI, progress, safety stashes, counter update)
+- [ ] Step 2: Test dry-run
+- [ ] Step 3: Run production

package/contracts/CoreMarketPlace.clar

@@ -0,0 +1,227 @@
+;; CoreMarketPlace Contract
+;; This contract manages the creation, updating, and purchasing of listings in the Strade decentralized marketplace.
+;; It handles the core logic for marketplace interactions, including listing management and purchase fulfillment.
+
+;; --- Constants ---
+;; Defines immutable values used throughout the contract for error handling and configuration.
+
+(define-constant CONTRACT_OWNER tx-sender) ;; Sets the contract deployer as the owner.
+(define-constant ERR_NOT_AUTHORIZED (err u100)) ;; Error for unauthorized actions.
+(define-constant ERR_LISTING_NOT_FOUND (err u101)) ;; Error when a listing cannot be found.
+(define-constant ERR_INVALID_PRICE (err u102)) ;; Error for invalid listing prices (e.g., zero or negative).
+(define-constant ERR_INVALID_SELLER (err u103)) ;; Error for invalid seller principals.
+(define-constant ERR_INSUFFICIENT_BALANCE (err u104)) ;; Error when a buyer has insufficient funds.
+(define-constant ERR_LISTING_EXPIRED (err u105)) ;; Error for expired listings.
+(define-constant ERR_INVALID_STATUS (err u106)) ;; Error for invalid listing statuses.
+(define-constant ERR_NOT_SELLER (err u107)) ;; Error when a user is not the seller of a listing.
+(define-constant ERR_ALREADY_PURCHASED (err u108)) ;; Error for listings that have already been sold.
+(define-constant ERR_INVALID_INPUT (err u109)) ;; Error for invalid input parameters.
+(define-constant ERR_INVALID_DURATION (err u110)) ;; Error for invalid listing durations.
+(define-constant ERR_INVALID_LISTING_ID (err u111)) ;; Error for invalid listing IDs.
+(define-constant MAX_LISTING_DURATION u52560) ;; Maximum duration of a listing (approximately 1 year).
+
+;; --- Data Maps ---
+;; Defines the data structures used to store marketplace information.
+
+(define-map Listings
+  { listing-id: uint }
+  {
+    seller: principal, ;; The principal of the seller.
+    name: (string-utf8 64), ;; The name of the listing.
+    description: (string-utf8 256), ;; A description of the item.
+    price: uint, ;; The price of the listing in micro-STX.
+    status: (string-ascii 20), ;; The current status of the listing (e.g., "active", "sold", "cancelled").
+    created-at: uint, ;; The block height at which the listing was created.
+    expires-at: uint ;; The block height at which the listing expires.
+  }
+)
+
+;; --- Variables ---
+;; Defines mutable variables for tracking the contract's state.
+
+(define-data-var last-listing-id uint u0) ;; Tracks the ID of the last created listing.
+
+;; --- Private Functions ---
+;; Helper functions intended for internal use by the contract.
+
+;; Checks if a given price is valid (greater than zero).
+(define-private (is-valid-price (price uint))
+  (> price u0)
+)
+
+;; Checks if a seller principal is valid (not the sender or the contract itself).
+(define-private (is-valid-seller (seller principal))
+  (and 
+    (not (is-eq seller tx-sender))
+    (not (is-eq seller (as-contract tx-sender)))
+  )
+)
+
+;; Checks if a string is within the specified length constraints.
+(define-private (is-valid-string (str (string-utf8 256)) (max-len uint))
+  (and (>= (len str) u1) (<= (len str) max-len))
+)
+
+;; Checks if a listing duration is valid.
+(define-private (is-valid-duration (duration uint))
+  (and (> duration u0) (<= duration MAX_LISTING_DURATION))
+)
+
+;; Checks if a listing ID is valid.
+(define-private (is-valid-listing-id (id uint))
+  (<= id (var-get last-listing-id))
+)
+
+;; Increments and returns the next listing ID.
+(define-private (increment-listing-id)
+  (let 
+    (
+      (current-id (var-get last-listing-id))
+    )
+    (var-set last-listing-id (+ current-id u1))
+    (var-get last-listing-id)
+  )
+)
+
+;; --- Public Functions ---
+;; Functions that can be called by any user.
+
+;; Creates a new listing in the marketplace.
+;; @param name: The name of the listing.
+;; @param description: A description of the item.
+;; @param price: The price of the listing in micro-STX.
+;; @param duration: The duration of the listing in blocks.
+;; @returns (ok uint): The ID of the newly created listing.
+(define-public (create-listing (name (string-utf8 64)) (description (string-utf8 256)) (price uint) (duration uint))
+  (let
+    (
+      (listing-id (increment-listing-id))
+      (expires-at (+ stacks-block-height duration))
+    )
+    (asserts! (is-valid-price price) (err ERR_INVALID_PRICE))
+    (asserts! (is-valid-string name u64) (err ERR_INVALID_INPUT))
+    (asserts! (is-valid-string description u256) (err ERR_INVALID_INPUT))
+    (asserts! (is-valid-duration duration) (err ERR_INVALID_DURATION))
+    (map-set Listings
+      { listing-id: listing-id }
+      {
+        seller: tx-sender,
+        name: name,
+        description: description,
+        price: price,
+        status: "active",
+        created-at: stacks-block-height,
+        expires-at: expires-at
+      }
+    )
+    (print { event: "listing_created", listing-id: listing-id, seller: tx-sender })
+    (ok listing-id)
+  )
+)
+
+;; Updates an existing listing.
+;; @param listing-id: The ID of the listing to update.
+;; @param new-price: The new price for the listing.
+;; @param new-description: The new description for the listing.
+;; @returns (ok bool): True if the update is successful.
+(define-public (update-listing (listing-id uint) (new-price uint) (new-description (string-utf8 256)))
+  (begin
+    (asserts! (is-valid-listing-id listing-id) (err ERR_INVALID_LISTING_ID))
+    (let
+      (
+        (listing (unwrap! (map-get? Listings { listing-id: listing-id }) (err ERR_LISTING_NOT_FOUND)))
+      )
+      (asserts! (is-eq (get seller listing) tx-sender) (err ERR_NOT_SELLER))
+      (asserts! (is-eq (get status listing) "active") (err ERR_INVALID_STATUS))
+      (asserts! (is-valid-price new-price) (err ERR_INVALID_PRICE))
+      (asserts! (is-valid-string new-description u256) (err ERR_INVALID_INPUT))
+      (map-set Listings
+        { listing-id: listing-id }
+        (merge listing 
+          {
+            price: new-price,
+            description: new-description
+          }
+        )
+      )
+      (print { event: "listing_updated", listing-id: listing-id, seller: tx-sender })
+      (ok true)
+    )
+  )
+)
+
+;; Cancels a listing.
+;; @param listing-id: The ID of the listing to cancel.
+;; @returns (ok bool): True if the cancellation is successful.
+(define-public (cancel-listing (listing-id uint))
+  (begin
+    (asserts! (is-valid-listing-id listing-id) (err ERR_INVALID_LISTING_ID))
+    (let
+      (
+        (listing (unwrap! (map-get? Listings { listing-id: listing-id }) (err ERR_LISTING_NOT_FOUND)))
+      )
+      (asserts! (is-eq (get seller listing) tx-sender) (err ERR_NOT_SELLER))
+      (asserts! (is-eq (get status listing) "active") (err ERR_INVALID_STATUS))
+      (map-set Listings
+        { listing-id: listing-id }
+        (merge listing { status: "cancelled" })
+      )
+      (print { event: "listing_cancelled", listing-id: listing-id, seller: tx-sender })
+      (ok true)
+    )
+  )
+)
+
+;; Purchases a listing.
+;; @param listing-id: The ID of the listing to purchase.
+;; @returns (ok bool): True if the purchase is successful.
+(define-public (purchase-listing (listing-id uint))
+  (begin
+    (asserts! (is-valid-listing-id listing-id) (err ERR_INVALID_LISTING_ID))
+    (let
+      (
+        (listing (unwrap! (map-get? Listings { listing-id: listing-id }) (err ERR_LISTING_NOT_FOUND)))
+        (price (get price listing))
+        (seller (get seller listing))
+      )
+      (asserts! (is-eq (get status listing) "active") (err ERR_INVALID_STATUS))
+      (asserts! (<= stacks-block-height (get expires-at listing)) (err ERR_LISTING_EXPIRED))
+      (asserts! (is-valid-seller seller) (err ERR_INVALID_SELLER))
+      (match (stx-transfer? price tx-sender seller)
+        success (begin
+          (map-set Listings
+            { listing-id: listing-id }
+            (merge listing { status: "sold" })
+          )
+          (print { event: "listing_purchased", listing-id: listing-id, buyer: tx-sender, seller: seller, price: price })
+          (ok true))
+        error (err ERR_INSUFFICIENT_BALANCE))
+    )
+  )
+)
+
+;; --- Read-Only Functions ---
+;; Functions for retrieving data from the contract without making state changes.
+
+;; Retrieves a listing by its ID.
+;; @param listing-id: The ID of the listing to retrieve.
+;; @returns (optional {<listing-data>}): The listing data or none if not found.
+(define-read-only (get-listing (listing-id uint))
+  (if (is-valid-listing-id listing-id)
+    (map-get? Listings { listing-id: listing-id })
+    none
+  )
+)
+
+;; Retrieves the ID of the last created listing.
+;; @returns (ok uint): The last listing ID.
+(define-read-only (get-last-listing-id)
+  (ok (var-get last-listing-id))
+)
+
+;; --- Contract Initialization ---
+;; Initializes the contract upon deployment.
+(begin
+  (print "CoreMarketPlace contract initialized")
+  (ok true)
+)