StacksRaise

Decentralized block-height crowdfunding secured by Bitcoin on Stacks.

---

📋 Table of Contents

• Overview
• Live Testnet Deployment
• System Architecture
• On-Chain Project Registration (Zero LocalStorage)
• Project Directory Structure
• Smart Contract Specification
• Frontend Experience & Lifecycle States
• Developer Quickstart
• Test & Verification Results
• Feedback — Scaffold Stacks Experience
• License

---

🌟 Overview

StacksRaise is a trustless, decentralized crowdfunding protocol built on the Stacks blockchain and anchored to Bitcoin consensus.

Traditional crowdfunding platforms suffer from opaque escrow custody, third-party payment freezes, high processing fees, and arbitrarily extended campaign deadlines. StacksRaise eliminates counterparty risk by encoding campaign logic into immutable Clarity smart contracts where:

1. Deadlines are governed strictly by Bitcoin tenure block heights (Clarity block-height).
2. Funds are locked in non-custodial smart contract escrow vaults.
3. Guaranteed 1-Click Refunds: If a campaign falls short of its goal when the deadline arrives, contributors can immediately claim 100% of their STX back directly on-chain.
4. 100% On-Chain Project Registration: Campaign titles and missions are stored directly in Clarity contract maps—no browser local storage or centralized database.
5. Zero Mock Data: All feed cards, balance metrics, and live block trackers read directly from Stacks Testnet nodes and smart contracts.

---

🔗 Live Testnet Deployment

Parameter	Value
Contract Name	crowdfund-v2
Contract Address	ST3E6N4PVNF8H0BJVQQR5A6KA9HMD9DDV5SW988C9.crowdfund-v2
Deployment Transaction	0xf175d11ad806e4a51474667a274f2151af9cab792cbbd7b9ceeaaca8051a3d27
Status	SUCCESS (Confirmed On-Chain)
Key Features	100% On-Chain Metadata (title, description), Autonomous Escrow, Guaranteed Refunds
Hiro Testnet Explorer	View Contract on Hiro Explorer ↗

---

🏗 System Architecture

flowchart TD
    A([User: Backer or Creator]) -->|Connects Wallet| B[Stacks Multi-Wallet\nXverse / Leather / Stacks Connect v8]
    B -->|Signs & Authenticates| C[Next.js 15 Frontend Application\nLanding Page & Campaigns Dashboard]
    
    C -->|1. Register Project| D[Create Campaign Modal\nOn-Chain Title + Description + Goal]
    C -->|2. Back Campaign| E[Fund Campaign Modal\nSTX Contribution + Smart Escrow]
    C -->|3. Settle Milestone| F[Campaign Card Actions\nCreator Payout or 100% Backer Refund]
    
    D -->|Broadcast Signed Tx| G[Hiro Stacks Testnet RPC Node]
    E -->|Broadcast Signed Tx| G
    F -->|Broadcast Signed Tx| G
    
    C -.->|Server-side Node Proxies| H[Next.js Edge API Routes\n/api/stacks/info & /api/stacks/balance]
    H -.->|Poll Live Block Height & Balances| G
    
    G -->|Execute Contract Mutations & Reads| I[(crowdfund-v2.clar\nClarity Smart Contract Escrow)]
    I -->|Enforce Tenure Block Deadlines| J[(Bitcoin Consensus Layer 1\nProof of Transfer & Block Height Anchoring)]

Loading

Architecture Highlights:

• Clarity Smart Contract: Epoch 2.5 compatible, enforces mathematical pre-conditions (asserts!), micro-STX precision, and zero-custody escrow.
• Scaffold Stacks TypeScript SDK: Auto-generated type-safe bindings (frontend/src/generated/) map Clarity functions directly to React hooks.
• Server-Side API Proxies (/api/stacks/*): Route requests server-side through Next.js to bypass client adblockers (Brave Shields, uBlock) and browser CORS restrictions.
• Jotai State Store: Manages reactive wallet connection, balance fetching, and tenure chain tip updates.
• Framer Motion Micro-Interactions: Smooth view transitions, responsive spring modals, and animated progress bars.

---

🛡 On-Chain Project Registration

When a creator creates a crowdfunding campaign:

• Project Title / Name (string-ascii 64): Stored directly in the Campaigns Clarity data map.
• Project Mission & Description (string-utf8 256): Stored immutably on-chain so every contributor can read the project's exact purpose, roadmap, and delivery promise.
• Validation: Enforced at the consensus layer with ERR_EMPTY_TITLE (u108) and ERR_EMPTY_DESCRIPTION (u109).

---

📁 Project Directory Structure

stacks-raise/
├── contracts/                            # Smart Contract Layer
│   ├── Clarinet.toml                     # Clarinet project configuration
│   ├── contracts/
│   │   ├── crowdfund-v2.clar             # Active Clarity contract with on-chain project metadata
│   │   └── crowdfund.clar                # Base Clarity crowdfunding contract
│   ├── deployments/
│   │   ├── default.simnet-plan.yaml      # Clarinet simnet plan for in-memory unit tests
│   │   └── default.testnet-plan.yaml     # Live testnet deployment record
│   ├── settings/
│   │   ├── Devnet.toml                   # Devnet network config
│   │   ├── Testnet.toml.example          # Safe template for testnet deployment mnemonics
│   │   └── Testnet.toml                  # [GITIGNORED] Real testnet deployment secrets
│   └── tests/
│       └── crowdfund.test.ts             # 6 comprehensive Vitest unit tests (100% pass)
│
├── frontend/                             # Next.js App Router Web Application
│   ├── package.json                      # Next.js 15.5.18, React 18, @stacks/connect v8
│   ├── public/
│   │   ├── apple-touch-icon.png          # High-resolution Apple icon
│   │   ├── favicon.ico                   # Standard favicon
│   │   └── favicon.svg                   # Scalable vector favicon
│   ├── src/
│   │   ├── app/
│   │   │   ├── api/stacks/
│   │   │   │   ├── balance/route.ts      # Server-side proxy for user STX balance
│   │   │   │   ├── campaigns/route.ts    # Server-side proxy for live campaigns feed
│   │   │   │   └── info/route.ts         # Server-side proxy for live chain tip
│   │   │   ├── dashboard/page.tsx        # dApp Crowdfunding Dashboard with Zone Routing
│   │   │   ├── globals.css               # Sharp borders, custom scrollbar stability
│   │   │   ├── layout.tsx                # Root layout, metadata & Footer
│   │   │   └── page.tsx                  # Landing page with escrow breakdown & FAQs
│   │   ├── components/
│   │   │   ├── BlockHeightBadge.tsx      # Real-time pulsing tenure block height indicator
│   │   │   ├── CampaignCard.tsx          # Dynamic campaign card displaying title, mission & progress
│   │   │   ├── CampaignFeed.tsx          # Dynamic feed fetching on-chain campaigns
│   │   │   ├── CreateCampaignModal.tsx   # Modal with title, mission, live block estimates & loading states
│   │   │   ├── Footer.tsx                # Responsive footer with mobile-safe layout & contract ID
│   │   │   ├── FundCampaignModal.tsx     # Modal displaying project mission, quick presets & signing states
│   │   │   ├── Header.tsx                # Responsive header with mobile hamburger drawer
│   │   │   ├── StatsBanner.tsx           # Aggregated real-time metrics
│   │   │   └── WalletConnect.tsx         # Multi-wallet connector with portaled centering
│   │   ├── generated/                    # Auto-generated by `stacksdapp generate`
│   │   │   ├── contracts.ts              # Clarity contract function wrappers
│   │   │   ├── deployments.json          # Deployment records & active contract IDs
│   │   │   └── hooks.ts                  # React hooks for read/write calls
│   │   ├── lib/
│   │   │   └── stacks-utils.ts           # Tenure height resolver, micro-STX converters
│   │   └── store/
│   │       └── wallet.ts                 # Jotai wallet atoms
│   └── scaffold.config.ts                # Network resolver (devnet / testnet / mainnet)
│
├── AGENTS.md                             # AI Agent guide & CLI instructions
├── README.md                             # Project documentation (this file)
└── stacksdapp.toml                       # Scaffold Stacks workspace configuration

---

📜 Smart Contract Specification

The smart contract contracts/contracts/crowdfund-v2.clar implements the complete crowdfunding lifecycle in Clarity:

Core Public Methods:

Function	Parameters	Description
create-campaign	title: (string-ascii 64), description: (string-utf8 256), target-stx: uint, duration-blocks: uint	Registers a new project on-chain with title, mission, target micro-STX, and calculates immutable deadline end-block = block-height + duration-blocks.
fund-campaign	campaign-id: uint, amount-stx: uint	Verifies block-height < end-block and transfers STX from contributor into contract escrow. Updates contributor balances. Supports stretch goals.
claim-funds	campaign-id: uint	Allows creator to claim funds if block-height >= end-block and raised >= target.
claim-refund	campaign-id: uint	Allows contributors to reclaim 100% of their STX if block-height >= end-block and raised < target.

Read-Only Getters:

• get-campaign (campaign-id uint): Returns campaign record (creator, title, description, target-stx, raised-stx, end-block, claimed).
• get-campaign-count (): Returns total number of registered campaigns.
• get-contribution (campaign-id uint, contributor principal): Returns a backer's individual contribution.
• get-current-block-height (): Returns current tenure block height from Clarity runtime.

---

🎨 Frontend Experience & Lifecycle States

Responsive Transaction Lifecycle:

• Button Locking & Loading Animation: Whenever a creator or backer submits a transaction:
  1. Phase 1 (Signature): All form inputs and buttons are disabled; button shows "Waiting for Wallet Signature..." with an animated spinner.
  2. Phase 2 (Mempool Confirmation): Button remains locked with "Confirming on Stacks..." while polling the Stacks node.
  3. Phase 3 (State Settlement): Displays "✓ Confirmed On-Chain!" and automatically triggers a reactive data re-render.
• Clean Responsive Mobile Design:
  • Full mobile hamburger menu with clean links (Home, Dashboard).
  • Mobile footer truncates overflowing contract hashes to display a clean copyright notice on small screens, preserving full details on desktop viewports.
• Consensus Tenure Block Accuracy:
  • Distinguishes between Nakamoto fast streaming blocks (530k+) and Clarity consensus tenure blocks (~19k), ensuring active campaigns never prematurely show as expired.

---

💻 Developer Quickstart

Prerequisites

• Node.js (v18 or v20+)
• Clarinet (v2.x or v3.x)
• Rust & Cargo (for stacksdapp CLI)
• stacksdapp CLI

1. Clone & Install

git clone https://github.com/Oluwa-Laughter/stacksraise.git
cd stacks-raise
stacksdapp doctor

2. Verify Smart Contract & Run Tests

# Type-check Clarity contract
stacksdapp check

# Run Vitest contract unit tests
npm test --prefix contracts

3. Generate TypeScript Bindings

stacksdapp generate

4. Run Frontend Locally

stacksdapp dev --network testnet
# or
cd frontend && npm run dev

Open http://localhost:3000 in your browser.

---

🧪 Test & Verification Results

Clarity Contract Type-Check (stacksdapp check):

[check] Type-checking Clarity contracts...
✔ 1 contract checked
[check] All contracts passed type-checking.

Smart Contract Unit Test Suite (npm test --prefix contracts):

 ✓ tests/crowdfund.test.ts (6 tests)
   ✓ crowdfund
     ✓ initializes with 0 campaigns
     ✓ can create a new campaign with title and description
     ✓ rejects campaign with empty title, 0 target or 0 duration
     ✓ allows contributors to fund a campaign
     ✓ creator can claim funds when goal met and expired
     ✓ contributor can claim refund if goal missed and campaign expired

Test Files  1 passed (1)
Tests       6 passed (6)
All tests passed.

Production Build (npm run build in frontend):

✓ Compiled successfully in 5.4s
✓ Linting and checking validity of types
✓ Collecting page data
✓ Generating static pages (8/8)
✓ Collecting build traces
✓ Finalizing page optimization

Route (app)
┌ ○ /                                    (Landing Page)
├ ○ /_not-found                          (Not Found)
├ ƒ /api/stacks/balance                  (STX Balance Proxy)
├ ○ /api/stacks/campaigns                (Live Campaigns Feed Proxy)
├ ○ /api/stacks/info                     (Chain Tip Proxy)
└ ○ /dashboard                           (Crowdfunding Dashboard)

---

💬 Feedback — Scaffold Stacks Experience

Building StacksRaise during this test-flight was one of the smoothest onboarding experiences I've had in the Stacks ecosystem, but it also taught me a few real-world lessons about shipping full-stack Clarity apps. Here’s an honest take from my experience:

❤️ What I Loved

• stacksdapp generate is pure magic: If you’ve ever written raw Stacks.js boilerplate with manual CV tuple conversions and buffer serialization, you know how tedious it can be. Running one command and getting typed React hooks ready to drop into components felt like modern web2 development, but on Bitcoin.
• Clarinet simnet made testing stress-free: Being able to test contract math, escrow states, and block boundary conditions locally with Vitest before deploying saved so much time and prevented costly deployment mistakes.
• Seamless Wallet Integration: Getting Xverse and Leather to connect cleanly without dealing with legacy compatibility quirks made getting to a working, interactive prototype fast.

🧗 Where I Hit Friction (And Ideas for the Team)

• The Testnet Gas Bottleneck: Waiting on web faucets or running low on STX while deploying and testing multiple contract iterations was the biggest speed bump. Having a quick CLI faucet helper (e.g. stacksdapp faucet) right in the terminal would be a huge quality-of-life upgrade for builders.
• Browser Privacy Shields vs Public RPCs: When testing the live UI on browsers like Brave, direct client-side requests to api.testnet.hiro.so occasionally got blocked by ad/privacy shields. I solved this by setting up simple server-side proxy routes in Next.js (/api/stacks/*), and having that included or documented in the starter template would save future builders a lot of debugging time.
• Handling On-Chain Feed Data: Because Clarity data maps can't be enumerated directly on-chain, rendering a live feed of campaigns requires tracking a counter and batching reads. A quick recipe or helper hook in the Scaffold Stacks docs showing recommended patterns for reading map lists would be super helpful for builders creating marketplaces, DAOs, or crowdfunding projects.

Overall, Scaffold Stacks dramatically lowers the barrier to building on Bitcoin with Stacks. Huge props to the team for putting this together! 🚀

---

📄 License

This project is open-source and licensed under the MIT License.