Quest Tavern - Decentralized Audit Platform

Status: ✅ Fully Functional Smart Contracts | 🧪 47/47 Tests Passing | 📝 Ready for Testnet

Quest Tavern is a decentralized security audit platform built on Stacks that connects security researchers (hunters) with blockchain projects seeking audits. Projects create audit quests with token rewards, hunters submit vulnerability findings, and rewards are distributed based on finding severity and impact.

🎯 Quick Start

# Install dependencies
npm install

# Run all tests
npm test

# Check contract syntax
clarinet check

# Deploy to testnet
clarinet deployments apply --testnet

✨ Key Features

For Projects (Tavernmasters)

• Create Audit Quests with custom token rewards (STX, sBTC, or any SIP-010 token)
• Review & Approve Findings with flexible reward percentages
• Escrow Integration for secure fund management
• Cancel Quests before hunters join (full refund)

For Security Researchers (Hunters)

• Join Quests to participate in audits
• Submit Findings with 5 severity levels (Critical to Info)
• Earn Rewards based on finding impact
• Track Stats including total earnings and findings accepted

Platform Features

• Multi-token Support: STX, sBTC, and whitelisted SIP-010 tokens
• Escrow System: Secure lock/release/refund operations
• Platform Fee: 5% fee on distributed rewards
• On-chain Verification: All findings and proofs stored on-chain via IPFS hashes

📁 Project Structure

LedgerGuard/
├── contracts/
│   ├── quest-manager.clar      # Core quest lifecycle (430+ lines)
│   ├── escrow.clar             # Token escrow system (280+ lines)
│   ├── token-whitelist.clar    # Payment token registry (240+ lines)
│   ├── test-token.clar         # SIP-010 test token
│   └── traits/
│       └── quest-trait.clar    # Quest operations interface
├── tests/
│   ├── quest-manager.test.ts   # 23 unit tests
│   ├── escrow.test.ts          # 19 unit tests
│   └── integration.test.ts     # 5 integration tests
├── docs/
│   ├── Dev.MD                  # Architecture & roadmap
│   └── CONTRACT_README.md      # Contract specifications
├── DEPLOYMENT.md               # Deployment guide
└── Clarinet.toml              # Project configuration

🧪 Test Coverage

All 47 Tests Passing ✅

• ✅ Quest Manager: 23 tests covering creation, joining, findings, rewards, cancellation
• ✅ Escrow: 19 tests covering locking, releasing, refunding, batch operations
• ✅ Integration: 5 tests covering complete workflows and edge cases

🏗️ Architecture

Smart Contracts

quest-manager.clar

Main contract managing the audit quest lifecycle:

• Quest creation with token support
• Hunter registration and tracking
• Finding submission with severity levels (1-5)
• Approval/rejection with custom reward percentages
• Automated reward distribution
• Platform fee collection (5%)

escrow.clar

Multi-token escrow system:

• Lock tokens for quest rewards
• Release to hunters after approval
• Refund to tavernmasters on cancellation
• Batch release for multiple recipients
• Token whitelist integration

token-whitelist.clar

Registry of approved payment tokens:

• Add/remove tokens with metadata
• Enable/disable tokens
• Admin management system
• Pre-configured: STX, sBTC

🚀 Usage Examples

Creating a Quest

;; Create audit quest with 1M test tokens, 100 block duration
(contract-call? .quest-manager create-quest-with-token
  "https://github.com/my-project/smart-contracts"
  u1000000
  'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.test-token
  u100
)
;; Returns: (ok u1) - quest ID

Joining a Quest

;; Register as hunter for quest #1
(contract-call? .quest-manager join-quest u1)
;; Returns: (ok true)

Submitting a Finding

;; Submit critical vulnerability
(contract-call? .quest-manager submit-finding
  u1                                    ;; quest-id
  u1                                    ;; severity (1=Critical)
  0x1234...                            ;; description IPFS hash
  0x5678...                            ;; proof IPFS hash
)
;; Returns: (ok u1) - finding ID

Approving a Finding

;; Approve finding with 40% of reward pool
(contract-call? .quest-manager approve-finding
  u1                                    ;; finding-id
  u40                                   ;; reward percentage
)
;; Returns: (ok true)

Claiming Rewards

;; After quest ends and rewards distributed
(contract-call? .quest-manager payout-finding-with-token u1)
;; Returns: (ok true) + transfers tokens to hunter

📊 Contract Functions

Quest Manager

Public Functions

• create-quest / create-quest-with-token - Create new audit quest
• join-quest - Register as hunter
• submit-finding - Submit vulnerability
• approve-finding - Approve with reward %
• reject-finding - Reject with reason
• distribute-rewards - Finalize quest (owner only)
• payout-finding / payout-finding-with-token - Claim reward
• cancel-quest - Cancel before hunters join

Read-Only Functions

• get-quest - Quest details
• is-quest-active - Check if active
• get-finding - Finding details
• get-hunter-stats - Hunter statistics

Escrow

Public Functions

• lock-tokens / lock-stx - Lock funds
• release-tokens - Release to recipient
• refund-escrow - Refund to depositor
• batch-release - Release to multiple recipients
• add-token-to-whitelist - Add approved token

Read-Only Functions

• get-escrow - Escrow details
• is-escrow-locked - Check lock status

🔒 Security

Error Codes

Quest Manager

• 100: Unauthorized
• 101: Quest not found
• 102: Quest ended
• 103: Quest cancelled
• 104: Already joined
• 105: Not a hunter
• 106: Invalid severity
• 107-115: Finding/reward errors

Escrow

• 100: Unauthorized
• 101: Invalid amount
• 102: Token not whitelisted
• 103-108: Escrow state errors

Audit Recommendations

Before mainnet deployment:

1. Professional security audit of all contracts
2. Token transfer logic verification
3. Economic model validation
4. Gas optimization review

See DEPLOYMENT.md for full security considerations.

📚 Documentation

• Dev.MD - Development roadmap and architecture
• CONTRACT_README.md - Detailed contract specifications
• DEPLOYMENT.md - Deployment guide with examples
• Stacks Documentation - Stacks blockchain docs
• Clarity Language - Smart contract language guide

🛠️ Development

Prerequisites

• Clarinet v2.0+
• Node.js 18+
• npm or yarn

Setup

# Clone repository
git clone <repository-url>
cd LedgerGuard

# Install dependencies
npm install

# Run tests
npm test

# Check contracts
clarinet check

# Start Clarinet console
clarinet console

Testing

# Run all tests
npm test

# Run specific test file
npx vitest run tests/quest-manager.test.ts

# Run with coverage
npm test -- --coverage

# Watch mode for development
npx vitest watch

🌐 Deployment

Testnet

# Generate deployment plan
clarinet deployments generate --testnet

# Deploy contracts
clarinet deployments apply --testnet

Mainnet

See DEPLOYMENT.md for detailed mainnet deployment instructions.

📈 Current Status

✅ Completed (Phase 1-3)

• Core contract architecture
• Quest lifecycle management
• Escrow system with multi-token support
• Token whitelist registry
• SIP-010 token integration
• Complete test suite (47 tests)
• Integration tests
• Documentation

🎯 Ready for Testing

• Testnet deployment
• User acceptance testing
• Security audit
• Mainnet deployment

🚀 Future Enhancements (Optional)

• Frontend dApp
• IPFS integration for finding storage
• Quest templates
• Reputation system
• Multi-signature approvals
• Automated severity classification

🤝 Contributing

This is a demonstration project for the Quest Tavern audit platform. For production use:

1. Conduct professional security audits
2. Test thoroughly on testnet
3. Review all economic parameters
4. Consider additional security measures

📄 License

See project documentation for license information.

🙏 Acknowledgments

Built with:

• Stacks: Bitcoin L2 blockchain
• Clarity: Smart contract language
• Clarinet: Development environment
• Vitest: Testing framework

---

⚠️ Disclaimer: These contracts are for demonstration purposes. Conduct thorough security audits before mainnet deployment.