Skip to content

Dev.MD

Latest commit

 

History

History
170 lines (164 loc) · 6.88 KB

Dev.MD

File metadata and controls

170 lines (164 loc) · 6.88 KB
  1. Project Overview Quest Tavern is a decentralized smart contract audit platform built on the Stacks blockchain (Bitcoin L2). The platform connects project owners (Tavernmasters) who need their smart contracts audited with security researchers (Hunters) who find and report vulnerabilities. 1.1 User Roles Role Description Capabilities 🏛️ Tavernmaster Project owner seeking audit Post quests, set rewards, review findings, approve payouts ⚔️ Hunter Security auditor/researcher Browse quests, join quests, submit findings, claim rewards

1.2 Technology Stack Blockchain Stacks (Bitcoin L2 with 100% Bitcoin finality) Smart Contracts Clarity (decidable, secure-by-design language) Dev Tools Clarinet (testing, local devnet, deployment) Frontend React/Next.js + Stacks.js + @stacks/connect Payments USDCx (SIP-010 token via Circle xReserve), sBTC, STX Wallets Leather, Xverse (via SIP-030 standard)

  1. Development Phases Phase 1: Project Setup & Core Contract Duration: 1-2 weeks Task 1.1: Initialize Clarinet Project • Install Clarinet CLI: brew install clarinet or cargo install clarinet • Create project: clarinet new quest-tavern && cd quest-tavern • Install VS Code extension: "Clarity - Stacks Labs" • Configure Clarinet.toml for devnet with test accounts Task 1.2: Create Core Traits File: contracts/traits/quest-trait.clar • Define trait for quest operations (create, join, submit, distribute) • Import SIP-010 trait for token compatibility: ◦ (use-trait ft-trait 'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-010-trait-ft-standard.sip-010-trait) Task 1.3: Quest Manager Contract File: contracts/quest-manager.clar Data Maps: • quests: { quest-id → { owner, repo-url, total-reward, token-contract, end-block, status, hunters-count } } • quest-hunters: { quest-id, hunter → { joined-block, findings-count } } • findings: { finding-id → { quest-id, hunter, severity, description-hash, status, reward-share } } • hunter-stats: { hunter → { total-earnings, quests-completed, findings-accepted } } Public Functions: • create-quest (repo-url, reward-amount, token-contract, duration-blocks) • join-quest (quest-id) • submit-finding (quest-id, severity, description-hash, proof-hash) • approve-finding (finding-id, reward-percentage) - Tavernmaster only • reject-finding (finding-id, reason-hash) - Tavernmaster only • distribute-rewards (quest-id) - Anyone can call after end-block • cancel-quest (quest-id) - Tavernmaster only, before hunters join Read-Only Functions: • get-quest (quest-id) • get-active-quests () • get-quest-hunters (quest-id) • get-hunter-findings (quest-id, hunter) • get-hunter-stats (hunter) • is-quest-active (quest-id)

Phase 2: Token Integration & Escrow Duration: 1-2 weeks Task 2.1: Multi-Token Escrow Contract File: contracts/escrow.clar • Support USDCx, sBTC, and STX as payment tokens • Lock funds when quest is created • Release funds based on approved finding allocations • Handle refunds for cancelled quests • Implement SIP-010 contract-call? for token transfers: ◦ (contract-call? token-contract transfer amount sender recipient none) Task 2.2: Token Whitelist • Create admin-controlled whitelist of allowed payment tokens • Add USDCx contract address (mainnet to be confirmed) • Add sBTC: SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token • Support native STX via stx-transfer? Task 2.3: Reward Distribution Logic • Calculate rewards based on finding severity and allocation • Severity tiers: Critical (40%), High (25%), Medium (20%), Low (15%) • Platform fee: 5% of total quest reward • Auto-distribute when block-height >= quest end-block • Unclaimed rewards return to Tavernmaster after grace period Phase 3: Unit Testing Duration: 1 week Task 3.1: Setup Clarinet SDK Testing File: tests/quest-manager.test.ts • Install: npm install @stacks/clarinet-sdk vitest @stacks/transactions • Configure vitest.config.ts with Clarinet manifest path • Use simnet for blockchain simulation Task 3.2: Test Scenarios • Quest lifecycle: create → join → submit → approve → distribute • Authorization: Only Tavernmaster can approve/reject findings • Time constraints: Cannot distribute before end-block • Token transfers: Verify escrow lock/release with post-conditions • Edge cases: Empty quests, duplicate findings, max hunters

  1. Smart Contract Specifications 3.1 quest-manager.clar Constants: • err-unauthorized (u100) - Caller not authorized • err-quest-not-found (u101) - Quest ID doesn't exist • err-quest-ended (u102) - Quest past deadline • err-quest-active (u103) - Quest still active • err-already-joined (u104) - Hunter already in quest • err-not-joined (u105) - Hunter not in quest • err-invalid-severity (u106) - Invalid severity level • err-finding-processed (u107) - Finding already approved/rejected Data Variables: • quest-counter (uint) - Auto-increment quest IDs • finding-counter (uint) - Auto-increment finding IDs • platform-fee-bps (uint) - Platform fee in basis points (500 = 5%) • fee-recipient (principal) - Address receiving platform fees Severity Enum: • u1 = Critical, u2 = High, u3 = Medium, u4 = Low, u5 = Informational 3.2 Frontend API Calls Action Method Stacks.js Function Connect Wallet

connect() Create Quest stx_callContract request() Get Quest List read-only fetchCallReadOnlyFunction() Submit Finding stx_callContract request() Claim Rewards stx_callContract request()

  1. Token Integration Details 4.1 USDCx Integration USDCx is a SIP-010 compliant token backed 1:1 by USDC via Circle's xReserve protocol. • Bridge URL: https://bridge.stacks.co/usdc/eth/stx • Minimum bridge amount: 10 USDC • Confirmation time: ~15 minutes • Decimals: 6 • Withdrawal: Burns USDCx on Stacks, releases USDC on Ethereum 4.2 sBTC Integration sBTC is a 1:1 Bitcoin-backed asset secured by decentralized signers. • Contract: SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token • Dashboard: https://app.stacks.co/sbtc • Decimals: 8 • Follows SIP-010 standard for transfers 4.3 SIP-010 Transfer Pattern All token transfers use the same SIP-010 interface: • (contract-call? transfer ) • Always verify tx-sender or contract-caller equals sender • Use post-conditions to protect user funds in frontend

  2. Project File Structure quest-tavern/ ├── contracts/ │ ├── traits/ │ │ └── quest-trait.clar │ ├── quest-manager.clar │ ├── escrow.clar │ └── token-whitelist.clar ├── tests/ │ ├── quest-manager.test.ts │ └── escrow.test.ts ├── Clarinet.toml ├── vitest.config.ts └── README.md