Skip to content

CONTRACT_README.md

Latest commit

 

History

History
230 lines (177 loc) · 6.56 KB

CONTRACT_README.md

File metadata and controls

230 lines (177 loc) · 6.56 KB

Quest Tavern - Smart Contract Audit Platform

A decentralized smart contract audit platform built on the Stacks blockchain (Bitcoin L2). Quest Tavern connects project owners (Tavernmasters) who need their smart contracts audited with security researchers (Hunters) who find and report vulnerabilities.

Project Structure

LedgerGuard/
├── contracts/
│   ├── traits/
│   │   └── quest-trait.clar          # Interface definition for quest operations
│   ├── quest-manager.clar             # Core contract managing quests and findings
│   ├── escrow.clar                    # Multi-token escrow system
│   └── token-whitelist.clar           # Approved payment tokens management
├── tests/                             # Unit tests (to be implemented)
├── docs/
│   └── Dev.MD                         # Detailed development guide
├── Clarinet.toml                      # Clarinet configuration
└── README.md                          # This file

Smart Contracts

1. quest-trait.clar

Defines the standard interface for quest operations:

  • create-quest - Create a new audit quest
  • join-quest - Join an existing quest as a hunter
  • submit-finding - Submit a vulnerability finding
  • distribute-rewards - Distribute rewards to approved findings

2. quest-manager.clar

Core contract for managing the entire quest lifecycle:

  • Quest Management: Create, join, and cancel quests
  • Finding Submission: Hunters submit vulnerability findings with severity levels
  • Approval System: Tavernmasters approve/reject findings and allocate rewards
  • Reward Distribution: Automatic distribution after quest completion
  • Hunter Statistics: Track earnings, completed quests, and accepted findings

Key Features:

  • 5 severity levels: Critical, High, Medium, Low, Informational
  • Platform fee: 5% (500 basis points)
  • Quest status tracking: Active, Completed, Cancelled
  • Finding status tracking: Pending, Approved, Rejected

3. escrow.clar

Multi-token escrow system supporting:

  • Token Support: USDCx, sBTC, and native STX
  • Escrow Operations: Lock, release, and refund tokens
  • Token Whitelist: Only approved tokens can be escrowed
  • Batch Release: Distribute rewards to multiple recipients
  • Admin Controls: Manage token whitelist and permissions

4. token-whitelist.clar

Manages approved payment tokens:

  • Default Tokens: STX and sBTC pre-configured
  • Admin Functions: Add/remove tokens, enable/disable tokens
  • Token Metadata: Name, symbol, decimals tracking
  • Multi-Admin Support: Flexible permission management

Development Status

✅ All contracts implemented and verified with Clarinet
✅ Core quest management functionality complete
✅ Multi-token escrow system ready
✅ Token whitelist management implemented

Current Limitations (Development Version)

  • Token transfers are simplified (commented out for development)
  • as-contract calls removed for initial testing
  • External SIP-010 trait imports simplified
  • Some functions marked as "Note: In production..." need full implementation

Getting Started

Prerequisites

  • Clarinet installed
  • Node.js (for tests)
  • VS Code with Clarity extension (recommended)

Installation

# Clone the repository
cd /home/oxcore/SideQuest/LedgerGuard

# Check contracts
clarinet check

# Run tests (once implemented)
npm install
npm test

Contract Verification

All contracts pass Clarinet's syntax checker:

clarinet check

Result: ✔ 4 contracts checked (52 warnings are code quality suggestions)

Usage Examples

Creating a Quest (Tavernmaster)

(contract-call? .quest-manager create-quest 
  "https://github.com/project/repo"
  u1000000  ;; 1,000,000 tokens reward
  'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token-contract
  u1000     ;; 1000 blocks duration
)

Joining a Quest (Hunter)

(contract-call? .quest-manager join-quest u1)  ;; Join quest #1

Submitting a Finding

(contract-call? .quest-manager submit-finding
  u1                                      ;; quest-id
  u1                                      ;; severity (1=Critical)
  0x1234...                              ;; description-hash (IPFS)
  0x5678...                              ;; proof-hash
)

Approving a Finding (Tavernmaster)

(contract-call? .quest-manager approve-finding
  u1     ;; finding-id
  u25    ;; reward-percentage (25% of total)
)

Distributing Rewards

(contract-call? .quest-manager distribute-rewards u1)  ;; quest-id

Error Codes

quest-manager.clar

  • u100 - Unauthorized
  • u101 - Quest not found
  • u102 - Quest ended
  • u103 - Quest still active
  • u104 - Already joined
  • u105 - Not joined
  • u106 - Invalid severity
  • u107 - Finding already processed
  • u111 - Quest has hunters (cannot cancel)

escrow.clar

  • u200 - Unauthorized
  • u201 - Escrow not found
  • u202 - Already released
  • u207 - Token not whitelisted

token-whitelist.clar

  • u300 - Unauthorized
  • u301 - Token not found
  • u302 - Token already exists
  • u303 - Token disabled

Technology Stack

  • Blockchain: Stacks (Bitcoin L2)
  • Smart Contract Language: Clarity
  • Development Tools: Clarinet
  • Testing: Vitest + @stacks/clarinet-sdk
  • Payment Tokens: USDCx, sBTC, STX

Roadmap

Phase 1: ✅ Complete

  • Project setup
  • Core contracts implemented
  • Clarinet verification passed

Phase 2: In Progress

  • Implement full token transfer logic
  • Add SIP-010 trait integration
  • Complete escrow functionality

Phase 3: Planned

  • Unit tests with Clarinet SDK
  • Integration tests
  • Gas optimization

Phase 4: Planned

  • Frontend development (React + Stacks.js)
  • Mainnet deployment
  • Security audit

Contributing

This is currently in development. See Dev.MD for detailed development guidelines.

Security Considerations

⚠️ This is a development version. Before production deployment:

  1. Complete security audit
  2. Implement full token transfer logic
  3. Add comprehensive test coverage
  4. Review all error handling
  5. Optimize gas usage
  6. Test on testnet extensively

License

[Add your license here]

Resources

Contact

[Add your contact information here]